Re: [PATCH 1/9] doc: convert git-log to new documentation format

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Tuesday, 17 June 2025 01:02:11 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> > 
> > - Switch the synopsis to a synopsis block which will automatically
> > 
> >   format placeholders in italics and keywords in monospace
> > 
> > - Use _<placeholder>_ instead of <placeholder> in the description
> > - Use `backticks` for keywords and more complex option
> > descriptions. The new rendering engine will apply synopsis rules to
> > these spans.
> > 
> > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> > ---
> > 
> >  Documentation/git-log.adoc | 83 ++++++++++++++++++++------------------
> >  1 file changed, 44 insertions(+), 39 deletions(-)
> 
> This hunk (lightly edited to shift contexts) ...
> 
> > ---no-decorate::
> > ---decorate[=short|full|auto|no]::
> > -	Print out the ref names of any commits that are shown. If 'short' 
is
> > -	specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
> > -	'refs/remotes/' will not be printed. If 'full' is specified, the
> > -	full ref name (including prefix) will be printed. If 'auto' is
> > -	specified, then if the output is going to a terminal, the ref names
> > -	are shown as if 'short' were given, otherwise no ref names are
> > -	shown. The option `--decorate` is short-hand for `--
decorate=short`.
> > -	Default to configuration value of `log.decorate` if configured,
> > -	otherwise, `auto`.
> > +`--no-decorate`::
> > +`--decorate[=(short|full|auto|no)]`::
> > +	Print out the ref names of any commits that are shown. Possible 
values
> > +	are:
> > ++
> > +----
> > +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
> > +	`refs/remotes/` are not printed.
> > +`full`;; the full ref name (including prefix) is printed.
> > +`auto`:: if the output is going to a terminal, the ref names
> > +	are shown as if `short` were given, otherwise no ref names are
> > +	shown.
> > +----
> > ++
> > +The option `--decorate` is short-hand for `--decorate=short`. Default to
> > +configuration value of `log.decorate` if configured, otherwise, `auto`.
> 
> ... does more than what the three-bullet list in the proposed log
> message describes.  The result is certainly easier to follow and
> more extensible to have these possible values in an enumerated list
> than in a prose.

True. That may become a new rule too.

> 
> > +`--decorate-refs=<pattern>`::
> > 
> > +`--decorate-refs-exclude=<pattern>`::
> >  	For each candidate reference, do not use it for decoration if it
> > 
> > -	matches any patterns given to `--decorate-refs-exclude` or if it
> > -	doesn't match any of the patterns given to `--decorate-refs`. The
> > +	matches any of _<pattern>_ given to `--decorate-refs-exclude` or 
if it
> > +	doesn't match any of _<pattern>_ given to `--decorate-refs`. The
> 
> "any patterns" in the original may not be grammatical, but the
> rewritten "any of _<pattern>_" does not sound grammatical, either.
> "any of the _<pattern>_s"?  I dunno what the convention should be
> when more than one <placeholder> instances have to be referenced.

Good question for which I was more inclined to consider placeholders as 
invariant, even if the result may sound "ungrammatical". This also simplifies 
the translation process where the plural forms can be complicated in some 
languages.