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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 19, 2025, 21:49 UTC
Message-ID: <xmqqa53vc77z.fsf@gitster.g>
In-Reply-To: <20250819212340.73886-1-jn.avila@free.fr>

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?

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

Show 24 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
>  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}".
>  
>  +