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