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

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

On Sunday, 1 February 2026 13:12:47 CET Kristoffer Haugsbakk wrote:
> >  +
> >  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 a change here but while `--pretty...` has all the symbols it is
> partly rendered, partly not.
> 

> > -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> > "{nbsp}++(++".
> > -** `suffix=<value>`: Shown after the list of ref names.  Defaults to
> > "+)+".
> > -** `separator=<value>`: Shown between ref names.  Defaults to
> > "+,+{nbsp}".
> 
> These are rendered serviceably.
> 
> > -** `pointer=<value>`: Shown between HEAD and the branch it points to,
> > if any.
> > -		      Defaults to "{nbsp}++->++{nbsp}".
> 
> This one is just `->` but it’s a bit confusing:
> 
>     " -> ".
> 
> (the spaces may be more narrow in the HTML?)
> 
> And the `-` has verbatim typeface while `>` does not.
> 
> I said the preceding ones were serviceable in the sense that they don’t
> look great but you see what they are. This one is questionable.
> 
> > -** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> > +`prefix=<value>`;; Shown before the list of ref names.  Defaults to
> > "{nbsp}++(++".
> > +`suffix=<value>`;; Shown after the list of ref names.  Defaults to
> > "+)+".
> > +`separator=<value>`;; Shown between ref names.  Defaults to
> > "+,+{nbsp}".
> > +`pointer=<value>`;; Shown between HEAD and the branch it points to, if
> > any.
> > +	      Defaults to "{nbsp}++->++{nbsp}".
> > +`tag=<value>`;; Shown before tag names. Defaults to "`tag:`{nbsp}".
> 
> Here I feel some deja vu.
> 
> >  +
> > 
> > ---
> > 
> >  For example, to produce decorations with no wrapping
> > 
> >  or tag annotations, and spaces as separators:
> > -
> > ++
> > 
> >  ++%(decorate:prefix=,suffix=,tag=,separator= )++
> > 
> > ---
> 
> Here is a a problem. The pluses in `++...++` are apparently markup. But
> the line starts with `+%` here:
> 
>     + %(decorate:prefix=,suffix=,tag=,separator= )
> 


OK, I understand that you are using asciidoctor for compilation. This is a 
difficult problem to sort out. For the translations, I'm working on an actual 
parser:
https://github.com/jnavila/git-manpages-l10n/blob/master/asciidoctor-extensions.rb

When the parsing fails, the formatting rolls back to simple verbatim 
formatting.

After polishing it a bit, this could make it into the git source, if the new 
dependency is accepted.

In the mean time, all I can propose is to remove all formatting when 
asciidoctor will not process it correctly and the output will be confusing.