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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 18, 2024, 00:35 UTC
Message-ID: <xmqqldxhxttb.fsf@gitster.g>
In-Reply-To: <2365334.irdbgypaU6@cayenne>

Jean-Noël AVILA <jn.avila@free.fr> writes:

Show 5 quoted lines

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

Makes sense. In this case, not like "--[no-]blah" whose description has to discuss two options with opposite meaning, we need to describe three choices.

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

Absolutely.

Show 18 quoted lines

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

OK.

Thanks.