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

[kristofferhaugsbakk@fastmail.com]

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
-- 
2.51.0.352.g356bc2d8d49