[PATCH v2 0/2] doc: format-rev: use [synopsis] on code block

From: Kristoffer Haugsbakk <[email protected]>

Topic name: kh/doc-format-rev-1

Topic summary: Use '[synopsis]' on code block in order to highlight
placeholder properly. Also quote the subject consistently.

§ Changes in v2

See the patches themselves for details.

• Patch 1/2: New; see “Well.”: https://lore.kernel.org/git/[email protected]/#t
• Patch 2/2: Add a new commit message paragraph to avoid confusion on
  `[synopsis]` on-command vs. on-code-block

§ Cc

I’ve added a soft Cc (?) on Jean-Noël Avila because I added more
“technical” discussion to the commit message. Hopefully it is formulated
correctly.

[1/2] doc: format-rev: quote subject placeholder before and after
[2/2] doc: format-rev: use [synopsis] on code block

 Documentation/git-format-rev.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 836ba4b0c24..d6c2e4aec1a 100644
--- a/Documentation/git-format-rev.adoc
+++ b/Documentation/git-format-rev.adoc
@@ -93,8 +93,8 @@ acts as a _terminator_, not a _separator_. In other words, the final
 line or record is also terminated by the terminator character.
 
 The mode `--stdin-mode=text` replaces each object name with the
-formatted commit, i.e. the format `%s` would transform some commit
-object name to `<subject>` without any termination. Like this:
+formatted commit, i.e. the format `"%s"` would transform some commit
+object name to `"<subject>"` without any termination. Like this:
 
 [synopsis]
 ----
Range-diff against v1:
-:  ----------- > 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after
1:  652198740e3 ! 2:  f528d7e9dcd doc: format-rev: use [synopsis] on code block
    @@ Commit message
         introduced in a34d1d53 (doc: convert git-show to synopsis style,
         2026-02-06).
     
    +    Yes, note that code blocks since commit a34d1d53 can, on synopsis-style
    +    docs like this one, be immediately preceded by `[synopsis]`, just like
    +    the command synopsis is:
    +
    +        [synopsis]
    +        (EXPERIMENTAL!) git format-rev - [...]
    +
    +    Cf. verse-style:
    +
    +        [verse]
    +        'git name-rev' [...]
    +
         Signed-off-by: Kristoffer Haugsbakk <[email protected]>
     
      ## Documentation/git-format-rev.adoc ##
     @@ Documentation/git-format-rev.adoc: The mode `--stdin-mode=text` replaces each object name with the
    - formatted commit, i.e. the format `%s` would transform some commit
    - object name to `<subject>` without any termination. Like this:
    + formatted commit, i.e. the format `"%s"` would transform some commit
    + object name to `"<subject>"` without any termination. Like this:
      
     +[synopsis]
      ----

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
-- 
2.54.0.22.g9e26862b904