Re: [PATCH] doc: git-notes.txt: migrate to new documentation format

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

On Monday, 6 January 2025 08:00:01 CET Patrick Steinhardt wrote:
> On Fri, Jan 03, 2025 at 05:10:16PM +0000, Jean-Noël Avila via GitGitGadget 
wrote:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> > 
> > The git-notes manpage files were converted to the new documentation
> > format:
> > 
> > - 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.
> 
> I think it might be a bit easier to send related changes like this and
> your changes to git-restore(1) in a single patch series going forward.
> It allows the reviewer to bundle related reviews together, which
> requires less context switching. It also allows them to more easily
> refer to similar review feedbacks sent for preceding patches.
> 

For simple manpages, I'll do this from now on.

> Other than that I've got the same comments here regarding the style of
> the commit message as with your git-restore(1) patch. Ah, I also noticed
> that the subject should probably be amended because we don't typically
> specify multiple subsystems with colons. For example:
> 
>     Documentation: migrate git-restore(1) to new style format
> 

Will do.

> > diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
> > index 43db8e808d7..70859f5c574 100644
> > --- a/Documentation/config/notes.txt
> > +++ b/Documentation/config/notes.txt
> > @@ -26,27 +26,27 @@ globs.
> >  A warning will be issued for refs that do not exist,
> >  but a glob that does not match any refs is silently ignored.
> >  +
> > -This setting can be disabled by the `--no-notes` option to the 'git
> > -log' family of commands, or by the `--notes=<ref>` option accepted by
> > +This setting can be disabled by the `--no-notes` option to the `git
> > +log` family of commands, or by the `--notes=<ref>` option accepted by
> >  those commands.
> 
> Should this rather use "to the linkgit:git-log[1] family of commands,
> ..."?
> 

Nice catch, although not really the primary aim of this patch. Will fix.

> > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> > index 84022f99d76..02a3495986a 100644
> > --- a/Documentation/git-notes.txt
> > +++ b/Documentation/git-notes.txt
> > @@ -33,34 +33,34 @@ ENVIRONMENT sections below.  If this ref does not 
exist, it will be
> >  quietly created when it is first needed to store a note.
> >  
> >  A typical use of notes is to supplement a commit message without
> > -changing the commit itself. Notes can be shown by 'git log' along with
> > +changing the commit itself. Notes can be shown by `git log` along with
> >  the original commit message. To distinguish these notes from the
> >  message stored in the commit object, the notes are indented like the
> > -message, after an unindented line saying "Notes (<refname>):" (or
> > -"Notes:" for `refs/notes/commits`).
> > +message, after an unindented line saying "`Notes (<refname>):`" (or
> > +"`Notes:`" for `refs/notes/commits`).
> 
> Curious. I'm not familiar with the modern best practices around where to
> apply what kind of quoting, so why is it "`foo`" here and not `"foo"` or
> `foo:`?
> 

Good question. I usually tend to remove double quotes and replace them by back 
quotes when the words are keywords. Here this is a string citation, but I 
would still prefer to apply the synopsis formatting. Maybe, something lighter 
such as "Notes (_<refname>_):", which would just format the placeholder, would 
better fit.

JN