doc: git-notes.txt: migrate to new documentation format

[jnavila]

cc: Patrick Steinhardt ps@pks.im

[jnavila]

/submit

[gitgitgadget]

Submitted as pull.1846.git.1735924216993.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1846/jnavila/git-notes-new-format-v1

To fetch this version to local tag pr-1846/jnavila/git-notes-new-format-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1846/jnavila/git-notes-new-format-v1

[gitgitgadget]

This patch series was integrated into seen via git@fbb9a9f.

[gitgitgadget]

On the Git mailing list, Patrick Steinhardt wrote (reply to this):

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.

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

> 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,
..."?

> 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:`?

Thanks!

Patrick

[gitgitgadget]

User Patrick Steinhardt <ps@pks.im> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Patrick Steinhardt <ps@pks.im> writes:

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

Thanks.  I had exactly the same reaction to these patches, and I,
after reading all your responses to them, agree with you.

[gitgitgadget]

This branch is now known as ja/doc-notes-markup-updates.

[gitgitgadget]

This patch series was integrated into seen via git@068cb6a.

[gitgitgadget]

There was a status update in the "New Topics" section about the branch ja/doc-notes-markup-updates on the Git mailing list:

Doc mark-up updates.

source: <pull.1846.git.1735924216993.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@e32a6de.

[gitgitgadget]

On the Git mailing list, Jean-Noël AVILA wrote (reply to this):

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

[gitgitgadget]

This patch series was integrated into seen via git@deafbbe.

[gitgitgadget]

This patch series was integrated into seen via git@c7ddbe3.