Re: [PATCH] doc: patch-id: convert to the modern synopsis style

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> Convert this command documentation to the modern synopsis style based on
> similar work.[1] Concretely:
> 
> • Change the Synopsis section from `verse` to a `synopsis` block which
>   will automatically apply the correct formatting to various elements
>   (although this Synopsis is very simple)
> • Use backticks (`) for code-like things which will also use the correct
>   formatting for interior placeholders (`<orderfile>`)
> • Use backticks on options
> 
> † 1: E.g.,
>      • 026f2e3b (doc: convert git-log to new documentation format,
>        2025-07-07)
>      • b983aaab (doc: convert git-switch manpage to new synopsis style,
>        2025-05-25)
>      • 16543967 (doc: convert git-mergetool manpage to new synopsis
>        style, 2025-05-25)
> 
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
> 
> Notes (series):
>     Topic name: kh/patch-id-doc-part-one
>     
>     Topic summary: The documentation for "git patch-id" has been converted
>     to the modern "synopsis" style.
>     
>     Update git-patch-id(1) to the new synopsis style.  This is done based on
>     observing what Jean-Noël Avila has done on other documentation pages.
>     
>     I don’t know what high-level plans Jean-Noël and the maintainer have for
>     the rewrite so I don’t know if posting this update is somehow
>     inappropriate in light of that.
>     
>     § Notes to the maintainer[1]
>     
>     This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
>     patch-id: fix accidental literal blocks, 2025-09-29) merged into
>     v2.50.0 (because that’s what the topic is based on).
>     
>     (is there a “reference” convention for mentioning a topic + commit?)
>     
>       † 1: Inspired by
>            • <cover.1759097191.git.me@ttaylorr.com>
>            • SubmittingPatches: guidance for topic names and multi-series efforts
>              • <cover.1759873165.git.me@ttaylorr.com>
>     
>     This is part one of a multi-series effort focusing on this
>     documentation page. Technically that intent started with topic
>     kh/doc-patch-id-markup-fix, but I published that before I learned
>     about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
>     So this gets named “part one” in the cover letter (and maybe on the
>     topic name).
>     
>     The current plan for parts 2–5:
>     
>     2. Various smaller fixups (many small patches/commits)
>     3. Mention the two config variables in git-config(1)
>     4. Make it more clear that you can feed multiple diffs to this command
>     5. An “Examples” section
>     
>     Why a multi-part series?  It started with the idea of (1) emphasizing
>     that this command can take multiple patches, and (2) making an
>     Examples. But then I saw other things to fix. And they ought to go
>     first... eventually I ended up with many commits or ideas.
>     
>     I wanted to see if this was easier to review.
>     
>     • Focus on uncontroversial changes first
>     • Make all the series either small, simple/trivial, or both
>     • Leave the changes that might spark discussion last; the ones that have
>       to do with authoring new paragraphs/sections
>     
>     (I realize that multi-part series are probably mostly used for
>     super-technical changes that take 50+ patches in total and that only
>     three people on the list have the time and capacity to review at any
>     given point in time.)
> 
>  Documentation/git-patch-id.adoc | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
> index 45da0f27acd..bfbf23f49c4 100644
> --- a/Documentation/git-patch-id.adoc
> +++ b/Documentation/git-patch-id.adoc
> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
>  
>  SYNOPSIS
>  --------
> -[verse]
> -'git patch-id' [--stable | --unstable | --verbatim]
> +[synopsis]
> +git patch-id [--stable | --unstable | --verbatim]
>  
>  DESCRIPTION
>  -----------
> @@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same
>  
>  The main usecase for this command is to look for likely duplicate commits.
>  
> -When dealing with 'git diff-tree' output, it takes advantage of
> +When dealing with `git diff-tree` output, it takes advantage of
>  the fact that the patch is prefixed with the object name of the
>  commit, and outputs two 40-byte hexadecimal strings.  The first
>  string is the patch ID, and the second string is the commit ID.
> @@ -30,19 +30,19 @@ This can be used to make a mapping from patch ID to commit ID.
>  OPTIONS
>  -------
>  
> ---verbatim::
> +`--verbatim`::
>  	Calculate the patch-id of the input as it is given, do not strip
>  	any whitespace.
>  +
>  This is the default if patchid.verbatim is true.

>  
> ---stable::
> +`--stable`::
>  	Use a "stable" sum of hashes as the patch ID. With this option:
>  +
>  --
>  - Reordering file diffs that make up a patch does not affect the ID.
>    In particular, two patches produced by comparing the same two trees
> -  with two different settings for "-O<orderfile>" result in the same
> +  with two different settings for `-O<orderfile>` result in the same
>    patch ID signature, thereby allowing the computed result to be used
>    as a key to index some meta-information about the change between
>    the two trees;
> @@ -50,7 +50,7 @@ This is the default if patchid.verbatim is true.
>  - Result is different from the value produced by git 1.9 and older
>    or produced when an "unstable" hash (see --unstable below) is

>    configured - even when used on a diff output taken without any use
> -  of "-O<orderfile>", thereby making existing databases storing such
> +  of `-O<orderfile>", thereby making existing databases storing such
>    "unstable" or historical patch-ids unusable.
>  
>  - All whitespace within the patch is ignored and does not affect the id.
> @@ -58,7 +58,7 @@ This is the default if patchid.verbatim is true.
>  +
>  This is the default if patchid.stable is set to true.

>  
> ---unstable::
> +`--unstable`::
>  	Use an "unstable" hash as the patch ID. With this option,
>  	the result produced is compatible with the patch-id value produced
>  	by git 1.9 and older and whitespace is ignored.  Users with pre-existing