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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Aug 5, 2024, 18:51 UTC
Message-ID: <5803739.DvuYhMxLoT@cayenne>
In-Reply-To: <ZrCXK8AmGSFwyqI4@tanuki>

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:

Show 11 quoted lines

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

Show 16 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)`.
>

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.

Show 6 quoted lines

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

Thanks