On Mon, Nov 18, 2024 at 10:05:49PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx>
>
> The documentation for git-diff has been updated to follow the new
> documentation guidelines. The following changes have been applied to
> the series of patches:
>
> - switching the synopsis to a synopsis block which will automatically
> format placeholders in italics and keywords in monospace
> - use _<placeholder>_ instead of <placeholder> in the description
> - use `backticks for keywords and more complex option
> descriptions`. The new rendering engine will apply synopsis rules to
> these spans.
> - prevent git-diff from self-referencing itself via gitlink macro when
> the generated link would point to the same page.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@xxxxxxx>
> ---
> Documentation/git-diff.txt | 122 ++++++++++++++++++++-----------------
> 1 file changed, 66 insertions(+), 56 deletions(-)
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index c065f023eca..e19f31e8b9d 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -8,13 +8,13 @@ git-diff - Show changes between commits, commit and working tree, etc
>
> SYNOPSIS
> --------
> -[verse]
> -'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>
> +[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>
Since this patch the synopsis in the man page looks like this when the
documentation is built with Asciidoctor:
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>__ [{empty}--{empty}]{empty} [__<path>__...]{empty}
{empty}`git diff [<options>] <blob> <blob>
git diff [<options>] --no-index [--] <path> <path>
I'm not sure what those '{empty}' strings are supposed to be, but they
shouldn't be there.
A similar issue is caused by 0b080a70ab (doc: git-diff: apply format
changes to diff-generate-patch, 2024-11-18) later in this series,
affecting all man pages that include 'diff-generate-patch.adoc':
2. It is followed by one or more extended header lines (this example shows a merge with two parents):
index <hash>,<hash>`..__<hash>__
{empty}`mode <mode>,<mode>``..``<mode>
new file mode <mode>
deleted file mode <mode>,<mode>
I use the distro packaged version of Asciidoctor:
$ asciidoctor --version
Asciidoctor 2.0.16 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
When the documentation is built with AsciiDoc (10.1.2) these all look
fine.
