{"thread":{"id":"66090","subject":"[PATCH] doc: format-rev: use [synopsis] on code block","startedAt":"2026-07-30T12:03:31Z","lastAt":"2026-08-17T21:46:56Z","messageCount":21,"participants":["kristofferhaugsbakk@fastmail.com","Patrick Steinhardt","Kristoffer Haugsbakk","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"549296","messageId":"synopsis_block.af9@msgid.xyz","threadId":"66090","inReplyTo":null,"subject":"[PATCH] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T12:02:55Z","receivedAt":"2026-07-30T12:03:31Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThis code block uses the placeholder `<subject>`. Let’s highlight this\nplaceholder properly by using the `synopsis` block definition which was\nintroduced in a34d1d53 (doc: convert git-show to synopsis style,\n2026-02-06).\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    Topic name: kh/doc-format-rev-1\n\n Documentation/git-format-rev.adoc | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 505a52feccd..836ba4b0c24 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n formatted commit, i.e. the format `%s` would transform some commit\n object name to `<subject>` without any termination. Like this:\n \n+[synopsis]\n ----\n Did we not fix this in \"<subject>\"?\n ----\n\nbase-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550201","messageId":"synopsis_block.b37@msgid.xyz","threadId":"66090","inReplyTo":"synopsis_block.af9@msgid.xyz","subject":"[PATCH resend] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-10T16:58:05Z","receivedAt":"2026-08-10T16:58:36Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThis code block uses the placeholder `<subject>`. Let’s highlight this\nplaceholder properly by using the `synopsis` block definition which was\nintroduced in a34d1d53 (doc: convert git-show to synopsis style,\n2026-02-06).\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    Topic name: kh/doc-format-rev-1\n\n Documentation/git-format-rev.adoc | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 505a52feccd..836ba4b0c24 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n formatted commit, i.e. the format `%s` would transform some commit\n object name to `<subject>` without any termination. Like this:\n \n+[synopsis]\n ----\n Did we not fix this in \"<subject>\"?\n ----\n\nbase-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550283","messageId":"ansWZxZ6lB0tYIJD@pks.im","threadId":"66090","inReplyTo":"synopsis_block.b37@msgid.xyz","subject":"Re: [PATCH resend] doc: format-rev: use [synopsis] on code block","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-11T12:32:39Z","receivedAt":"2026-08-11T12:32:47Z","isPatch":true,"body":"On Mon, Aug 10, 2026 at 06:58:05PM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n> \n> This code block uses the placeholder `<subject>`. Let’s highlight this\n> placeholder properly by using the `synopsis` block definition which was\n> introduced in a34d1d53 (doc: convert git-show to synopsis style,\n> 2026-02-06).\n\nI'm not particularly knowledgeable in AsciiDoc, I only picked it up\nbecause nobody else did. So please consider me even more clueless than I\ntypically am :)\n\n> diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\n> index 505a52feccd..836ba4b0c24 100644\n> --- a/Documentation/git-format-rev.adoc\n> +++ b/Documentation/git-format-rev.adoc\n> @@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n>  formatted commit, i.e. the format `%s` would transform some commit\n>  object name to `<subject>` without any termination. Like this:\n>  \n> +[synopsis]\n>  ----\n>  Did we not fix this in \"<subject>\"?\n>  ----\n\nHm. I was always under the impression that `[synopsis]` is used as\nexactly that, so it surprises me a bit that you want to use it for a\nrandom block that doesn't look like one at all. But going through our\ndocs (like for example git-blame(1)) I see that we also do this for\nother non-synopsis-like blocks, so maybe this is fine?\n\nThere's probably a good reason for this, but can't we instead just use\nbackticks to make `<subject>` render the exact same as four lines above?\n\nThanks!\n\nPatrick\n"},{"id":"550294","messageId":"a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com","threadId":"66090","inReplyTo":"ansWZxZ6lB0tYIJD@pks.im","subject":"Re: [PATCH resend] doc: format-rev: use [synopsis] on code block","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-11T16:23:18Z","receivedAt":"2026-08-11T16:23:43Z","isPatch":true,"body":"On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:\n> On Mon, Aug 10, 2026 at 06:58:05PM +0200,\n> kristofferhaugsbakk@fastmail.com wrote:\n>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n>>\n>> This code block uses the placeholder `<subject>`. Let’s highlight this\n>> placeholder properly by using the `synopsis` block definition which was\n>> introduced in a34d1d53 (doc: convert git-show to synopsis style,\n>> 2026-02-06).\n>\n> I'm not particularly knowledgeable in AsciiDoc, I only picked it up\n> because nobody else did. So please consider me even more clueless than I\n> typically am :)\n\nThanks for taking a look.\n\n>\n>> diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\n>> index 505a52feccd..836ba4b0c24 100644\n>> --- a/Documentation/git-format-rev.adoc\n>> +++ b/Documentation/git-format-rev.adoc\n>> @@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n>>  formatted commit, i.e. the format `%s` would transform some commit\n>>  object name to `<subject>` without any termination. Like this:\n>>\n>> +[synopsis]\n>>  ----\n>>  Did we not fix this in \"<subject>\"?\n>>  ----\n>\n> Hm. I was always under the impression that `[synopsis]` is used as\n> exactly that, so it surprises me a bit that you want to use it for a\n> random block that doesn't look like one at all. But going through our\n> docs (like for example git-blame(1)) I see that we also do this for\n> other non-synopsis-like blocks, so maybe this is fine?\n\nTo be clear, it’s not this kind of [synopsis]:\n\n    [synopsis]\n    git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]\n\nThis [synopsis] is for a code block to highlight <subject> just like how\n<subject> is highlighted in running text when using (_) or (`).\n\n> There's probably a good reason for this, but can't we instead just use\n> backticks to make `<subject>` render the exact same as four lines above?\n\nIt’s a code block and the literal text is supposed to use quotation\nmarks.\n\nWell. I wrote the text to mean that subject is supposed to be quoted. So\nperhaps I should have written `\"%s\"` instead of `\"%s\"`:\n\n     i.e. the format `\"%s\"` would transform some commit object name to\n     `\"<subject>\"` without any termination. Like this: ...\n\n;-)\n"},{"id":"550296","messageId":"antNhDECvV5Kynsy@pks.im","threadId":"66090","inReplyTo":"a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com","subject":"Re: [PATCH resend] doc: format-rev: use [synopsis] on code block","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-11T16:27:48Z","receivedAt":"2026-08-11T16:27:54Z","isPatch":true,"body":"On Tue, Aug 11, 2026 at 06:23:18PM +0200, Kristoffer Haugsbakk wrote:\n> On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:\n> > On Mon, Aug 10, 2026 at 06:58:05PM +0200,\n> > kristofferhaugsbakk@fastmail.com wrote:\n> >> diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\n> >> index 505a52feccd..836ba4b0c24 100644\n> >> --- a/Documentation/git-format-rev.adoc\n> >> +++ b/Documentation/git-format-rev.adoc\n> >> @@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n> >>  formatted commit, i.e. the format `%s` would transform some commit\n> >>  object name to `<subject>` without any termination. Like this:\n> >>\n> >> +[synopsis]\n> >>  ----\n> >>  Did we not fix this in \"<subject>\"?\n> >>  ----\n> >\n> > Hm. I was always under the impression that `[synopsis]` is used as\n> > exactly that, so it surprises me a bit that you want to use it for a\n> > random block that doesn't look like one at all. But going through our\n> > docs (like for example git-blame(1)) I see that we also do this for\n> > other non-synopsis-like blocks, so maybe this is fine?\n> \n> To be clear, it’s not this kind of [synopsis]:\n> \n>     [synopsis]\n>     git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]\n> \n> This [synopsis] is for a code block to highlight <subject> just like how\n> <subject> is highlighted in running text when using (_) or (`).\n\nAh, so we have different kinds of synopsis depending on what it applies\nto?\n\n> > There's probably a good reason for this, but can't we instead just use\n> > backticks to make `<subject>` render the exact same as four lines above?\n> \n> It’s a code block and the literal text is supposed to use quotation\n> marks.\n> \n> Well. I wrote the text to mean that subject is supposed to be quoted. So\n> perhaps I should have written `\"%s\"` instead of `\"%s\"`:\n> \n>      i.e. the format `\"%s\"` would transform some commit object name to\n>      `\"<subject>\"` without any termination. Like this: ...\n\nMakes sense, thanks!\n\nPatrick\n"},{"id":"550297","messageId":"d81d6e3a-8489-4aba-ac1b-d678daac5ee3@app.fastmail.com","threadId":"66090","inReplyTo":"antNhDECvV5Kynsy@pks.im","subject":"Re: [PATCH resend] doc: format-rev: use [synopsis] on code block","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-11T16:30:35Z","receivedAt":"2026-08-11T16:31:00Z","isPatch":true,"body":"On Tue, Aug 11, 2026, at 18:27, Patrick Steinhardt wrote:\n> On Tue, Aug 11, 2026 at 06:23:18PM +0200, Kristoffer Haugsbakk wrote:\n>> On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:\n>>>[snip]\n>> <subject> is highlighted in running text when using (_) or (`).\n>\n> Ah, so we have different kinds of synopsis depending on what it applies\n> to?\n\nYeah, that must be it. To be honest I had neglected to consider that the\ncommand description part uses the same syntax already... x)\n\n>>[snip]\n>>\n>>      i.e. the format `\"%s\"` would transform some commit object name to\n>>      `\"<subject>\"` without any termination. Like this: ...\n>\n> Makes sense, thanks!\n\nThank you.\n"},{"id":"550324","messageId":"9270d916-2673-4041-be18-92fc0306903b@app.fastmail.com","threadId":"66090","inReplyTo":"a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com","subject":"Re: [PATCH resend] doc: format-rev: use [synopsis] on code block","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-11T19:38:53Z","receivedAt":"2026-08-11T19:39:32Z","isPatch":true,"body":"On Tue, Aug 11, 2026, at 18:23, Kristoffer Haugsbakk wrote:\n>[snip]\n> Well. I wrote the text to mean that subject is supposed to be quoted. So\n> perhaps I should have written `\"%s\"` instead of `\"%s\"`:\n>\n>      i.e. the format `\"%s\"` would transform some commit object name to\n>      `\"<subject>\"` without any termination. Like this: ...\n>\n> ;-)\n\nI might do a re-roll with a change to use \"\". I’ll see how\nit looks first.\n"},{"id":"550490","messageId":"V2_CV_synopsis_block.b4a@msgid.xyz","threadId":"66090","inReplyTo":"synopsis_block.af9@msgid.xyz","subject":"[PATCH v2 0/2] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T09:57:34Z","receivedAt":"2026-08-13T09:57:55Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nTopic name: kh/doc-format-rev-1\n\nTopic summary: Use '[synopsis]' on code block in order to highlight\nplaceholder properly. Also quote the subject consistently.\n\n§ Changes in v2\n\nSee the patches themselves for details.\n\n• Patch 1/2: New; see “Well.”: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t\n• Patch 2/2: Add a new commit message paragraph to avoid confusion on\n  `[synopsis]` on-command vs. on-code-block\n\n§ Cc\n\nI’ve added a soft Cc (?) on Jean-Noël Avila because I added more\n“technical” discussion to the commit message. Hopefully it is formulated\ncorrectly.\n\n[1/2] doc: format-rev: quote subject placeholder before and after\n[2/2] doc: format-rev: use [synopsis] on code block\n\n Documentation/git-format-rev.adoc | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 836ba4b0c24..d6c2e4aec1a 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -93,8 +93,8 @@ acts as a _terminator_, not a _separator_. In other words, the final\n line or record is also terminated by the terminator character.\n \n The mode `--stdin-mode=text` replaces each object name with the\n-formatted commit, i.e. the format `%s` would transform some commit\n-object name to `<subject>` without any termination. Like this:\n+formatted commit, i.e. the format `\"%s\"` would transform some commit\n+object name to `\"<subject>\"` without any termination. Like this:\n \n [synopsis]\n ----\nRange-diff against v1:\n-:  ----------- > 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after\n1:  652198740e3 ! 2:  f528d7e9dcd doc: format-rev: use [synopsis] on code block\n    @@ Commit message\n         introduced in a34d1d53 (doc: convert git-show to synopsis style,\n         2026-02-06).\n     \n    +    Yes, note that code blocks since commit a34d1d53 can, on synopsis-style\n    +    docs like this one, be immediately preceded by `[synopsis]`, just like\n    +    the command synopsis is:\n    +\n    +        [synopsis]\n    +        (EXPERIMENTAL!) git format-rev - [...]\n    +\n    +    Cf. verse-style:\n    +\n    +        [verse]\n    +        'git name-rev' [...]\n    +\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n     \n      ## Documentation/git-format-rev.adoc ##\n     @@ Documentation/git-format-rev.adoc: The mode `--stdin-mode=text` replaces each object name with the\n    - formatted commit, i.e. the format `%s` would transform some commit\n    - object name to `<subject>` without any termination. Like this:\n    + formatted commit, i.e. the format `\"%s\"` would transform some commit\n    + object name to `\"<subject>\"` without any termination. Like this:\n      \n     +[synopsis]\n      ----\n\nbase-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550491","messageId":"V2_quote_subject.b4b@msgid.xyz","threadId":"66090","inReplyTo":"V2_CV_synopsis_block.b4a@msgid.xyz","subject":"[PATCH v2 1/2] doc: format-rev: quote subject placeholder before and after","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T09:57:35Z","receivedAt":"2026-08-13T09:58:14Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nWe first talk about just `%s`, but then show the result with\nquotes. That is inconsistent. Let’s use quotes both in the format\nas well as in the result.\n\nThe implied input here, which is not spelled out for brevity, is:\n\n    Did we not fix this in <commit object name>?\n\nWhich is then supposed to be formatted to `\"<subject>\"`.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v2:\n    • [new]\n    • I wanted to add this after spotting the problem in [1]\n      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t\n\n Documentation/git-format-rev.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 505a52feccd..19241837345 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -93,8 +93,8 @@ acts as a _terminator_, not a _separator_. In other words, the final\n line or record is also terminated by the terminator character.\n \n The mode `--stdin-mode=text` replaces each object name with the\n-formatted commit, i.e. the format `%s` would transform some commit\n-object name to `<subject>` without any termination. Like this:\n+formatted commit, i.e. the format `\"%s\"` would transform some commit\n+object name to `\"<subject>\"` without any termination. Like this:\n \n ----\n Did we not fix this in \"<subject>\"?\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550492","messageId":"V2_synopsis_block.b4c@msgid.xyz","threadId":"66090","inReplyTo":"V2_CV_synopsis_block.b4a@msgid.xyz","subject":"[PATCH v2 2/2] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T09:57:36Z","receivedAt":"2026-08-13T09:58:32Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThis code block uses the placeholder `<subject>`. Let’s highlight this\nplaceholder properly by using the `synopsis` block definition which was\nintroduced in a34d1d53 (doc: convert git-show to synopsis style,\n2026-02-06).\n\nYes, note that code blocks since commit a34d1d53 can, on synopsis-style\ndocs like this one, be immediately preceded by `[synopsis]`, just like\nthe command synopsis is:\n\n    [synopsis]\n    (EXPERIMENTAL!) git format-rev - [...]\n\nCf. verse-style:\n\n    [verse]\n    'git name-rev' [...]\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v2:\n    • Add a paragraph to contrast synopsis code blocks with synopsis\n      command description after talk with Patrick on v1[1]\n    \n      🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/\n\n Documentation/git-format-rev.adoc | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 19241837345..d6c2e4aec1a 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n formatted commit, i.e. the format `\"%s\"` would transform some commit\n object name to `\"<subject>\"` without any termination. Like this:\n \n+[synopsis]\n ----\n Did we not fix this in \"<subject>\"?\n ----\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550494","messageId":"an2Wwe4ytilGoyHz@pks.im","threadId":"66090","inReplyTo":"V2_synopsis_block.b4c@msgid.xyz","subject":"Re: [PATCH v2 2/2] doc: format-rev: use [synopsis] on code block","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-13T10:04:49Z","receivedAt":"2026-08-13T10:04:55Z","isPatch":true,"body":"On Thu, Aug 13, 2026 at 11:57:36AM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n> \n> This code block uses the placeholder `<subject>`. Let’s highlight this\n> placeholder properly by using the `synopsis` block definition which was\n> introduced in a34d1d53 (doc: convert git-show to synopsis style,\n> 2026-02-06).\n> \n> Yes, note that code blocks since commit a34d1d53 can, on synopsis-style\n> docs like this one, be immediately preceded by `[synopsis]`, just like\n> the command synopsis is:\n> \n>     [synopsis]\n>     (EXPERIMENTAL!) git format-rev - [...]\n> \n> Cf. verse-style:\n> \n>     [verse]\n>     'git name-rev' [...]\n\nThanks for the additional reference to the above commit. That helps, and\nyou can see that as part of the commit we have similar changes to our\ndocs like you do them in your patch.\n\nSo I'm happy with this version, thanks!\n\nPatrick\n"},{"id":"550507","messageId":"V3_CV_synopsis_block.b64@msgid.xyz","threadId":"66090","inReplyTo":"synopsis_block.af9@msgid.xyz","subject":"[PATCH v3 0/2] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T14:23:44Z","receivedAt":"2026-08-13T14:23:57Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nTopic name: kh/doc-format-rev-1\n\nTopic summary: Use '[synopsis]' on code block in order to highlight\nplaceholder properly. Also quote the subject consistently.\n\n§ Changes in v3\n\n• Patch 2/2: Add Ack\n\n§ Cc\n\n(See v2)\n\n§ Link to v2\n\nhttps://lore.kernel.org/git/V2_CV_synopsis_block.b4a@msgid.xyz/\n\n[1/2] doc: format-rev: quote subject placeholder before and after\n[2/2] doc: format-rev: use [synopsis] on code block\n\n Documentation/git-format-rev.adoc | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\nInterdiff against v2:\nRange-diff against v2:\n1:  c82aec7969f = 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after\n2:  f528d7e9dcd ! 2:  b9a93c83c88 doc: format-rev: use [synopsis] on code block\n    @@ Commit message\n             [verse]\n             'git name-rev' [...]\n     \n    +    Acked-by: Patrick Steinhardt <ps@pks.im>\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n     \n      ## Documentation/git-format-rev.adoc ##\n\nbase-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550508","messageId":"V3_quote_subject.b65@msgid.xyz","threadId":"66090","inReplyTo":"V3_CV_synopsis_block.b64@msgid.xyz","subject":"[PATCH v3 1/2] doc: format-rev: quote subject placeholder before and after","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T14:23:45Z","receivedAt":"2026-08-13T14:24:16Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nWe first talk about just `%s`, but then show the result with\nquotes. That is inconsistent. Let’s use quotes both in the format\nas well as in the result.\n\nThe implied input here, which is not spelled out for brevity, is:\n\n    Did we not fix this in <commit object name>?\n\nWhich is then supposed to be formatted to `\"<subject>\"`.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v2:\n    • [new]\n    • I wanted to add this after spotting the problem in [1]\n      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t\n\n Documentation/git-format-rev.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 505a52feccd..19241837345 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -93,8 +93,8 @@ acts as a _terminator_, not a _separator_. In other words, the final\n line or record is also terminated by the terminator character.\n \n The mode `--stdin-mode=text` replaces each object name with the\n-formatted commit, i.e. the format `%s` would transform some commit\n-object name to `<subject>` without any termination. Like this:\n+formatted commit, i.e. the format `\"%s\"` would transform some commit\n+object name to `\"<subject>\"` without any termination. Like this:\n \n ----\n Did we not fix this in \"<subject>\"?\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550509","messageId":"V3_synopsis_block.b66@msgid.xyz","threadId":"66090","inReplyTo":"V3_CV_synopsis_block.b64@msgid.xyz","subject":"[PATCH v3 2/2] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T14:23:46Z","receivedAt":"2026-08-13T14:24:34Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThis code block uses the placeholder `<subject>`. Let’s highlight this\nplaceholder properly by using the `synopsis` block definition which was\nintroduced in a34d1d53 (doc: convert git-show to synopsis style,\n2026-02-06).\n\nYes, note that code blocks since commit a34d1d53 can, on synopsis-style\ndocs like this one, be immediately preceded by `[synopsis]`, just like\nthe command synopsis is:\n\n    [synopsis]\n    (EXPERIMENTAL!) git format-rev - [...]\n\nCf. verse-style:\n\n    [verse]\n    'git name-rev' [...]\n\nAcked-by: Patrick Steinhardt <ps@pks.im>\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v3: add Ack: https://lore.kernel.org/git/an2Wwe4ytilGoyHz@pks.im/\n    v2:\n    • Add a paragraph to contrast synopsis code blocks with synopsis\n      command description after talk with Patrick on v1[1]\n    \n      🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/\n\n Documentation/git-format-rev.adoc | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 19241837345..d6c2e4aec1a 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the\n formatted commit, i.e. the format `\"%s\"` would transform some commit\n object name to `\"<subject>\"` without any termination. Like this:\n \n+[synopsis]\n ----\n Did we not fix this in \"<subject>\"?\n ----\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550585","messageId":"xmqqfr0hqzvl.fsf@gitster.g","threadId":"66090","inReplyTo":"V3_synopsis_block.b66@msgid.xyz","subject":"Re: [PATCH v3 2/2] doc: format-rev: use [synopsis] on code block","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-08-14T01:01:18Z","receivedAt":"2026-08-14T01:01:20Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n>\n> This code block uses the placeholder `<subject>`. Let’s highlight this\n> placeholder properly by using the `synopsis` block definition which was\n> introduced in a34d1d53 (doc: convert git-show to synopsis style,\n> 2026-02-06).\n>\n> Yes, note that code blocks since commit a34d1d53 can, on synopsis-style\n> docs like this one, be immediately preceded by `[synopsis]`, just like\n> the command synopsis is:\n>\n>     [synopsis]\n>     (EXPERIMENTAL!) git format-rev - [...]\n>\n> Cf. verse-style:\n>\n>     [verse]\n>     'git name-rev' [...]\n>\n> Acked-by: Patrick Steinhardt <ps@pks.im>\n> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n> ---\n\nHas this been tested with both AsciiDoc and AsciiDoctor?\n\n  https://github.com/git/git/actions/runs/31751206776/job/94617158587#step:4:4886\n\nCuriously, it does not fail for me locally (by default my builds use\nAsciiDoctor).\n"},{"id":"550595","messageId":"ef8ee6fb-ef3d-4a83-b8fc-121448d58e53@app.fastmail.com","threadId":"66090","inReplyTo":"xmqqfr0hqzvl.fsf@gitster.g","subject":"Re: [PATCH v3 2/2] doc: format-rev: use [synopsis] on code block","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-14T07:45:49Z","receivedAt":"2026-08-14T07:46:18Z","isPatch":true,"body":"On Fri, Aug 14, 2026, at 03:01, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n>>\n>> This code block uses the placeholder `<subject>`. Let’s highlight this\n>> placeholder properly by using the `synopsis` block definition which was\n>> introduced in a34d1d53 (doc: convert git-show to synopsis style,\n>> 2026-02-06).\n>>\n>> Yes, note that code blocks since commit a34d1d53 can, on synopsis-style\n>> docs like this one, be immediately preceded by `[synopsis]`, just like\n>> the command synopsis is:\n>>\n>>     [synopsis]\n>>     (EXPERIMENTAL!) git format-rev - [...]\n>>\n>> Cf. verse-style:\n>>\n>>     [verse]\n>>     'git name-rev' [...]\n>>\n>> Acked-by: Patrick Steinhardt <ps@pks.im>\n>> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n>> ---\n>\n> Has this been tested with both AsciiDoc and AsciiDoctor?\n>\n>\n> https://github.com/git/git/actions/runs/31751206776/job/94617158587#step:4:4886\n>\n> Curiously, it does not fail for me locally (by default my builds use\n> AsciiDoctor).\n\nNope. :/\n\nMy change uses a code block:\n\n    [synopsis]\n    ----\n    ...\n    ----\n\nBut the ones in `pretty-formats.adoc` use open blocks:\n\n    [synopsis]\n    --\n    ...\n    --\n\nI’ll do some better testing next.\n"},{"id":"550619","messageId":"xmqqtsowpxmz.fsf@gitster.g","threadId":"66090","inReplyTo":"ef8ee6fb-ef3d-4a83-b8fc-121448d58e53@app.fastmail.com","subject":"Re: [PATCH v3 2/2] doc: format-rev: use [synopsis] on code block","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-08-14T14:47:16Z","receivedAt":"2026-08-14T14:47:19Z","isPatch":true,"body":"\"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n\n> My change uses a code block:\n>\n>     [synopsis]\n>     ----\n>     ...\n>     ----\n>\n> But the ones in `pretty-formats.adoc` use open blocks:\n>\n>     [synopsis]\n>     --\n>     ...\n>     --\n>\n> I’ll do some better testing next.\n\nThanks.\n"},{"id":"550716","messageId":"V4_CV_synopsis_block.b8e@msgid.xyz","threadId":"66090","inReplyTo":"synopsis_block.af9@msgid.xyz","subject":"[PATCH v4 0/2] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-17T18:51:47Z","receivedAt":"2026-08-17T18:52:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nTopic name (applied): kh/format-rev-doc-synopsis\n\nTopic summary: Use '[synopsis]' on block in order to highlight\nplaceholder properly. Also quote the subject consistently.\n\n§ Changes in v4\n\nSorry about not reading carefully. An open block is not a code block.\n\n(copied from the patch note)\n\nFix block: use open block, not code block.[1] This is what was done for the\nsynopsis blocks in commit a34d1d53, the commit mentioned here. I have\ntested this with what I believe are the use-asciidoc (tool) and\nuse-asciidoctor (tool):\n\n    make doc\n    make USE_ASCIIDOCTOR=1 doc\n\nAnd they didn’t give any warnings. And they produced the correct result.\n\n  🔗 1: https://lore.kernel.org/git/xmqqfr0hqzvl.fsf@gitster.g/\n\nRewrite or flesh out the commit message to reflect this newfound knowledge.\n\nAlso remove the Ack since this change invalidates it.\n\n§ Cc\n\n(See v2)\n\n§ Link to v3\n\nhttps://lore.kernel.org/git/V3_CV_synopsis_block.b64@msgid.xyz/\n\n[1/2] doc: format-rev: quote subject placeholder before and after\n[2/2] doc: format-rev: use [synopsis] on code block\n\n Documentation/git-format-rev.adoc | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\nInterdiff against v3:\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex d6c2e4aec1a..c2268c92b56 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -97,9 +97,9 @@ formatted commit, i.e. the format `\"%s\"` would transform some commit\n object name to `\"<subject>\"` without any termination. Like this:\n \n [synopsis]\n-----\n+--\n Did we not fix this in \"<subject>\"?\n-----\n+--\n \n It is safe to interactively read and write from this command since each\n record is immediately flushed.\nRange-diff against v3:\n1:  c82aec7969f = 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after\n2:  b9a93c83c88 ! 2:  16d7bea804a doc: format-rev: use [synopsis] on code block\n    @@ Commit message\n         doc: format-rev: use [synopsis] on code block\n     \n         This code block uses the placeholder `<subject>`. Let’s highlight this\n    -    placeholder properly by using the `synopsis` block definition which was\n    -    introduced in a34d1d53 (doc: convert git-show to synopsis style,\n    -    2026-02-06).\n    +    placeholder properly by using the `synopsis` open block definition which\n    +    was introduced in a34d1d53 (doc: convert git-show to synopsis style,\n    +    2026-02-06). This renders the block like a code block but with emphasis\n    +    styling on placeholders, just like inline-verbatim (`) in running text.\n     \n    -    Yes, note that code blocks since commit a34d1d53 can, on synopsis-style\n    +    Yes, note that open blocks since commit a34d1d53 can, on synopsis-style\n         docs like this one, be immediately preceded by `[synopsis]`, just like\n         the command synopsis is:\n     \n    @@ Commit message\n             [verse]\n             'git name-rev' [...]\n     \n    -    Acked-by: Patrick Steinhardt <ps@pks.im>\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n     \n      ## Documentation/git-format-rev.adoc ##\n    @@ Documentation/git-format-rev.adoc: The mode `--stdin-mode=text` replaces each ob\n      formatted commit, i.e. the format `\"%s\"` would transform some commit\n      object name to `\"<subject>\"` without any termination. Like this:\n      \n    +-----\n     +[synopsis]\n    - ----\n    ++--\n      Did we not fix this in \"<subject>\"?\n    - ----\n    +-----\n    ++--\n    + \n    + It is safe to interactively read and write from this command since each\n    + record is immediately flushed.\n\nbase-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc\n-- \n2.55.0.13.g85d2d65e389\n\n"},{"id":"550718","messageId":"V4_quote_subject.b8f@msgid.xyz","threadId":"66090","inReplyTo":"V4_CV_synopsis_block.b8e@msgid.xyz","subject":"[PATCH v4 1/2] doc: format-rev: quote subject placeholder before and after","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-17T18:51:48Z","receivedAt":"2026-08-17T18:52:53Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nWe first talk about just `%s`, but then show the result with\nquotes. That is inconsistent. Let’s use quotes both in the format\nas well as in the result.\n\nThe implied input here, which is not spelled out for brevity, is:\n\n    Did we not fix this in <commit object name>?\n\nWhich is then supposed to be formatted to `\"<subject>\"`.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v2:\n    • [new]\n    • I wanted to add this after spotting the problem in [1]\n      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t\n\n Documentation/git-format-rev.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 505a52feccd..19241837345 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -93,8 +93,8 @@ acts as a _terminator_, not a _separator_. In other words, the final\n line or record is also terminated by the terminator character.\n \n The mode `--stdin-mode=text` replaces each object name with the\n-formatted commit, i.e. the format `%s` would transform some commit\n-object name to `<subject>` without any termination. Like this:\n+formatted commit, i.e. the format `\"%s\"` would transform some commit\n+object name to `\"<subject>\"` without any termination. Like this:\n \n ----\n Did we not fix this in \"<subject>\"?\n-- \n2.55.0.13.g85d2d65e389\n\n"},{"id":"550719","messageId":"V4_synopsis_block.b90@msgid.xyz","threadId":"66090","inReplyTo":"V4_CV_synopsis_block.b8e@msgid.xyz","subject":"[PATCH v4 2/2] doc: format-rev: use [synopsis] on code block","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-17T18:51:49Z","receivedAt":"2026-08-17T18:53:12Z","isPatch":true,"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThis code block uses the placeholder `<subject>`. Let’s highlight this\nplaceholder properly by using the `synopsis` open block definition which\nwas introduced in a34d1d53 (doc: convert git-show to synopsis style,\n2026-02-06). This renders the block like a code block but with emphasis\nstyling on placeholders, just like inline-verbatim (`) in running text.\n\nYes, note that open blocks since commit a34d1d53 can, on synopsis-style\ndocs like this one, be immediately preceded by `[synopsis]`, just like\nthe command synopsis is:\n\n    [synopsis]\n    (EXPERIMENTAL!) git format-rev - [...]\n\nCf. verse-style:\n\n    [verse]\n    'git name-rev' [...]\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v4:\n    • Fix block: use open block, not code block.[1] This is what was\n      done for the synopsis blocks in commit a34d1d53, the commit\n      mentioned here. I have tested this with what I believe are the\n      use-asciidoc (tool) and use-asciidoctor (tool):\n    \n          make doc\n          make USE_ASCIIDOCTOR=1 doc\n    \n      And they didn’t give any warnings. And they produced the correct\n      result.\n    \n      🔗 1: https://lore.kernel.org/git/xmqqfr0hqzvl.fsf@gitster.g/\n    • Msg: Rewrite or flesh out the message to reflect this newfound\n      knowledge\n    • Remove Ack from the previous round since I had to make these\n      changes\n    ---\n    v3: add Ack: https://lore.kernel.org/git/an2Wwe4ytilGoyHz@pks.im/\n    v2:\n    • Add a paragraph to contrast synopsis code blocks with synopsis\n      command description after talk with Patrick on v1[1]\n    \n      🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/\n\n Documentation/git-format-rev.adoc | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc\nindex 19241837345..c2268c92b56 100644\n--- a/Documentation/git-format-rev.adoc\n+++ b/Documentation/git-format-rev.adoc\n@@ -96,9 +96,10 @@ The mode `--stdin-mode=text` replaces each object name with the\n formatted commit, i.e. the format `\"%s\"` would transform some commit\n object name to `\"<subject>\"` without any termination. Like this:\n \n-----\n+[synopsis]\n+--\n Did we not fix this in \"<subject>\"?\n-----\n+--\n \n It is safe to interactively read and write from this command since each\n record is immediately flushed.\n-- \n2.55.0.13.g85d2d65e389\n\n"},{"id":"550727","messageId":"xmqq33wc4dyq.fsf@gitster.g","threadId":"66090","inReplyTo":"V4_CV_synopsis_block.b8e@msgid.xyz","subject":"Re: [PATCH v4 0/2] doc: format-rev: use [synopsis] on code block","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-08-17T21:46:53Z","receivedAt":"2026-08-17T21:46:56Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n>\n> Topic name (applied): kh/format-rev-doc-synopsis\n>\n> Topic summary: Use '[synopsis]' on block in order to highlight\n> placeholder properly. Also quote the subject consistently.\n>\n> § Changes in v4\n>\n> Sorry about not reading carefully. An open block is not a code block.\n>\n> (copied from the patch note)\n>\n> Fix block: use open block, not code block.[1] This is what was done for the\n> synopsis blocks in commit a34d1d53, the commit mentioned here. I have\n> tested this with what I believe are the use-asciidoc (tool) and\n> use-asciidoctor (tool):\n>\n>     make doc\n>     make USE_ASCIIDOCTOR=1 doc\n>\n> And they didn’t give any warnings. And they produced the correct result.\n>\n>   🔗 1: https://lore.kernel.org/git/xmqqfr0hqzvl.fsf@gitster.g/\n>\n> Rewrite or flesh out the commit message to reflect this newfound knowledge.\n>\n> Also remove the Ack since this change invalidates it.\n>\n> § Cc\n>\n> (See v2)\n>\n> § Link to v3\n>\n> https://lore.kernel.org/git/V3_CV_synopsis_block.b64@msgid.xyz/\n>\n> [1/2] doc: format-rev: quote subject placeholder before and after\n> [2/2] doc: format-rev: use [synopsis] on code block\n\nHopefully this is now ready for 'next'.\n\nThanks.\n"}]}