Re: [PATCH] doc: fix asciidoc format compatibility in pretty-formats.adoc
- From
Jean-Noël AVILA <jn.avila@free.fr>
- Date
- Aug 20, 2025, 21:00 UTC
- Message-ID
- <4673610.LvFx2qVVIh@cayenne>
- In-Reply-To
- <xmqqa53vc77z.fsf@gitster.g>
On Tuesday, 19 August 2025 23:49:36 CEST Junio C Hamano wrote:
Show 6 quoted lines
> 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
Show 8 quoted lines
> > 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.
Show 13 quoted lines
> > > 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
Show 5 quoted lines
> > 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.
Show 7 quoted lines
> >
> > - Defaults to "{nbsp}+->+{nbsp}".
> > + Defaults to "{nbsp}++->++{nbsp}".
> >
> > ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> >
> > +