[PATCH 0/4] Doc difftool

[PATCH 0/4] Doc difftool

[Jean-Noël Avila via GitGitGadget]

This is another set of changes to convert the manual pages to synopsis
style.

Nothing noteworthy to add, pretty straight-forward.

Jean-Noël Avila (4):
  doc: convert git-difftool manual page to synopsis style
  doc: convert git-range-diff manual page to synopsis style
  doc: convert git-shortlog manual page to synopsis style
  doc: convert git-describe manual page to synopsis style

 Documentation/config/difftool.adoc  | 24 ++++----
 Documentation/config/mergetool.adoc |  8 +--
 Documentation/git-describe.adoc     | 96 ++++++++++++++---------------
 Documentation/git-difftool.adoc     | 80 ++++++++++++------------
 Documentation/git-range-diff.adoc   | 50 +++++++--------
 Documentation/git-shortlog.adoc     | 60 +++++++++---------
 6 files changed, 159 insertions(+), 159 deletions(-)


base-commit: 270e10ad6dda3379ea0da7efd11e4fbf2cd7a325
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2077%2Fjnavila%2Fdoc_difftool-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2077/jnavila/doc_difftool-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2077
-- 
gitgitgadget

[PATCH 1/4] doc: convert git-difftool manual page to synopsis style

[Jean-Noël Avila via GitGitGadget]

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

     * convert commands to synopsis style
     * use _<placeholder>_ for arguments
     * fix conditional text to sentence limits

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/difftool.adoc  | 24 ++++-----
 Documentation/config/mergetool.adoc |  8 +--
 Documentation/git-difftool.adoc     | 80 ++++++++++++++---------------
 3 files changed, 56 insertions(+), 56 deletions(-)

diff --git a/Documentation/config/difftool.adoc b/Documentation/config/difftool.adoc
index 4f7d40ce24..1b8d483813 100644
--- a/Documentation/config/difftool.adoc
+++ b/Documentation/config/difftool.adoc
@@ -1,43 +1,43 @@
-diff.tool::
+`diff.tool`::
 	Controls which diff tool is used by linkgit:git-difftool[1].
 	This variable overrides the value configured in `merge.tool`.
 	The list below shows the valid built-in values.
 	Any other value is treated as a custom diff tool and requires
-	that a corresponding difftool.<tool>.cmd variable is defined.
+	that a corresponding `difftool.<tool>.cmd` variable is defined.
 
-diff.guitool::
+`diff.guitool`::
 	Controls which diff tool is used by linkgit:git-difftool[1] when
-	the -g/--gui flag is specified. This variable overrides the value
+	the `-g`/`--gui` flag is specified. This variable overrides the value
 	configured in `merge.guitool`. The list below shows the valid
 	built-in values. Any other value is treated as a custom diff tool
-	and requires that a corresponding difftool.<guitool>.cmd variable
+	and requires that a corresponding `difftool.<guitool>.cmd` variable
 	is defined.
 
 include::{build_dir}/mergetools-diff.adoc[]
 
-difftool.<tool>.cmd::
+`difftool.<tool>.cmd`::
 	Specify the command to invoke the specified diff tool.
 	The specified command is evaluated in shell with the following
-	variables available:  'LOCAL' is set to the name of the temporary
-	file containing the contents of the diff pre-image and 'REMOTE'
+	variables available: `LOCAL` is set to the name of the temporary
+	file containing the contents of the diff pre-image and `REMOTE`
 	is set to the name of the temporary file containing the contents
 	of the diff post-image.
 +
 See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
 
-difftool.<tool>.path::
+`difftool.<tool>.path`::
 	Override the path for the given tool.  This is useful in case
 	your tool is not in the PATH.
 
-difftool.trustExitCode::
+`difftool.trustExitCode`::
 	Exit difftool if the invoked diff tool returns a non-zero exit status.
 +
 See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
 
