From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Fri, 04 Jul 2025 20:43:03 GMT
Subject: Re: [PATCH 7/9] doc: git-log: convert pretty formats to new doc format
Message-ID: <bc18712a-8f72-4827-b47f-afac69ea6fa0@app.fastmail.com>
In-Reply-To: <d54e297567ac8f3009daa8fdf3de158338b2b700.1749373787.git.gitgitgadget@gmail.com>

On Sun, Jun 8, 2025, at 11:09, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> - Use _<placeholder>_ instead of <placeholder> in the description
> - Use `backticks` for keywords and more complex option
> descriptions. The new rendering engine will apply synopsis rules to
> these spans.
>
> For all the formats in the form of %(foo), the formatting needs to be
> heavier because we not want the parentheses to be rendered as syntax
> elements,but as keywords, i.e. we need to circumvent the syntax highlighting

nit: s/elements,but/elements, but/

> -** '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}".
> +** `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}".

`+->+` gets rendered as `+→+` in the HTMl output.
`Documentation/doc-diff` shows the same.

Has using `␣` to denote SP in verbatim code blocks been considered
by anyone?

> +** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
>
>  +
>  For example, to produce decorations with no wrapping
>  or tag annotations, and spaces as separators:
>  +
> -`%(decorate:prefix=,suffix=,tag=,separator= )`
> +++%(decorate:prefix=,suffix=,tag=,separator= )++