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

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Monday, 5 August 2024 11:11:07 CEST Patrick Steinhardt wrote:
> 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.
> 

Thanks for the remark. The context is effectively missing, so I'll restate it.

> > @@ -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)`.
> 

Here we are referring to the 'diff' command, not git-diff. That is why we don't 
use the linkgit macro (which is used to generate cross links for html output).

Still, the general format of a reference to a man-page is to put the command 
name in bold, which our filters get by backquoting. 

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

Thanks