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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Nov 17, 2024, 16:44 UTC
Message-ID: <2365334.irdbgypaU6@cayenne>
In-Reply-To: <7f24a030-bae2-4712-8593-61a9d4089cfb@kdbg.org>

On Sunday, 17 November 2024 15:04:13 CET Johannes Sixt wrote:

Show 41 quoted lines

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

OK, I'm not fond of my solution either, but I strongly dislike mixing synonyms (which is the usual meaning of putting several options in the same description) with incompatible behavioral alternatives. But, for this one, let's consider that the alternatives are just like `--[no-]bla` option descriptions, for the sake of ending this PR.

I would still rephrase the description to make it clear, how the alternatives are working:

`-1`::
`--base`::
`-2`::
`--ours`::
`-3`::
`--theirs`::
	Compare the working tree with
+
--
 * the "base" version (stage #1) when using `-1` or `--base`,
 * "our branch" (stage #2) when using `-2` or `--ours`, or
 * "their branch" (stage #3) when using `-3` or `--theirs`.
--
+
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.

Show 13 quoted lines

> 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

To be honest, this is the form I would prefer because it can be automatically processed for translation as "do not translate". Any addition involving human language to a segment requires translation.

Thanks,

JN