Re: [PATCH v2 4/4] doc: convert git-show to synopsis style

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Mon, Jan 26, 2026, at 22:25, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
>  * add synopsis block definition in asciidoc.conf.in
>  * convert commands to synopsis style
>  * use _<placeholder>_ for arguments
>  * minor formatting fixes
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---

I will go through and discuss both the markup as well as the HTML
rendering at the same time when relevant.

(Confession. I never check the man page output since I haven’t managed
to set it up. I don’t know if that is a potential reviewer blindspot.)

>  Documentation/asciidoc.conf.in    |   6 ++
>  Documentation/git-show.adoc       |  16 +--
>  Documentation/pretty-formats.adoc | 164 +++++++++++++++++-------------
>  3 files changed, 108 insertions(+), 78 deletions(-)
>
> diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
>[snip]
> diff --git a/Documentation/git-show.adoc b/Documentation/git-show.adoc
> index 51044c814f..3b180e8c7a 100644
> --- a/Documentation/git-show.adoc
> +++ b/Documentation/git-show.adoc
> @@ -8,8 +8,8 @@ git-show - Show various types of objects
>
>  SYNOPSIS
>  --------
> -[verse]
> -'git show' [<options>] [<object>...]
> +[synopsis]
> +git show [<options>] [<object>...]

Ok.

>
>  DESCRIPTION
>  -----------
> @@ -17,16 +17,16 @@ Shows one or more objects (blobs, trees, tags and commits).
>
>  For commits it shows the log message and textual diff. It also
>  presents the merge commit in a special format as produced by
> -'git diff-tree --cc'.
> +`git diff-tree --cc`.

Ok.

>
>  For tags, it shows the tag message and the referenced objects.
>
> -For trees, it shows the names (equivalent to 'git ls-tree'
> -with --name-only).
> +For trees, it shows the names (equivalent to `git ls-tree`
> +with `--name-only`).

More conversion to backticks. Ok.

>
>  For plain blobs, it shows the plain contents.
>
> -Some options that 'git log' command understands can be used to
> +Some options that `git log` command understands can be used to

Like what was discussed in the last round it makes sense to use `git
log` instead of `linkgit` here.

>  control how the changes the commit introduces are shown.
>
>  This manual page describes only the most frequently used options.
> @@ -34,8 +34,8 @@ This manual page describes only the most frequently
> used options.
>
>  OPTIONS
>  -------
> -<object>...::
> -	The names of objects to show (defaults to 'HEAD').
> +`<object>...`::
> +	The names of objects to show (defaults to `HEAD`).

synopsis-style argument markup and backticks. Ok.

>  	For a more complete list of ways to spell object names, see
>  	"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
>
> diff --git a/Documentation/pretty-formats.adoc
> b/Documentation/pretty-formats.adoc
> index 2121e8e1df..806c588658 100644
> --- a/Documentation/pretty-formats.adoc
> +++ b/Documentation/pretty-formats.adoc
> @@ -18,54 +18,72 @@ config option to either another format name, or a
>  linkgit:git-config[1]). Here are the details of the
>  built-in formats:
>
> -* `oneline`
> -
> -	  <hash> <title-line>

Okay. This now looks good in the HTML output.

> +`oneline`::
> ++
> +[synopsis]
> +--
> +<hash> <title-line>
> +--

Also good. The `[synopsis]` gives us verbatim typeface for code and
italics/emphasis for placeholders. Just like inline backticks.

>  +
>  This is designed to be as compact as possible.
>
> -* `short`
> -
> -	  commit <hash>
> -	  Author: <author>

These have tab indent followed by two spaces. I’m guessing this is
intentional.

The HTML rendering looks good.

> -
> -	      <title-line>
> -
> -* `medium`
> -
> -	  commit <hash>
> -	  Author: <author>
> -	  Date:   <author-date>
> -
> -	      <title-line>
> +`short`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author><hash> <title-line>
>
> -	      <full-commit-message>
> +    <title-line>
> +--
>
> -* `full`
> +`medium`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
> +Date:   <author-date>
>
> -	  commit <hash>
> -	  Author: <author>
> -	  Commit: <committer>
> +    <title-line>
>
> -	      <title-line>
> +    <full-commit-message>
> +--
>
> -	      <full-commit-message>
> +`full`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
> +Commit: <committer>
>
> -* `fuller`
> +    <title-line>
>
> -	  commit <hash>
> -	  Author:     <author>
> -	  AuthorDate: <author-date>
> -	  Commit:     <committer>
> -	  CommitDate: <committer-date>
> +    <full-commit-message>
> +--
>
> -	       <title-line>
> +`fuller`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author:     <author>
> +AuthorDate: <author-date>
> +Commit:     <committer>
> +CommitDate: <committer-date>
>
> -	       <full-commit-message>
> +     <title-line>
>
> -* `reference`
> +     <full-commit-message>
> +--
>
> -	  <abbrev-hash> (<title-line>, <short-author-date>)
> +`reference`::
> ++
> +[synopsis]
> +--
> +<abbrev-hash> (<title-line>, <short-author-date>)
> +--

