[PATCH 0/9] doc: convert checkout, switch and merge to new format

[PATCH 0/9] doc: convert checkout, switch and merge to new format

[Jean-Noël Avila via GitGitGadget]

This is the follow-up in the conversion of the manpages to the synopsis
style.

This time, we address git checkout, git switch, git merge and git mergetool.

I added a small grammatical fixup in merge options.

Jean-Noël Avila (9):
  doc: convert git-checkout manpage to new style
  doc: convert git-merge manpage to new style
  doc: convert merge options to new synopsis format
  doc: merge-options.adoc remove a misleading double negation
  doc: convert merge strategies to synopsis format
  doc: switch merge config description to new synopsis format
  doc: convert git-mergetool manpage to new synopsis style
  doc: convert git-mergetool options to new synopsis style
  doc: convert git-switch manpage to new synopsis style

 Documentation/config/checkout.adoc      |  14 +-
 Documentation/config/fmt-merge-msg.adoc |   8 +-
 Documentation/config/merge.adoc         |  84 ++++-----
 Documentation/config/mergetool.adoc     |  54 +++---
 Documentation/git-checkout.adoc         | 228 ++++++++++++------------
 Documentation/git-merge.adoc            |  51 +++---
 Documentation/git-mergetool.adoc        |  62 +++----
 Documentation/git-switch.adoc           | 114 ++++++------
 Documentation/merge-options.adoc        | 110 ++++++------
 Documentation/merge-strategies.adoc     |  58 +++---
 Documentation/mergetools/vimdiff.adoc   |  16 +-
 Documentation/rerere-options.adoc       |   4 +-
 12 files changed, 403 insertions(+), 400 deletions(-)


base-commit: 845c48a16a7f7b2c44d8cb137b16a4a1f0140229
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1927%2Fjnavila%2Fcheckout_merge-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1927/jnavila/checkout_merge-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1927
-- 
gitgitgadget

[PATCH 1/9] doc: convert git-checkout manpage to new style

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/checkout.adoc |  14 +-
 Documentation/git-checkout.adoc    | 228 ++++++++++++++---------------
 2 files changed, 121 insertions(+), 121 deletions(-)

diff --git a/Documentation/config/checkout.adoc b/Documentation/config/checkout.adoc
index a32302299380..e35d21296978 100644
--- a/Documentation/config/checkout.adoc
+++ b/Documentation/config/checkout.adoc
@@ -1,9 +1,9 @@
-checkout.defaultRemote::
+`checkout.defaultRemote`::
 	When you run `git checkout <something>`
 	or `git switch <something>` and only have one
 	remote, it may implicitly fall back on checking out and
 	tracking e.g. `origin/<something>`. This stops working as soon
-	as you have more than one remote with a `<something>`
+	as you have more than one remote with a _<something>_
 	reference. This setting allows for setting the name of a
 	preferred remote that should always win when it comes to
 	disambiguation. The typical use-case is to set this to
@@ -12,17 +12,17 @@ checkout.defaultRemote::
 Currently this is used by linkgit:git-switch[1] and
 linkgit:git-checkout[1] when `git checkout <something>`
 or `git switch <something>`
-will checkout the `<something>` branch on another remote,
+will checkout the _<something>_ branch on another remote,
 and by linkgit:git-worktree[1] when `git worktree add` refers to a
 remote branch. This setting might be used for other checkout-like
 commands or functionality in the future.
 
-checkout.guess::
+`checkout.guess`::
 	Provides the default value for the `--guess` or `--no-guess`
 	option in `git checkout` and `git switch`. See
 	linkgit:git-switch[1] and linkgit:git-checkout[1].
 
-checkout.workers::
+`checkout.workers`::
 	The number of parallel workers to use when updating the working tree.
 	The default is one, i.e. sequential execution. If set to a value less
 	than one, Git will use as many workers as the number of logical cores
@@ -30,13 +30,13 @@ checkout.workers::
 	all commands that perform checkout. E.g. checkout, clone, reset,
 	sparse-checkout, etc.
 +
-Note: Parallel checkout usually delivers better performance for repositories
+NOTE: Parallel checkout usually delivers better performance for repositories
 located on SSDs or over NFS. For repositories on spinning disks and/or machines
 with a small number of cores, the default sequential checkout often performs
 better. The size and compression level of a repository might also influence how
 well the parallel version performs.
 
-checkout.thresholdForParallelism::
+`checkout.thresholdForParallelism`::
 	When running parallel checkout with a small number of files, the cost
 	of subprocess spawning and inter-process communication might outweigh
 	the parallelization gains. This setting allows you to define the minimum
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index a66c53a5cd1e..ee83b6d9ba9a 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -7,54 +7,54 @@ git-checkout - Switch branches or restore working tree files
 
 SYNOPSIS
 --------
-[verse]
-'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] --detach [<branch>]
-'git checkout' [-q] [-f] [-m] [--detach] <commit>
-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-'git checkout' [-f] <tree-ish> [--] <pathspec>...
-'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
-'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
+[synopsis]
+git checkout [-q] [-f] [-m] [<branch>]
+git checkout [-q] [-f] [-m] --detach [<branch>]
+git checkout [-q] [-f] [-m] [--detach] <commit>
+git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
+git checkout [-f] <tree-ish> [--] <pathspec>...
+git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
 Updates files in the working tree to match the version in the index
-or the specified tree.  If no pathspec was given, 'git checkout' will
+or the specified tree.  If no pathspec was given, `git checkout` will
 also update `HEAD` to set the specified branch as the current
 branch.
 
-'git checkout' [<branch>]::
-	To prepare for working on `<branch>`, switch to it by updating
+`git checkout [<branch>]`::
+	To prepare for working on _<branch>_, switch to it by updating
 	the index and the files in the working tree, and by pointing
 	`HEAD` at the branch. Local modifications to the files in the
 	working tree are kept, so that they can be committed to the
-	`<branch>`.
+	_<branch>_.
 +
-If `<branch>` is not found but there does exist a tracking branch in
-exactly one remote (call it `<remote>`) with a matching name and
+If _<branch>_ is not found but there does exist a tracking branch in
+exactly one remote (call it _<remote>_) with a matching name and
 `--no-guess` is not specified, treat as equivalent to
 +
 ------------
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
 +
-You could omit `<branch>`, in which case the command degenerates to
+You could omit _<branch>_, in which case the command degenerates to
 "check out the current branch", which is a glorified no-op with
 rather expensive side-effects to show only the tracking information,
 if it exists, for the current branch.
 
-'git checkout' -b|-B <new-branch> [<start-point>]::
+`git checkout (-b|-B) <new-branch> [<start-point>]`::
 
 	Specifying `-b` causes a new branch to be created as if
 	linkgit:git-branch[1] were called and then checked out.  In
 	this case you can use the `--track` or `--no-track` options,
-	which will be passed to 'git branch'.  As a convenience,
+	which will be passed to `git branch`.  As a convenience,
 	`--track` without `-b` implies branch creation; see the
 	description of `--track` below.
 +
-If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it
+If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it
 is reset. This is the transactional equivalent of
 +
 ------------
@@ -67,30 +67,30 @@ successful (e.g., when the branch is in use in another worktree, not
 just the current branch stays the same, but the branch is not reset to
 the start-point, either).
 
-'git checkout' --detach [<branch>]::
-'git checkout' [--detach] <commit>::
+`git checkout --detach [<branch>]`::
+`git checkout [--detach] <commit>`::
 
-	Prepare to work on top of `<commit>`, by detaching `HEAD` at it
+	Prepare to work on top of _<commit>_, by detaching `HEAD` at it
 	(see "DETACHED HEAD" section), and updating the index and the
 	files in the working tree.  Local modifications to the files
 	in the working tree are kept, so that the resulting working
 	tree will be the state recorded in the commit plus the local
 	modifications.
 +
-When the `<commit>` argument is a branch name, the `--detach` option can
+When the _<commit>_ argument is a branch name, the `--detach` option can
 be used to detach `HEAD` at the tip of the branch (`git checkout
 <branch>` would check out that branch without detaching `HEAD`).
 +
-Omitting `<branch>` detaches `HEAD` at the tip of the current branch.
+Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...::
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
 	Overwrite the contents of the files that match the pathspec.
-	When the `<tree-ish>` (most often a commit) is not given,
+	When the _<tree-ish>_ (most often a commit) is not given,
 	overwrite working tree with the contents in the index.
-	When the `<tree-ish>` is given, overwrite both the index and
-	the working tree with the contents at the `<tree-ish>`.
+	When the _<tree-ish>_ is given, overwrite both the index and
+	the working tree with the contents at the _<tree-ish>_.
 +
 The index may contain unmerged entries because of a previous failed merge.
 By default, if you try to check out such an entry from the index, the
