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

From: Patrick Steinhardt <ps@pks.im>
Date: Aug 5, 2024, 09:11 UTC
Message-ID: <ZrCXK8AmGSFwyqI4@tanuki>
In-Reply-To: <515ddbf1dceacc0c186e3d31c13e76a5afc6c45f.1722801936.git.gitgitgadget@gmail.com>

On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget wrote:

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

Nit: please provide a summary of what adaptations you made. It would
certainly help the reviewer to learn about the recently-introduced
`[synopsis]` style and why/since when we use backticks and underscores
for formatting.

The same also applies to subsequent commits, providing some pointers would certainly help an unknowing reviewer such as myself.

Show 11 quoted lines

> @@ -225,11 +225,12 @@ CONFIGURATION
>  
>  include::includes/cmd-config-section-all.txt[]
>  
> +:git-diff: 1
>  include::config/diff.txt[]
>  
>  SEE ALSO
>  --------
> -diff(1),
> +`diff`(1),

This one looks curious to me. Why is this item formatted differently than the next three? I would have expected it to be formatted as something like linkgit:git-diff[1] instead of `diff`(1)`.

Patrick

Show 7 quoted lines

>  linkgit:git-difftool[1],
>  linkgit:git-log[1],
>  linkgit:gitdiffcore[7],
> -- 
> gitgitgadget
> 
>