Le 12/11/2024 à 01:48, Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
>
> You may already have explained the rules elsewhere, but please
> help me refresh my memory with some explanation.
>
>> -'git diff' [<options>] [--] [<path>...]::
>> +`git diff [<options>] [--] [<path>...]`::
>
> Here, we just say `everything in literal, including placeholders`,
> which is very pleasant for us writers.
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>_...]
All the keywords are literal, the placeholders are emphasized, and the
syntactic signs ('[', ']', '...') are left without formatting.
The general rule of thumb for the writer is: if it's a singled
placeholder then quote it with underscores, otherwise use back ticks
elsewhere.
>
>> --1 --base::
>> --2 --ours::
>> --3 --theirs::
>> +`-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?
>> -<path>...::
>> - The <paths> parameters, when given, are used to limit
>> +_<path>_...::
>
> This has to do the _italics_ for placeholders, unlike the full
> command line examples we saw earlier?
>
> Where does this difference come from?
Well, according to the rule of thumb above, the whole segment should
have been quoted in back ticks. This is a mistake and must be fixed for
consistency.
