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

From: Johannes Sixt <j6t@kdbg.org>
Date: Nov 12, 2024, 18:28 UTC
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:

Show 10 quoted lines

> 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