Re: [PATCH 4/4] doc: convert git-show to synopsis style

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Jan 26, 2026, 05:58 UTC
Message-ID: <0dec5e08-f4a2-4bcd-9324-b0fcbc2fabe0@app.fastmail.com>
In-Reply-To: <3926333.kQq0lBPeGt@piment-oiseau>

On Sun, Jan 25, 2026, at 22:11, Jean-Noël AVILA wrote:

Show 32 quoted lines

>>[snip]
>> >  +
>> >  This format is used to refer to another commit in a commit message and
>> >  is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++.  By default,
>>
>> Not changed in this patch but this doesn’t render correctly for me. It’s
>> not inline verbatim/code all the way through. But it is correct if I
>> remove the `\`.
>>
>> I don’t know why `++` was used either.
>
> That's where the synopsis style fails. If we use backticks for this span, the
> parenthesis are interpreted as grammar signs, whereas here, we intend to pass
> the whole span as verbatim.
>
>
> For asciidoc.py, using the verbatim form '++' ensures that the whole span is
> treated as such. On my computer (asciidoc.py version 10.2.1), this renders as
> correctly.
>
> For asciidoctor unfortunately, the synopsis processing is performed very late
> in the generation, after all parsing has been done. So, the '++' verbatim is
> processed the same way as backticked contents. I haven't found a better
> alternative. The output is this wrongly processed span here.
>
> This is the least breaking way I found. It means that for asciidoc.py, we can
> bypass the synopsis style with '++' formatting.
>
> If I remove the backslash in this, the span inside the single quotes is
> converted to italics by both engines.
>
> Can you describe your setup?

    $ asciidoc --version
    asciidoc 10.1.2
    $ asciidoctor --version
    Asciidoctor 2.0.20 [https://asciidoctor.org]
    Runtime Environment (ruby 3.1.4p223 (2023-03-30 revision 957bb7cb81) [x86_64-linux]) (lc:US-ASCII fs:US-ASCII in:US-ASCII ex:US-ASCII)

Anything else that is relevant?

>
>>
>> This looks correct just looking quickly over.
>>[snip]