@@ -100,7 +100,7 @@ specific side of the merge can be checked out of the index by
 using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
 file can be discarded to re-create the original conflicted merge result.
 
-'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
+`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
 	This is similar to the previous mode, but lets you use the
 	interactive interface to show the "diff" output and choose which
 	hunks to use in the result.  See below for the description of
@@ -108,19 +108,19 @@ file can be discarded to re-create the original conflicted merge result.
 
 OPTIONS
 -------
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Quiet, suppress feedback messages.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal, unless `--quiet`
 	is specified. This flag enables progress reporting even if not
 	attached to a terminal, regardless of `--quiet`.
 
--f::
---force::
+`-f`::
+`--force`::
 	When switching branches, proceed even if the index or the
 	working tree differs from `HEAD`, and even if there are untracked
 	files in the way.  This is used to throw away local changes and
@@ -129,13 +129,13 @@ OPTIONS
 When checking out paths from the index, do not fail upon unmerged
 entries; instead, unmerged entries are ignored.
 
---ours::
---theirs::
+`--ours`::
+`--theirs`::
 	When checking out paths from the index, check out stage #2
-	('ours') or #3 ('theirs') for unmerged paths.
+	(`ours`) or #3 (`theirs`) for unmerged paths.
 +
-Note that during `git rebase` and `git pull --rebase`, 'ours' and
-'theirs' may appear swapped; `--ours` gives the version from the
+Note that during `git rebase` and `git pull --rebase`, `ours` and
+`theirs` may appear swapped; `--ours` gives the version from the
 branch the changes are rebased onto, while `--theirs` gives the
 version from the branch that holds your work that is being rebased.
 +
@@ -149,22 +149,22 @@ as `ours` (i.e. "our shared canonical history"), while what you did
 on your side branch as `theirs` (i.e. "one contributor's work on top
 of it").
 
--b <new-branch>::
-	Create a new branch named `<new-branch>`, start it at
-	`<start-point>`, and check the resulting branch out;
+`-b <new-branch>`::
+	Create a new branch named _<new-branch>_, start it at
+	_<start-point>_, and check the resulting branch out;
 	see linkgit:git-branch[1] for details.
 
--B <new-branch>::
-	Creates the branch `<new-branch>`, start it at `<start-point>`;
-	if it already exists, then reset it to `<start-point>`. And then
+`-B <new-branch>`::
+	Creates the branch _<new-branch>_, start it at _<start-point>_;
+	if it already exists, then reset it to _<start-point>_. And then
 	check the resulting branch out.  This is equivalent to running
-	"git branch" with "-f" followed by "git checkout" of that branch;
+	`git branch` with `-f` followed by `git checkout` of that branch;
 	see linkgit:git-branch[1] for details.
 
--t::
---track[=(direct|inherit)]::
+`-t`::
+`--track[=(direct|inherit)]`::
 	When creating a new branch, set up "upstream" configuration. See
-	"--track" in linkgit:git-branch[1] for details.
+	`--track` in linkgit:git-branch[1] for details.
 +
 If no `-b` option is given, the name of the new branch will be
 derived from the remote-tracking branch, by looking at the local part of
@@ -176,14 +176,14 @@ off of `origin/hack` (or `remotes/origin/hack`, or even
 guessing results in an empty name, the guessing is aborted.  You can
 explicitly give a name with `-b` in such a case.
 
---no-track::
+`--no-track`::
 	Do not set up "upstream" configuration, even if the
 	`branch.autoSetupMerge` configuration variable is true.
 
---guess::
---no-guess::
-	If `<branch>` is not found but there does exist a tracking
-	branch in exactly one remote (call it `<remote>`) with a
+`--guess`::
+`--no-guess`::
+	If _<branch>_ is not found but there does exist a tracking
+	branch in exactly one remote (call it _<remote>_) with a
 	matching name, treat as equivalent to
 +
 ------------
@@ -192,10 +192,10 @@ $ git checkout -b <branch> --track <remote>/<branch>
 +
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
-one for the purposes of disambiguation, even if the `<branch>` isn't
+one for the purposes of disambiguation, even if the _<branch>_ isn't
 unique across all remotes. Set it to
 e.g. `checkout.defaultRemote=origin` to always checkout remote
-branches from there if `<branch>` is ambiguous but exists on the
+branches from there if _<branch>_ is ambiguous but exists on the
 'origin' remote. See also `checkout.defaultRemote` in
 linkgit:git-config[1].
 +
@@ -204,28 +204,28 @@ linkgit:git-config[1].
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
--l::
+`-l`::
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
 
--d::
---detach::
+`-d`::
+`--detach`::
 	Rather than checking out a branch to work on it, check out a
 	commit for inspection and discardable experiments.
 	This is the default behavior of `git checkout <commit>` when
-	`<commit>` is not a branch name.  See the "DETACHED HEAD" section
+	_<commit>_ is not a branch name.  See the "DETACHED HEAD" section
 	below for details.
 
---orphan <new-branch>::
-	Create a new unborn branch, named `<new-branch>`, started from
-	`<start-point>` and switch to it.  The first commit made on this
+`--orphan <new-branch>`::
+	Create a new unborn branch, named _<new-branch>_, started from
+	_<start-point>_ and switch to it.  The first commit made on this
 	new branch will have no parents and it will be the root of a new
 	history totally disconnected from all the other branches and
 	commits.
 +
 The index and the working tree are adjusted as if you had previously run
 `git checkout <start-point>`.  This allows you to start a new history
-that records a set of paths similar to `<start-point>` by easily running
+that records a set of paths similar to _<start-point>_ by easily running
 `git commit -a` to make the root commit.
 +
 This can be useful when you want to publish the tree from a commit
@@ -235,20 +235,20 @@ whose full history contains proprietary or otherwise encumbered bits of
 code.
 +
 If you want to start a disconnected history that records a set of paths
-that is totally different from the one of `<start-point>`, then you should
+that is totally different from the one of _<start-point>_, then you should
 clear the index and the working tree right after creating the orphan
 branch by running `git rm -rf .` from the top level of the working tree.
 Afterwards you will be ready to prepare your new files, repopulating the
 working tree, by copying them from elsewhere, extracting a tarball, etc.
 
---ignore-skip-worktree-bits::
-	In sparse checkout mode, `git checkout -- <paths>` would
-	update only entries matched by `<paths>` and sparse patterns
+`--ignore-skip-worktree-bits`::
+	In sparse checkout mode, `git checkout -- <path>...` would
+	update only entries matched by _<paths>_ and sparse patterns
 	in `$GIT_DIR/info/sparse-checkout`. This option ignores
-	the sparse patterns and adds back any files in `<paths>`.
+	the sparse patterns and adds back any files in `<path>...`.
 
--m::
---merge::
+`-m`::
+`--merge`::
 	When switching branches,
 	if you have local modifications to one or more files that
 	are different between the current branch and the branch to
@@ -269,40 +269,40 @@ used when checking out paths from a tree-ish.
 +
 When switching branches with `--merge`, staged changes may be lost.
 
---conflict=<style>::
+`--conflict=<style>`::
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values are
-	"merge" (default), "diff3", and "zdiff3".
+	`merge` (default), `diff3`, and `zdiff3`.
 
--p::
---patch::
+`-p`::
+`--patch`::
 	Interactively select hunks in the difference between the
-	`<tree-ish>` (or the index, if unspecified) and the working
+	_<tree-ish>_ (or the index, if unspecified) and the working
 	tree.  The chosen hunks are then applied in reverse to the
-	working tree (and if a `<tree-ish>` was specified, the index).
+	working tree (and if a _<tree-ish>_ was specified, the index).
 +
 This means that you can use `git checkout -p` to selectively discard
-edits from your current working tree. See the ``Interactive Mode''
+edits from your current working tree. See the "Interactive Mode"
 section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
 +
 Note that this option uses the no overlay mode by default (see also
 `--overlay`), and currently doesn't support overlay mode.
 
---ignore-other-worktrees::
+`--ignore-other-worktrees`::
 	`git checkout` refuses when the wanted branch is already checked
 	out or otherwise in use by another worktree. This option makes
 	it check the branch out anyway. In other words, the branch can
 	be in use by more than one worktree.
 
---overwrite-ignore::
---no-overwrite-ignore::
+`--overwrite-ignore`::
+`--no-overwrite-ignore`::
 	Silently overwrite ignored files when switching branches. This
 	is the default behavior. Use `--no-overwrite-ignore` to abort
 	the operation when the new branch contains ignored files.
 
---recurse-submodules::
---no-recurse-submodules::
+`--recurse-submodules`::
+`--no-recurse-submodules`::
 	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
@@ -311,25 +311,25 @@ Note that this option uses the no overlay mode by default (see also
 	Just like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodule.
 
---overlay::
---no-overlay::
+`--overlay`::
+`--no-overlay`::
 	In the default overlay mode, `git checkout` never
 	removes files from the index or the working tree.  When
 	specifying `--no-overlay`, files that appear in the index and
-	working tree, but not in `<tree-ish>` are removed, to make them
-	match `<tree-ish>` exactly.
+	working tree, but not in _<tree-ish>_ are removed, to make them
+	match _<tree-ish>_ exactly.
 
---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
+`--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
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 	global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	Only meaningful with `--pathspec-from-file`. Pathspec elements are
-	separated with NUL character and all other characters are taken
+	separated with _NUL_ character and all other characters are taken
 	literally (including newlines and quotes).
 
 <branch>::
