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

From: Jean-Noël Avila <jn.avila@free.fr>
Date: Nov 13, 2024, 08:59 UTC
Message-ID: <4ad6b044-5eec-4d46-a862-20f374ede527@free.fr>
In-Reply-To: <xmqqcyj03vlk.fsf@gitster.g>

Le 13/11/2024 à 00:01, Junio C Hamano a écrit :

Show 23 quoted lines

> Johannes Sixt <j6t@kdbg.org> writes:
> 
>> Does
>>
>> `-1`, `--base`::
>> `-2`, `--ours`::
>> `-3`, `--theirs`::
>>
>> not work? (I think we agree that grouping synonyms should be done and
>> not all tokens moved onto a flat line.)
> 
> With the current
> 
>     -1 --base::
>     -2 --ours::
>     -3 --theirs::
> 	body text
> 
> these are coalesced into a single header and get rendered as
> 
>     -1 --base, -2 --ours, -3 --theirs
> 	body text
>

When I first reviewed this part, I interpreted it as "there are 3 forms, made of pairs of options used together", which did not make sense. That is only after reading git-read-tree, that this explanation made sense.

Show 9 quoted lines

> which reasonably shows that 1 and base belong to the same family
> that is different from 2 and ours, etc.  With an explicit comma
> in between 1 and base, would we end up with
> 
>     -1, --base, -2, --ours, -3, --theirs
> 
> which may be worse than what we have currently?
> 
> Thanks.

To be consistant with description of option, I think the 3 alternatives should be split into their own items.