Good. Things that are indented (like commit message) are correctly
indented here.

>  +
>  This format is used to refer to another commit in a commit message and
>  is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++.  By default,

Not a change here but while `--pretty...` has all the symbols it is
partly rendered, partly not.

> @@ -74,23 +92,24 @@ is explicitly specified.  As with any `format:` with format
>  placeholders, its output is not affected by other options like
>  `--decorate` and `--walk-reflogs`.
>
> -* `email`
> -
> -	  From <hash> <date>
> -	  From: <author>
> -	  Date: <author-date>
> -	  Subject: [PATCH] <title-line>
> +`email`::
> ++
> +[synopsis]
> +--
> +From <hash> <date>
> +From: <author>
> +Date: <author-date>
> +Subject: [PATCH] <title-line>
>
> -	  <full-commit-message>
> +<full-commit-message>
> +--

Good.

>
> -* `mboxrd`
> -+
> +`mboxrd`::
>  Like `email`, but lines in the commit message starting with "From "
>  (preceded by zero or more ">") are quoted with ">" so they aren't
>  confused as starting a new commit.

Good.

>
> -* `raw`
> -+
> +`raw`::
>  The `raw` format shows the entire commit exactly as
>  stored in the commit object.  Notably, the hashes are
>  displayed in full, regardless of whether `--abbrev` or
> @@ -101,8 +120,7 @@ commits are displayed, but not the way the diff is
> shown e.g. with
>  `git log --raw`. To get full object names in a raw diff format,
>  use `--no-abbrev`.
>
> -* `format:<format-string>`
> -+
> +`format:<format-string>`::
>  The `format:<format-string>` format allows you to specify which
> information
>  you want to show. It works a little bit like printf format,
>  with the notable exception that you get a newline with `%n`

All good.

> @@ -120,13 +138,18 @@ The title was >>t4119: test autocomputing -p<n>
> for traditional diff input.<<
>  The placeholders are:
>
>  - Placeholders that expand to a single literal character:
> ++
> +--
>  ++%n++:: newline
>  ++%%++:: a raw ++%++
>  ++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a
>  	 byte with the hexadecimal digits' value (we will call this
>  	 "literal formatting code" in the rest of this document).
> +--
>
>  - Placeholders that affect formatting of later placeholders:
> ++
> +--
>  ++%Cred++:: switch color to red
>  ++%Cgreen++:: switch color to green
>  ++%Cblue++:: switch color to blue

Good.

> @@ -181,8 +204,11 @@ The placeholders are:
>  ++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
>  			  respectively, but padding both sides
>  			  (i.e. the text is centered)
> +--
>
>  - Placeholders that expand to information extracted from the commit:
> ++
> +--
>  +%H+:: commit hash
>  +%h+:: abbreviated commit hash
>  +%T+:: tree hash
> @@ -233,20 +259,18 @@ colon and zero or more comma-separated options.
> Option values may contain
>  literal formatting codes. These must be used for commas (`%x2C`) and
> closing
>  parentheses (`%x29`), due to their role in the option syntax.
>
> -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> "{nbsp}++(++".
> -** `suffix=<value>`: Shown after the list of ref names.  Defaults to
> "+)+".
> -** `separator=<value>`: Shown between ref names.  Defaults to
> "+,+{nbsp}".

These are rendered serviceably.

> -** `pointer=<value>`: Shown between HEAD and the branch it points to,
> if any.
> -		      Defaults to "{nbsp}++->++{nbsp}".

This one is just `->` but it’s a bit confusing:

    " -> ".

(the spaces may be more narrow in the HTML?)

And the `-` has verbatim typeface while `>` does not.

I said the preceding ones were serviceable in the sense that they don’t
look great but you see what they are. This one is questionable.

> -** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> +`prefix=<value>`;; Shown before the list of ref names.  Defaults to
> "{nbsp}++(++".
> +`suffix=<value>`;; Shown after the list of ref names.  Defaults to
> "+)+".
> +`separator=<value>`;; Shown between ref names.  Defaults to
> "+,+{nbsp}".
> +`pointer=<value>`;; Shown between HEAD and the branch it points to, if
> any.
> +	      Defaults to "{nbsp}++->++{nbsp}".
> +`tag=<value>`;; Shown before tag names. Defaults to "`tag:`{nbsp}".

