Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax
- From
Jean-Noël Avila <jn.avila@free.fr>
- Date
- Feb 21, 2024, 07:41 UTC
- 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 :
Show 19 quoted lines
> "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?
Show 58 quoted lines
> > 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.