From: kristofferhaugsbakk@fastmail.com Date: Mon, 17 Aug 2026 18:51:47 GMT Subject: [PATCH v4 0/2] doc: format-rev: use [synopsis] on code block Message-ID: In-Reply-To: From: Kristoffer Haugsbakk 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/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 `""` without any termination. Like this: [synopsis] ----- +-- Did we not fix this in ""? ----- +-- 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 ``. 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 Signed-off-by: Kristoffer Haugsbakk ## 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 `""` without any termination. Like this: +----- +[synopsis] - ---- ++-- Did we not fix this in ""? - ---- +----- ++-- + + 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