[PATCH v4 2/2] doc: format-rev: use [synopsis] on code block
- From
- kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
- Date
- Aug 17, 2026, 18:51 UTC
- Message-ID
- <V4_synopsis_block.b90@msgid.xyz>
- In-Reply-To
- <V4_CV_synopsis_block.b8e@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
This code block uses the placeholder `<subject>`. Let’s highlight this 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 open 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 <code@khaugsbakk.name> ---
Notes (series):
v4:
• 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/xmqqfr0hqzvl.fsf@gitster.g/
• Msg: Rewrite or flesh out the message to reflect this newfound
knowledge
• Remove Ack from the previous round since I had to make these
changes
---
v3: add Ack: https://lore.kernel.org/git/an2Wwe4ytilGoyHz@pks.im/
v2:
• Add a paragraph to contrast synopsis code blocks with synopsis
command description after talk with Patrick on v1[1]
🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/Documentation/git-format-rev.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc index 19241837345..c2268c92b56 100644 --- a/Documentation/git-format-rev.adoc +++ b/Documentation/git-format-rev.adoc @@ -96,9 +96,10 @@ 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: ----- +[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.
-- 2.55.0.13.g85d2d65e389