Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines
- From
Jean-Noël Avila <jn.avila@free.fr>
- Date
- Nov 12, 2024, 08:40 UTC
- Message-ID
- <7b42828a-2cbe-47c6-b21e-b8c1e3a2ad01@free.fr>
- In-Reply-To
- <xmqqo72l8egu.fsf@gitster.g>
Le 12/11/2024 à 01:48, Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 9 quoted lines
> > 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.
Show 10 quoted lines
> >> --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?
Show 8 quoted lines
>> -<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.