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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Jan 25, 2026, 21:11 UTC
Message-ID: <3926333.kQq0lBPeGt@piment-oiseau>
In-Reply-To: <51016c02-40de-431f-a4ba-e08cb1bb8235@app.fastmail.com>

On Sunday, 25 January 2026 20:27:38 CET Kristoffer Haugsbakk wrote:

Show 7 quoted lines

> On Fri, Jan 23, 2026, at 22:15, Jean-Noël Avila via GitGitGadget wrote:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> > 
> >  * add synopsis block definition in asciidoc.conf.in
> 
> This is for e.g. ``<hash> <title-line>`` it looks like. Is the intent to
> use italics on placeholders like `<hash>`?

Yes, it is. It turns out that asciidoc.py treats differently, paragraph styles and block styles. Until now, we only used paragraph style for synopsis.

Show 9 quoted lines

> >  For plain blobs, it shows the plain contents.
> > 
> > -Some options that 'git log' command understands can be used to
> > +Some options that `git log` command understands can be used to
> 
> Same here.
> 
> It could be nice to s/`git log` command/linkgit:git-log[1]/ either on
> this commit or in a separate one.

The problem is that pretty-formats.adoc is also included in git-log.adoc and I don't think it makes sense to self-cross-reference. If we want to generalize, it would need some conditional inclusion/replacement.

Show 18 quoted lines

> >> 
> >  built-in formats:
> > -* `oneline`
> > -
> > -	  <hash> <title-line>
> > +`oneline`::
> > ++
> > +[synopsis]
> > +--
> > +`<hash> <title-line>`
> > +--
> 
> HTML looks wrong in git-show(1) and others that include it. Something
> like this:
> 
>     oneline
>         __<hash>__ __<title-line>__
>

The first edit was `<hash> <title-line>` but the rendering odd with the following items which where more spaced. So, I changed to synopsis block but forgot the back-ticks.

Will reroll.

> This doesn’t happen when I run asciidoc(1) or asciidoctor(1) directly.
>

<snip>

> 
> (For these pretty formats) The diff got confused I think but the
> conversion looks correct.
>

It looks better but not perfect. It is difficult to render correctly when the usual grammatical signs are in fact keywords. See below for better explanation.

Show 9 quoted lines

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

Show 9 quoted lines

> 
> This looks correct just looking quickly over.
> 
> > -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> > "{nbsp}++(++".
> 
> All of these use the "(" style which doesn’t look good in my
> opinion. But I’m guessing it has to do with some of them using spaces in
> them and `"` being used as a boundary.

Same here as above. I get the correct rendering for asciidoc.py. For asciidoctor, this is rendered as normal text. Not correct but not completely bogus.

Show 8 quoted lines

> > 
> > -++%(describe++`[:<option>,...]`++)++::
> 
> > +++%(`describe++``[:<option>,...]`++)++::
> This renders with backticks in HTML:
> 
>     %(describe++`[:<option>,...]`)++
>

Ah, thanks for spotting. I mixed again synopsis and plain verbatim. Will reroll.

Show 7 quoted lines

> > 
> >     the literal formatting codes described above. To use comma as
> >     separator one must use `%x2C` as it would otherwise be parsed as
> >     next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+
> >     shows all trailer lines whose key is "Ticket" separated by a comma
> 
> Might as well s/"Ticket"/`Ticket`/ ?

Difficult to say. This is not a keyword per se. Changing is ok for me.

> The rest looks okay.