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

From: Junio C Hamano <[email-masked]>
Date: Thu, 01 May 2025 16:10:19 -0700

Eric Sunshine <[email-masked]> writes:

>> -'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"?

No.  I would understand if it is spelled '.idx', to refer to a
concrete file suffix that people would type verbatim.  In this
sentence, however, I think "idx file" and "pack file" are used as a
general noun.

>>  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?

Given these entries in Documentation/glossary-content.adoc

        [[def_hash]]hash::
                In Git's context, synonym for <<def_object_name,object name>>.
        [[def_object_identifier]]object identifier (oid)::
                Synonym for <<def_object_name,object name>>.

I do not think so, and if we find somebody doing so, we should
correct them.

>> 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.

Once the dust settles from this series, yes, but not in this series
that is about mark-up.

Thanks.