Re: [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions

From: Eric Sunshine <sunshine@sunshineco.com>
Date: May 1, 2025, 22:43 UTC
Message-ID: <CAPig+cR-mbtwvUZBdhVCKsimVCETKdWHNG14hXDO77qMWMwVkg@mail.gmail.com>
In-Reply-To: <20250501213414.370514-2-gitster@pobox.com>

On Thu, May 1, 2025 at 5:34 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 16 quoted lines

> To unify mark-up used in our documentation to a newer convention,
> started by 22293895 (doc: apply synopsis simplification on git-clone
> and git-init, 2024-09-24), update the documentation pages for 'git
> verify-commit', 'git verify-tag', and 'git verify-pack' to
>
>  * use [synopsis], not [verse] in the SYNOPSIS section
>  * enclose `--option=<value>` in backquotes
>  * do not describe non-option arguments in the OPTIONS section
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc
> @@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits
> -Validates the GPG signature created by 'git commit -S'.
> +Validates the GPG signature created by `git commit -S`
> +on the commit objects given on the command line.

Taking note of the casing of GPG (all uppercase)...

Show 7 quoted lines

> diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc
> @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files
> -Reads given idx file for packed Git archive created with the
> -'git pack-objects' command and verifies the idx file and the
> -corresponding pack file.
> +Read each idx file for packed Git archive given on the command line,
> +and verify the idx file and the corresponding pack file.

Okay, rewrite seems reasonable. Do we want to backtick "idx" and "pack"?

Show 7 quoted lines

>  OUTPUT FORMAT
>  -------------
> -When specifying the -v option the format used is:
> +When specifying the `-v` option the format used is:
>
> -       SHA-1 type size size-in-packfile offset-in-packfile
> +       object-name type size size-in-packfile offset-in-packfile

Do we not typically call this object-ID (OID) rather than object-name?

> diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc
> @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags

...all uppercase GPG...

> -Validates the gpg signature created by 'git tag'.
> +Validates the gpg signature created by 'git tag' in the tag
> +objects listed on the command line.

...since this is being rewritten anyhow, it probably would make sense to employ consistent casing of GPG.