doc: format-rev: use [synopsis] on code block
PATCH 1/1 doc: format-rev: use [synopsis] on code block
From: Kristoffer Haugsbakk <[email protected]>
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).
---
Notes (series):
Topic name: kh/doc-format-rev-1
Documentation/git-format-rev.adoc | 1 + 1 file changed, 1 insertion(+)
Documentation/git-format-rev.adoc +1 -0
@@ -96,6 +96,7 @@ 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 `<subject>` without any termination. Like this: +[synopsis] ---- Did we not fix this in "<subject>"? ----
base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH RESEND 1/1 doc: format-rev: use [synopsis] on code block
From: Kristoffer Haugsbakk <[email protected]>
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).
---
Notes (series):
Topic name: kh/doc-format-rev-1
Documentation/git-format-rev.adoc | 1 + 1 file changed, 1 insertion(+)
Documentation/git-format-rev.adoc +1 -0
@@ -96,6 +96,7 @@ 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 `<subject>` without any termination. Like this: +[synopsis] ---- Did we not fix this in "<subject>"? ----
base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
Signature · 1 line
2.54.0.22.g9e26862b904
Quoted 6 lines · On Mon, Aug 10, 2026 at 06:58:05PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
This code block uses the placeholder
<subject>. Let’s highlight this placeholder properly by using thesynopsisblock definition which was introduced ina34d1d53(doc: convert git-show to synopsis style, 2026-02-06).
I'm not particularly knowledgeable in AsciiDoc, I only picked it up because nobody else did. So please consider me even more clueless than I typically am :)
Documentation/git-format-rev.adoc The mode `--stdin-mode=text` replaces each object name with the · line 102
Quoted 12 lines
Documentation/git-format-rev.adoc +1
-0@@ -96,6 +96,7 @@ 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 `<subject>` without any termination. Like this: +[synopsis] ---- Did we not fix this in "<subject>"? ----
Hm. I was always under the impression that [synopsis] is used as exactly that, so it surprises me a bit that you want to use it for a random block that doesn't look like one at all. But going through our docs (like for example git-blame(1)) I see that we also do this for other non-synopsis-like blocks, so maybe this is fine?
There's probably a good reason for this, but can't we instead just use backticks to make <subject> render the exact same as four lines above?
Thanks!
Patrick
Quoted 4 lines · Patrick Steinhardt
Quoted 2 lines · On Mon, Aug 10, 2026 at 06:58:05PM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
Quoted 8 lines
Quoted 4 lines
This code block uses the placeholder
<subject>. Let’s highlight this placeholder properly by using thesynopsisblock definition which was introduced ina34d1d53(doc: convert git-show to synopsis style, 2026-02-06).I'm not particularly knowledgeable in AsciiDoc, I only picked it up because nobody else did. So please consider me even more clueless than I typically am :)
Thanks for taking a look.
Quoted 9 lines
Quoted 9 lines
Documentation/git-format-rev.adoc +0
-0@@ -96,6 +96,7 @@ 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 `<subject>` without any termination. Like this:
Quoted 10 lines
Documentation/git-format-rev.adoc The mode `--stdin-mode=text` replaces each object name with the · line 102
Quoted 4 lines
Documentation/git-format-rev.adoc +1
-0+[synopsis] ---- Did we not fix this in "<subject>"? ----Hm. I was always under the impression that
[synopsis]is used as exactly that, so it surprises me a bit that you want to use it for a random block that doesn't look like one at all. But going through our docs (like for example git-blame(1)) I see that we also do this for other non-synopsis-like blocks, so maybe this is fine?
To be clear, it’s not this kind of [synopsis]:
[synopsis]
git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]This [synopsis] is for a code block to highlight <subject> just like how <subject> is highlighted in running text when using (_) or (`).
Quoted 2 lines
There's probably a good reason for this, but can't we instead just use backticks to make
<subject>render the exact same as four lines above?
It’s a code block and the literal text is supposed to use quotation marks.
Well. I wrote the text to mean that subject is supposed to be quoted. So perhaps I should have written "%s" instead of "%s":
i.e. the format "%s" would transform some commit object name to "<subject>" without any termination. Like this: ...
;-)
Quoted 22 lines · Kristoffer Haugsbakk
Quoted 10 lines · Patrick Steinhardt
Quoted 8 lines · On Mon, Aug 10, 2026 at 06:58:05PM +0200, [email protected]…
Documentation/git-format-rev.adoc +0
-0@@ -96,6 +96,7 @@ 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 `<subject>` without any termination. Like this:Quoted 10 lines
Documentation/git-format-rev.adoc The mode `--stdin-mode=text` replaces each object name with the · line 102
Quoted 4 lines
Documentation/git-format-rev.adoc +1
-0+[synopsis] ---- Did we not fix this in "<subject>"? ----Hm. I was always under the impression that
[synopsis]is used as exactly that, so it surprises me a bit that you want to use it for a random block that doesn't look like one at all. But going through our docs (like for example git-blame(1)) I see that we also do this for other non-synopsis-like blocks, so maybe this is fine?
Quoted 7 lines
To be clear, it’s not this kind of [synopsis]:
[synopsis] git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]This [synopsis] is for a code block to highlight <subject> just like how <subject> is highlighted in running text when using (_) or (`).
Ah, so we have different kinds of synopsis depending on what it applies to?
Quoted 11 lines
Quoted 2 lines
There's probably a good reason for this, but can't we instead just use backticks to make
<subject>render the exact same as four lines above?It’s a code block and the literal text is supposed to use quotation marks.
Well. I wrote the text to mean that subject is supposed to be quoted. So perhaps I should have written
"%s"instead of"%s":i.e. the format
"%s"would transform some commit object name to"<subject>"without any termination. Like this: ...
Makes sense, thanks!
Patrick
Quoted 7 lines · Patrick Steinhardt
Quoted 3 lines · Kristoffer Haugsbakk
Quoted 1 line · Patrick Steinhardt
[snip]
<subject> is highlighted in running text when using (_) or (`).
Ah, so we have different kinds of synopsis depending on what it applies to?
Yeah, that must be it. To be honest I had neglected to consider that the command description part uses the same syntax already... x)
Quoted 6 lines
Quoted 4 lines
[snip]
i.e. the format
"%s"would transform some commit object name to"<subject>"without any termination. Like this: ...Makes sense, thanks!
Thank you.
Quoted 8 lines · Kristoffer Haugsbakk
[snip]
Well. I wrote the text to mean that subject is supposed to be quoted. So perhaps I should have written"%s"instead of"%s":i.e. the format
"%s"would transform some commit object name to"<subject>"without any termination. Like this: ...;-)
I might do a re-roll with a change to use "". I’ll see how it looks first.
v2 cover doc: format-rev: use [synopsis] on code block
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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/[email protected]/#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:
Documentation/git-format-rev.adoc +2 -2
@@ -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 `<subject>` without any termination. Like this: +formatted commit, i.e. the format `"%s"` would transform some commit +object name to `"<subject>"` 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' [...]
+
## 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 <subject> without any termination. Like this:
+ formatted commit, i.e. the format "%s" would transform some commit
+ object name to "<subject>" without any termination. Like this:
+[synopsis]
----
base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v2 1/2 doc: format-rev: quote subject placeholder before and after
From: Kristoffer Haugsbakk <[email protected]>
We first talk about just %s, but then show the result with quotes. That is inconsistent. Let’s use quotes both in the format as well as in the result.
The implied input here, which is not spelled out for brevity, is:
Did we not fix this in <commit object name>?
Which is then supposed to be formatted to "<subject>".
---
Notes (series):
v2:
• [new]
• I wanted to add this after spotting the problem in [1]
🔗 1: https://lore.kernel.org/git/[email protected]/#t
Documentation/git-format-rev.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-format-rev.adoc +2 -2
@@ -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 `<subject>` without any termination. Like this: +formatted commit, i.e. the format `"%s"` would transform some commit +object name to `"<subject>"` without any termination. Like this: ---- Did we not fix this in "<subject>"?
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v2 2/2 doc: format-rev: use [synopsis] on code block
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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).
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' [...]---
Notes (series):
v2:
• Add a paragraph to contrast synopsis code blocks with synopsis command description after talk with Patrick on v1[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
Documentation/git-format-rev.adoc | 1 + 1 file changed, 1 insertion(+)
Documentation/git-format-rev.adoc +1 -0
@@ -96,6 +96,7 @@ 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 `"<subject>"` without any termination. Like this: +[synopsis] ---- Did we not fix this in "<subject>"? ----
Signature · 1 line
2.54.0.22.g9e26862b904
Quoted 11 lines · On Thu, Aug 13, 2026 at 11:57:36AM +0200, [email protected]…
From: Kristoffer Haugsbakk <[email protected]>
This code block uses the placeholder
<subject>. Let’s highlight this placeholder properly by using thesynopsisblock definition which was introduced ina34d1d53(doc: convert git-show to synopsis style, 2026-02-06).Yes, note that code blocks since commit
a34d1d53can, on synopsis-style docs like this one, be immediately preceded by[synopsis], just like the command synopsis is:
Quoted 7 lines
[synopsis] (EXPERIMENTAL!) git format-rev - [...]Cf. verse-style:
[verse] 'git name-rev' [...]
Thanks for the additional reference to the above commit. That helps, and you can see that as part of the commit we have similar changes to our docs like you do them in your patch.
So I'm happy with this version, thanks!
Patrick
v3 cover doc: format-rev: use [synopsis] on code block
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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 v3
• Patch 2/2: Add Ack
§ Cc
(See v2)
§ Link to v2
https://lore.kernel.org/git/[email protected]/
[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 v2:
Range-diff against v2:
1: c82aec7969f = 1: c82aec7969f doc: format-rev: quote subject placeholder before and after 2: f528d7e9dcd ! 2: b9a93c83c88 doc: format-rev: use [synopsis] on code block
@@ Commit message
[verse]
'git name-rev' [...]
+ Acked-by: Patrick Steinhardt <[email protected]>
## Documentation/git-format-rev.adoc ##
base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 1/2 doc: format-rev: quote subject placeholder before and after
From: Kristoffer Haugsbakk <[email protected]>
We first talk about just %s, but then show the result with quotes. That is inconsistent. Let’s use quotes both in the format as well as in the result.
The implied input here, which is not spelled out for brevity, is:
Did we not fix this in <commit object name>?
Which is then supposed to be formatted to "<subject>".
---
Notes (series):
v2:
• [new]
• I wanted to add this after spotting the problem in [1]
🔗 1: https://lore.kernel.org/git/[email protected]/#t
Documentation/git-format-rev.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-format-rev.adoc +2 -2
@@ -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 `<subject>` without any termination. Like this: +formatted commit, i.e. the format `"%s"` would transform some commit +object name to `"<subject>"` without any termination. Like this: ---- Did we not fix this in "<subject>"?
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 2/2 doc: format-rev: use [synopsis] on code block
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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).
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' [...]---
Notes (series):
v3: add Ack: https://lore.kernel.org/git/[email protected]/
v2:
• Add a paragraph to contrast synopsis code blocks with synopsis command description after talk with Patrick on v1[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
Documentation/git-format-rev.adoc | 1 + 1 file changed, 1 insertion(+)
Documentation/git-format-rev.adoc +1 -0
@@ -96,6 +96,7 @@ 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 `"<subject>"` without any termination. Like this: +[synopsis] ---- Did we not fix this in "<subject>"? ----
Signature · 1 line
2.54.0.22.g9e26862b904
Quoted 14 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
This code block uses the placeholder
<subject>. Let’s highlight this placeholder properly by using thesynopsisblock definition which was introduced ina34d1d53(doc: convert git-show to synopsis style, 2026-02-06).Yes, note that code blocks since commit
a34d1d53can, on synopsis-style docs like this one, be immediately preceded by[synopsis], just like the command synopsis is:[synopsis] (EXPERIMENTAL!) git format-rev - [...]
Quoted 8 lines
Cf. verse-style:
[verse] 'git name-rev' [...]Signed-off-by Kristoffer Haugsbakk <[email protected]>---
Has this been tested with both AsciiDoc and AsciiDoctor?
https://github.com/git/git/actions/runs/31751206776/job/94617158587#step:4:4886
Curiously, it does not fail for me locally (by default my builds use AsciiDoctor).
Quoted 25 lines · Junio C Hamano
Quoted 14 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
This code block uses the placeholder
<subject>. Let’s highlight this placeholder properly by using thesynopsisblock definition which was introduced ina34d1d53(doc: convert git-show to synopsis style, 2026-02-06).Yes, note that code blocks since commit
a34d1d53can, on synopsis-style docs like this one, be immediately preceded by[synopsis], just like the command synopsis is:[synopsis] (EXPERIMENTAL!) git format-rev - [...]Quoted 8 lines
Cf. verse-style:
[verse] 'git name-rev' [...]Signed-off-by Kristoffer Haugsbakk <[email protected]>---
Quoted 7 lines
Has this been tested with both AsciiDoc and AsciiDoctor?
https://github.com/git/git/actions/runs/31751206776/job/94617158587#step:4:4886
Curiously, it does not fail for me locally (by default my builds use AsciiDoctor).
Nope. :/
My change uses a code block:
[synopsis]
----
...
----But the ones in pretty-formats.adoc use open blocks:
[synopsis]
--
...
--I’ll do some better testing next.
Quoted 7 lines · Kristoffer Haugsbakk
My change uses a code block:
[synopsis] ---- ... ----
Quoted 8 lines
But the ones in
pretty-formats.adocuse open blocks:[synopsis] -- ... --I’ll do some better testing next.
Thanks.
v4 cover doc: format-rev: use [synopsis] on code block
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
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/[email protected]/
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/[email protected]/
[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:
Documentation/git-format-rev.adoc +2 -2
@@ -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 <[email protected]>
## 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
Signature · 1 line
2.55.0.13.g85d2d65e389
PATCH v4 1/2 doc: format-rev: quote subject placeholder before and after
From: Kristoffer Haugsbakk <[email protected]>
We first talk about just %s, but then show the result with quotes. That is inconsistent. Let’s use quotes both in the format as well as in the result.
The implied input here, which is not spelled out for brevity, is:
Did we not fix this in <commit object name>?
Which is then supposed to be formatted to "<subject>".
---
Notes (series):
v2:
• [new]
• I wanted to add this after spotting the problem in [1]
🔗 1: https://lore.kernel.org/git/[email protected]/#t
Documentation/git-format-rev.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-format-rev.adoc +2 -2
@@ -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 `<subject>` without any termination. Like this: +formatted commit, i.e. the format `"%s"` would transform some commit +object name to `"<subject>"` without any termination. Like this: ---- Did we not fix this in "<subject>"?
Signature · 1 line
2.55.0.13.g85d2d65e389
PATCH v4 2/2 doc: format-rev: use [synopsis] on code block
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
This code block uses the placeholder <subject>. Let’s highlight this 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 open 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' [...]---
Notes (series):
v4:
• 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/[email protected]/
• Msg: Rewrite or flesh out the message to reflect this newfound knowledge
• Remove Ack from the previous round since I had to make these changes
---
v3: add Ack: https://lore.kernel.org/git/[email protected]/
v2:
• Add a paragraph to contrast synopsis code blocks with synopsis command description after talk with Patrick on v1[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
Documentation/git-format-rev.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-format-rev.adoc +3 -2
@@ -96,9 +96,10 @@ 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 `"<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.
Signature · 1 line
2.55.0.13.g85d2d65e389
Quoted 31 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
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/[email protected]/
Rewrite or flesh out the commit message to reflect this newfound knowledge.
Also remove the Ack since this change invalidates it.
§ Cc
Quoted 8 lines
(See v2)
§ Link to v3
https://lore.kernel.org/git/[email protected]/
[1/2] doc: format-rev: quote subject placeholder before and after [2/2] doc: format-rev: use [synopsis] on code block
Hopefully this is now ready for 'next'.
Thanks.