"Jean-Noël Avila via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx> > > - 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@xxxxxxx> > --- > 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.
