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

From: "Jean-Noël Avila via GitGitGadget" <[email-masked]>
Date: Sat, 04 Apr 2026 17:12:46 +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-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