[PATCH] doc: format-rev: use [synopsis] on code block

[PATCH] doc: format-rev: use [synopsis] on code block

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name: kh/doc-format-rev-1

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 505a52feccd..836ba4b0c24 100644
--- a/Documentation/git-format-rev.adoc
+++ b/Documentation/git-format-rev.adoc
@@ -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
-- 
2.54.0.22.g9e26862b904

[PATCH resend] doc: format-rev: use [synopsis] on code block

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name: kh/doc-format-rev-1

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 505a52feccd..836ba4b0c24 100644
--- a/Documentation/git-format-rev.adoc
+++ b/Documentation/git-format-rev.adoc
@@ -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
-- 
2.54.0.22.g9e26862b904

Re: [PATCH resend] doc: format-rev: use [synopsis] on code block

[Patrick Steinhardt]

On Mon, Aug 10, 2026 at 06:58:05PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> 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).

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 :)

> diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
> index 505a52feccd..836ba4b0c24 100644
> --- a/Documentation/git-format-rev.adoc
> +++ b/Documentation/git-format-rev.adoc
> @@ -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

Re: [PATCH resend] doc: format-rev: use [synopsis] on code block

[Kristoffer Haugsbakk]

On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:
> On Mon, Aug 10, 2026 at 06:58:05PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> 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).
>
> 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.

>
>> diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
>> index 505a52feccd..836ba4b0c24 100644
>> --- a/Documentation/git-format-rev.adoc
>> +++ b/Documentation/git-format-rev.adoc
>> @@ -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?

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 (`).

> 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: ...

;-)

Re: [PATCH resend] doc: format-rev: use [synopsis] on code block

[Patrick Steinhardt]

On Tue, Aug 11, 2026 at 06:23:18PM +0200, Kristoffer Haugsbakk wrote:
> On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:
> > On Mon, Aug 10, 2026 at 06:58:05PM +0200,
> > kristofferhaugsbakk@fastmail.com wrote:
> >> diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
> >> index 505a52feccd..836ba4b0c24 100644
> >> --- a/Documentation/git-format-rev.adoc
> >> +++ b/Documentation/git-format-rev.adoc
> >> @@ -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?
> 
> 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?

> > 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

Re: [PATCH resend] doc: format-rev: use [synopsis] on code block

[Kristoffer Haugsbakk]

On Tue, Aug 11, 2026, at 18:27, Patrick Steinhardt wrote:
> On Tue, Aug 11, 2026 at 06:23:18PM +0200, Kristoffer Haugsbakk wrote:
>> On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:
>>>[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)

>>[snip]
>>
>>      i.e. the format `"%s"` would transform some commit object name to
>>      `"<subject>"` without any termination. Like this: ...
>
> Makes sense, thanks!

Thank you.

Re: [PATCH resend] doc: format-rev: use [synopsis] on code block

[Kristoffer Haugsbakk]

On Tue, Aug 11, 2026, at 18:23, Kristoffer Haugsbakk wrote:
>[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.

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 `<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' [...]
    +
         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 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
-- 
2.54.0.22.g9e26862b904

[PATCH v2 1/2] doc: format-rev: quote subject placeholder before and after

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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>"`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • [new]
    • I wanted to add this after spotting the problem in [1]
      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t

 Documentation/git-format-rev.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 505a52feccd..19241837345 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 `<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>"?
-- 
2.54.0.22.g9e26862b904

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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' [...]

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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/ansWZxZ6lB0tYIJD@pks.im/

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 19241837345..d6c2e4aec1a 100644
--- a/Documentation/git-format-rev.adoc
+++ b/Documentation/git-format-rev.adoc
@@ -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>"?
 ----
-- 
2.54.0.22.g9e26862b904

Re: [PATCH v2 2/2] doc: format-rev: use [synopsis] on code block

[Patrick Steinhardt]

On Thu, Aug 13, 2026 at 11:57:36AM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> 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' [...]

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