-difftool.prompt::
+`difftool.prompt`::
 	Prompt before each invocation of the diff tool.
 
-difftool.guiDefault::
+`difftool.guiDefault`::
 	Set `true` to use the `diff.guitool` by default (equivalent to specifying
 	the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool`
 	depending on the presence of a `DISPLAY` environment variable value. The
diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc
index 7064f5a462..7afdcad92b 100644
--- a/Documentation/config/mergetool.adoc
+++ b/Documentation/config/mergetool.adoc
@@ -52,13 +52,13 @@
 	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
-	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'
+	fallback. If that too is not available, a default layout with 4 windows
+	will be used.
 ifdef::git-mergetool[]
-	section.
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section.
 endif::[]
 ifndef::git-mergetool[]
-	section in linkgit:git-mergetool[1].
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section in linkgit:git-mergetool[1].
 endif::[]
 
 `mergetool.hideResolved`::
diff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc
index 064bc68347..dd7cacf95e 100644
--- a/Documentation/git-difftool.adoc
+++ b/Documentation/git-difftool.adoc
@@ -7,64 +7,64 @@ git-difftool - Show changes using common diff tools
 
 SYNOPSIS
 --------
-[verse]
-'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
+[synopsis]
+git difftool [<options>] [<commit> [<commit>]] [--] [<path>...]
 
 DESCRIPTION
 -----------
-'git difftool' is a Git command that allows you to compare and edit files
-between revisions using common diff tools.  'git difftool' is a frontend
-to 'git diff' and accepts the same options and arguments. See
+`git difftool` is a Git command that allows you to compare and edit files
+between revisions using common diff tools. `git difftool` is a frontend
+to `git diff` and accepts the same options and arguments. See
 linkgit:git-diff[1].
 
 OPTIONS
 -------
--d::
---dir-diff::
+`-d`::
+`--dir-diff`::
 	Copy the modified files to a temporary location and perform
 	a directory diff on them. This mode never prompts before
 	launching the diff tool.
 
--y::
---no-prompt::
+`-y`::
+`--no-prompt`::
 	Do not prompt before launching a diff tool.
 
---prompt::
+`--prompt`::
 	Prompt before each invocation of the diff tool.
 	This is the default behaviour; the option is provided to
 	override any configuration settings.
 
---rotate-to=<file>::
-	Start showing the diff for the given path,
+`--rotate-to=<file>`::
+	Start showing the diff for _<file>_,
 	the paths before it will move to the end and output.
 
---skip-to=<file>::
-	Start showing the diff for the given path, skipping all
+`--skip-to=<file>`::
+	Start showing the diff for _<file>_, skipping all
 	the paths before it.
 
--t <tool>::
---tool=<tool>::
-	Use the diff tool specified by <tool>.  Valid values include
+`-t <tool>`::
+`--tool=<tool>`::
+	Use the diff tool specified by _<tool>_. Valid values include
 	emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help`
-	for the list of valid <tool> settings.
+	for the list of valid _<tool>_ settings.
 +
-If a diff tool is not specified, 'git difftool'
+If a diff tool is not specified, `git difftool`
 will use the configuration variable `diff.tool`.  If the
-configuration variable `diff.tool` is not set, 'git difftool'
+configuration variable `diff.tool` is not set, `git difftool`
 will pick a suitable default.
 +
 You can explicitly provide a full path to the tool by setting the
 configuration variable `difftool.<tool>.path`. For example, you
 can configure the absolute path to kdiff3 by setting
-`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the
+`difftool.kdiff3.path`. Otherwise, `git difftool` assumes the
 tool is available in PATH.
 +
 Instead of running one of the known diff tools,
-'git difftool' can be customized to run an alternative program
+`git difftool` can be customized to run an alternative program
 by specifying the command line to invoke in a configuration
 variable `difftool.<tool>.cmd`.
 +
-When 'git difftool' is invoked with this tool (either through the
+When `git difftool` is invoked with this tool (either through the
 `-t` or `--tool` option or the `diff.tool` configuration variable)
 the configured command line will be invoked with the following
 variables available: `$LOCAL` is set to the name of the temporary
@@ -74,30 +74,30 @@ of the diff post-image.  `$MERGED` is the name of the file which is
 being compared. `$BASE` is provided for compatibility
 with custom merge tool commands and has the same value as `$MERGED`.
 
---tool-help::
+`--tool-help`::
 	Print a list of diff tools that may be used with `--tool`.
 
---symlinks::
---no-symlinks::
-	'git difftool''s default behavior is to create symlinks to the
+`--symlinks`::
+`--no-symlinks`::
+	`git difftool`'s default behavior is to create symlinks to the
 	working tree when run in `--dir-diff` mode and the right-hand
 	side of the comparison yields the same content as the file in
 	the working tree.
 +
-Specifying `--no-symlinks` instructs 'git difftool' to create copies
+Specifying `--no-symlinks` instructs `git difftool` to create copies
 instead.  `--no-symlinks` is the default on Windows.
 
--x <command>::
---extcmd=<command>::
+`-x <command>`::
+`--extcmd=<command>`::
 	Specify a custom command for viewing diffs.
-	'git-difftool' ignores the configured defaults and runs
+	`git-difftool` ignores the configured defaults and runs
 	`<command> $LOCAL $REMOTE` when this option is specified.
 	Additionally, `$BASE` is set in the environment.
 
--g::
---gui::
---no-gui::
-	When 'git-difftool' is invoked with the `-g` or `--gui` option
+`-g`::
+`--gui`::
+`--no-gui`::
+	When `git-difftool` is invoked with the `-g` or `--gui` option
 	the default diff tool will be read from the configured
 	`diff.guitool` variable instead of `diff.tool`. This may be
 	selected automatically using the configuration variable
@@ -106,20 +106,20 @@ instead.  `--no-symlinks` is the default on Windows.
 	fallback in the order of `merge.guitool`, `diff.tool`,
 	`merge.tool` until a tool is found.
 
---trust-exit-code::
---no-trust-exit-code::
+`--trust-exit-code`::
+`--no-trust-exit-code`::
 	Errors reported by the diff tool are ignored by default.
-	Use `--trust-exit-code` to make 'git-difftool' exit when an
+	Use `--trust-exit-code` to make `git-difftool` exit when an
 	invoked diff tool returns a non-zero exit code.
 +
-'git-difftool' will forward the exit code of the invoked tool when
+`git-difftool` will forward the exit code of the invoked tool when
 `--trust-exit-code` is used.
 
 See linkgit:git-diff[1] for the full list of supported options.
 
 CONFIGURATION
 -------------
-'git difftool' falls back to 'git mergetool' config variables when the
+`git difftool` falls back to `git mergetool` config variables when the
 difftool equivalents have not been defined.
 
 include::includes/cmd-config-section-rest.adoc[]
-- 
gitgitgadget

[PATCH 2/4] doc: convert git-range-diff manual page to synopsis style

[Jean-Noël Avila via GitGitGadget]

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

     * convert commands and options to synopsis style
     * use _<placeholder>_ for arguments
     * small style fixes

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

diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc
index b5e85d37f1..8805570845 100644
--- a/Documentation/git-range-diff.adoc
+++ b/Documentation/git-range-diff.adoc
@@ -7,8 +7,8 @@ git-range-diff - Compare two commit ranges (e.g. two versions of a branch)
 
 SYNOPSIS
 --------
-[verse]
-'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>]
+[synopsis]
+git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
 	[--no-dual-color] [--creation-factor=<factor>]
 	[--left-only | --right-only] [--diff-merges=<format>]
 	[--remerge-diff]
@@ -21,14 +21,14 @@ DESCRIPTION
 This command shows the differences between two versions of a patch
 series, or more generally, two commit ranges (ignoring merge commits).
 
-In the presence of `<path>` arguments, these commit ranges are limited
+In the presence of _<path>_ arguments, these commit ranges are limited
 accordingly.
 
 To that end, it first finds pairs of commits from both commit ranges
 that correspond with each other. Two commits are said to correspond when
 the diff between their patches (i.e. the author information, the commit
 message and the commit diff) is reasonably small compared to the
-patches' size. See ``Algorithm`` below for details.
+patches' size. See 'Algorithm' below for details.
 
 Finally, the list of matching commits is shown in the order of the
 second commit range, with unmatched commits being inserted just after
@@ -37,7 +37,7 @@ all of their ancestors have been shown.
 There are three ways to specify the commit ranges:
 
 - `<range1> <range2>`: Either commit range can be of the form
-  `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See `SPECIFYING RANGES`
+  `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See 'SPECIFYING RANGES'
   in linkgit:gitrevisions[7] for more details.
 
 - `<rev1>...<rev2>`. This is equivalent to
@@ -48,7 +48,7 @@ There are three ways to specify the commit ranges:
 
 OPTIONS
 -------
---no-dual-color::
+`--no-dual-color`::
 	When the commit diffs differ, `git range-diff` recreates the
 	original diffs' coloring, and adds outer -/+ diff markers with
 	the *background* being red/green to make it easier to see e.g.
@@ -56,33 +56,33 @@ OPTIONS
 +
 Additionally, the commit diff lines that are only present in the first commit
 range are shown "dimmed" (this can be overridden using the `color.diff.<slot>`
-config setting where `<slot>` is one of `contextDimmed`, `oldDimmed` and
+config setting where _<slot>_ is one of `contextDimmed`, `oldDimmed` and
 `newDimmed`), and the commit diff lines that are only present in the second
 commit range are shown in bold (which can be overridden using the config
-settings `color.diff.<slot>` with `<slot>` being one of `contextBold`,
+settings `color.diff.<slot>` with _<slot>_ being one of `contextBold`,
 `oldBold` or `newBold`).
 +
 This is known to `range-diff` as "dual coloring". Use `--no-dual-color`
 to revert to color all lines according to the outer diff markers
 (and completely ignore the inner diff when it comes to color).
 
---creation-factor=<percent>::
-	Set the creation/deletion cost fudge factor to `<percent>`.
+`--creation-factor=<percent>`::
+	Set the creation/deletion cost fudge factor to _<percent>_.
 	Defaults to 60. Try a larger value if `git range-diff` erroneously
 	considers a large change a total rewrite (deletion of one commit
 	and addition of another), and a smaller one in the reverse case.
-	See the ``Algorithm`` section below for an explanation of why this is
+	See the 'Algorithm' section below for an explanation of why this is
 	needed.
 
---left-only::
+`--left-only`::
 	Suppress commits that are missing from the first specified range
-	(or the "left range" when using the `<rev1>...<rev2>` format).
+	(or the "left range" when using the `<rev1>...<rev2>` form).
 
---right-only::
+`--right-only`::
 	Suppress commits that are missing from the second specified range
-	(or the "right range" when using the `<rev1>...<rev2>` format).
+	(or the "right range" when using the `<rev1>...<rev2>` form).
 
---diff-merges=<format>::
+`--diff-merges=<format>`::
 	Instead of ignoring merge commits, generate diffs for them using the
 	corresponding `--diff-merges=<format>` option of linkgit:git-log[1],
 	and include them in the comparison.
@@ -93,30 +93,30 @@ have produced. In other words, if a merge commit is the result of a
 non-conflicting `git merge`, the `remerge` mode will represent it with an empty
 diff.
 
---remerge-diff::
+`--remerge-diff`::
 	Convenience option, equivalent to `--diff-merges=remerge`.
 
---notes[=<ref>]::
---no-notes::
+`--notes[=<ref>]`::
+`--no-notes`::
 	This flag is passed to the `git log` program
 	(see linkgit:git-log[1]) that generates the patches.
 
-<range1> <range2>::
+`<range1> <range2>`::
 	Compare the commits specified by the two ranges, where
-	`<range1>` is considered an older version of `<range2>`.
+	_<range1>_ is considered an older version of _<range2>_.
 
-<rev1>...<rev2>::
+`<rev1>...<rev2>`::
 	Equivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`.
 
-<base> <rev1> <rev2>::
+`<base> <rev1> <rev2>`::
 	Equivalent to passing `<base>..<rev1>` and `<base>..<rev2>`.
-	Note that `<base>` does not need to be the exact branch point
+	Note that _<base>_ does not need to be the exact branch point
 	of the branches. Example: after rebasing a branch `my-topic`,
 	`git range-diff my-topic@{u} my-topic@{1} my-topic` would
 	show the differences introduced by the rebase.
 
 `git range-diff` also accepts the regular diff options (see
-linkgit:git-diff[1]), most notably the `--color=[<when>]` and
+linkgit:git-diff[1]), most notably the `--color[=<when>]` and
 `--no-color` options. These options are used when generating the "diff
 between patches", i.e. to compare the author, commit message and diff of
 corresponding old/new commits. There is currently no means to tweak most of the
