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

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

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

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

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

> 
> > +`--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 

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