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

[Patrick Steinhardt <ps@pks.im>]

On Sat, Jan 04, 2025 at 01:16:40PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> 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.

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

> @@ -122,30 +122,29 @@ in linkgit:git-checkout[1] for details.
>  	not be updated. Just like linkgit:git-checkout[1], this will detach
>  	`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
> +	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.

Thanks!

Patrick