From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Sun, 25 Jan 2026 19:27:38 GMT
Subject: Re: [PATCH 4/4] doc: convert git-show to synopsis style
Message-ID: <51016c02-40de-431f-a4ba-e08cb1bb8235@app.fastmail.com>
In-Reply-To: <d078e1d94fcf8511743787623f0c1abfd0321849.1769202903.git.gitgitgadget@gmail.com>

On Fri, Jan 23, 2026, at 22:15, 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

This is for e.g. ``<hash> <title-line>`` it looks like. Is the intent to
use italics on placeholders like `<hash>`?

>  * convert commands to synopsis style
>  * use _<placeholder>_ for arguments
>  * minor formatting fixes
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  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
> index ff9ea0a294..31b883a72c 100644
> --- 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>...]

Looks good.

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

Good.

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

Again replacing (') with (`). Looks good.

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

Same here.

It could be nice to s/`git log` command/linkgit:git-log[1]/ either on
this commit or in a separate one.

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

Looks correct in the HTML output.

>  	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..5b73f03433 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>
> +`oneline`::
> ++
> +[synopsis]
> +--
> +`<hash> <title-line>`
> +--

HTML looks wrong in git-show(1) and others that include it. Something
like this:

    oneline
        __<hash>__ __<title-line>__

This doesn’t happen when I run asciidoc(1) or asciidoctor(1) directly.

>  +
>  This is designed to be as compact as possible.
>
> -* `short`
> -
> -	  commit <hash>
> -	  Author: <author>
> -
> -	      <title-line>
> -
> -* `medium`
> -
> -	  commit <hash>
> -	  Author: <author>
> -	  Date:   <author-date>
> -
> -	      <title-line>
> +`short`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
>
> -	      <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>)
> +--

(For these pretty formats) The diff got confused I think but the
conversion looks correct.


>  +
>  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 changed in this patch but this doesn’t render correctly for me. It’s
not inline verbatim/code all the way through. But it is correct if I
remove the `\`.

I don’t know why `++` was used either.

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

By the way. It renders with nice italic for placeholders. Again back to
the presumed point of these `[synopsis]` blocks.

>
> -* `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.
>
> -* `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`
> @@ -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:
> ++
> +--

The HTML structure here is correct.

>  ++%Cred++:: switch color to red
>  ++%Cgreen++:: switch color to green
>  ++%Cblue++:: switch color to blue
> @@ -181,8 +204,11 @@ The placeholders are:
>  ++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
>  			 erespectively, 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,36 +259,34 @@ 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.

This looks correct just looking quickly over.

>
> -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> "{nbsp}++(++".

All of these use the "(" style which doesn’t look good in my
opinion. But I’m guessing it has to do with some of them using spaces in
them and `"` being used as a boundary.

> -** `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}".
> +`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}".
>
>  +
> ---
>  For example, to produce decorations with no wrapping
>  or tag annotations, and spaces as separators:
> -
> ++
>  ++%(decorate:prefix=,suffix=,tag=,separator= )++
> ---
>
> -++%(describe++`[:<option>,...]`++)++::
> +++%(`describe++``[:<option>,...]`++)++::

This renders with backticks in HTML:

    %(describe++`[:<option>,...]`)++

>  human-readable name, like linkgit:git-describe[1]; empty string for
>  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,
> 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.
>
>  +%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

Might as well s/"Ticket"/`Ticket`/ ?

>     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.
>
> @@ -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
> --
> gitgitgadget

The rest looks okay.