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

From: Junio C Hamano <gitster@pobox.com>
Date: May 1, 2025, 23:10 UTC
Message-ID: <xmqqecx8vsf8.fsf@gitster.g>
In-Reply-To: <CAPig+cR-mbtwvUZBdhVCKsimVCETKdWHNG14hXDO77qMWMwVkg@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 6 quoted lines

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

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

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.

Show 11 quoted lines

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