doc: format-rev: use [synopsis] on code block

From: Kristoffer Haugsbakk <[email protected]>

Topic name (applied): kh/format-rev-doc-synopsis

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

§ Changes in v4

Sorry about not reading carefully. An open block is not a code block.

(copied from the patch note)

Fix block: use open block, not code block.[1] This is what was done for the synopsis blocks in commit a34d1d53, the commit mentioned here. I have tested this with what I believe are the use-asciidoc (tool) and use-asciidoctor (tool):

make doc
make USE_ASCIIDOCTOR=1 doc

And they didn’t give any warnings. And they produced the correct result.

🔗 1: https://lore.kernel.org/git/[email protected]/

Rewrite or flesh out the commit message to reflect this newfound knowledge.

Also remove the Ack since this change invalidates it.

§ Cc

(See v2)

§ Link to v3

https://lore.kernel.org/git/[email protected]/

[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 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

Interdiff against v3:

index d6c2e4aec1a..c2268c92b56 100644
@@ -97,9 +97,9 @@ formatted commit, i.e. the format `"%s"` would transform some commit
 object name to `"<subject>"` without any termination. Like this:
 
 [synopsis]
-----
+--
 Did we not fix this in "<subject>"?
-----
+--
 
 It is safe to interactively read and write from this command since each
 record is immediately flushed.

Range-diff against v3:

1:  c82aec7969f = 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after
2:  b9a93c83c88 ! 2:  16d7bea804a doc: format-rev: use [synopsis] on code block

@@ Commit message
doc: format-rev: use [synopsis] on code block

This code block uses the placeholder <subject>. Let’s highlight this
- placeholder properly by using the synopsis block definition which was
- introduced in a34d1d53 (doc: convert git-show to synopsis style,
- 2026-02-06).
+ placeholder properly by using the synopsis open block definition which
+ was introduced in a34d1d53 (doc: convert git-show to synopsis style,
+ 2026-02-06). This renders the block like a code block but with emphasis
+ styling on placeholders, just like inline-verbatim (`) in running text.

- Yes, note that code blocks since commit a34d1d53 can, on synopsis-style
+ Yes, note that open blocks since commit a34d1d53 can, on synopsis-style
docs like this one, be immediately preceded by [synopsis], just like the command synopsis is:

@@ Commit message
[verse]
'git name-rev' [...]

- Acked-by: Patrick Steinhardt <[email protected]>

## Documentation/git-format-rev.adoc ##
@@ Documentation/git-format-rev.adoc: The mode --stdin-mode=text replaces each ob
formatted commit, i.e. the format "%s" would transform some commit object name to "<subject>" without any termination. Like this:

+-----
+[synopsis]
- ----
++--
Did we not fix this in "<subject>"?
- ----
+-----
++--
+
+ It is safe to interactively read and write from this command since each
+ record is immediately flushed.

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc

2.55.0.13.g85d2d65e389