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

From: Junio C Hamano <[email-masked]>
Date: Tue, 19 Aug 2025 14:49:36 -0700

Jean-Noël Avila <[email-masked]> 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?

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

>
> Signed-off-by: Jean-Noël Avila <[email-masked]>
> ---
>  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}".
>  
>  +