Here I feel some deja vu.

>
>  +
> ---
>  For example, to produce decorations with no wrapping
>  or tag annotations, and spaces as separators:
> -
> ++
>  ++%(decorate:prefix=,suffix=,tag=,separator= )++
> ---

Here is a a problem. The pluses in `++...++` are apparently markup. But
the line starts with `+%` here:

    + %(decorate:prefix=,suffix=,tag=,separator= )

>
>  ++%(describe++`[:<option>,...]`++)++::
>  human-readable name, like linkgit:git-describe[1]; empty string for
> @@ -254,15 +278,15 @@ undescribable commits.  The `describe` string may
> be followed by a colon and
>  zero or more comma-separated options.  Descriptions can be
> inconsistent when
>  tags are added or removed at the same time.
>  +
> -** `tags[=<bool-value>]`: Instead of only considering annotated tags,
> +`tags[=<bool-value>]`;; Instead of only considering annotated tags,
>     consider lightweight tags as well.
> -** `abbrev=<number>`: Instead of using the default number of
> hexadecimal digits
> +`abbrev=<number>`;; Instead of using the default number of hexadecimal
> digits
>     (which will vary according to the number of objects in the
> repository with a
>     default of 7) of the abbreviated object name, use <number> digits,

Need an edit here: s/<number>/_<number>_/

> or as many
>     digits as needed to form a unique object name.
> -** `match=<pattern>`: Only consider tags matching the given
> +`match=<pattern>`;; Only consider tags matching the given
>     `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
> -** `exclude=<pattern>`: Do not consider tags matching the given
> +`exclude=<pattern>`;; Do not consider tags matching the given
>     `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.

Good.

>
>  +%S+:: ref name given on the command line by which the commit was
> reached
> @@ -311,7 +335,7 @@ linkgit:git-interpret-trailers[1]. The `trailers`
> string may be followed by
>  a colon and zero or more comma-separated options. If any option is
> provided
>  multiple times, the last occurrence wins.
>  +
> -** `key=<key>`: only show trailers with specified <key>. Matching is
> done
> +`key=<key>`;; only show trailers with specified <key>. Matching is done
>     case-insensitively and trailing colon is optional. If option is
>     given multiple times trailer lines matching any of the keys are
>     shown. This option automatically enables the `only` option so that
> @@ -319,21 +343,21 @@ multiple times, the last occurrence wins.
>     desired it can be disabled with `only=false`.  E.g.,
>     +%(trailers:key=Reviewed-by)+ shows trailer lines with key
>     `Reviewed-by`.
> -** `only[=<bool>]`: select whether non-trailer lines from the trailer
> +`only[=<bool>]`;; select whether non-trailer lines from the trailer
>     block should be included.
> -** `separator=<sep>`: specify the separator inserted between trailer
> + `separator=<sep>`;; specify the separator inserted between trailer
>     lines. Defaults to a line feed character. The string <sep> may
> contain
>     the literal formatting codes described above. To use comma as
>     separator one must use `%x2C` as it would otherwise be parsed as
>     next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+
> -   shows all trailer lines whose key is "Ticket" separated by a comma
> +   shows all trailer lines whose key is `Ticket` separated by a comma
>     and a space.
> -** `unfold[=<bool>]`: make it behave as if interpret-trailer's
> `--unfold`
> +`unfold[=<bool>]`;; make it behave as if interpret-trailer's `--unfold`
>     option was given. E.g.,
>     +%(trailers:only,unfold=true)+ unfolds and shows all trailer lines.
> -** `keyonly[=<bool>]`: only show the key part of the trailer.
> -** `valueonly[=<bool>]`: only show the value part of the trailer.
> -** `key_value_separator=<sep>`: specify the separator inserted between
> +`keyonly[=<bool>]`;; only show the key part of the trailer.
> +`valueonly[=<bool>]`;; only show the value part of the trailer.
> +`key_value_separator=<sep>`;; specify the separator inserted between
>     the key and value of each trailer. Defaults to ": ". Otherwise it
>     shares the same semantics as `separator=<sep>` above.

All of this looks good.

>
> @@ -360,9 +384,9 @@ placeholder expands to an empty string.
>  If you add a `' '` (space) after +%+ of a placeholder, a space
>  is inserted immediately before the expansion if and only if the
>  placeholder expands to a non-empty string.
> +--
>
> -* `tformat:`
> -+
> +`tformat:`::
>  The `tformat:` format works exactly like `format:`, except that it
>  provides "terminator" semantics instead of "separator" semantics. In
>  other words, each commit has the message terminator character (usually a

Good.

> --
> gitgitgadget