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

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Sunday, 25 January 2026 20:27:38 CET Kristoffer Haugsbakk wrote:
> 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.

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

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

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



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

> > 
> > -++%(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.



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