Re: [PATCH] doc: fix asciidoc format compatibility in pretty-formats.adoc

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

On Tuesday, 19 August 2025 23:49:36 CEST Junio C Hamano wrote:
> Jean-Noël Avila <jn.avila@free.fr> writes:
> > Asciidoc.py and Asciidoctor do not process the same '+' verbatim syntax in
> > the same way. For most usages, Asciidoctor requires a double '+'.
> 
> The word "same" on the first line is probably unwanted?
> 

Definitely. Rerolled in V2.

> > Unfortunately, the postprocessing of verbatim synopsis in asciidoctor 
cannot
> > be bypassed and formatting of the parentheses is forced in syntax sign
> > instead of keywords, unless a proper grammar analyzer is used.
> 
> Sorry, I've read the above three times, but it would not explain why
> the change is needed for the "prefix" line, but no change is needed
> for the "suffix" line or for the "separator" line, even though they
> look quite similar.  Is open-parenthesis somehow special?  And '>'
> also special in the same way?

The detection of opening of spans in Asciidoc is driven by a span markup 
character (here '+') preceded by a non-word character. The condition is 
symmetrical for closing of spans. I haven't dug into the source code, but it 
seems that asciidoc.py considers '{nbsp}' as a non-word character, whereas 
Asciidoctor does not.

Using double markup characters creates 'unconstrained' spans, which do not 
need the non-word character condition.

Note also that this "feature" is very centric on roman based languages (like 
many of light markup design decisions) and is a pain in other writing systems 
which do not require space between words.

> 
> > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> > ---
> > 
> >  Documentation/pretty-formats.adoc | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/pretty-formats.adoc
> > b/Documentation/pretty-formats.adoc
> > index 9ed0417fc8..618ddc4a0c 100644
> > --- a/Documentation/pretty-formats.adoc
> > +++ b/Documentation/pretty-formats.adoc
> > @@ -233,11 +233,11 @@ colon and zero or more comma-separated options. 
Option
> > values may contain> 
> >  literal formatting codes. These must be used for commas (`%x2C`) and 
closing
> >  parentheses (`%x29`), due to their role in the option syntax.
> >  +
> > 
> > -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> > "{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}".
> > +		      Defaults to "{nbsp}++->++{nbsp}".
> > 
> >  ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> >  
> >  +