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

[Junio C Hamano <gitster@pobox.com>]

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

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