From ce55ab8ef20d5aead287aa0e20b7e09194a86376 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Thu, 21 Sep 2023 21:45:13 +0200 Subject: [PATCH] Workaround go-md2man warning about HTML comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit go-md2man 2.0.2 (not 1.0.10) does not recognize HTML comments, triggering a warning. Work around that, just to have a silent build. This uses a "comment" syntax by defining a reference-style link ( https://stackoverflow.com/a/20885980 ). Alternatively, go-md2man _does_ recognize comments inline inside a paragraph, so preceding the HTML comment with a space would probably work as well. Either way is _weird_, and we can't add a comment to explain the comment mechanism... so use the more visually distinct alternative to hopefully minimize regressions; using a leading space would tempt future readers to just remove the space, thinking it's a mistake. Signed-off-by: Miloslav Trmač --- docs/containers-policy.json.5.md | 8 +++++--- docs/containers-registries.d.5.md | 2 +- docs/containers-transports.5.md | 4 ++-- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/containers-policy.json.5.md b/docs/containers-policy.json.5.md index 909d04afd0..50341b4106 100644 --- a/docs/containers-policy.json.5.md +++ b/docs/containers-policy.json.5.md @@ -58,7 +58,8 @@ This is expressed in JSON using the top-level syntax The global `default` set of policy requirements is mandatory; all of the other fields (`transports` itself, any specific transport, the transport-specific default, etc.) are optional. - +[comment]: # (NOTE: Keep this in sync with transports/transports.go!) + ## Supported transports and their scopes See containers-transports(5) for general documentation about the transports and their reference syntax. @@ -235,7 +236,8 @@ This requirement requires an image to be signed using “simple signing” with "signedIdentity": identity_requirement } ``` - + +[comment]: # (Later: other keyType values) Exactly one of `keyPath`, `keyPaths` and `keyData` must be present, containing a GPG keyring of one or more public keys. Only signatures made by these keys are accepted. @@ -309,7 +311,7 @@ If the `signedIdentity` field is missing, it is treated as `matchRepoDigestOrExa provided by the transport. In particular, the `dir:` and `oci:` transports can be only used with `exactReference` or `exactRepository`. - +[comment]: # (### `signedBaseLayer`) ### `sigstoreSigned` diff --git a/docs/containers-registries.d.5.md b/docs/containers-registries.d.5.md index 04434de4b6..18c0c6cdda 100644 --- a/docs/containers-registries.d.5.md +++ b/docs/containers-registries.d.5.md @@ -73,7 +73,7 @@ If no `docker` section can be found for the container image, and no `default-doc A single configuration section is selected for a container image using the process described above. The configuration section is a YAML mapping, with the following keys: - +[comment]: # (`sigstore` and `sigstore-staging` are deprecated and intentionally not documented here.) - `lookaside-staging` defines an URL of of the signature storage, used for editing it (adding or deleting signatures). diff --git a/docs/containers-transports.5.md b/docs/containers-transports.5.md index 8ec42fe87a..76b2946f61 100644 --- a/docs/containers-transports.5.md +++ b/docs/containers-transports.5.md @@ -16,7 +16,7 @@ they are evaluated. For example: if evaluated on a remote server, image names might refer to paths on that server; relative paths are relative to the current directory of the image consumer. - +[comment]: # (atomic: is deprecated and not documented here.) ### **containers-storage**:[**[**storage-specifier**]**]{image-id|docker-reference[@image-id]} @@ -91,7 +91,7 @@ An image using the Singularity image format at _path_. Only reading images is supported, and not all scripts can be represented in the OCI format. - +[comment]: # (tarball: can only usefully be used from Go callers who call tarballReference.ConfigUpdate, and is not documented here.) ## Examples