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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 12, 2024, 09:13 UTC
Message-ID: <xmqq34jw6ci7.fsf@gitster.g>
In-Reply-To: <7b42828a-2cbe-47c6-b21e-b8c1e3a2ad01@free.fr>

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

Show 6 quoted lines

> With the new document processor extension, the back tick quotes have
> become smarter and they behave basically like an inline synopsis
> section. Here, this means that the line will be formatted roughly as
> follows:
>
> `git diff` [_<options>_] [`--`] [_<path>_...]

Ahh, yes, it is the key magic how your "enclosing the whole line" works. It's been so long since we adopted the topic that laid the groundwork that I forgot ;-)

Again, it is very pleasant for us writers to be able to just do so.

Show 19 quoted lines

>>> +`-1` `--base`::
>>> +`-2` `--ours`::
>>> +`-3` `--theirs`::
>> 
>> Why aren't these `-1 --base` and instead mark up individual tokens?
>> 
>
> Here, it is quite awkward, because we are mixing alternate spellings of
> the same option (`-1` and `--base` have the same meaning) with the fact
> that these options are meant to be alternatives. The latter meaning is
> not what is usually conveyed in the lists of options, which blurs the
> following explanation.
>
> 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).

Thanks.