Le 20/02/2024 à 23:57, Junio C Hamano a écrit :
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@xxxxxxxxx> 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.
