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@xxxxxxx>
>
> 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
