[PATCH v4 0/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_CV_synopsis_block.b8e@msgid.xyz>
- In-Reply-To
- <synopsis_block.af9@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 docAnd they didn’t give any warnings. And they produced the correct result.
🔗 1: https://lore.kernel.org/git/xmqqfr0hqzvl.fsf@gitster.g/
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/V3_CV_synopsis_block.b64@msgid.xyz/
[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:
diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc index d6c2e4aec1a..c2268c92b56 100644 --- a/Documentation/git-format-rev.adoc +++ b/Documentation/git-format-rev.adoc @@ -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 <ps@pks.im> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> ## 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