@@ -343,33 +343,33 @@ You can use the `@{-N}` syntax to refer to the N-th last
 branch/commit checked out using "git checkout" operation. You may
 also specify `-` which is synonymous to `@{-1}`.
 +
-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 `<rev-a>...<rev-b>` as a shortcut for the
+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
 
-<new-branch>::
+_<new-branch>_::
 	Name for the new branch.
 
-<start-point>::
+_<start-point>_::
 	The name of a commit at which to start the new branch; see
 	linkgit:git-branch[1] for details. Defaults to `HEAD`.
 +
-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 `<rev-a>...<rev-b>` as a shortcut for the
+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
 
-<tree-ish>::
+_<tree-ish>_::
 	Tree to checkout from (when paths are given). If not specified,
 	the index will be used.
 +
-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 `<rev-a>...<rev-b>` as a shortcut for the
+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
 
-\--::
+`--`::
 	Do not interpret any more arguments as options.
 
-<pathspec>...::
+`<pathspec>...`::
 	Limits the paths affected by the operation.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -391,7 +391,7 @@ a---b---c  branch 'master' (refers to commit 'c')
 ------------
 
 When a commit is created in this state, the branch is updated to refer to
-the new commit. Specifically, 'git commit' creates a new commit `d`, whose
+the new commit. Specifically, `git commit` creates a new commit `d`, whose
 parent is commit `c`, and then updates branch `master` to refer to new
 commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers
 to commit `d`:
@@ -510,11 +510,11 @@ ARGUMENT DISAMBIGUATION
 -----------------------
 
 When there is only one argument given and it is not `--` (e.g. `git
-checkout abc`), and when the argument is both a valid `<tree-ish>`
-(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file
+checkout abc`), and when the argument is both a valid _<tree-ish>_
+(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file
 or a directory whose name is "abc" exists), Git would usually ask
 you to disambiguate.  Because checking out a branch is so common an
-operation, however, `git checkout abc` takes "abc" as a `<tree-ish>`
+operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_
 in such a situation.  Use `git checkout -- <pathspec>` if you want
 to checkout these paths out of the index.
 
-- 
gitgitgadget

[PATCH 2/9] doc: convert git-merge manpage to new style

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

In order to avoid breaking the format on '<<<<<<' and '>>>>>' lines
by applying the synopsis rules to these spans, they are formatted using '+'
signs instead of '`' signs.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-merge.adoc | 51 ++++++++++++++++++------------------
 1 file changed, 25 insertions(+), 26 deletions(-)

diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc
index 64281d6d44dd..12aa859d16de 100644
--- a/Documentation/git-merge.adoc
+++ b/Documentation/git-merge.adoc
@@ -8,13 +8,13 @@ git-merge - Join two or more development histories together
 
 SYNOPSIS
 --------
-[verse]
-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
+[synopsis]
+git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
 	[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
 	[--[no-]allow-unrelated-histories]
 	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
 	[--into-name <branch>] [<commit>...]
-'git merge' (--continue | --abort | --quit)
+git merge (--continue | --abort | --quit)
 
 DESCRIPTION
 -----------
@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified
 after the merge was started), `git merge --abort` will in some cases be
 unable to reconstruct the original (pre-merge) changes. Therefore:
 
-*Warning*: Running `git merge` with non-trivial uncommitted changes is
+WARNING: Running `git merge` with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
@@ -67,7 +67,7 @@ OPTIONS
 
 include::merge-options.adoc[]
 
--m <msg>::
+`-m <msg>`::
 	Set the commit message to be used for the merge commit (in
 	case one is created).
 +
@@ -78,13 +78,13 @@ The `git fmt-merge-msg` command can be
 used to give a good default for automated `git merge`
 invocations. The automated message can include the branch description.
 
---into-name <branch>::
+`--into-name <branch>`::
 	Prepare the default merge message as if merging to the branch
-	`<branch>`, instead of the name of the real branch to which
+	_<branch>_, instead of the name of the real branch to which
 	the merge is made.
 
--F <file>::
---file=<file>::
+`-F <file>`::
+`--file=<file>`::
 	Read the commit message to be used for the merge commit (in
 	case one is created).
 +
@@ -93,12 +93,12 @@ will be appended to the specified message.
 
 include::rerere-options.adoc[]
 
---overwrite-ignore::
---no-overwrite-ignore::
+`--overwrite-ignore`::
+`--no-overwrite-ignore`::
 	Silently overwrite ignored files from the merge result. This
 	is the default behavior. Use `--no-overwrite-ignore` to abort.
 
---abort::
+`--abort`::
 	Abort the current conflict resolution process, and
 	try to reconstruct the pre-merge state. If an autostash entry is
 	present, apply it to the worktree.
@@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree
 whereas `git reset --merge` will save the stashed changes in the stash
 list.
 
---quit::
+`--quit`::
 	Forget about the current merge in progress. Leave the index
 	and the working tree as-is. If `MERGE_AUTOSTASH` is present, the
 	stash entry will be saved to the stash list.
 
---continue::
+`--continue`::
 	After a `git merge` stops due to conflicts you can conclude the
 	merge by running `git merge --continue` (see "HOW TO RESOLVE
 	CONFLICTS" section below).
 
-<commit>...::
+`<commit>...`::
 	Commits, usually other branch heads, to merge into our branch.
 	Specifying more than one commit will create a merge with
 	more than two parents (affectionately called an Octopus merge).
@@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit,
 `git pull` and `git merge` will also abort if there are any changes
 registered in the index relative to the `HEAD` commit.  (Special
 narrow exceptions to this rule may exist depending on which merge
-strategy is in use, but generally, the index must match HEAD.)
+strategy is in use, but generally, the index must match `HEAD`.)
 
 If all named commits are already ancestors of `HEAD`, `git merge`
 will exit early with the message "Already up to date."
@@ -195,11 +195,11 @@ happens:
    stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the merge operation; i.e. 3-way
-   merge results with familiar conflict markers `<<<` `===` `>>>`.
+   merge results with familiar conflict markers +<<<+ `===` +>>>+.
 5. A ref named `AUTO_MERGE` is written, pointing to a tree
    corresponding to the current content of the working tree (including
    conflict markers for textual conflicts).  Note that this ref is only
-   written when the 'ort' merge strategy is used (the default).
+   written when the `ort` merge strategy is used (the default).
 6. No other changes are made.  In particular, the local
    modifications you had before you started merge will stay the
    same and the index entries for them stay as they were,
@@ -231,7 +231,6 @@ git merge v1.2.3^0
 git merge --ff-only v1.2.3
 ----
 
-
 HOW CONFLICTS ARE PRESENTED
 ---------------------------
 
@@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified.
 ------------
 
 The area where a pair of conflicting changes happened is marked with markers
-`<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`
++<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`
 is typically your side, and the part afterwards is typically their side.
 
 The default format does not show what the original said in the conflicting
@@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the
 other side wants to claim it is easy.
 
 An alternative style can be used by setting the `merge.conflictStyle`
-configuration variable to either "diff3" or "zdiff3".  In "diff3"
+configuration variable to either `diff3` or `zdiff3`.  In `diff3`
 style, the above conflict may look like this:
 
 ------------
@@ -290,7 +289,7 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-while in "zdiff3" style, it may look like this:
+while in `zdiff3` style, it may look like this:
 
 ------------
 Here are lines that are either unchanged from the common
@@ -308,8 +307,8 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
-another `|||||||` marker that is followed by the original text.  You can
+In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
+another +|||||||+ marker that is followed by the original text.  You can
 tell that the original just stated a fact, and your side simply gave in to
 that statement and gave up, while the other side tried to have a more
 positive attitude.  You can sometimes come up with a better resolution by
@@ -390,8 +389,8 @@ include::merge-strategies.adoc[]
 CONFIGURATION
 -------------
 
-branch.<name>.mergeOptions::
-	Sets default options for merging into branch <name>. The syntax and
+`branch.<name>.mergeOptions`::
+	Sets default options for merging into branch _<name>_. The syntax and
 	supported options are the same as those of `git merge`, but option
 	values containing whitespace characters are currently not supported.
 
-- 
gitgitgadget

[PATCH 3/9] doc: convert merge options to new synopsis format

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/merge-options.adoc  | 108 +++++++++++++++---------------
 Documentation/rerere-options.adoc |   4 +-
 2 files changed, 56 insertions(+), 56 deletions(-)

diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc
index 0022185201fc..9b3c7d6df4ef 100644
--- a/Documentation/merge-options.adoc
+++ b/Documentation/merge-options.adoc
@@ -1,23 +1,23 @@
---commit::
---no-commit::
+`--commit`::
+`--no-commit`::
 	Perform the merge and commit the result. This option can
-	be used to override --no-commit.
+	be used to override `--no-commit`.
 ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 +
-With --no-commit perform the merge and stop just before creating
+With `--no-commit` perform the merge and stop just before creating
 a merge commit, to give the user a chance to inspect and further
 tweak the merge result before committing.
 +
 Note that fast-forward updates do not create a merge commit and
-therefore there is no way to stop those merges with --no-commit.
+therefore there is no way to stop those merges with `--no-commit`.
 Thus, if you want to ensure your branch is not changed or updated
-by the merge command, use --no-ff with --no-commit.
+by the merge command, use `--no-ff` with `--no-commit`.
 
---edit::
--e::
---no-edit::
+`--edit`::
+`-e`::
+`--no-edit`::
 	Invoke an editor before committing successful mechanical merge to
 	further edit the auto-generated merge message, so that the user
 	can explain and justify the merge. The `--no-edit` option can be
@@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the
 updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be
 set to `no` at the beginning of them.
 
---cleanup=<mode>::
+`--cleanup=<mode>`::
 	This option determines how the merge message will be cleaned up before
 	committing. See linkgit:git-commit[1] for more details. In addition, if
-	the '<mode>' is given a value of `scissors`, scissors will be appended
+	the _<mode>_ is given a value of `scissors`, scissors will be appended
 	to `MERGE_MSG` before being passed on to the commit machinery in the
 	case of a merge conflict.
 
 ifdef::git-merge[]
---ff::
---no-ff::
---ff-only::
+`--ff`::
+`--no-ff`::
+`--ff-only`::
 	Specifies how a merge is handled when the merged-in history is
 	already a descendant of the current history.  `--ff` is the
 	default unless merging an annotated (and possibly signed) tag
@@ -53,13 +53,13 @@ ifdef::git-merge[]
 	hierarchy, in which case `--no-ff` is assumed.
 endif::git-merge[]
 ifdef::git-pull[]
---ff-only::
+`--ff-only`::
 	Only update to the new history if there is no divergent local
 	history.  This is the default when no method for reconciling
 	divergent histories is provided (via the --rebase=* flags).
 
---ff::
---no-ff::
+`--ff`::
+`--no-ff`::
 	When merging rather than rebasing, specifies how a merge is
 	handled when the merged-in history is already a descendant of
 	the current history.  If merging is requested, `--ff` is the
@@ -81,40 +81,40 @@ With `--ff-only`, resolve the merge as a fast-forward when possible.
 When not possible, refuse to merge and exit with a non-zero status.
 endif::git-merge[]
 
--S[<keyid>]::
---gpg-sign[=<keyid>]::
---no-gpg-sign::
-	GPG-sign the resulting merge commit. The `keyid` argument is
+`-S[<key-id>]`::
+`--gpg-sign[=<key-id>]`::
+`--no-gpg-sign`::
+	GPG-sign the resulting merge commit. The _<key-id>_ argument is
 	optional and defaults to the committer identity; if specified,
 	it must be stuck to the option without a space. `--no-gpg-sign`
 	is useful to countermand both `commit.gpgSign` configuration variable,
 	and earlier `--gpg-sign`.
 
---log[=<n>]::
---no-log::
+`--log[=<n>]`::
+`--no-log`::
 	In addition to branch names, populate the log message with
-	one-line descriptions from at most <n> actual commits that are being
+	one-line descriptions from at most _<n>_ actual commits that are being
 	merged. See also linkgit:git-fmt-merge-msg[1].
 ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 +
-With --no-log do not list one-line descriptions from the
+With `--no-log` do not list one-line descriptions from the
 actual commits being merged.
 
 include::signoff-option.adoc[]
 
---stat::
--n::
---no-stat::
+`--stat`::
+`-n`::
+`--no-stat`::
 	Show a diffstat at the end of the merge. The diffstat is also
 	controlled by the configuration option merge.stat.
 +
-With -n or --no-stat do not show a diffstat at the end of the
+With `-n` or `--no-stat` do not show a diffstat at the end of the
 merge.
 
---squash::
---no-squash::
+`--squash`::
+`--no-squash`::
 	Produce the working tree and index state as if a real merge
 	happened (except for the merge information), but do not actually
 	make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`
@@ -123,16 +123,16 @@ merge.
 	the current branch whose effect is the same as merging another
 	branch (or more in case of an octopus).
 +
-With --no-squash perform the merge and commit the result. This
-option can be used to override --squash.
+With `--no-squash` perform the merge and commit the result. This
+option can be used to override `--squash`.
 +
-With --squash, --commit is not allowed, and will fail.
+With `--squash`, `--commit` is not allowed, and will fail.
 ifdef::git-pull[]
 +
 Only useful when merging.
 endif::git-pull[]
 
---[no-]verify::
+`--[no-]verify`::
 	By default, the pre-merge and commit-msg hooks are run.
 	When `--no-verify` is given, these are bypassed.
 	See also linkgit:githooks[5].
@@ -140,21 +140,21 @@ ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 
--s <strategy>::
---strategy=<strategy>::
+`-s <strategy>`::
+`--strategy=<strategy>`::
 	Use the given merge strategy; can be supplied more than
 	once to specify them in the order they should be tried.
 	If there is no `-s` option, a built-in list of strategies
 	is used instead (`ort` when merging a single head,
 	`octopus` otherwise).
 
--X <option>::
---strategy-option=<option>::
+`-X <option>`::
+`--strategy-option=<option>`::
 	Pass merge strategy specific option through to the merge
 	strategy.
 
---verify-signatures::
---no-verify-signatures::
+`--verify-signatures`::
+`--no-verify-signatures`::
 	Verify that the tip commit of the side branch being merged is
 	signed with a valid key, i.e. a key that has a valid uid: in the
 	default trust model, this means the signing key has been signed by
@@ -165,22 +165,22 @@ ifdef::git-pull[]
 Only useful when merging.
 endif::git-pull[]
 
---summary::
---no-summary::
-	Synonyms to --stat and --no-stat; these are deprecated and will be
+`--summary`::
+`--no-summary`::
+	Synonyms to `--stat` and `--no-stat`; these are deprecated and will be
 	removed in the future.
 
 ifndef::git-pull[]
--q::
---quiet::
-	Operate quietly. Implies --no-progress.
+`-q`::
+`--quiet`::
+	Operate quietly. Implies `--no-progress`.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Be verbose.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Turn progress on/off explicitly. If neither is specified,
 	progress is shown if standard error is connected to a terminal.
 	Note that not all merge strategies may support progress
@@ -188,8 +188,8 @@ ifndef::git-pull[]
 
 endif::git-pull[]
 
---autostash::
---no-autostash::
+`--autostash`::
+`--no-autostash`::
 	Automatically create a temporary stash entry before the operation
 	begins, record it in the ref `MERGE_AUTOSTASH`
 	and apply it after the operation ends.  This means
@@ -197,7 +197,7 @@ endif::git-pull[]
 	with care: the final stash application after a successful
 	merge might result in non-trivial conflicts.
 
---allow-unrelated-histories::
+`--allow-unrelated-histories`::
 	By default, `git merge` command refuses to merge histories
 	that do not share a common ancestor.  This option can be
 	used to override this safety when merging histories of two
diff --git a/Documentation/rerere-options.adoc b/Documentation/rerere-options.adoc
index c3321ddea248..b0b920144a6c 100644
--- a/Documentation/rerere-options.adoc
+++ b/Documentation/rerere-options.adoc
@@ -1,5 +1,5 @@
---rerere-autoupdate::
---no-rerere-autoupdate::
+`--rerere-autoupdate`::
+`--no-rerere-autoupdate`::
 	After the rerere mechanism reuses a recorded resolution on
 	the current conflict to update the files in the working
 	tree, allow it to also update the index with the result of
-- 
gitgitgadget

[PATCH 4/9] doc: merge-options.adoc remove a misleading double negation

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/merge-options.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/merge-options.adoc b/Documentation/merge-options.adoc
index 9b3c7d6df4ef..078f4f6157a1 100644
--- a/Documentation/merge-options.adoc
+++ b/Documentation/merge-options.adoc
@@ -203,7 +203,7 @@ endif::git-pull[]
 	used to override this safety when merging histories of two
 	projects that started their lives independently. As that is
 	a very rare occasion, no configuration variable to enable
-	this by default exists and will not be added.
+	this by default exists or will be added.
 ifdef::git-pull[]
 +
 Only useful when merging.
-- 
gitgitgadget

[PATCH 5/9] doc: convert merge strategies to synopsis format

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/merge-strategies.adoc | 58 ++++++++++++++---------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc
index 9e034f447e76..2ba43f84e709 100644
--- a/Documentation/merge-strategies.adoc
+++ b/Documentation/merge-strategies.adoc
@@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option.  Some strategies
 can also take their own options, which can be passed by giving `-X<option>`
 arguments to `git merge` and/or `git pull`.
 
-ort::
+`ort`::
 	This is the default merge strategy when pulling or merging one
 	branch.  This strategy can only resolve two heads using a
 	3-way merge algorithm.  When there is more than one common
@@ -29,26 +29,26 @@ descendant. Otherwise, Git will treat this case as a conflict, suggesting
 as a resolution a submodule commit that is descendant of the conflicting
 ones, if one exists.
 +
-The 'ort' strategy can take the following options:
+The `ort` strategy can take the following options:
 
-ours;;
+`ours`;;
 	This option forces conflicting hunks to be auto-resolved cleanly by
 	favoring 'our' version.  Changes from the other tree that do not
 	conflict with our side are reflected in the merge result.
 	For a binary file, the entire contents are taken from our side.
 +
-This should not be confused with the 'ours' merge strategy, which does not
+This should not be confused with the `ours` merge strategy, which does not
 even look at what the other tree contains at all.  It discards everything
 the other tree did, declaring 'our' history contains all that happened in it.
 
-theirs;;
-	This is the opposite of 'ours'; note that, unlike 'ours', there is
-	no 'theirs' merge strategy to confuse this merge option with.
+`theirs`;;
+	This is the opposite of `ours`; note that, unlike `ours`, there is
+	no `theirs` merge strategy to confuse this merge option with.
 
-ignore-space-change;;
-ignore-all-space;;
-ignore-space-at-eol;;
-ignore-cr-at-eol;;
+`ignore-space-change`;;
+`ignore-all-space`;;
+`ignore-space-at-eol`;;
+`ignore-cr-at-eol`;;
 	Treats lines with the indicated type of whitespace change as
 	unchanged for the sake of a three-way merge.  Whitespace
 	changes mixed with other changes to a line are not ignored.
@@ -61,7 +61,7 @@ ignore-cr-at-eol;;
   version includes a substantial change, 'their' version is used;
 * Otherwise, the merge proceeds in the usual way.
 
-renormalize;;
+`renormalize`;;
 	This runs a virtual check-out and check-in of all three stages
 	of any file which needs a three-way merge.  This option is
 	meant to be used when merging branches with different clean
@@ -69,31 +69,31 @@ renormalize;;
 	branches with differing checkin/checkout attributes" in
 	linkgit:gitattributes[5] for details.
 
-no-renormalize;;
+`no-renormalize`;;
 	Disables the `renormalize` option.  This overrides the
 	`merge.renormalize` configuration variable.
 
-find-renames[=<n>];;
+`find-renames[=<n>]`;;
 	Turn on rename detection, optionally setting the similarity
 	threshold.  This is the default. This overrides the
-	'merge.renames' configuration variable.
+	`merge.renames` configuration variable.
 	See also linkgit:git-diff[1] `--find-renames`.
 
-rename-threshold=<n>;;
+`rename-threshold=<n>`;;
 	Deprecated synonym for `find-renames=<n>`.
 
-no-renames;;
+`no-renames`;;
 	Turn off rename detection. This overrides the `merge.renames`
 	configuration variable.
 	See also linkgit:git-diff[1] `--no-renames`.
 
-histogram;;
+`histogram`;;
 	Deprecated synonym for `diff-algorithm=histogram`.
 
-patience;;
+`patience`;;
 	Deprecated synonym for `diff-algorithm=patience`.
 
-diff-algorithm=[histogram|minimal|myers|patience];;
+`diff-algorithm=(histogram|minimal|myers|patience)`;;
 	Use a different diff algorithm while merging, which can help
 	avoid mismerges that occur due to unimportant matching lines
 	(such as braces from distinct functions).  See also
@@ -101,49 +101,49 @@ diff-algorithm=[histogram|minimal|myers|patience];;
 	defaults to `diff-algorithm=histogram`, while regular diffs
 	currently default to the `diff.algorithm` config setting.
 
-subtree[=<path>];;
+`subtree[=<path>]`;;
 	This option is a more advanced form of 'subtree' strategy, where
 	the strategy makes a guess on how two trees must be shifted to
 	match with each other when merging.  Instead, the specified path
 	is prefixed (or stripped from the beginning) to make the shape of
 	two trees to match.
 
-recursive::
+`recursive`::
 	This is now a synonym for `ort`.  It was an alternative
 	implementation until v2.49.0, but was redirected to mean `ort`
 	in v2.50.0.  The previous recursive strategy was the default
 	strategy for resolving two heads from Git v0.99.9k until
 	v2.33.0.
 
-resolve::
+`resolve`::
 	This can only resolve two heads (i.e. the current branch
 	and another branch you pulled from) using a 3-way merge
 	algorithm.  It tries to carefully detect criss-cross
 	merge ambiguities.  It does not handle renames.
 
-octopus::
+`octopus`::
 	This resolves cases with more than two heads, but refuses to do
 	a complex merge that needs manual resolution.  It is
 	primarily meant to be used for bundling topic branch
 	heads together.  This is the default merge strategy when
 	pulling or merging more than one branch.
 
-ours::
+`ours`::
 	This resolves any number of heads, but the resulting tree of the
 	merge is always that of the current branch head, effectively
 	ignoring all changes from all other branches.  It is meant to
 	be used to supersede old development history of side
-	branches.  Note that this is different from the -Xours option to
-	the 'ort' merge strategy.
+	branches.  Note that this is different from the `-Xours` option to
+	the `ort` merge strategy.
 
-subtree::
+`subtree`::
 	This is a modified `ort` strategy. When merging trees A and
 	B, if B corresponds to a subtree of A, B is first adjusted to
 	match the tree structure of A, instead of reading the trees at
 	the same level. This adjustment is also done to the common
 	ancestor tree.
 
-With the strategies that use 3-way merge (including the default, 'ort'),
+With the strategies that use 3-way merge (including the default, `ort`),
 if a change is made on both branches, but later reverted on one of the
 branches, that change will be present in the merged result; some people find
 this behavior confusing.  It occurs because only the heads and the merge base
-- 
gitgitgadget

[PATCH 6/9] doc: switch merge config description to new synopsis format

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Additionally, a list of option possible values has been reformatted as a
standalone definition list.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/fmt-merge-msg.adoc |  8 +--
 Documentation/config/merge.adoc         | 84 +++++++++++++------------
 2 files changed, 48 insertions(+), 44 deletions(-)

diff --git a/Documentation/config/fmt-merge-msg.adoc b/Documentation/config/fmt-merge-msg.adoc
index 3fbf40e24f62..696ba0531ae1 100644
--- a/Documentation/config/fmt-merge-msg.adoc
+++ b/Documentation/config/fmt-merge-msg.adoc
@@ -1,19 +1,19 @@
-merge.branchdesc::
+`merge.branchdesc`::
 	In addition to branch names, populate the log message with
 	the branch description text associated with them.  Defaults
 	to false.
 
-merge.log::
+`merge.log`::
 	In addition to branch names, populate the log message with at
 	most the specified number of one-line descriptions from the
 	actual commits that are being merged.  Defaults to false, and
 	true is a synonym for 20.
 
-merge.suppressDest::
+`merge.suppressDest`::
 	By adding a glob that matches the names of integration
 	branches to this multi-valued configuration variable, the
 	default merge message computed for merges into these
-	integration branches will omit "into <branch name>" from
+	integration branches will omit "into _<branch-name>_" from
 	its title.
 +
 An element with an empty value can be used to clear the list
diff --git a/Documentation/config/merge.adoc b/Documentation/config/merge.adoc
index d2d0f21a712d..86359f6dd2d9 100644
--- a/Documentation/config/merge.adoc
+++ b/Documentation/config/merge.adoc
@@ -1,9 +1,9 @@
-merge.conflictStyle::
+`merge.conflictStyle`::
 	Specify the style in which conflicted hunks are written out to
 	working tree files upon merge.  The default is "merge", which
-	shows a `<<<<<<<` conflict marker, changes made by one side,
+	shows a +<<<<<<<+ conflict marker, changes made by one side,
 	a `=======` marker, changes made by the other side, and then
-	a `>>>>>>>` marker.  An alternate style, "diff3", adds a `|||||||`
+	a +>>>>>>>+ marker.  An alternate style, "diff3", adds a +|||||||+
 	marker and the original text before the `=======` marker.  The
 	"merge" style tends to produce smaller conflict regions than diff3,
 	both because of the exclusion of the original text, and because
@@ -13,17 +13,17 @@ merge.conflictStyle::
 	the conflict region when those matching lines appear near either
 	the beginning or end of a conflict region.
 
-merge.defaultToUpstream::
+`merge.defaultToUpstream`::
 	If merge is called without any commit argument, merge the upstream
 	branches configured for the current branch by using their last
 	observed values stored in their remote-tracking branches.
 	The values of the `branch.<current branch>.merge` that name the
-	branches at the remote named by `branch.<current branch>.remote`
+	branches at the remote named by `branch.<current-branch>.remote`
 	are consulted, and then they are mapped via `remote.<remote>.fetch`
 	to their corresponding remote-tracking branches, and the tips of
 	these tracking branches are merged. Defaults to true.
 
-merge.ff::
+`merge.ff`::
 	By default, Git does not create an extra merge commit when merging
 	a commit that is a descendant of the current commit. Instead, the
 	tip of the current branch is fast-forwarded. When set to `false`,
@@ -33,42 +33,46 @@ merge.ff::
 	allowed (equivalent to giving the `--ff-only` option from the
 	command line).
 
-merge.verifySignatures::
-	If true, this is equivalent to the --verify-signatures command
+`merge.verifySignatures`::
+	If true, this is equivalent to the `--verify-signatures` command
 	line option. See linkgit:git-merge[1] for details.
 
 include::fmt-merge-msg.adoc[]
 
-merge.renameLimit::
+`merge.renameLimit`::
 	The number of files to consider in the exhaustive portion of
 	rename detection during a merge.  If not specified, defaults
-	to the value of diff.renameLimit.  If neither
-	merge.renameLimit nor diff.renameLimit are specified,
+	to the value of `diff.renameLimit`.  If neither
+	`merge.renameLimit` nor `diff.renameLimit` are specified,
 	currently defaults to 7000.  This setting has no effect if
 	rename detection is turned off.
 
-merge.renames::
-	Whether Git detects renames.  If set to "false", rename detection
-	is disabled. If set to "true", basic rename detection is enabled.
+`merge.renames`::
+	Whether Git detects renames.  If set to `false`, rename detection
+	is disabled. If set to `true`, basic rename detection is enabled.
 	Defaults to the value of diff.renames.
 
-merge.directoryRenames::
+`merge.directoryRenames`::
 	Whether Git detects directory renames, affecting what happens at
 	merge time to new files added to a directory on one side of
 	history when that directory was renamed on the other side of
-	history.  If merge.directoryRenames is set to "false", directory
-	rename detection is disabled, meaning that such new files will be
-	left behind in the old directory.  If set to "true", directory
-	rename detection is enabled, meaning that such new files will be
-	moved into the new directory.  If set to "conflict", a conflict
-	will be reported for such paths.  If merge.renames is false,
-	merge.directoryRenames is ignored and treated as false.  Defaults
-	to "conflict".
-
-merge.renormalize::
+	history. Possible values are:
++
+--
+`false`;; Directory rename detection is disabled, meaning that such new files will be
+	left behind in the old directory.
+`true`;; Directory rename detection is enabled, meaning that such new files will be
+	moved into the new directory.
+`conflict`;; A conflict will be reported for such paths.
+--
++
+If `merge.renames` is `false`, `merge.directoryRenames` is ignored and treated
+as `false`. Defaults to `conflict`.
+
+`merge.renormalize`::
 	Tell Git that canonical representation of files in the
 	repository has changed over time (e.g. earlier commits record
-	text files with CRLF line endings, but recent ones use LF line
+	text files with _CRLF_ line endings, but recent ones use _LF_ line
 	endings).  In such a repository, for each file where a
 	three-way content merge is needed, Git can convert the data
 	recorded in commits to a canonical form before performing a
@@ -76,35 +80,35 @@ merge.renormalize::
 	see section "Merging branches with differing checkin/checkout
 	attributes" in linkgit:gitattributes[5].
 
-merge.stat::
-	Whether to print the diffstat between ORIG_HEAD and the merge result
+`merge.stat`::
+	Whether to print the diffstat between `ORIG_HEAD` and the merge result
 	at the end of the merge.  True by default.
 
-merge.autoStash::
-	When set to true, automatically create a temporary stash entry
+`merge.autoStash`::
+	When set to `true`, automatically create a temporary stash entry
 	before the operation begins, and apply it after the operation
 	ends.  This means that you can run merge on a dirty worktree.
 	However, use with care: the final stash application after a
 	successful merge might result in non-trivial conflicts.
 	This option can be overridden by the `--no-autostash` and
 	`--autostash` options of linkgit:git-merge[1].
-	Defaults to false.
+	Defaults to `false`.
 
-merge.tool::
+`merge.tool`::
 	Controls which merge tool is used by linkgit:git-mergetool[1].
 	The list below shows the valid built-in values.
 	Any other value is treated as a custom merge tool and requires
-	that a corresponding mergetool.<tool>.cmd variable is defined.
+	that a corresponding `mergetool.<tool>.cmd` variable is defined.
 
-merge.guitool::
+`merge.guitool`::
 	Controls which merge tool is used by linkgit:git-mergetool[1] when the
-	-g/--gui flag is specified. The list below shows the valid built-in values.
+	`-g`/`--gui` flag is specified. The list below shows the valid built-in values.
 	Any other value is treated as a custom merge tool and requires that a
-	corresponding mergetool.<guitool>.cmd variable is defined.
+	corresponding `mergetool.<guitool>.cmd` variable is defined.
 
 include::{build_dir}/mergetools-merge.adoc[]
 
-merge.verbosity::
+`merge.verbosity`::
 	Controls the amount of output shown by the recursive merge
 	strategy.  Level 0 outputs nothing except a final error
 	message if conflicts were detected. Level 1 outputs only
@@ -112,15 +116,15 @@ merge.verbosity::
 	above outputs debugging information.  The default is level 2.
 	Can be overridden by the `GIT_MERGE_VERBOSITY` environment variable.
 
-merge.<driver>.name::
+`merge.<driver>.name`::
 	Defines a human-readable name for a custom low-level
 	merge driver.  See linkgit:gitattributes[5] for details.
 
-merge.<driver>.driver::
+`merge.<driver>.driver`::
 	Defines the command that implements a custom low-level
 	merge driver.  See linkgit:gitattributes[5] for details.
 
-merge.<driver>.recursive::
+`merge.<driver>.recursive`::
 	Names a low-level merge driver to be used when
 	performing an internal merge between common ancestors.
 	See linkgit:gitattributes[5] for details.
-- 
gitgitgadget

[PATCH 7/9] doc: convert git-mergetool manpage to new synopsis style

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-mergetool.adoc | 62 ++++++++++++++++----------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/Documentation/git-mergetool.adoc b/Documentation/git-mergetool.adoc
index 046c3258f050..77d0b5055057 100644
--- a/Documentation/git-mergetool.adoc
+++ b/Documentation/git-mergetool.adoc
@@ -7,95 +7,95 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
 
 SYNOPSIS
 --------
-[verse]
-'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
+[synopsis]
+git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
 
 DESCRIPTION
 -----------
 
 Use `git mergetool` to run one of several merge utilities to resolve
-merge conflicts.  It is typically run after 'git merge'.
+merge conflicts.  It is typically run after `git merge`.
 
 If one or more <file> parameters are given, the merge tool program will
 be run to resolve differences in each file (skipping those without
 conflicts).  Specifying a directory will include all unresolved files in
-that path.  If no <file> names are specified, 'git mergetool' will run
+that path.  If no _<file>_ names are specified, `git mergetool` will run
 the merge tool program on every file with merge conflicts.
 
 OPTIONS
 -------
--t <tool>::
---tool=<tool>::
-	Use the merge resolution program specified by <tool>.
-	Valid values include emerge, gvimdiff, kdiff3,
-	meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help`
-	for the list of valid <tool> settings.
+`-t <tool>`::
+`--tool=<tool>`::
+	Use the merge resolution program specified by _<tool>_.
+	Valid values include `emerge`, `gvimdiff`, `kdiff3`,
+	`meld`, `vimdiff`, and `tortoisemerge`. Run `git mergetool --tool-help`
+	for the list of valid _<tool>_ settings.
 +
-If a merge resolution program is not specified, 'git mergetool'
+If a merge resolution program is not specified, `git mergetool`
 will use the configuration variable `merge.tool`.  If the
-configuration variable `merge.tool` is not set, 'git mergetool'
+configuration variable `merge.tool` is not set, `git mergetool`
 will pick a suitable default.
 +
 You can explicitly provide a full path to the tool by setting the
 configuration variable `mergetool.<tool>.path`. For example, you
 can configure the absolute path to kdiff3 by setting
-`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the
-tool is available in PATH.
+`mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the
+tool is available in `$PATH`.
 +
 Instead of running one of the known merge tool programs,
-'git mergetool' can be customized to run an alternative program
+`git mergetool` can be customized to run an alternative program
 by specifying the command line to invoke in a configuration
 variable `mergetool.<tool>.cmd`.
 +
-When 'git mergetool' is invoked with this tool (either through the
+When `git mergetool` is invoked with this tool (either through the
 `-t` or `--tool` option or the `merge.tool` configuration
-variable), the configured command line will be invoked with `$BASE`
+variable), the configured command line will be invoked with `BASE`
 set to the name of a temporary file containing the common base for
-the merge, if available; `$LOCAL` set to the name of a temporary
+the merge, if available; `LOCAL` set to the name of a temporary
 file containing the contents of the file on the current branch;
-`$REMOTE` set to the name of a temporary file containing the
-contents of the file to be merged, and `$MERGED` set to the name
+`REMOTE` set to the name of a temporary file containing the
+contents of the file to be merged, and `MERGED` set to the name
 of the file to which the merge tool should write the result of the
 merge resolution.
 +
 If the custom merge tool correctly indicates the success of a
 merge resolution with its exit code, then the configuration
 variable `mergetool.<tool>.trustExitCode` can be set to `true`.
-Otherwise, 'git mergetool' will prompt the user to indicate the
+Otherwise, `git mergetool` will prompt the user to indicate the
 success of the resolution after the custom tool has exited.
 
---tool-help::
+`--tool-help`::
 	Print a list of merge tools that may be used with `--tool`.
 
--y::
---no-prompt::
+`-y`::
+`--no-prompt`::
 	Don't prompt before each invocation of the merge resolution
 	program.
 	This is the default if the merge resolution program is
 	explicitly specified with the `--tool` option or with the
 	`merge.tool` configuration variable.
 
---prompt::
+`--prompt`::
 	Prompt before each invocation of the merge resolution program
 	to give the user a chance to skip the path.
 
--g::
---gui::
-	When 'git-mergetool' is invoked with the `-g` or `--gui` option,
+`-g`::
+`--gui`::
+	When `git-mergetool` is invoked with the `-g` or `--gui` option,
 	the default merge tool will be read from the configured
 	`merge.guitool` variable instead of `merge.tool`. If
 	`merge.guitool` is not set, we will fallback to the tool
 	configured under `merge.tool`. This may be autoselected using
 	the configuration variable `mergetool.guiDefault`.
 
---no-gui::
+`--no-gui`::
 	This overrides a previous `-g` or `--gui` setting or
 	`mergetool.guiDefault` configuration and reads the default merge
 	tool from the configured `merge.tool` variable.
 
--O<orderfile>::
+`-O<orderfile>`::
 	Process files in the order specified in the
-	<orderfile>, which has one shell glob pattern per line.
+	_<orderfile>_, which has one shell glob pattern per line.
 	This overrides the `diff.orderFile` configuration variable
 	(see linkgit:git-config[1]).  To cancel `diff.orderFile`,
 	use `-O/dev/null`.
-- 
gitgitgadget

[PATCH 8/9] doc: convert git-mergetool options to new synopsis style

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/mergetool.adoc   | 54 +++++++++++++--------------
 Documentation/mergetools/vimdiff.adoc | 16 ++++----
 2 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc
index 00bf665aa09b..6be506145c15 100644
--- a/Documentation/config/mergetool.adoc
+++ b/Documentation/config/mergetool.adoc
@@ -1,24 +1,24 @@
-mergetool.<tool>.path::
+`mergetool.<tool>.path`::
 	Override the path for the given tool.  This is useful in case
-	your tool is not in the PATH.
+	your tool is not in the `$PATH`.
 
-mergetool.<tool>.cmd::
+`mergetool.<tool>.cmd`::
 	Specify the command to invoke the specified merge tool.  The
 	specified command is evaluated in shell with the following
-	variables available: 'BASE' is the name of a temporary file
+	variables available: `BASE` is the name of a temporary file
 	containing the common base of the files to be merged, if available;
-	'LOCAL' is the name of a temporary file containing the contents of
-	the file on the current branch; 'REMOTE' is the name of a temporary
+	`LOCAL` is the name of a temporary file containing the contents of
+	the file on the current branch; `REMOTE` is the name of a temporary
 	file containing the contents of the file from the branch being
-	merged; 'MERGED' contains the name of the file to which the merge
+	merged; `MERGED` contains the name of the file to which the merge
 	tool should write the results of a successful merge.
 
-mergetool.<tool>.hideResolved::
+`mergetool.<tool>.hideResolved`::
 	Allows the user to override the global `mergetool.hideResolved` value
 	for a specific tool. See `mergetool.hideResolved` for the full
 	description.
 
-mergetool.<tool>.trustExitCode::
+`mergetool.<tool>.trustExitCode`::
 	For a custom merge command, specify whether the exit code of
 	the merge command can be used to determine whether the merge was
 	successful.  If this is not set to true then the merge target file
@@ -26,7 +26,7 @@ mergetool.<tool>.trustExitCode::
 	if the file has been updated; otherwise, the user is prompted to
 	indicate the success of the merge.
 
-mergetool.meld.hasOutput::
+`mergetool.meld.hasOutput`::
 	Older versions of `meld` do not support the `--output` option.
 	Git will attempt to detect whether `meld` supports `--output`
 	by inspecting the output of `meld --help`.  Configuring
@@ -35,7 +35,7 @@ mergetool.meld.hasOutput::
 	to `true` tells Git to unconditionally use the `--output` option,
 	and `false` avoids using `--output`.
 
-mergetool.meld.useAutoMerge::
+`mergetool.meld.useAutoMerge`::
 	When the `--auto-merge` is given, meld will merge all non-conflicting
 	parts automatically, highlight the conflicting parts, and wait for
 	user decision.  Setting `mergetool.meld.useAutoMerge` to `true` tells
@@ -45,15 +45,15 @@ mergetool.meld.useAutoMerge::
 	value of `false` avoids using `--auto-merge` altogether, and is the
 	default value.
 
-mergetool.<vimdiff variant>.layout::
-	Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`,
+`mergetool.<variant>.layout`::
+	Configure the split window layout for vimdiff's _<variant>_, which is any of `vimdiff`,
 	`nvimdiff`, `gvimdiff`.
 	Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool`
-	if `merge.tool` is configured as `<variant>`), Git will consult
+	if `merge.tool` is configured as _<variant>_), Git will consult
 	`mergetool.<variant>.layout` to determine the tool's layout. If the
-	variant-specific configuration is not available, `vimdiff`'s is used as
+	variant-specific configuration is not available, `vimdiff` ' s is used as
 	fallback.  If that too is not available, a default layout with 4 windows
-	will be used.  To configure the layout, see the `BACKEND SPECIFIC HINTS`
+	will be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'
 ifdef::git-mergetool[]
 	section.
 endif::[]
@@ -61,39 +61,39 @@ ifndef::git-mergetool[]
 	section in linkgit:git-mergetool[1].
 endif::[]
 
-mergetool.hideResolved::
+`mergetool.hideResolved`::
 	During a merge, Git will automatically resolve as many conflicts as
-	possible and write the 'MERGED' file containing conflict markers around
-	any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally
-	represent the versions of the file from before Git's conflict
-	resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so
+	possible and write the `$MERGED` file containing conflict markers around
+	any conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally
+	are the versions of the file from before Git`s conflict
+	resolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so
 	that only the unresolved conflicts are presented to the merge tool. Can
 	be configured per-tool via the `mergetool.<tool>.hideResolved`
 	configuration variable. Defaults to `false`.
 
-mergetool.keepBackup::
+`mergetool.keepBackup`::
 	After performing a merge, the original file with conflict markers
 	can be saved as a file with a `.orig` extension.  If this variable
 	is set to `false` then this file is not preserved.  Defaults to
 	`true` (i.e. keep the backup files).
 
-mergetool.keepTemporaries::
+`mergetool.keepTemporaries`::
 	When invoking a custom merge tool, Git uses a set of temporary
 	files to pass to the tool. If the tool returns an error and this
 	variable is set to `true`, then these temporary files will be
 	preserved; otherwise, they will be removed after the tool has
 	exited. Defaults to `false`.
 
-mergetool.writeToTemp::
-	Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of
+`mergetool.writeToTemp`::
+	Git writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of
 	conflicting files in the worktree by default.  Git will attempt
 	to use a temporary directory for these files when set `true`.
 	Defaults to `false`.
 
-mergetool.prompt::
+`mergetool.prompt`::
 	Prompt before each invocation of the merge resolution program.
 
-mergetool.guiDefault::
+`mergetool.guiDefault`::
 	Set `true` to use the `merge.guitool` by default (equivalent to
 	specifying the `--gui` argument), or `auto` to select `merge.guitool`
 	or `merge.tool` depending on the presence of a `DISPLAY` environment
diff --git a/Documentation/mergetools/vimdiff.adoc b/Documentation/mergetools/vimdiff.adoc
index ab915df408e8..abfd426f74a0 100644
--- a/Documentation/mergetools/vimdiff.adoc
+++ b/Documentation/mergetools/vimdiff.adoc
@@ -183,13 +183,13 @@ latter will be used as fallback if the variant-specific one is not set).
 In addition, for backwards compatibility with previous Git versions, you can
 also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:
 `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout.
-In other words, using `--tool=[g,n,]vimdiffx` is the same as using
-`--tool=[g,n,]vimdiff` and setting configuration variable
-`mergetool.[g,n,]vimdiff.layout` to...
+In other words, using `--tool=[g|n]vimdiff<x>` is the same as using
+`--tool=[g|n]vimdiff` and setting configuration variable
+`mergetool.[g|n]vimdiff.layout` to...
 
-  * `x=1`: `"@LOCAL, REMOTE"`
-  * `x=2`: `"LOCAL, MERGED, REMOTE"`
-  * `x=3`: `"MERGED"`
+  * `<x>=1`: `"@LOCAL, REMOTE"`
+  * `<x>=2`: `"LOCAL, MERGED, REMOTE"`
+  * `<x>=3`: `"MERGED"`
 
-Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL,
-MERGED and REMOTE).
+Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`,
+`MERGED` and `REMOTE`).
-- 
gitgitgadget

