From: Jean-Noël Avila <jn.avila@free.fr>
Date: Wed, 21 Feb 2024 07:41:48 GMT
Subject: Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax
Message-ID: <67dca173-3048-430b-88a1-d3b5d853f84b@free.fr>
In-Reply-To: <xmqqsf1mlp6f.fsf@gitster.g>

Le 20/02/2024 à 23:57, Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>>   [verse]
>> -'git rev-parse' [<options>] <args>...
>> +'git rev-parse' [<options>] <arg>...
> 
> Good.  The "or more" is signalled by the ellipsis, not "args" being
> plural.
> 
>> ---short[=length]::
>> +--short[=<length>]::
>>   	Same as `--verify` but shortens the object name to a unique
>>   	prefix with at least `length` characters. The minimum length
> 
> This same comment applies throughout this patch, but in other places
> when we use <placeholder> in the option argument description, don't
> we use the same <placeholder> in text as well?  I am wondering if
> the `length` (typeset in fixed-width) should become <length>.  What
> do other recent[*] documentation pages commonly do?

This is another part of the inconsistences in documentation that I'd 
like to tackle (hopefully, not in another life).

Using angle brackets for placeholders everywhere they appear is a visual 
link to the preceding syntax description, but may feel a bit heavy on 
some cases. Anyway, I'm all for applying the rule everywhere, for the 
sake of consistency.

Backticks and single quotes are used indistinctively (by the way, 
asciidoctor does not process single quotes as markup) and are not used 
everywhere they should. Using backticks is also a good hint for 
translators to mean "verbatim, do not translate". Obviously, the 
placeholders ask for translation, so the backtick rule should not apply 
to them, even if another formating would be welcome : _<placeholder>_ 
for instance?

> 
> 	Side note: I say "recent" because rev-parse doc is one of
> 	the oldest ones that did not get typesetting attention they
> 	deserve, compared to more recent ones that got nitpicked
> 	while they were written and updated.
> 
>> ---branches[=pattern]::
>> ---tags[=pattern]::
>> ---remotes[=pattern]::
>> +--branches[=<pattern>]::
>> +--tags[=<pattern>]::
>> +--remotes[=<pattern>]::
>>   	Show all branches, tags, or remote-tracking branches,
>>   	respectively (i.e., refs found in `refs/heads`,
>>   	`refs/tags`, or `refs/remotes`, respectively).
> 
> Ditto.  We see `pattern` that may want to become <pattern> in the
> description (after the post context of this hunk).
> 
>> ---glob=pattern::
>> +--glob=<pattern>::
>>   	Show all refs matching the shell glob pattern `pattern`. If
>>   	the pattern does not start with `refs/`, this is automatically
>>   	prepended.  If the pattern does not contain a globbing
> 
> Ditto.
> 
>> ---exclude-hidden=[fetch|receive|uploadpack]::
>> +--exclude-hidden=(fetch|receive|uploadpack)::
>>   	Do not include refs that would be hidden by `git-fetch`,
>>   	`git-receive-pack` or `git-upload-pack` by consulting the appropriate
>>   	`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
> 
> Good.
> 
>> ---since=datestring::
>> ---after=datestring::
>> +--since=<datestring>::
>> +--after=<datestring>::
>>   	Parse the date string, and output the corresponding
>>   	--max-age= parameter for 'git rev-list'.
> 
> Good, modulo possibly "date string" -> "<datestring>".
> 
>> ---until=datestring::
>> ---before=datestring::
>> +--until=<datestring>::
>> +--before=<datestring>::
>>   	Parse the date string, and output the corresponding
>>   	--min-age= parameter for 'git rev-list'.
> 
> Ditto.
> 
>> -<args>...::
>> +<arg>...::
>>   	Flags and parameters to be parsed.
> 
> Good.