-- 
gitgitgadget

[PATCH 3/4] doc: convert git-shortlog manual page to synopsis style

[Jean-Noël Avila via GitGitGadget]

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

     * convert commands and options to synopsis style
     * use _<placeholder>_ for arguments
     * small style fixes

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

diff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc
index a11b57c1cd..e067d39b38 100644
--- a/Documentation/git-shortlog.adoc
+++ b/Documentation/git-shortlog.adoc
@@ -3,63 +3,63 @@ git-shortlog(1)
 
 NAME
 ----
-git-shortlog - Summarize 'git log' output
+git-shortlog - Summarize `git log` output
 
 SYNOPSIS
 --------
-[verse]
-'git shortlog' [<options>] [<revision-range>] [[--] <path>...]
-git log --pretty=short | 'git shortlog' [<options>]
+[synopsis]
+git shortlog [<options>] [<revision-range>] [[--] <path>...]
+git log --pretty=short | git shortlog [<options>]
 
 DESCRIPTION
 -----------
-Summarizes 'git log' output in a format suitable for inclusion
+Summarizes `git log` output in a format suitable for inclusion
 in release announcements. Each commit will be grouped by author and title.
 
 Additionally, "[PATCH]" will be stripped from the commit description.
 
 If no revisions are passed on the command line and either standard input
