From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 12 Nov 2024 00:48:01 GMT
Subject: Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines
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:

> +[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.

> --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.