Merge branch 'ja/doc-synopsis-style'

Doc mark-up fixes.

* ja/doc-synopsis-style:
  doc: convert git-switch manpage to new synopsis style
  doc: convert git-mergetool options to new synopsis style
  doc: convert git-mergetool manpage to new synopsis style
  doc: switch merge config description to new synopsis format
  doc: convert merge strategies to synopsis format
  doc: merge-options.adoc remove a misleading double negation
  doc: convert merge options to new synopsis format
  doc: convert git-merge manpage to new style
  doc: convert git-checkout manpage to new style

4 files changed, 81 insertions, 77 deletions

diff --git a/Documentation/config/checkout.adoc b/Documentation/config/checkout.adoc
index a323022993..e35d212969 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/config/fmt-merge-msg.adoc b/Documentation/config/fmt-merge-msg.adoc
index 3fbf40e24f..696ba0531a 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 d2d0f21a71..86359f6dd2 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".
+	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::
+`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.
diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc
index 00bf665aa0..6be506145c 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