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

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

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

;-)