-is not a terminal or there is no current branch, 'git shortlog' will
+is not a terminal or there is no current branch, `git shortlog` will
 output a summary of the log read from standard input, without
 reference to the current repository.
 
 OPTIONS
 -------
 
--n::
---numbered::
+`-n`::
+`--numbered`::
 	Sort output according to the number of commits per author instead
 	of author alphabetic order.
 
--s::
---summary::
+`-s`::
+`--summary`::
 	Suppress commit description and provide a commit count summary only.
 
--e::
---email::
+`-e`::
+`--email`::
 	Show the email address of each author.
 
---format[=<format>]::
+`--format[=<format>]`::
 	Instead of the commit subject, use some other information to
-	describe each commit.  '<format>' can be any string accepted
-	by the `--format` option of 'git log', such as '* [%h] %s'.
-	(See the "PRETTY FORMATS" section of linkgit:git-log[1].)
+	describe each commit. _<format>_ can be any string accepted
+	by the `--format` option of `git log`, such as '* [%h] %s'.
+	(See the 'PRETTY FORMATS' section of linkgit:git-log[1].)
 +
 Each pretty-printed commit will be rewrapped before it is shown.
 
---date=<format>::
+`--date=<format>`::
 	Show dates formatted according to the given date string. (See
-	the `--date` option in the "Commit Formatting" section of
+	the `--date` option in the 'Commit Formatting' section of
 	linkgit:git-log[1]). Useful with `--group=format:<format>`.
 
