Re: [PATCH] doc: git-restore: migrate to new style format

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Jan 7, 2025, 21:48 UTC
Message-ID: <6011894.MhkbZ0Pkbq@cayenne>
In-Reply-To: <Z3t8sjsCeiPmHffA@pks.im>

On Monday, 6 January 2025 07:48:27 CET Patrick Steinhardt wrote:

> On Sat, Jan 04, 2025 at 01:16:40PM +0000, Jean-Noël Avila via GitGitGadget

wrote:

Show 21 quoted lines

> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> > 
> > The git-restore manpage was converted to the new documentation
> > format:
> 
> Commit messages should typically use imperative style, as if asking the
> code to change. For example:
> 
>   Convert the git-restore(1) man page to our new documentation format.
>   This includes the following conversions:
> 
>     - Switch 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.
>

Will do.

Show 11 quoted lines

> > diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
> > index 975825b44aa..541a39b5d28 100644
> > --- a/Documentation/git-restore.txt
> > +++ b/Documentation/git-restore.txt
> > @@ -41,79 +41,79 @@ OPTIONS
> >  If not specified, the contents are restored from `HEAD` if `--staged` is
> >  given, otherwise from the index.
> >  +
> > -As a special case, you may use `"A...B"` as a shortcut for the
> > -merge base of `A` and `B` if there is exactly one merge base. You can
> > -leave out at most one of `A` and `B`, in which case it defaults to

`HEAD`.

> > +As a special case, you may use `"<refA>...<refB>"` as a shortcut for the
> > +merge base of _<refA>_ and _<refB>_ if there is exactly one merge base.

You can

> > +leave out at most one of _<refA>__ and _<refB>_, in which case it

defaults to `HEAD`.

> 
> This change is a bit surprising to me though. Why was this renamed from
> A and B to refA and refB, respectively? It should be possible for these
> to be object IDs and not refs.

Sorry for mixing things up revs with refs. The "A" and "B" are just placeholders for revisions, and their names need to be more informative.

So, it should be <rev-A> and <rev-B> all along.

> 
> > @@ -122,30 +122,29 @@ in linkgit:git-checkout[1] for details.
> >  	not be updated. Just like linkgit:git-checkout[1], this will

detach

Show 16 quoted lines

> >  	`HEAD` of the submodule.
> >  
> > ---overlay::
> > ---no-overlay::
> > -	In overlay mode, the command never removes files when
> > -	restoring. In no-overlay mode, tracked files that do not
> > -	appear in the `--source` tree are removed, to make them match
> > -	`<tree>` exactly. The default is no-overlay mode.
> > -
> > ---pathspec-from-file=<file>::
> > -	Pathspec is passed in `<file>` instead of commandline args. If
> > -	`<file>` is exactly `-` then standard input is used. Pathspec
> > -	elements are separated by LF or CR/LF. Pathspec elements can be
> > +`--overlay`::
> > +`--no-overlay`::
> > +	In overlay mode, never remove files when restoring. In no-overlay

mode,

> > +	remove tracked files that do not appear in the `--source` tree, to

make

Show 6 quoted lines

> > +	them match _<tree>_ exactly. The default is no-overlay mode.
> > +
> > +`--pathspec-from-file=<file>`::
> > +	Pathspec is passed in _<file>_ instead of commandline args. If
> > +	_<file>_ is exactly `-` then standard input is used. Pathspec
> > +	elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can

be

> 
> The reflowing of these paragraphs makes it a bit hard to see what
> exactly is changing.
>

For the first set of options, there is a conversion to imperative mood, and I 
triggered a reflow.
 For the second one, it just appears that all lines are slightly changed by 
the new formatting.

More generally, I kept reflowing the paragraphs to maintain the width, because 
this was done everywhere before, but I would strongly prefer having each 
sentence on separate line, regardless of its length. For asciidoc texts, this 
policy has some advantages:
 * keep a lexical entity as a single line, and get rid messed up diffs due to 
reflowing.
 * unfortunate automatic reflows can create errors, for instance when a part of 
text is sent to the beginning of line and is interpreted as a list item.

JN