From: Johannes Sixt <j6t@kdbg.org>
Date: Tue, 12 Nov 2024 18:28:34 GMT
Subject: Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines
Message-ID: <45211c3c-e077-4de3-a167-0fc973a78dba@kdbg.org>
In-Reply-To: <xmqq34jw6ci7.fsf@gitster.g>

Am 12.11.24 um 10:13 schrieb Junio C Hamano:
> Jean-Noël Avila <jn.avila@free.fr> writes:
>> To clarify, from what I understand, it would be better to fully spell
>> out the way these options are used by using the synopsis syntax:
>>
>> `(-1|--base) | (-2|--ours) | (-3|--theirs)`::
>>
>> Is it how it works?
> 
> Yeah, that may be a more sensible rewrite (regardless of this
> "better mark-up" topic).

I would disagree. IMHO, it is not necessary to copy this sort of
nerdfulness (the syntax annotations) from the synopsis to the
description section.

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

-- Hannes