---group=<type>::
-	Group commits based on `<type>`. If no `--group` option is
-	specified, the default is `author`. `<type>` is one of:
+`--group=<type>`::
+	Group commits based on _<type>_. If no `--group` option is
+	specified, the default is `author`. _<type>_ is one of:
 +
 --
  - `author`, commits are grouped by author
  - `committer`, commits are grouped by committer (the same as `-c`)
- - `trailer:<field>`, the `<field>` is interpreted as a case-insensitive
+ - `trailer:<field>`, the _<field>_ is interpreted as a case-insensitive
    commit message trailer (see linkgit:git-interpret-trailers[1]). For
    example, if your project uses `Reviewed-by` trailers, you might want
    to see who has been reviewing with
@@ -76,7 +76,7 @@ unless the `--email` option is specified. If the value cannot be parsed
 as an identity, it will be taken literally and completely.
 
  - `format:<format>`, any string accepted by the `--format` option of
-   'git log'. (See the "PRETTY FORMATS" section of
+   `git log`. (See the 'PRETTY FORMATS' section of
    linkgit:git-log[1].)
 --
 +
@@ -85,11 +85,11 @@ value (but again, only once per unique value in that commit). For
 example, `git shortlog --group=author --group=trailer:co-authored-by`
 counts both authors and co-authors.
 
--c::
---committer::
+`-c`::
+`--committer`::
 	This is an alias for `--group=committer`.
 
--w[<width>[,<indent1>[,<indent2>]]]::
+`-w[<width>[,<indent1>[,<indent2>]]]`::
 	Linewrap the output by wrapping each line at `width`.  The first
 	line of each entry is indented by `indent1` spaces, and the second
 	and subsequent lines are indented by `indent2` spaces. `width`,
@@ -98,16 +98,16 @@ counts both authors and co-authors.
 If width is `0` (zero) then indent the lines of the output without wrapping
 them.
 
-<revision-range>::
+`<revision-range>`::
 	Show only commits in the specified revision range.  When no
-	<revision-range> is specified, it defaults to `HEAD` (i.e. the
+	_<revision-range>_ is specified, it defaults to `HEAD` (i.e. the
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision-range>, see the "Specifying Ranges"
+	ways to spell _<revision-range>_, see the 'Specifying Ranges'
 	section of linkgit:gitrevisions[7].
 
-[--] <path>...::
+`[--] <path>...`::
 	Consider only commits that are enough to explain how the files
 	that match the specified paths came to be.
 +
-- 
gitgitgadget

[PATCH 4/4] doc: convert git-describe manual page to synopsis style

[Jean-Noël Avila via GitGitGadget]

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

     * convert commands and options to synopsis style
     * use _<placeholder>_ for arguments

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

diff --git a/Documentation/git-describe.adoc b/Documentation/git-describe.adoc
index 08ff715709..b2cb1e47e4 100644
--- a/Documentation/git-describe.adoc
+++ b/Documentation/git-describe.adoc
@@ -7,10 +7,10 @@ git-describe - Give an object a human readable name based on an available ref
 
 SYNOPSIS
 --------
-[verse]
-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
-'git describe' <blob>
+[synopsis]
+git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
+git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
+git describe <blob>
 
 DESCRIPTION
 -----------
@@ -22,70 +22,70 @@ abbreviated object name of the most recent commit. The result
 is a "human-readable" object name which can also be used to
 identify the commit to other git commands.
 
-By default (without --all or --tags) `git describe` only shows
+By default (without `--all` or `--tags`) `git describe` only shows
 annotated tags.  For more information about creating annotated tags
-see the -a and -s options to linkgit:git-tag[1].
+see the `-a` and `-s` options to linkgit:git-tag[1].
 
 If the given object refers to a blob, it will be described
 as `<commit-ish>:<path>`, such that the blob can be found
-at `<path>` in the `<commit-ish>`, which itself describes the
+at _<path>_ in the _<commit-ish>_, which itself describes the
 first commit in which this blob occurs in a reverse revision walk
-from HEAD.
+from `HEAD`.
 
 OPTIONS
 -------
-<commit-ish>...::
-	Commit-ish object names to describe.  Defaults to HEAD if omitted.
+`<commit-ish>...`::
+	Commit-ish object names to describe. Defaults to `HEAD` if omitted.
 
---dirty[=<mark>]::
---broken[=<mark>]::
+`--dirty[=<mark>]`::
+`--broken[=<mark>]`::
 	Describe the state of the working tree.  When the working
-	tree matches HEAD, the output is the same as "git describe
-	HEAD".  If the working tree has local modification "-dirty"
+	tree matches `HEAD`, the output is the same as `git describe HEAD`.
+	If the working tree has local modification, `-dirty`
 	is appended to it.  If a repository is corrupt and Git
 	cannot determine if there is local modification, Git will
-	error out, unless `--broken' is given, which appends
-	the suffix "-broken" instead.
+	error out, unless `--broken` is given, which appends
+	the suffix `-broken` instead.
 
---all::
+`--all`::
 	Instead of using only the annotated tags, use any ref
 	found in `refs/` namespace.  This option enables matching
 	any known branch, remote-tracking branch, or lightweight tag.
 
---tags::
+`--tags`::
 	Instead of using only the annotated tags, use any tag
 	found in `refs/tags` namespace.  This option enables matching
 	a lightweight (non-annotated) tag.
 
---contains::
+`--contains`::
 	Instead of finding the tag that predates the commit, find
 	the tag that comes after the commit, and thus contains it.
-	Automatically implies --tags.
+	Automatically implies `--tags`.
 
---abbrev=<n>::
+`--abbrev=<n>`::
 	Instead of using the default number of hexadecimal digits (which
 	will vary according to the number of objects in the repository with
-	a default of 7) of the abbreviated object name, use <n> digits, or
-	as many digits as needed to form a unique object name. An <n> of 0
+	a default of 7) of the abbreviated object name, use _<n>_ digits, or
+	as many digits as needed to form a unique object name. An _<n>_ of 0
 	will suppress long format, only showing the closest tag.
 
---candidates=<n>::
+`--candidates=<n>`::
 	Instead of considering only the 10 most recent tags as
 	candidates to describe the input commit-ish consider
-	up to <n> candidates.  Increasing <n> above 10 will take
+	up to _<n>_ candidates.  Increasing _<n>_ above 10 will take
 	slightly longer but may produce a more accurate result.
-	An <n> of 0 will cause only exact matches to be output.
+	An _<n>_ of 0 will cause only exact matches to be output.
 
---exact-match::
+`--exact-match`::
 	Only output exact matches (a tag directly references the
-	supplied commit).  This is a synonym for --candidates=0.
+	supplied commit).  This is a synonym for `--candidates=0`.
 
---debug::
+`--debug`::
 	Verbosely display information about the searching strategy
 	being employed to standard error.  The tag name will still
 	be printed to standard out.
 
---long::
+`--long`::
 	Always output the long format (the tag, the number of commits
 	and the abbreviated commit name) even when it matches a tag.
 	This is useful when you want to see parts of the commit object name
@@ -94,8 +94,8 @@ OPTIONS
 	describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
 	that points at object deadbee....).
 
---match <pattern>::
-	Only consider tags matching the given `glob(7)` pattern,
+`--match <pattern>`::
+	Only consider tags matching the given `glob`(7) pattern,
 	excluding the "refs/tags/" prefix. If used with `--all`, it also
 	considers local branches and remote-tracking references matching the
 	pattern, excluding respectively "refs/heads/" and "refs/remotes/"
@@ -104,22 +104,22 @@ OPTIONS
 	matching any of the patterns will be considered.  Use `--no-match` to
 	clear and reset the list of patterns.
 
---exclude <pattern>::
-	Do not consider tags matching the given `glob(7)` pattern, excluding
+`--exclude <pattern>`::
+	Do not consider tags matching the given `glob`(7) pattern, excluding
 	the "refs/tags/" prefix. If used with `--all`, it also does not consider
 	local branches and remote-tracking references matching the pattern,
-	excluding respectively "refs/heads/" and "refs/remotes/" prefix;
+	excluding respectively "`refs/heads/`" and "`refs/remotes/`" prefix;
 	references of other types are never considered. If given multiple times,
 	a list of patterns will be accumulated and tags matching any of the
-	patterns will be excluded. When combined with --match a tag will be
-	considered when it matches at least one --match pattern and does not
-	match any of the --exclude patterns. Use `--no-exclude` to clear and
+	patterns will be excluded. When combined with `--match` a tag will be
+	considered when it matches at least one `--match` pattern and does not
+	match any of the `--exclude` patterns. Use `--no-exclude` to clear and
 	reset the list of patterns.
 
---always::
+`--always`::
 	Show uniquely abbreviated commit object as fallback.
 
---first-parent::
+`--first-parent`::
 	Follow only the first parent commit upon seeing a merge commit.
 	This is useful when you wish to not match tags on branches merged
 	in the history of the target commit.
@@ -139,8 +139,8 @@ an abbreviated object name for the commit itself ("2414721")
 at the end.
 
 The number of additional commits is the number
-of commits which would be displayed by "git log v1.0.4..parent".
-The hash suffix is "-g" + an unambiguous abbreviation for the tip commit
+of commits which would be displayed by `git log v1.0.4..parent`.
+The hash suffix is "`-g`" + an unambiguous abbreviation for the tip commit
 of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The
 length of the abbreviation scales as the repository grows, using the
 approximate number of objects in the repository and a bit of math
@@ -149,12 +149,12 @@ The "g" prefix stands for "git" and is used to allow describing the version of
 a software depending on the SCM the software is managed with. This is useful
 in an environment where people may use different SCMs.
 
-Doing a 'git describe' on a tag-name will just show the tag name:
+Doing a `git describe` on a tag-name will just show the tag name:
 
 	[torvalds@g5 git]$ git describe v1.0.4
 	v1.0.4
 
-With --all, the command can use branch heads as references, so
+With `--all`, the command can use branch heads as references, so
 the output shows the reference path as well:
 
 	[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
@@ -163,7 +163,7 @@ the output shows the reference path as well:
 	[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
 	heads/lt/describe-7-g975b
 
-With --abbrev set to 0, the command can be used to find the
+With `--abbrev` set to 0, the command can be used to find the
 closest tagname without any suffix:
 
 	[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
@@ -179,13 +179,13 @@ be sufficient to disambiguate these commits.
 SEARCH STRATEGY
 ---------------
 
-For each commit-ish supplied, 'git describe' will first look for
+For each commit-ish supplied, `git describe` will first look for
 a tag which tags exactly that commit.  Annotated tags will always
 be preferred over lightweight tags, and tags with newer dates will
 always be preferred over tags with older dates.  If an exact match
 is found, its name will be output and searching will stop.
 
-If an exact match was not found, 'git describe' will walk back
+If an exact match was not found, `git describe` will walk back
 through the commit history to locate an ancestor commit which
 has been tagged.  The ancestor's tag will be output along with an
 abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
@@ -203,7 +203,7 @@ BUGS
 
 Tree objects as well as tag objects not pointing at commits, cannot be described.
 When describing blobs, the lightweight tags pointing at blobs are ignored,
-but the blob is still described as <commit-ish>:<path> despite the lightweight
+but the blob is still described as `<commit-ish>:<path>` despite the lightweight
 tag being favorable.
 
 GIT
-- 
gitgitgadget