From: kristofferhaugsbakk@fastmail.com Date: Thu, 13 Aug 2026 09:57:34 GMT Subject: [PATCH v2 0/2] doc: format-rev: use [synopsis] on code block Message-ID: In-Reply-To: From: Kristoffer Haugsbakk 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/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#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 `` without any termination. Like this: +formatted commit, i.e. the format `"%s"` would transform some commit +object name to `""` 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 ## 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 `` without any termination. Like this: + formatted commit, i.e. the format `"%s"` would transform some commit + object name to `""` without any termination. Like this: +[synopsis] ---- base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc -- 2.54.0.22.g9e26862b904