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

From: "Jean-Noël Avila via GitGitGadget" <[email-masked]>
Date: Sat, 04 Apr 2026 17:12:45 +0000

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email-masked]>

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

Signed-off-by: Jean-Noël Avila <[email-masked]>
---
 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