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@xxxxxxx>
>
> - 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= )++
