From: Martin Ågren <martin.agren@gmail.com>
Date: Fri, 04 Apr 2025 16:39:42 GMT
Subject: Re: [PATCH 1/5] doc: convert git-reset to new documentation format
Message-ID: <CAN0heSpQVWEko_=Ld1yQvduH4amB+Ei8Gf2pOjWA1Y4Pq7GSKA@mail.gmail.com>
In-Reply-To: <1676b5ac628fd2898c3dab1b25d6a852cedfa6ae.1743354964.git.gitgitgadget@gmail.com>

Hi Jean-Noël,

On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:

> - Switch the synopsis to a synopsis block which will automatically
>   format placeholders in italics and keywords in monospace
> - 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.

> ---soft::
> +`--soft`::
>         Does not touch the index file or the working tree at all (but
> -       resets the head to `<commit>`, just like all modes do). This leaves
> -       all your changed files "Changes to be committed", as `git status`
> +       resets the head to _<commit>_, just like all modes do). This leaves
> +       all your changed files "Changes to be committed", as `git status
>         would put it.

This loses the closing backtick after "git status".

> ---pathspec-from-file=<file>::
> -       Pathspec is passed in `<file>` instead of commandline args. If
> -       `<file>` is exactly `-` then standard input is used. Pathspec
> -       elements are separated by LF or CR/LF. Pathspec elements can be
> +`--pathspec-from-file=<file>`::
> +       Pathspec is passed in _<file>_ instead of commandline args. If
> +       _<file>_ is exactly `-` then standard input is used. Pathspec
> +       elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
>         quoted as explained for the configuration variable `core.quotePath`
>         (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
>         global `--literal-pathspecs`.
>
> ---pathspec-file-nul::
> +`--pathspec-file-nul`::
>         Only meaningful with `--pathspec-from-file`. Pathspec elements are
> -       separated with NUL character and all other characters are taken
> +       separated with _NUL_ character and all other characters are taken
>         literally (including newlines and quotes).

I was surprised that you wrapped CR, LF, and NUL in underscores. The
commit message only talks about <placeholders>, similar to
CodingGuidelines. That said, these _CR_ and friends seem to be
consistent with similar conversions you've done before.


Martin