Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Nov 12, 2024, 00:48 UTC
- Message-ID
- <xmqqo72l8egu.fsf@gitster.g>
- In-Reply-To
- <c104bd50b646646e980905a9294209f381b9e61c.1731343985.git.gitgitgadget@gmail.com>
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 7 quoted lines
> +[synopsis] > +git diff [<options>] [<commit>] [--] [<path>...] > +git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...] > +git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...] > +git diff [<options>] <commit>...<commit> [--] [<path>...] > +git diff [<options>] <blob> <blob> > +git diff [<options>] --no-index [--] <path> <path>
Again, not having to worry about `mark-up` _<rules>_ in SYNOPSIS section is very nice.
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.
Show 6 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?
> -<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?
Thanks.