Subject: Re: [PATCH v3 1/5] doc: git-diff: apply new documentation guidelines

From: Johannes Sixt <[email-masked]>
Date: Sun, 17 Nov 2024 15:04:13 +0100

Am 16.11.24 um 20:36 schrieb Jean-Noël Avila via GitGitGadget:
> --1 --base::
> --2 --ours::
> --3 --theirs::
> +`-1`::
> +`--base`::
> +
> +or `-2`::
> +`--ours`::
> +
> +or `-3`::
> +`--theirs`::
>  	Compare the working tree with the "base" version (stage #1),
>  	"our branch" (stage #2) or "their branch" (stage #3).  The
>  	index contains these stages only for unmerged entries i.e.
>  	while resolving conflicts.  See linkgit:git-read-tree[1]
>  	section "3-Way Merge" for detailed information.

Having seen this new proposal (which I am not a fan of), I reconsidered
my take on how this could be formatted.

First, I wonder why the pre-image is not

-1::
--base::
-2::
--ours::
-3::
--theirs::

like we write in other cases where multiple options are described by the
same paragraph (e.g.: -p -u --patch; -W --function-context; --textconv
--no-textconv).

Next, since with such a scheme all options are treated equally, we have
to ask whether the description in the body text makes sufficiently clear
that they not all do the same thing (it does), that there are actually 3
distinct groups (it does), and which options mean the same thing. The
latter is rather meh, but it is the fault of the text and can be
remedied easily.

Finally, with all this considered, I think it is not so bad at all that
all options are lumped together in a single line (or remain on six
separate header lines, depending on the processor). So, I would no
longer mind seeing this transformed into

`-1`::
`--base`::
`-2`::
`--ours`::
`-3`::
`--theirs`::

for consistency, or

`-1`, `--base`::
`-2`, `--ours`::
`-3`, `--theirs`::

for brevity.

-- Hannes