git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v4 0/2] doc: format-rev: use [synopsis] on code block

From
Kkristofferhaugsbakk@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 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 `"<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
Previous: Junio C HamanoNext: kristofferhaugsbakk@fastmail.com
Message 18 of 21 in “doc: format-rev: use [synopsis] on code block”
  1. doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  2. doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 10, 2026
  3. Patrick SteinhardtAug 11, 2026
  4. Kristoffer HaugsbakkAug 11, 2026
  5. Patrick SteinhardtAug 11, 2026
  6. Kristoffer HaugsbakkAug 11, 2026
  7. Kristoffer HaugsbakkAug 11, 2026
  8. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  9. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  10. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  11. Patrick SteinhardtAug 13, 2026
  12. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  13. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  14. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  15. Junio C HamanoAug 14, 2026
  16. Kristoffer HaugsbakkAug 14, 2026
  17. Junio C HamanoAug 14, 2026
  18. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  19. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  20. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  21. Junio C HamanoAug 17, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.