Re: [PATCH v4 1/5] doc: git-diff: apply new documentation guidelines

From: SZEDER Gábor <szeder.dev@gmail.com>
Date: Mar 31, 2025, 09:37 UTC
Message-ID: <Z+piTsfJdx4BG2oI@szeder.dev>
In-Reply-To: <fd3ee137fe4f22eb864f1f972c216b7a7f05d0f9.1731967553.git.gitgitgadget@gmail.com>

On Mon, Nov 18, 2024 at 10:05:49PM +0000, Jean-Noël Avila via GitGitGadget wrote:

Show 42 quoted lines

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> 
> 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@free.fr>
> ---
>  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.