[PATCH v3 3/4] git-verify-* doc: update mark-up of synopsis option descriptions

From

Jean-Noël Avila <jn.avila@free.fr>

Date

May 10, 2025, 12:33 UTC

Message-ID

<20250510123346.20927-4-jn.avila@free.fr>

In-Reply-To

<20250510123346.20927-1-jn.avila@free.fr>

From: Junio C Hamano <gitster@pobox.com>

 * use [synopsis], not [verse] in the SYNOPSIS section
 * enclose `--option=<value>` in backquotes
 * do not describe non-option arguments in the OPTIONS section

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-verify-commit.adoc | 16 +++++++---------
 Documentation/git-verify-pack.adoc   | 28 ++++++++++++----------------
 Documentation/git-verify-tag.adoc    | 16 +++++++---------
 3 files changed, 26 insertions(+), 34 deletions(-)

diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc
index aee4c40eac..ff5b8b97ef 100644
--- a/Documentation/git-verify-commit.adoc
+++ b/Documentation/git-verify-commit.adoc
@@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits
 
 SYNOPSIS
 --------
-[verse]
-'git verify-commit' [-v | --verbose] [--raw] <commit>...
+[synopsis]
+git verify-commit [-v | --verbose] [--raw] <commit>...
 
 DESCRIPTION
 -----------
-Validates the GPG signature created by 'git commit -S'.
+Validates the GPG signature created by `git commit -S`
+on the commit objects given on the command line.
 
 OPTIONS
 -------
---raw::
+`--raw`::
 	Print the raw gpg status output to standard error instead of the normal
 	human-readable output.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Print the contents of the commit object before validating it.
 
-<commit>...::
-	SHA-1 identifiers of Git commit objects.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc
index d7e886918a..b0462d8db3 100644
--- a/Documentation/git-verify-pack.adoc
+++ b/Documentation/git-verify-pack.adoc
@@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files
 
 SYNOPSIS
 --------
-[verse]
-'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
+[synopsis]
+git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
 
 
 DESCRIPTION
 -----------
-Reads given idx file for packed Git archive created with the
-'git pack-objects' command and verifies the idx file and the
-corresponding pack file.
+Read each idx file for packed Git archive given on the command line,
+and verify the idx file and the corresponding pack file.
 
 OPTIONS
 -------
-<pack>.idx ...::
-	The idx files to verify.
-
--v::
---verbose::
+`-v`::
+`--verbose`::
 	After verifying the pack, show the list of objects contained
 	in the pack and a histogram of delta chain length.
 
--s::
---stat-only::
+`-s`::
+`--stat-only`::
 	Do not verify the pack contents; only show the histogram of delta
 	chain length.  With `--verbose`, the list of objects is also shown.
 
-\--::
+`--`::
 	Do not interpret any more arguments as options.
 
 OUTPUT FORMAT
 -------------
-When specifying the -v option the format used is:
+When specifying the `-v` option the format used is:
 
-	SHA-1 type size size-in-packfile offset-in-packfile
+	object-name type size size-in-packfile offset-in-packfile
 
 for objects that are not deltified in the pack, and
 
-	SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1
+	object-name type size size-in-packfile offset-in-packfile depth base-object-name
 
 for objects that are deltified.
 
diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc
index 81d50ecc4c..b3721a86f4 100644
--- a/Documentation/git-verify-tag.adoc
+++ b/Documentation/git-verify-tag.adoc
@@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags
 
 SYNOPSIS
 --------
-[verse]
-'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
+[synopsis]
+git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...
 
 DESCRIPTION
 -----------
-Validates the gpg signature created by 'git tag'.
+Validates the gpg signature created by `git tag` in the tag
+objects listed on the command line.
 
 OPTIONS
 -------
---raw::
+`--raw`::
 	Print the raw gpg status output to standard error instead of the normal
 	human-readable output.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Print the contents of the tag object before validating it.
 
-<tag>...::
-	SHA-1 identifiers of Git tag objects.
-
 GIT
 ---
 Part of the linkgit:git[1] suite

-- 
2.48.0