[PATCH 9/9] doc: convert git-switch manpage to new synopsis style

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-switch.adoc | 114 +++++++++++++++++-----------------
 1 file changed, 57 insertions(+), 57 deletions(-)

diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc
index f55315c51ea0..9f62abf9e2b8 100644
--- a/Documentation/git-switch.adoc
+++ b/Documentation/git-switch.adoc
@@ -7,11 +7,11 @@ git-switch - Switch branches
 
 SYNOPSIS
 --------
-[verse]
-'git switch' [<options>] [--no-guess] <branch>
-'git switch' [<options>] --detach [<start-point>]
-'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]
-'git switch' [<options>] --orphan <new-branch>
+[synopsis]
+git switch [<options>] [--no-guess] <branch>
+git switch [<options>] --detach [<start-point>]
+git switch [<options>] (-c|-C) <new-branch> [<start-point>]
+git switch [<options>] --orphan <new-branch>
 
 DESCRIPTION
 -----------
@@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 
 OPTIONS
 -------
-<branch>::
+_<branch>_::
 	Branch to switch to.
 
-<new-branch>::
+_<new-branch>_::
 	Name for the new branch.
 
-<start-point>::
+_<start-point>_::
 	The starting point for the new branch. Specifying a
-	`<start-point>` allows you to create a branch based on some
-	other point in history than where HEAD currently points. (Or,
+	_<start-point>_ allows you to create a branch based on some
+	other point in history than where `HEAD` currently points. (Or,
 	in the case of `--detach`, allows you to inspect and detach
 	from some other point.)
 +
-You can use the `@{-N}` syntax to refer to the N-th last
-branch/commit switched to using "git switch" or "git checkout"
+You can use the `@{-<N>}` syntax to refer to the _<N>_-th last
+branch/commit switched to using `git switch` or `git checkout`
 operation. You may also specify `-` which is synonymous to `@{-1}`.
 This is often used to switch quickly between two branches, or to undo
 a branch switch by mistake.
 +
-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`.
-
--c <new-branch>::
---create <new-branch>::
-	Create a new branch named `<new-branch>` starting at
-	`<start-point>` before switching to the branch. This is the
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge
+base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave
+out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
+
+`-c <new-branch>`::
+`--create <new-branch>`::
+	Create a new branch named _<new-branch>_ starting at
+	_<start-point>_ before switching to the branch. This is the
 	transactional equivalent of
 +
 ------------
@@ -67,32 +67,32 @@ $ git branch <new-branch>
 $ git switch <new-branch>
 ------------
 +
-that is to say, the branch is not reset/created unless "git switch" is
+that is to say, the branch is not reset/created unless `git switch` is
 successful (e.g., when the branch is in use in another worktree, not
 just the current branch stays the same, but the branch is not reset to
 the start-point, either).
 
--C <new-branch>::
---force-create <new-branch>::
-	Similar to `--create` except that if `<new-branch>` already
-	exists, it will be reset to `<start-point>`. This is a
+`-C <new-branch>`::
+`--force-create <new-branch>`::
+	Similar to `--create` except that if _<new-branch>_ already
+	exists, it will be reset to _<start-point>_. This is a
 	convenient shortcut for:
 +
 ------------
-$ git branch -f <new-branch>
-$ git switch <new-branch>
+$ git branch -f _<new-branch>_
+$ git switch _<new-branch>_
 ------------
 
--d::
---detach::
+`-d`::
+`--detach`::
 	Switch to a commit for inspection and discardable
 	experiments. See the "DETACHED HEAD" section in
 	linkgit:git-checkout[1] for details.
 
---guess::
---no-guess::
-	If `<branch>` is not found but there does exist a tracking
-	branch in exactly one remote (call it `<remote>`) with a
+`--guess`::
+`--no-guess`::
+	If _<branch>_ is not found but there does exist a tracking
+	branch in exactly one remote (call it _<remote>_) with a
 	matching name, treat as equivalent to
 +
 ------------
@@ -101,9 +101,9 @@ $ git switch -c <branch> --track <remote>/<branch>
 +
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
-one for the purposes of disambiguation, even if the `<branch>` isn't
+one for the purposes of disambiguation, even if the _<branch>_ isn't
 unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`
-to always checkout remote branches from there if `<branch>` is
+to always checkout remote branches from there if _<branch>_ is
 ambiguous but exists on the 'origin' remote. See also
 `checkout.defaultRemote` in linkgit:git-config[1].
 +
@@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
--f::
---force::
+`-f`::
+`--force`::
 	An alias for `--discard-changes`.
 
---discard-changes::
+`--discard-changes`::
 	Proceed even if the index or the working tree differs from
 	`HEAD`. Both the index and working tree are restored to match
 	the switching target. If `--recurse-submodules` is specified,
 	submodule content is also restored to match the switching
 	target. This is used to throw away local changes.
 
--m::
---merge::
+`-m`::
+`--merge`::
 	If you have local modifications to one or more files that are
 	different between the current branch and the branch to which
 	you are switching, the command refuses to switch branches in
@@ -138,25 +138,25 @@ paths are left unmerged, and you need to resolve the conflicts
 and mark the resolved paths with `git add` (or `git rm` if the merge
 should result in deletion of the path).
 
---conflict=<style>::
+`--conflict=<style>`::
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values are
-	"merge" (default), "diff3", and "zdiff3".
+	`merge` (default), `diff3`, and `zdiff3`.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Quiet, suppress feedback messages.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal, unless `--quiet`
 	is specified. This flag enables progress reporting even if not
 	attached to a terminal, regardless of `--quiet`.
 
--t::
---track [direct|inherit]::
+`-t`::
+`--track[ (direct|inherit)]`::
 	When creating a new branch, set up "upstream" configuration.
 	`-c` is implied. See `--track` in linkgit:git-branch[1] for
 	details.
@@ -171,22 +171,22 @@ given name has no slash, or the above guessing results in an empty
 name, the guessing is aborted.  You can explicitly give a name with
 `-c` in such a case.
 
---no-track::
+`--no-track`::
 	Do not set up "upstream" configuration, even if the
 	`branch.autoSetupMerge` configuration variable is true.
 
---orphan <new-branch>::
-	Create a new unborn branch, named `<new-branch>`. All
+`--orphan <new-branch>`::
+	Create a new unborn branch, named _<new-branch>_. All
 	tracked files are removed.
 
---ignore-other-worktrees::
+`--ignore-other-worktrees`::
 	`git switch` refuses when the wanted ref is already
 	checked out by another worktree. This option makes it check
 	the ref out anyway. In other words, the ref can be held by
 	more than one worktree.
 
---recurse-submodules::
---no-recurse-submodules::
+`--recurse-submodules`::
+`--no-recurse-submodules`::
 	Using `--recurse-submodules` will update the content of all
 	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
@@ -239,7 +239,7 @@ $ git switch -
 ------------
 
 You can grow a new branch from any commit. For example, switch to
-"HEAD~3" and create branch "fixup":
+"`HEAD~3`" and create branch "`fixup`":
 
 ------------
 $ git switch -c fixup HEAD~3
@@ -251,8 +251,8 @@ name:
 
 ------------
 $ git switch new-topic
-Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin'
-Switched to a new branch 'new-topic'
+Branch `new-topic` set up to track remote branch `new-topic` from `origin`
+Switched to a new branch `new-topic`
 ------------
 
 To check out commit `HEAD~3` for temporary inspection or experiment
-- 
gitgitgadget