[PATCH 0/4] A handful of doc synopsis/options update

[PATCH 0/4] A handful of doc synopsis/options update

[Junio C Hamano]

Continuing what Jean-Noël started with 22293895 (doc: apply synopsis
simplification on git-clone and git-init, 2024-09-24), use more
[synopsis] (rather than [verse]) mark-up and also make sure

 - dashed options in the text, including the heading for enumerated
   dashed options in the OPTIONS section, are `backquoted` to be
   typeset verbatim.

 - both positive and negative variants are spelled out when the
   option is negatable, i.e. a heading "--[no-]opt::" is separated
   into "--opt::" and "--no-opt::", to help grep hit with simpler
   patterns.

 - non-options are not described in the OPTIONS section.

The "git worktree" one is a bit unsatisfactory and should be
considered WIP.

Junio C Hamano (4):
  git-verify-* doc: update mark-up of synopsis option descriptions
  git-{var,write-tree} docs: update mark-up of synopsis option
    descriptions
  git-daemon doc: update mark-up of synopsis option descriptions
  git-worktree doc: update mark-up of synopsis option descriptions

 Documentation/git-daemon.adoc        | 107 ++++++++++++++-------------
 Documentation/git-var.adoc           |   6 +-
 Documentation/git-verify-commit.adoc |  16 ++--
 Documentation/git-verify-pack.adoc   |  28 +++----
 Documentation/git-verify-tag.adoc    |  16 ++--
 Documentation/git-worktree.adoc      |  71 +++++++++---------
 Documentation/git-write-tree.adoc    |  16 ++--
 7 files changed, 129 insertions(+), 131 deletions(-)

-- 
2.49.0-599-g90c2cffacf

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

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation pages for 'git
verify-commit', 'git verify-tag', and 'git verify-pack' to

 * 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>
---
 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..ec995323f6 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.49.0-599-g90c2cffacf

[PATCH 2/4] git-{var,write-tree} docs: update mark-up of synopsis option descriptions

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation for 'git var' and
'git write-tree' to

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

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-var.adoc        |  6 +++---
 Documentation/git-write-tree.adoc | 16 ++++++++--------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc
index 0680568dfd..909963b1c2 100644
--- a/Documentation/git-var.adoc
+++ b/Documentation/git-var.adoc
@@ -8,8 +8,8 @@ git-var - Show a Git logical variable
 
 SYNOPSIS
 --------
-[verse]
-'git var' (-l | <variable>)
+[synopsis]
+git var (-l | <variable>)
 
 DESCRIPTION
 -----------
@@ -18,7 +18,7 @@ no value.
 
 OPTIONS
 -------
--l::
+`-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
 	as well. (However, the configuration variables listing functionality
diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc
index f22041a9dc..4e1c3b9c0c 100644
--- a/Documentation/git-write-tree.adoc
+++ b/Documentation/git-write-tree.adoc
@@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index
 
 SYNOPSIS
 --------
-[verse]
-'git write-tree' [--missing-ok] [--prefix=<prefix>/]
+[synopsis]
+git write-tree [--missing-ok] [--prefix=<prefix>/]
 
 DESCRIPTION
 -----------
@@ -18,21 +18,21 @@ tree object is printed to standard output.
 
 The index must be in a fully merged state.
 
-Conceptually, 'git write-tree' sync()s the current index contents
+Conceptually, `git write-tree` sync()s the current index contents
 into a set of tree files.
 In order to have that match what is actually in your directory right
-now, you need to have done a 'git update-index' phase before you did the
-'git write-tree'.
+now, you need to have done a `git update-index` phase before you did the
+`git write-tree`.
 
 
 OPTIONS
 -------
---missing-ok::
-	Normally 'git write-tree' ensures that the objects referenced by the
+`--missing-ok`::
+	Normally `git write-tree` ensures that the objects referenced by the
 	directory exist in the object database.  This option disables this
 	check.
 
---prefix=<prefix>/::
+`--prefix=<prefix>/`::
 	Writes a tree object that represents a subdirectory
 	`<prefix>`.  This can be used to write the tree object
 	for a subproject that is in the named subdirectory.
-- 
2.49.0-599-g90c2cffacf

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

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation of 'git daemon'
to

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

Also, split '--[no-]option' into '--option' and '--no-option'
to make it easier to grep for them.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-daemon.adoc | 107 +++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 53 deletions(-)

diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc
index ede7b935d6..3eb9332e55 100644
--- a/Documentation/git-daemon.adoc
+++ b/Documentation/git-daemon.adoc
@@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories
 
 SYNOPSIS
 --------
-[verse]
-'git daemon' [--verbose] [--syslog] [--export-all]
-	     [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
-	     [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
-	     [--user-path | --user-path=<path>]
-	     [--interpolated-path=<pathtemplate>]
-	     [--reuseaddr] [--detach] [--pid-file=<file>]
-	     [--enable=<service>] [--disable=<service>]
-	     [--allow-override=<service>] [--forbid-override=<service>]
-	     [--access-hook=<path>] [--[no-]informative-errors]
-	     [--inetd |
-	      [--listen=<host-or-ipaddr>] [--port=<n>]
-	      [--user=<user> [--group=<group>]]]
-	     [--log-destination=(stderr|syslog|none)]
-	     [<directory>...]
+[synopsis]
+git daemon [--verbose] [--syslog] [--export-all]
+	   [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+	   [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+	   [--user-path | --user-path=<path>]
+	   [--interpolated-path=<pathtemplate>]
+	   [--reuseaddr] [--detach] [--pid-file=<file>]
+	   [--enable=<service>] [--disable=<service>]
+	   [--allow-override=<service>] [--forbid-override=<service>]
+	   [--access-hook=<path>] [--[no-]informative-errors]
+	   [--inetd |
+	     [--listen=<host-or-ipaddr>] [--port=<n>]
+	     [--user=<user> [--group=<group>]]]
+	   [--log-destination=(stderr|syslog|none)]
+	   [<directory>...]
 
 DESCRIPTION
 -----------
@@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'.
 
 OPTIONS
 -------
---strict-paths::
+`--strict-paths`::
 	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
 	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
 	'git daemon' will refuse to start when this option is enabled and no
 	directory arguments are provided.
 
---base-path=<path>::
+`--base-path=<path>`::
 	Remap all the path requests as relative to the given path.
 	This is sort of "Git root" - if you run 'git daemon' with
 	'--base-path=/srv/git' on example.com, then if you later try to pull
 	'git://example.com/hello.git', 'git daemon' will interpret the path
 	as `/srv/git/hello.git`.
 
---base-path-relaxed::
-	If --base-path is enabled and repo lookup fails, with this option
+`--base-path-relaxed`::
+	If `--base-path` is enabled and repo lookup fails, with this option
 	'git daemon' will attempt to lookup without prefixing the base path.
-	This is useful for switching to --base-path usage, while still
+	This is useful for switching to `--base-path` usage, while still
 	allowing the old paths.
 
---interpolated-path=<pathtemplate>::
+`--interpolated-path=<pathtemplate>`::
 	To support virtual hosting, an interpolated path template can be
 	used to dynamically construct alternate paths.  The template
 	supports %H for the target hostname as supplied by the client but
@@ -75,48 +75,48 @@ OPTIONS
 	After interpolation, the path is validated against the directory
 	list.
 
---export-all::
+`--export-all`::
 	Allow pulling from all directories that look like Git repositories
 	(have the 'objects' and 'refs' subdirectories), even if they
 	do not have the 'git-daemon-export-ok' file.
 
---inetd::
-	Have the server run as an inetd service. Implies --syslog (may be
-	overridden with `--log-destination=`).
-	Incompatible with --detach, --port, --listen, --user and --group
-	options.
+`--inetd`::
+	Have the server run as an inetd service. Implies `--syslog` (may
+	be overridden with `--log-destination=`).
+	Incompatible with `--detach`, `--port`, `--listen`, `--user` and
+	`--group` options.
 
---listen=<host-or-ipaddr>::
+`--listen=<host-or-ipaddr>`::
 	Listen on a specific IP address or hostname.  IP addresses can
 	be either an IPv4 address or an IPv6 address if supported.  If IPv6
-	is not supported, then --listen=<hostname> is also not supported and
-	--listen must be given an IPv4 address.
+	is not supported, then `--listen=<hostname>` is also not supported
+	and `--listen` must be given an IPv4 address.
 	Can be given more than once.
 	Incompatible with `--inetd` option.
 
---port=<n>::
+`--port=<n>`::
 	Listen on an alternative port.  Incompatible with `--inetd` option.
 
---init-timeout=<n>::
+`--init-timeout=<n>`::
 	Timeout (in seconds) between the moment the connection is established
 	and the client request is received (typically a rather low value, since
 	that should be basically immediate).
 
---timeout=<n>::
+`--timeout=<n>`::
 	Timeout (in seconds) for specific client sub-requests. This includes
 	the time it takes for the server to process the sub-request and the
 	time spent waiting for the next client's request.
 
---max-connections=<n>::
+`--max-connections=<n>`::
 	Maximum number of concurrent clients, defaults to 32.  Set it to
 	zero for no limit.
 
---syslog::
+`--syslog`::
 	Short for `--log-destination=syslog`.
 
---log-destination=<destination>::
+`--log-destination=<destination>`::
 	Send log messages to the specified destination.
-	Note that this option does not imply --verbose,
+	Note that this option does not imply `--verbose`,
 	thus by default only error conditions will be logged.
 	The <destination> must be one of:
 +
@@ -135,8 +135,8 @@ none::
 The default destination is `syslog` if `--inetd` or `--detach` is specified,
 otherwise `stderr`.
 
---user-path::
---user-path=<path>::
+`--user-path`::
+`--user-path=<path>`::
 	Allow {tilde}user notation to be used in requests.  When
 	specified with no parameter, a request to
 	git://host/{tilde}alice/foo is taken as a request to access
@@ -145,23 +145,23 @@ otherwise `stderr`.
 	taken as a request to access `<path>/foo` repository in
 	the home directory of user `alice`.
 
---verbose::
+`--verbose`::
 	Log details about the incoming connections and requested files.
 
---reuseaddr::
+`--reuseaddr`::
 	Use SO_REUSEADDR when binding the listening socket.
 	This allows the server to restart without waiting for
 	old connections to time out.
 
---detach::
-	Detach from the shell. Implies --syslog.
+`--detach`::
+	Detach from the shell. Implies `--syslog`.
 
---pid-file=<file>::
+`--pid-file=<file>`::
 	Save the process id in 'file'.  Ignored when the daemon
 	is run under `--inetd`.
 
---user=<user>::
---group=<group>::
+`--user=<user>`::
+`--group=<group>`::
 	Change daemon's uid and gid before entering the service loop.
 	When only `--user` is given without `--group`, the
 	primary group ID for the user is used.  The values of
@@ -179,30 +179,31 @@ may also want to set and export `HOME` to point at the home
 directory of `<user>` before starting the daemon, and make sure any
 Git configuration files in that directory are readable by `<user>`.
 
---enable=<service>::
---disable=<service>::
+`--enable=<service>`::
+`--disable=<service>`::
 	Enable/disable the service site-wide per default.  Note
 	that a service disabled site-wide can still be enabled
 	per repository if it is marked overridable and the
 	repository enables the service with a configuration
 	item.
 
---allow-override=<service>::
---forbid-override=<service>::
+`--allow-override=<service>`::
+`--forbid-override=<service>`::
 	Allow/forbid overriding the site-wide default with per
 	repository configuration.  By default, all the services
 	may be overridden.
 
---[no-]informative-errors::
+`--informative-errors`::
+`--no-informative-errors`::
 	When informative errors are turned on, git-daemon will report
 	more verbose errors to the client, differentiating conditions
 	like "no such repository" from "repository not exported". This
 	is more convenient for clients, but may leak information about
 	the existence of unexported repositories.  When informative
 	errors are not enabled, all errors report "access denied" to the
-	client. The default is --no-informative-errors.
+	client. The default is `--no-informative-errors`.
 
---access-hook=<path>::
+`--access-hook=<path>`::
 	Every time a client connects, first run an external command
 	specified by the <path> with service name (e.g. "upload-pack"),
 	path to the repository, hostname (%H), canonical hostname
-- 
2.49.0-599-g90c2cffacf

[WIP PATCH 4/4] git-worktree doc: update mark-up of synopsis option descriptions

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation of 'git worktree'
to

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

Also, split '--[no-]option' into '--option' and '--no-option'
to make it easier to grep for them.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-worktree.adoc | 71 ++++++++++++++++++---------------
 1 file changed, 38 insertions(+), 33 deletions(-)

diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index 8340b7f028..46715cbef7 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@ -8,16 +8,16 @@ git-worktree - Manage multiple working trees
 
 SYNOPSIS
 --------
-[verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
-		   [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
-'git worktree list' [-v | --porcelain [-z]]
-'git worktree lock' [--reason <string>] <worktree>
-'git worktree move' <worktree> <new-path>
-'git worktree prune' [-n] [-v] [--expire <expire>]
-'git worktree remove' [-f] <worktree>
-'git worktree repair' [<path>...]
-'git worktree unlock' <worktree>
+[synopsis]
+git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+		 [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
+git worktree list [-v | --porcelain [-z]]
+git worktree lock [--reason <string>] <worktree>
+git worktree move <worktree> <new-path>
+git worktree prune [-n] [-v] [--expire <expire>]
+git worktree remove [-f] <worktree>
+git worktree repair [<path>...]
+git worktree unlock <worktree>
 
 DESCRIPTION
 -----------
@@ -169,8 +169,8 @@ Unlock a worktree, allowing it to be pruned, moved or deleted.
 OPTIONS
 -------
 
--f::
---force::
+`-f`::
+`--force`::
 	By default, `add` refuses to create a new worktree when
 	`<commit-ish>` is a branch name and is already checked out by
 	another worktree, or if `<path>` is already assigned to some
@@ -186,8 +186,8 @@ allows the move to proceed; use `--force` twice if the destination is locked.
 `remove` refuses to remove an unclean worktree unless `--force` is used.
 To remove a locked worktree, specify `--force` twice.
 
--b <new-branch>::
--B <new-branch>::
+`-b <new-branch>`::
+`-B <new-branch>`::
 	With `add`, create a new branch named `<new-branch>` starting at
 	`<commit-ish>`, and check out `<new-branch>` into the new worktree.
 	If `<commit-ish>` is omitted, it defaults to `HEAD`.
@@ -195,18 +195,20 @@ To remove a locked worktree, specify `--force` twice.
 	exists. `-B` overrides this safeguard, resetting `<new-branch>` to
 	`<commit-ish>`.
 
--d::
---detach::
+`-d`::
+`--detach`::
 	With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD"
 	in linkgit:git-checkout[1].
 
---[no-]checkout::
+`--checkout`::
+`--no-checkout`::
 	By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can
 	be used to suppress checkout in order to make customizations,
 	such as configuring sparse-checkout. See "Sparse checkout"
 	in linkgit:git-read-tree[1].
 
---[no-]guess-remote::
+`--guess-remote`::
+`--no-guess-remote`::
 	With `worktree add <path>`, without `<commit-ish>`, instead
 	of creating a new branch from `HEAD`, if there exists a tracking
 	branch in exactly one remote matching the basename of `<path>`,
@@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice.
 This can also be set up as the default behaviour by using the
 `worktree.guessRemote` config option.
 
---[no-]relative-paths::
+`--relative-paths`
+`--no-relative-paths`::
 	Link worktrees using relative paths or absolute paths (default).
 	Overrides the `worktree.useRelativePaths` config option, see
 	linkgit:git-config[1].
@@ -224,55 +227,57 @@ This can also be set up as the default behaviour by using the
 With `repair`, the linking files will be updated if there's an absolute/relative
 mismatch, even if the links are correct.
 
---[no-]track::
-	When creating a new branch, if `<commit-ish>` is a branch,
+`--track`::
+`--no-track`::
+	With `--track`, when creating a new branch,
+	if `<commit-ish>` is a branch,
 	mark it as "upstream" from the new branch.  This is the
 	default if `<commit-ish>` is a remote-tracking branch.  See
 	`--track` in linkgit:git-branch[1] for details.
 
---lock::
+`--lock`::
 	Keep the worktree locked after creation. This is the
 	equivalent of `git worktree lock` after `git worktree add`,
 	but without a race condition.
 
--n::
---dry-run::
+`-n`::
+`--dry-run`::
 	With `prune`, do not remove anything; just report what it would
 	remove.
 
---orphan::
+`--orphan`::
 	With `add`, make the new worktree and index empty, associating
 	the worktree with a new unborn branch named `<new-branch>`.
 
---porcelain::
+`--porcelain`::
 	With `list`, output in an easy-to-parse format for scripts.
 	This format will remain stable across Git versions and regardless of user
 	configuration.  It is recommended to combine this with `-z`.
 	See below for details.
 
--z::
+`-z`::
 	Terminate each line with a NUL rather than a newline when
 	`--porcelain` is specified with `list`. This makes it possible
 	to parse the output when a worktree path contains a newline
 	character.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	With `add`, suppress feedback messages.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	With `prune`, report all removals.
 +
 With `list`, output additional information about worktrees (see below).
 
---expire <time>::
+`--expire <time>`::
 	With `prune`, only expire unused worktrees older than `<time>`.
 +
 With `list`, annotate missing worktrees as prunable if they are older than
 `<time>`.
 
---reason <string>::
+`--reason <string>`::
 	With `lock` or with `add --lock`, an explanation why the worktree
 	is locked.
 
-- 
2.49.0-599-g90c2cffacf

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

[Eric Sunshine]

On Thu, May 1, 2025 at 5:34 PM Junio C Hamano <gitster@pobox.com> wrote:
> To unify mark-up used in our documentation to a newer convention,
> started by 22293895 (doc: apply synopsis simplification on git-clone
> and git-init, 2024-09-24), update the documentation pages for 'git
> verify-commit', 'git verify-tag', and 'git verify-pack' to
>
>  * 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>
> ---
> diff --git 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
> -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.

Taking note of the casing of GPG (all uppercase)...

> diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc
> @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files
> -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.

Okay, rewrite seems reasonable. Do we want to backtick "idx" and "pack"?

>  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

Do we not typically call this object-ID (OID) rather than object-name?

> diff --git 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

...all uppercase GPG...

> -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.

...since this is being rewritten anyhow, it probably would make sense
to employ consistent casing of GPG.

Re: [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions

[Eric Sunshine]

On Thu, May 1, 2025 at 5:34 PM Junio C Hamano <gitster@pobox.com> wrote:
> To unify mark-up used in our documentation to a newer convention,
> started by 22293895 (doc: apply synopsis simplification on git-clone
> and git-init, 2024-09-24), update the documentation of 'git daemon'
> to
>
>  * use [synopsis], not [verse] in the SYNOPSIS section
>  * enclose `--option=<value>` in backquotes
>
> Also, split '--[no-]option' into '--option' and '--no-option'
> to make it easier to grep for them.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc
> @@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'.
> ---strict-paths::
> +`--strict-paths`::
>         Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
>         "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
>         'git daemon' will refuse to start when this option is enabled and no
>         directory arguments are provided.

Should 'git daemon' be wrapped in backticks instead?

> ---base-path=<path>::
> +`--base-path=<path>`::
>         Remap all the path requests as relative to the given path.
>         This is sort of "Git root" - if you run 'git daemon' with
>         '--base-path=/srv/git' on example.com, then if you later try to pull

Should the '--base-path=/srv/git' example be wrapped in backticks instead?

>         'git://example.com/hello.git', 'git daemon' will interpret the path
>         as `/srv/git/hello.git`.

These are inconsistent, as well: the first two use apostrophes, and
the latter backticks.

> @@ -135,8 +135,8 @@ none::
> +`--user-path`::
> +`--user-path=<path>`::
>         Allow {tilde}user notation to be used in requests.  When
>         specified with no parameter, a request to
>         git://host/{tilde}alice/foo is taken as a request to access

And this URL has no quoting.

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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>> -'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.
>
> Okay, rewrite seems reasonable. Do we want to backtick "idx" and "pack"?

No.  I would understand if it is spelled '.idx', to refer to a
concrete file suffix that people would type verbatim.  In this
sentence, however, I think "idx file" and "pack file" are used as a
general noun.

>>  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
>
> Do we not typically call this object-ID (OID) rather than object-name?

Given these entries in Documentation/glossary-content.adoc

        [[def_hash]]hash::
                In Git's context, synonym for <<def_object_name,object name>>.
        [[def_object_identifier]]object identifier (oid)::
                Synonym for <<def_object_name,object name>>.

I do not think so, and if we find somebody doing so, we should
correct them.

>> diff --git 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
>
> ...all uppercase GPG...
>
>> -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.
>
> ...since this is being rewritten anyhow, it probably would make sense
> to employ consistent casing of GPG.

Once the dust settles from this series, yes, but not in this series
that is about mark-up.

Thanks.

Re: [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>> diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc
>> @@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'.
>> ---strict-paths::
>> +`--strict-paths`::
>>         Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
>>         "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
>>         'git daemon' will refuse to start when this option is enabled and no
>>         directory arguments are provided.
>
> Should 'git daemon' be wrapped in backticks instead?

Yup, good eyes.

>> ---base-path=<path>::
>> +`--base-path=<path>`::
>>         Remap all the path requests as relative to the given path.
>>         This is sort of "Git root" - if you run 'git daemon' with
>>         '--base-path=/srv/git' on example.com, then if you later try to pull
>
> Should the '--base-path=/srv/git' example be wrapped in backticks instead?

Probably, so should `git daemon` one line before it.

>>         'git://example.com/hello.git', 'git daemon' will interpret the path
>>         as `/srv/git/hello.git`.
>
> These are inconsistent, as well: the first two use apostrophes, and
> the latter backticks.

I am not sure what the best mark-up for the sample strings.  They
are not what the end-users are expected to type verbatim, so I've
punted and left them out as in the original ;-)

>> @@ -135,8 +135,8 @@ none::
>> +`--user-path`::
>> +`--user-path=<path>`::
>>         Allow {tilde}user notation to be used in requests.  When
>>         specified with no parameter, a request to
>>         git://host/{tilde}alice/foo is taken as a request to access
>
> And this URL has no quoting.

Likewise.

Re: [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions

[Junio C Hamano]

Here are incremental changes relative to the previous round, taking
inspiration from your suggestions.

I think the sample option, sitename, and pathname must be typed
verbatim by the readers if the behaviour described in the text
is to be reproduced, so changed them in the base-path description
all to be marked up as `literal string`.


diff --git c/Documentation/git-daemon.adoc w/Documentation/git-daemon.adoc
index 3eb9332e55..bc3f77405e 100644
--- c/Documentation/git-daemon.adoc
+++ w/Documentation/git-daemon.adoc
@@ -32,7 +32,7 @@ that service if it is enabled.
 It verifies that the directory has the magic file "git-daemon-export-ok", and
 it will refuse to export any Git directory that hasn't explicitly been marked
 for export this way (unless the `--export-all` parameter is specified). If you
-pass some directory paths as 'git daemon' arguments, the offers are limited to
+pass some directory paths as `git daemon` arguments, the offers are limited to
 repositories within those directories.
 
 By default, only `upload-pack` service is enabled, which serves
@@ -49,15 +49,15 @@ OPTIONS
 `--strict-paths`::
 	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
 	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
-	'git daemon' will refuse to start when this option is enabled and no
+	`git daemon` will refuse to start when this option is enabled and no
 	directory arguments are provided.
 
 `--base-path=<path>`::
 	Remap all the path requests as relative to the given path.
-	This is sort of "Git root" - if you run 'git daemon' with
-	'--base-path=/srv/git' on example.com, then if you later try to pull
-	'git://example.com/hello.git', 'git daemon' will interpret the path
-	as `/srv/git/hello.git`.
+	This is sort of "Git root" - if you run `git daemon` with
+	`--base-path=/srv/git` on `example.com`, then if you later try
+	to pull from `git://example.com/hello.git`, `git daemon` will
+	interpret the path as `/srv/git/hello.git`.
 
 `--base-path-relaxed`::
 	If `--base-path` is enabled and repo lookup fails, with this option

[PATCH v2 0/3] A handful of doc synopsis/options update

[Junio C Hamano]

Continuing what Jean-Noël started with 22293895 (doc: apply synopsis
simplification on git-clone and git-init, 2024-09-24), use more
[synopsis] (rather than [verse]) mark-up and also make sure

 - dashed options in the text, including the heading for enumerated
   dashed options in the OPTIONS section, are `backquoted` to be
   typeset verbatim.

 - both positive and negative variants are spelled out when the
   option is negatable, i.e. a heading "--[no-]opt::" is separated
   into "--opt::" and "--no-opt::", to help grep hit with simpler
   patterns.

 - non-options are not described in the OPTIONS section.

The changes in the first two patches are unchanged.

The update to "git daemon" documentation has acquired a bit more
`literal` mark-ups, prompted by a comment by Eric Sunshine on the
previous iteration.

The initial iteration contained a WIP on worktree documentation,
which has been dropped in this iteration.


1:  65a5556d4b = 1:  5e8ae75a6b git-verify-* doc: update mark-up of synopsis option descriptions
2:  a9c5bd63ee = 2:  c6cc44c72b git-{var,write-tree} docs: update mark-up of synopsis option descriptions
3:  eb0e783e21 ! 3:  d424d8c846 git-daemon doc: update mark-up of synopsis option descriptions
    @@ Documentation/git-daemon.adoc: git-daemon - A really simple server for Git repos
      
      DESCRIPTION
      -----------
    +@@ Documentation/git-daemon.adoc: that service if it is enabled.
    + It verifies that the directory has the magic file "git-daemon-export-ok", and
    + it will refuse to export any Git directory that hasn't explicitly been marked
    + for export this way (unless the `--export-all` parameter is specified). If you
    +-pass some directory paths as 'git daemon' arguments, the offers are limited to
    ++pass some directory paths as `git daemon` arguments, the offers are limited to
    + repositories within those directories.
    + 
    + By default, only `upload-pack` service is enabled, which serves
     @@ Documentation/git-daemon.adoc: An `upload-archive` also exists to serve 'git archive'.
      
      OPTIONS
    @@ Documentation/git-daemon.adoc: An `upload-archive` also exists to serve 'git arc
     +`--strict-paths`::
      	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
      	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
    - 	'git daemon' will refuse to start when this option is enabled and no
    +-	'git daemon' will refuse to start when this option is enabled and no
    ++	`git daemon` will refuse to start when this option is enabled and no
      	directory arguments are provided.
      
     ---base-path=<path>::
     +`--base-path=<path>`::
      	Remap all the path requests as relative to the given path.
    - 	This is sort of "Git root" - if you run 'git daemon' with
    - 	'--base-path=/srv/git' on example.com, then if you later try to pull
    - 	'git://example.com/hello.git', 'git daemon' will interpret the path
    - 	as `/srv/git/hello.git`.
    +-	This is sort of "Git root" - if you run 'git daemon' with
    +-	'--base-path=/srv/git' on example.com, then if you later try to pull
    +-	'git://example.com/hello.git', 'git daemon' will interpret the path
    +-	as `/srv/git/hello.git`.
    ++	This is sort of "Git root" - if you run `git daemon` with
    ++	`--base-path=/srv/git` on `example.com`, then if you later try
    ++	to pull from `git://example.com/hello.git`, `git daemon` will
    ++	interpret the path as `/srv/git/hello.git`.
      
     ---base-path-relaxed::
     -	If --base-path is enabled and repo lookup fails, with this option



Junio C Hamano (3):
  git-verify-* doc: update mark-up of synopsis option descriptions
  git-{var,write-tree} docs: update mark-up of synopsis option
    descriptions
  git-daemon doc: update mark-up of synopsis option descriptions

 Documentation/git-daemon.adoc        | 119 ++++++++++++++-------------
 Documentation/git-var.adoc           |   6 +-
 Documentation/git-verify-commit.adoc |  16 ++--
 Documentation/git-verify-pack.adoc   |  28 +++----
 Documentation/git-verify-tag.adoc    |  16 ++--
 Documentation/git-write-tree.adoc    |  16 ++--
 6 files changed, 97 insertions(+), 104 deletions(-)

-- 
2.49.0-601-ga5925c3955

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

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation pages for 'git
verify-commit', 'git verify-tag', and 'git verify-pack' to

 * 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>
---
 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..ec995323f6 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.49.0-601-ga5925c3955

[PATCH v2 2/3] git-{var,write-tree} docs: update mark-up of synopsis option descriptions

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation for 'git var' and
'git write-tree' to

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

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-var.adoc        |  6 +++---
 Documentation/git-write-tree.adoc | 16 ++++++++--------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc
index 0680568dfd..909963b1c2 100644
--- a/Documentation/git-var.adoc
+++ b/Documentation/git-var.adoc
@@ -8,8 +8,8 @@ git-var - Show a Git logical variable
 
 SYNOPSIS
 --------
-[verse]
-'git var' (-l | <variable>)
+[synopsis]
+git var (-l | <variable>)
 
 DESCRIPTION
 -----------
@@ -18,7 +18,7 @@ no value.
 
 OPTIONS
 -------
--l::
+`-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
 	as well. (However, the configuration variables listing functionality
diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc
index f22041a9dc..4e1c3b9c0c 100644
--- a/Documentation/git-write-tree.adoc
+++ b/Documentation/git-write-tree.adoc
@@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index
 
 SYNOPSIS
 --------
-[verse]
-'git write-tree' [--missing-ok] [--prefix=<prefix>/]
+[synopsis]
+git write-tree [--missing-ok] [--prefix=<prefix>/]
 
 DESCRIPTION
 -----------
@@ -18,21 +18,21 @@ tree object is printed to standard output.
 
 The index must be in a fully merged state.
 
-Conceptually, 'git write-tree' sync()s the current index contents
+Conceptually, `git write-tree` sync()s the current index contents
 into a set of tree files.
 In order to have that match what is actually in your directory right
-now, you need to have done a 'git update-index' phase before you did the
-'git write-tree'.
+now, you need to have done a `git update-index` phase before you did the
+`git write-tree`.
 
 
 OPTIONS
 -------
---missing-ok::
-	Normally 'git write-tree' ensures that the objects referenced by the
+`--missing-ok`::
+	Normally `git write-tree` ensures that the objects referenced by the
 	directory exist in the object database.  This option disables this
 	check.
 
---prefix=<prefix>/::
+`--prefix=<prefix>/`::
 	Writes a tree object that represents a subdirectory
 	`<prefix>`.  This can be used to write the tree object
 	for a subproject that is in the named subdirectory.
-- 
2.49.0-601-ga5925c3955

[PATCH v2 3/3] git-daemon doc: update mark-up of synopsis option descriptions

[Junio C Hamano]

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation of 'git daemon'
to

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

Also, split '--[no-]option' into '--option' and '--no-option'
to make it easier to grep for them.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-daemon.adoc | 119 +++++++++++++++++-----------------
 1 file changed, 60 insertions(+), 59 deletions(-)

diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc
index ede7b935d6..bc3f77405e 100644
--- a/Documentation/git-daemon.adoc
+++ b/Documentation/git-daemon.adoc
@@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories
 
 SYNOPSIS
 --------
-[verse]
-'git daemon' [--verbose] [--syslog] [--export-all]
-	     [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
-	     [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
-	     [--user-path | --user-path=<path>]
-	     [--interpolated-path=<pathtemplate>]
-	     [--reuseaddr] [--detach] [--pid-file=<file>]
-	     [--enable=<service>] [--disable=<service>]
-	     [--allow-override=<service>] [--forbid-override=<service>]
-	     [--access-hook=<path>] [--[no-]informative-errors]
-	     [--inetd |
-	      [--listen=<host-or-ipaddr>] [--port=<n>]
-	      [--user=<user> [--group=<group>]]]
-	     [--log-destination=(stderr|syslog|none)]
-	     [<directory>...]
+[synopsis]
+git daemon [--verbose] [--syslog] [--export-all]
+	   [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+	   [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+	   [--user-path | --user-path=<path>]
+	   [--interpolated-path=<pathtemplate>]
+	   [--reuseaddr] [--detach] [--pid-file=<file>]
+	   [--enable=<service>] [--disable=<service>]
+	   [--allow-override=<service>] [--forbid-override=<service>]
+	   [--access-hook=<path>] [--[no-]informative-errors]
+	   [--inetd |
+	     [--listen=<host-or-ipaddr>] [--port=<n>]
+	     [--user=<user> [--group=<group>]]]
+	   [--log-destination=(stderr|syslog|none)]
+	   [<directory>...]
 
 DESCRIPTION
 -----------
@@ -32,7 +32,7 @@ that service if it is enabled.
 It verifies that the directory has the magic file "git-daemon-export-ok", and
 it will refuse to export any Git directory that hasn't explicitly been marked
 for export this way (unless the `--export-all` parameter is specified). If you
-pass some directory paths as 'git daemon' arguments, the offers are limited to
+pass some directory paths as `git daemon` arguments, the offers are limited to
 repositories within those directories.
 
 By default, only `upload-pack` service is enabled, which serves
@@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'.
 
 OPTIONS
 -------
---strict-paths::
+`--strict-paths`::
 	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
 	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
-	'git daemon' will refuse to start when this option is enabled and no
+	`git daemon` will refuse to start when this option is enabled and no
 	directory arguments are provided.
 
---base-path=<path>::
+`--base-path=<path>`::
 	Remap all the path requests as relative to the given path.
-	This is sort of "Git root" - if you run 'git daemon' with
-	'--base-path=/srv/git' on example.com, then if you later try to pull
-	'git://example.com/hello.git', 'git daemon' will interpret the path
-	as `/srv/git/hello.git`.
+	This is sort of "Git root" - if you run `git daemon` with
+	`--base-path=/srv/git` on `example.com`, then if you later try
+	to pull from `git://example.com/hello.git`, `git daemon` will
+	interpret the path as `/srv/git/hello.git`.
 
---base-path-relaxed::
-	If --base-path is enabled and repo lookup fails, with this option
+`--base-path-relaxed`::
+	If `--base-path` is enabled and repo lookup fails, with this option
 	'git daemon' will attempt to lookup without prefixing the base path.
-	This is useful for switching to --base-path usage, while still
+	This is useful for switching to `--base-path` usage, while still
 	allowing the old paths.
 
---interpolated-path=<pathtemplate>::
+`--interpolated-path=<pathtemplate>`::
 	To support virtual hosting, an interpolated path template can be
 	used to dynamically construct alternate paths.  The template
 	supports %H for the target hostname as supplied by the client but
@@ -75,48 +75,48 @@ OPTIONS
 	After interpolation, the path is validated against the directory
 	list.
 
---export-all::
+`--export-all`::
 	Allow pulling from all directories that look like Git repositories
 	(have the 'objects' and 'refs' subdirectories), even if they
 	do not have the 'git-daemon-export-ok' file.
 
---inetd::
-	Have the server run as an inetd service. Implies --syslog (may be
-	overridden with `--log-destination=`).
-	Incompatible with --detach, --port, --listen, --user and --group
-	options.
+`--inetd`::
+	Have the server run as an inetd service. Implies `--syslog` (may
+	be overridden with `--log-destination=`).
+	Incompatible with `--detach`, `--port`, `--listen`, `--user` and
+	`--group` options.
 
---listen=<host-or-ipaddr>::
+`--listen=<host-or-ipaddr>`::
 	Listen on a specific IP address or hostname.  IP addresses can
 	be either an IPv4 address or an IPv6 address if supported.  If IPv6
-	is not supported, then --listen=<hostname> is also not supported and
-	--listen must be given an IPv4 address.
+	is not supported, then `--listen=<hostname>` is also not supported
+	and `--listen` must be given an IPv4 address.
 	Can be given more than once.
 	Incompatible with `--inetd` option.
 
---port=<n>::
+`--port=<n>`::
 	Listen on an alternative port.  Incompatible with `--inetd` option.
 
---init-timeout=<n>::
+`--init-timeout=<n>`::
 	Timeout (in seconds) between the moment the connection is established
 	and the client request is received (typically a rather low value, since
 	that should be basically immediate).
 
---timeout=<n>::
+`--timeout=<n>`::
 	Timeout (in seconds) for specific client sub-requests. This includes
 	the time it takes for the server to process the sub-request and the
 	time spent waiting for the next client's request.
 
---max-connections=<n>::
+`--max-connections=<n>`::
 	Maximum number of concurrent clients, defaults to 32.  Set it to
 	zero for no limit.
 
---syslog::
+`--syslog`::
 	Short for `--log-destination=syslog`.
 
---log-destination=<destination>::
+`--log-destination=<destination>`::
 	Send log messages to the specified destination.
-	Note that this option does not imply --verbose,
+	Note that this option does not imply `--verbose`,
 	thus by default only error conditions will be logged.
 	The <destination> must be one of:
 +
@@ -135,8 +135,8 @@ none::
 The default destination is `syslog` if `--inetd` or `--detach` is specified,
 otherwise `stderr`.
 
---user-path::
---user-path=<path>::
+`--user-path`::
+`--user-path=<path>`::
 	Allow {tilde}user notation to be used in requests.  When
 	specified with no parameter, a request to
 	git://host/{tilde}alice/foo is taken as a request to access
@@ -145,23 +145,23 @@ otherwise `stderr`.
 	taken as a request to access `<path>/foo` repository in
 	the home directory of user `alice`.
 
---verbose::
+`--verbose`::
 	Log details about the incoming connections and requested files.
 
---reuseaddr::
+`--reuseaddr`::
 	Use SO_REUSEADDR when binding the listening socket.
 	This allows the server to restart without waiting for
 	old connections to time out.
 
---detach::
-	Detach from the shell. Implies --syslog.
+`--detach`::
+	Detach from the shell. Implies `--syslog`.
 
---pid-file=<file>::
+`--pid-file=<file>`::
 	Save the process id in 'file'.  Ignored when the daemon
 	is run under `--inetd`.
 
---user=<user>::
---group=<group>::
+`--user=<user>`::
+`--group=<group>`::
 	Change daemon's uid and gid before entering the service loop.
 	When only `--user` is given without `--group`, the
 	primary group ID for the user is used.  The values of
@@ -179,30 +179,31 @@ may also want to set and export `HOME` to point at the home
 directory of `<user>` before starting the daemon, and make sure any
 Git configuration files in that directory are readable by `<user>`.
 
---enable=<service>::
---disable=<service>::
+`--enable=<service>`::
+`--disable=<service>`::
 	Enable/disable the service site-wide per default.  Note
 	that a service disabled site-wide can still be enabled
 	per repository if it is marked overridable and the
 	repository enables the service with a configuration
 	item.
 
---allow-override=<service>::
---forbid-override=<service>::
+`--allow-override=<service>`::
+`--forbid-override=<service>`::
 	Allow/forbid overriding the site-wide default with per
 	repository configuration.  By default, all the services
 	may be overridden.
 
---[no-]informative-errors::
+`--informative-errors`::
+`--no-informative-errors`::
 	When informative errors are turned on, git-daemon will report
 	more verbose errors to the client, differentiating conditions
 	like "no such repository" from "repository not exported". This
 	is more convenient for clients, but may leak information about
 	the existence of unexported repositories.  When informative
 	errors are not enabled, all errors report "access denied" to the
-	client. The default is --no-informative-errors.
+	client. The default is `--no-informative-errors`.
 
---access-hook=<path>::
+`--access-hook=<path>`::
 	Every time a client connects, first run an external command
 	specified by the <path> with service name (e.g. "upload-pack"),
 	path to the repository, hostname (%H), canonical hostname
-- 
2.49.0-601-ga5925c3955

Additional changes

[Jean-Noël Avila]

Thank you for helping out with this dull task.

Here are a few additional changes after reviewing the manpages.

Thanks

Jean-Noël

[PATCH] Additional changes

[Jean-Noël Avila]

---
 Documentation/git-daemon.adoc     | 60 +++++++++++++++----------------
 Documentation/git-var.adoc        | 40 ++++++++++-----------
 Documentation/git-verify-tag.adoc |  2 +-
 Documentation/git-write-tree.adoc |  2 +-
 4 files changed, 51 insertions(+), 53 deletions(-)

diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc
index bc3f77405e..99389f0388 100644
--- a/Documentation/git-daemon.adoc
+++ b/Documentation/git-daemon.adoc
@@ -36,13 +36,13 @@ pass some directory paths as `git daemon` arguments, the offers are limited to
 repositories within those directories.
 
 By default, only `upload-pack` service is enabled, which serves
-'git fetch-pack' and 'git ls-remote' clients, which are invoked
-from 'git fetch', 'git pull', and 'git clone'.
+`git fetch-pack` and `git ls-remote` clients, which are invoked
+from `git fetch`, `git pull`, and `git clone`.
 
 This is ideally suited for read-only updates, i.e., pulling from
 Git repositories.
 
-An `upload-archive` also exists to serve 'git archive'.
+An `upload-archive` also exists to serve `git archive`.
 
 OPTIONS
 -------
@@ -61,24 +61,24 @@ OPTIONS
 
 `--base-path-relaxed`::
 	If `--base-path` is enabled and repo lookup fails, with this option
-	'git daemon' will attempt to lookup without prefixing the base path.
+	`git daemon` will attempt to lookup without prefixing the base path.
 	This is useful for switching to `--base-path` usage, while still
 	allowing the old paths.
 
 `--interpolated-path=<pathtemplate>`::
 	To support virtual hosting, an interpolated path template can be
 	used to dynamically construct alternate paths.  The template
-	supports %H for the target hostname as supplied by the client but
-	converted to all lowercase, %CH for the canonical hostname,
-	%IP for the server's IP address, %P for the port number,
-	and %D for the absolute path of the named repository.
+	supports `%H` for the target hostname as supplied by the client but
+	converted to all lowercase, `%CH` for the canonical hostname,
+	`%IP` for the server's IP address, `%P` for the port number,
+	and `%D` for the absolute path of the named repository.
 	After interpolation, the path is validated against the directory
 	list.
 
 `--export-all`::
 	Allow pulling from all directories that look like Git repositories
 	(have the 'objects' and 'refs' subdirectories), even if they
-	do not have the 'git-daemon-export-ok' file.
+	do not have the `git-daemon-export-ok` file.
 
 `--inetd`::
 	Have the server run as an inetd service. Implies `--syslog` (may
@@ -118,17 +118,17 @@ OPTIONS
 	Send log messages to the specified destination.
 	Note that this option does not imply `--verbose`,
 	thus by default only error conditions will be logged.
-	The <destination> must be one of:
+	The _<destination>_ must be one of:
 +
 --
-stderr::
+`stderr`::
 	Write to standard error.
 	Note that if `--detach` is specified,
 	the process disconnects from the real standard error,
 	making this destination effectively equivalent to `none`.
-syslog::
+`syslog`::
 	Write to syslog, using the `git-daemon` identifier.
-none::
+`none`::
 	Disable all logging.
 --
 +
@@ -149,7 +149,7 @@ otherwise `stderr`.
 	Log details about the incoming connections and requested files.
 
 `--reuseaddr`::
-	Use SO_REUSEADDR when binding the listening socket.
+	Use `SO_REUSEADDR` when binding the listening socket.
 	This allows the server to restart without waiting for
 	old connections to time out.
 
@@ -157,7 +157,7 @@ otherwise `stderr`.
 	Detach from the shell. Implies `--syslog`.
 
 `--pid-file=<file>`::
-	Save the process id in 'file'.  Ignored when the daemon
+	Save the process id in _<file>_.  Ignored when the daemon
 	is run under `--inetd`.
 
 `--user=<user>`::
@@ -170,14 +170,14 @@ otherwise `stderr`.
 +
 Giving these options is an error when used with `--inetd`; use
 the facility of inet daemon to achieve the same before spawning
-'git daemon' if needed.
+`git daemon` if needed.
 +
 Like many programs that switch user id, the daemon does not reset
-environment variables such as `$HOME` when it runs git programs,
+environment variables such as `HOME` when it runs git programs,
 e.g. `upload-pack` and `receive-pack`. When using this option, you
 may also want to set and export `HOME` to point at the home
-directory of `<user>` before starting the daemon, and make sure any
-Git configuration files in that directory are readable by `<user>`.
+directory of _<user>_ before starting the daemon, and make sure any
+Git configuration files in that directory are readable by _<user>_.
 
 `--enable=<service>`::
 `--disable=<service>`::
@@ -206,8 +206,8 @@ Git configuration files in that directory are readable by `<user>`.
 `--access-hook=<path>`::
 	Every time a client connects, first run an external command
 	specified by the <path> with service name (e.g. "upload-pack"),
-	path to the repository, hostname (%H), canonical hostname
-	(%CH), IP address (%IP), and TCP port (%P) as its command-line
+	path to the repository, hostname (`%H`), canonical hostname
+	(`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line
 	arguments. The external command can decide to decline the
 	service by exiting with a non-zero status (or to allow it by
 	exiting with a zero status).  It can also look at the $REMOTE_ADDR
@@ -218,7 +218,7 @@ The external command can optionally write a single line to its
 standard output to be sent to the requestor as an error message when
 it declines the service.
 
-<directory>::
+_<directory>_::
 	The remaining arguments provide a list of directories. If any
 	directories are specified, then the `git-daemon` process will
 	serve a requested directory only if it is contained in one of
@@ -230,24 +230,24 @@ SERVICES
 
 These services can be globally enabled/disabled using the
 command-line options of this command.  If finer-grained
-control is desired (e.g. to allow 'git archive' to be run
+control is desired (e.g. to allow `git archive` to be run
 against only in a few selected repositories the daemon serves),
 the per-repository configuration file can be used to enable or
 disable them.
 
 upload-pack::
-	This serves 'git fetch-pack' and 'git ls-remote'
+	This serves `git fetch-pack` and `git ls-remote`
 	clients.  It is enabled by default, but a repository can
 	disable it by setting `daemon.uploadpack` configuration
 	item to `false`.
 
 upload-archive::
-	This serves 'git archive --remote'.  It is disabled by
+	This serves `git archive --remote`.  It is disabled by
 	default, but a repository can enable it by setting
 	`daemon.uploadarch` configuration item to `true`.
 
 receive-pack::
-	This serves 'git send-pack' clients, allowing anonymous
+	This serves `git send-pack` clients, allowing anonymous
 	push.  It is disabled by default, as there is _no_
 	authentication in the protocol (in other words, anybody
 	can push anything into the repository, including removal
@@ -301,7 +301,7 @@ default repository could be made as well.
 
 
 'git daemon' as regular daemon for virtual hosts::
-	To set up 'git daemon' as a regular, non-inetd service that
+	To set up `git daemon` as a regular, non-inetd service that
 	handles repositories for multiple virtual hosts based on
 	their IP addresses, start the daemon like this:
 +
@@ -318,7 +318,7 @@ Repositories can still be accessed by hostname though, assuming
 they correspond to these IP addresses.
 
 selectively enable/disable services per repository::
-	To enable 'git archive --remote' and disable 'git fetch' against
+	To enable `git archive --remote` and disable `git fetch` against
 	a repository, have the following in the configuration file in the
 	repository (that is the file 'config' next to `HEAD`, 'refs' and
 	'objects').
@@ -332,8 +332,8 @@ selectively enable/disable services per repository::
 
 ENVIRONMENT
 -----------
-'git daemon' will set REMOTE_ADDR to the IP address of the client
-that connected to it, if the IP address is available. REMOTE_ADDR will
+`git daemon` will set `REMOTE_ADDR` to the IP address of the client
+that connected to it, if the IP address is available. `REMOTE_ADDR` will
 be available in the environment of hooks called when
 services are performed.
 
diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc
index 909963b1c2..b606c2d649 100644
--- a/Documentation/git-var.adoc
+++ b/Documentation/git-var.adoc
@@ -32,58 +32,56 @@ EXAMPLES
 
 VARIABLES
 ---------
-GIT_AUTHOR_IDENT::
+`GIT_AUTHOR_IDENT`::
     The author of a piece of code.
 
-GIT_COMMITTER_IDENT::
+`GIT_COMMITTER_IDENT`::
     The person who put a piece of code into Git.
 
-GIT_EDITOR::
+`GIT_EDITOR`::
     Text editor for use by Git commands.  The value is meant to be
     interpreted by the shell when it is used.  Examples: `~/bin/vi`,
     `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe"
-    --nofork`.  The order of preference is the `$GIT_EDITOR`
-    environment variable, then `core.editor` configuration, then
-    `$VISUAL`, then `$EDITOR`, and then the default chosen at compile
+    --nofork`.  The order of preference is `$GIT_EDITOR`, then
+    `core.editor` configuration value, then `$VISUAL`, then
+    `$EDITOR`, and then the default chosen at compile
     time, which is usually 'vi'.
 ifdef::git-default-editor[]
     The build you are using chose '{git-default-editor}' as the default.
 endif::git-default-editor[]
 
-GIT_SEQUENCE_EDITOR::
+`GIT_SEQUENCE_EDITOR`::
     Text editor used to edit the 'todo' file while running `git rebase
     -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by
-    the shell when it is used. The order of preference is the
-    `$GIT_SEQUENCE_EDITOR` environment variable, then
-    `sequence.editor` configuration, and then the value of `git var
-    GIT_EDITOR`.
+    the shell when it is used. The order of preference is
+    `$GIT_SEQUENCE_EDITOR`, then `sequence.editor` configuration value,
+    and then the value of `git var GIT_EDITOR`.
 
-GIT_PAGER::
+`GIT_PAGER`::
     Text viewer for use by Git commands (e.g., 'less').  The value
     is meant to be interpreted by the shell.  The order of preference
-    is the `$GIT_PAGER` environment variable, then `core.pager`
-    configuration, then `$PAGER`, and then the default chosen at
-    compile time (usually 'less').
+    is `$GIT_PAGER`, then the value of `core.pager` configuration, then
+    `$PAGER`, and then the default chosen at compile time (usually `less`).
 ifdef::git-default-pager[]
     The build you are using chose '{git-default-pager}' as the default.
 endif::git-default-pager[]
 
-GIT_DEFAULT_BRANCH::
+`GIT_DEFAULT_BRANCH`::
     The name of the first branch created in newly initialized repositories.
 
-GIT_SHELL_PATH::
+`GIT_SHELL_PATH`::
     The path of the binary providing the POSIX shell for commands which use the shell.
 
-GIT_ATTR_SYSTEM::
+`GIT_ATTR_SYSTEM`::
     The path to the system linkgit:gitattributes[5] file, if one is enabled.
 
-GIT_ATTR_GLOBAL::
+`GIT_ATTR_GLOBAL`::
     The path to the global (per-user) linkgit:gitattributes[5] file.
 
-GIT_CONFIG_SYSTEM::
+`GIT_CONFIG_SYSTEM`::
     The path to the system configuration file, if one is enabled.
 
-GIT_CONFIG_GLOBAL::
+`GIT_CONFIG_GLOBAL`::
     The path to the global (per-user) configuration files, if any.
 
 Most path values contain only one value. However, some can contain multiple
diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc
index ec995323f6..b3721a86f4 100644
--- a/Documentation/git-verify-tag.adoc
+++ b/Documentation/git-verify-tag.adoc
@@ -12,7 +12,7 @@ git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...
 
 DESCRIPTION
 -----------
-Validates the gpg signature created by 'git tag' in the tag
+Validates the gpg signature created by `git tag` in the tag
 objects listed on the command line.
 
 OPTIONS
diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc
index 4e1c3b9c0c..4c7100ea1e 100644
--- a/Documentation/git-write-tree.adoc
+++ b/Documentation/git-write-tree.adoc
@@ -34,7 +34,7 @@ OPTIONS
 
 `--prefix=<prefix>/`::
 	Writes a tree object that represents a subdirectory
-	`<prefix>`.  This can be used to write the tree object
+	_<prefix>_.  This can be used to write the tree object
 	for a subproject that is in the named subdirectory.
 
 GIT
-- 
2.48.0

Re: [PATCH] Additional changes

[Junio C Hamano]

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

> ---
>  Documentation/git-daemon.adoc     | 60 +++++++++++++++----------------
>  Documentation/git-var.adoc        | 40 ++++++++++-----------
>  Documentation/git-verify-tag.adoc |  2 +-
>  Documentation/git-write-tree.adoc |  2 +-
>  4 files changed, 51 insertions(+), 53 deletions(-)

I was somewhat confused where this patch is designed to apply, but I
think I figured it out.  These are to further update on top of my
synopsis related mark-up updates.

Do you mean this as a set of review comment, i.e. I am expected to
spilt them into parts and fold them into those three commits to
produce an updated version of those three patches with "Helped-by:"
attributing you?

Or do you want this to sit on top of the 3-patch series separately
as the 4th patch?  If the latter we'd need a log message plus
sign-off.

I'd assume it is the former (as the three-patch series hasn't hit
'next' yet) and start updating htese three patches.

Thanks.

Re: [PATCH] Additional changes

[Jean-Noël AVILA]

On Thursday, 8 May 2025 17:14:40 CEST Junio C Hamano wrote:
> Jean-Noël Avila <jn.avila@free.fr> writes:
> > ---
> > 
> >  Documentation/git-daemon.adoc     | 60 +++++++++++++++----------------
> >  Documentation/git-var.adoc        | 40 ++++++++++-----------
> >  Documentation/git-verify-tag.adoc |  2 +-
> >  Documentation/git-write-tree.adoc |  2 +-
> >  4 files changed, 51 insertions(+), 53 deletions(-)
> 
> I was somewhat confused where this patch is designed to apply, but I
> think I figured it out.  These are to further update on top of my
> synopsis related mark-up updates.
> 
> Do you mean this as a set of review comment, i.e. I am expected to
> spilt them into parts and fold them into those three commits to
> produce an updated version of those three patches with "Helped-by:"
> attributing you?
> 
> Or do you want this to sit on top of the 3-patch series separately
> as the 4th patch?  If the latter we'd need a log message plus
> sign-off.
> 
> I'd assume it is the former (as the three-patch series hasn't hit
> 'next' yet) and start updating htese three patches.
> 
> Thanks.

Sorry for not being clear. I was wary of what the provided patches did not 
address, so I reviewed after applying your series and bundled it in another 
patch, which was not signed off on purpose.

Of course, the proposed changes can be discussed. If you prefer, I can 
dispatch them and propose a v3.


Thanks,

JN

Re: [PATCH] Additional changes

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

>> I'd assume it is the former (as the three-patch series hasn't hit
>> 'next' yet) and start updating htese three patches.
>> 
>> Thanks.
>
> Sorry for not being clear. I was wary of what the provided patches did not 
> address, so I reviewed after applying your series and bundled it in another 
> patch, which was not signed off on purpose.

I see.  In the original, I deliberately ignored what the patches did
not address ;-) as I wanted to limit the scope of the changes to
reduce the number of things the reviewers need to look for.

In any case, i assumed the former and squashed your changes (which
looked all sensible) and the result is what is in my tree right now
(but it can be further modified as the series is not yet in 'next').

> Of course, the proposed changes can be discussed. If you prefer, I can 
> dispatch them and propose a v3.

Surely.  Are there particular things that you were either unsure
about (which may lead to possible partial retraction) or want to
stress on (which would help other developers and reviewers recall
what they need to watch out for when touching the documentation)?

Thanks.

Re: [PATCH] Additional changes

[Jean-Noël AVILA]

On Friday, 9 May 2025 16:35:42 CEST Junio C Hamano wrote:
> Surely.  Are there particular things that you were either unsure
> about (which may lead to possible partial retraction) or want to
> stress on (which would help other developers and reviewers recall
> what they need to watch out for when touching the documentation)?
> 

Now that you're asking, the heavy additional changes to git-var's manpage are 
mainly targeted at clearing out some misuses of $ENV_VAR vs ENV_VAR as I see 
them. Others can disagree. 

Maybe these changes should go into a separated patch because they do not 
really fit with the "new style" changes.

Thanks

Re: [PATCH] Additional changes

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

> On Friday, 9 May 2025 16:35:42 CEST Junio C Hamano wrote:
>> Surely.  Are there particular things that you were either unsure
>> about (which may lead to possible partial retraction) or want to
>> stress on (which would help other developers and reviewers recall
>> what they need to watch out for when touching the documentation)?
>> 
>
> Now that you're asking, the heavy additional changes to git-var's manpage are 
> mainly targeted at clearing out some misuses of $ENV_VAR vs ENV_VAR as I see 
> them. Others can disagree. 
>
> Maybe these changes should go into a separated patch because they do not 
> really fit with the "new style" changes.

OK, then I'll revert the changes from these three patches I squashed
your additional changes in, so that we can have a separate series to
clean up "$ENV_VAR vs ENV_VAR" (Documentation/CodingGuidelines tells
us when to use and not to use "$", which is quite useful), perhaps?

Thanks.

[PATCH v3 0/4] Additional changes

[Jean-Noël Avila]

This series is just applying additional 'new style' changes on top of the
previous versions. Another patch is added to fix $ENV_VAR vs ENV_VAR misuse.

Jean-Noël Avila (1):
  git-var doc: fix usage of $ENV_VAR vs ENV_VAR

Junio C Hamano (3):
  git-daemon doc: update mark-up of synopsis option descriptions
  git-{var,write-tree} docs: update mark-up of synopsis option
    descriptions
  git-verify-* doc: update mark-up of synopsis option descriptions

 Documentation/git-daemon.adoc        | 181 ++++++++++++++-------------
 Documentation/git-var.adoc           |  46 ++++---
 Documentation/git-verify-commit.adoc |  16 ++-
 Documentation/git-verify-pack.adoc   |  28 ++---
 Documentation/git-verify-tag.adoc    |  16 ++-
 Documentation/git-write-tree.adoc    |  18 +--
 6 files changed, 148 insertions(+), 157 deletions(-)

-- 
2.48.0

[PATCH v3 1/4] git-daemon doc: update mark-up of synopsis option descriptions

[Jean-Noël Avila]

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

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation of 'git daemon'
to

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

Also, split '--[no-]option' into '--option' and '--no-option'
to make it easier to grep for them.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-daemon.adoc | 181 +++++++++++++++++-----------------
 1 file changed, 91 insertions(+), 90 deletions(-)

diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc
index ede7b935d6..99389f0388 100644
--- a/Documentation/git-daemon.adoc
+++ b/Documentation/git-daemon.adoc
@@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories
 
 SYNOPSIS
 --------
-[verse]
-'git daemon' [--verbose] [--syslog] [--export-all]
-	     [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
-	     [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
-	     [--user-path | --user-path=<path>]
-	     [--interpolated-path=<pathtemplate>]
-	     [--reuseaddr] [--detach] [--pid-file=<file>]
-	     [--enable=<service>] [--disable=<service>]
-	     [--allow-override=<service>] [--forbid-override=<service>]
-	     [--access-hook=<path>] [--[no-]informative-errors]
-	     [--inetd |
-	      [--listen=<host-or-ipaddr>] [--port=<n>]
-	      [--user=<user> [--group=<group>]]]
-	     [--log-destination=(stderr|syslog|none)]
-	     [<directory>...]
+[synopsis]
+git daemon [--verbose] [--syslog] [--export-all]
+	   [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+	   [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+	   [--user-path | --user-path=<path>]
+	   [--interpolated-path=<pathtemplate>]
+	   [--reuseaddr] [--detach] [--pid-file=<file>]
+	   [--enable=<service>] [--disable=<service>]
+	   [--allow-override=<service>] [--forbid-override=<service>]
+	   [--access-hook=<path>] [--[no-]informative-errors]
+	   [--inetd |
+	     [--listen=<host-or-ipaddr>] [--port=<n>]
+	     [--user=<user> [--group=<group>]]]
+	   [--log-destination=(stderr|syslog|none)]
+	   [<directory>...]
 
 DESCRIPTION
 -----------
@@ -32,111 +32,111 @@ that service if it is enabled.
 It verifies that the directory has the magic file "git-daemon-export-ok", and
 it will refuse to export any Git directory that hasn't explicitly been marked
 for export this way (unless the `--export-all` parameter is specified). If you
-pass some directory paths as 'git daemon' arguments, the offers are limited to
+pass some directory paths as `git daemon` arguments, the offers are limited to
 repositories within those directories.
 
 By default, only `upload-pack` service is enabled, which serves
-'git fetch-pack' and 'git ls-remote' clients, which are invoked
-from 'git fetch', 'git pull', and 'git clone'.
+`git fetch-pack` and `git ls-remote` clients, which are invoked
+from `git fetch`, `git pull`, and `git clone`.
 
 This is ideally suited for read-only updates, i.e., pulling from
 Git repositories.
 
-An `upload-archive` also exists to serve 'git archive'.
+An `upload-archive` also exists to serve `git archive`.
 
 OPTIONS
 -------
---strict-paths::
+`--strict-paths`::
 	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
 	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
-	'git daemon' will refuse to start when this option is enabled and no
+	`git daemon` will refuse to start when this option is enabled and no
 	directory arguments are provided.
 
---base-path=<path>::
+`--base-path=<path>`::
 	Remap all the path requests as relative to the given path.
-	This is sort of "Git root" - if you run 'git daemon' with
-	'--base-path=/srv/git' on example.com, then if you later try to pull
-	'git://example.com/hello.git', 'git daemon' will interpret the path
-	as `/srv/git/hello.git`.
-
---base-path-relaxed::
-	If --base-path is enabled and repo lookup fails, with this option
-	'git daemon' will attempt to lookup without prefixing the base path.
-	This is useful for switching to --base-path usage, while still
+	This is sort of "Git root" - if you run `git daemon` with
+	`--base-path=/srv/git` on `example.com`, then if you later try
+	to pull from `git://example.com/hello.git`, `git daemon` will
+	interpret the path as `/srv/git/hello.git`.
+
+`--base-path-relaxed`::
+	If `--base-path` is enabled and repo lookup fails, with this option
+	`git daemon` will attempt to lookup without prefixing the base path.
+	This is useful for switching to `--base-path` usage, while still
 	allowing the old paths.
 
---interpolated-path=<pathtemplate>::
+`--interpolated-path=<pathtemplate>`::
 	To support virtual hosting, an interpolated path template can be
 	used to dynamically construct alternate paths.  The template
-	supports %H for the target hostname as supplied by the client but
-	converted to all lowercase, %CH for the canonical hostname,
-	%IP for the server's IP address, %P for the port number,
-	and %D for the absolute path of the named repository.
+	supports `%H` for the target hostname as supplied by the client but
+	converted to all lowercase, `%CH` for the canonical hostname,
+	`%IP` for the server's IP address, `%P` for the port number,
+	and `%D` for the absolute path of the named repository.
 	After interpolation, the path is validated against the directory
 	list.
 
---export-all::
+`--export-all`::
 	Allow pulling from all directories that look like Git repositories
 	(have the 'objects' and 'refs' subdirectories), even if they
-	do not have the 'git-daemon-export-ok' file.
+	do not have the `git-daemon-export-ok` file.
 
---inetd::
-	Have the server run as an inetd service. Implies --syslog (may be
-	overridden with `--log-destination=`).
-	Incompatible with --detach, --port, --listen, --user and --group
-	options.
+`--inetd`::
+	Have the server run as an inetd service. Implies `--syslog` (may
+	be overridden with `--log-destination=`).
+	Incompatible with `--detach`, `--port`, `--listen`, `--user` and
+	`--group` options.
 
---listen=<host-or-ipaddr>::
+`--listen=<host-or-ipaddr>`::
 	Listen on a specific IP address or hostname.  IP addresses can
 	be either an IPv4 address or an IPv6 address if supported.  If IPv6
-	is not supported, then --listen=<hostname> is also not supported and
-	--listen must be given an IPv4 address.
+	is not supported, then `--listen=<hostname>` is also not supported
+	and `--listen` must be given an IPv4 address.
 	Can be given more than once.
 	Incompatible with `--inetd` option.
 
---port=<n>::
+`--port=<n>`::
 	Listen on an alternative port.  Incompatible with `--inetd` option.
 
---init-timeout=<n>::
+`--init-timeout=<n>`::
 	Timeout (in seconds) between the moment the connection is established
 	and the client request is received (typically a rather low value, since
 	that should be basically immediate).
 
---timeout=<n>::
+`--timeout=<n>`::
 	Timeout (in seconds) for specific client sub-requests. This includes
 	the time it takes for the server to process the sub-request and the
 	time spent waiting for the next client's request.
 
---max-connections=<n>::
+`--max-connections=<n>`::
 	Maximum number of concurrent clients, defaults to 32.  Set it to
 	zero for no limit.
 
---syslog::
+`--syslog`::
 	Short for `--log-destination=syslog`.
 
---log-destination=<destination>::
+`--log-destination=<destination>`::
 	Send log messages to the specified destination.
-	Note that this option does not imply --verbose,
+	Note that this option does not imply `--verbose`,
 	thus by default only error conditions will be logged.
-	The <destination> must be one of:
+	The _<destination>_ must be one of:
 +
 --
-stderr::
+`stderr`::
 	Write to standard error.
 	Note that if `--detach` is specified,
 	the process disconnects from the real standard error,
 	making this destination effectively equivalent to `none`.
-syslog::
+`syslog`::
 	Write to syslog, using the `git-daemon` identifier.
-none::
+`none`::
 	Disable all logging.
 --
 +
 The default destination is `syslog` if `--inetd` or `--detach` is specified,
 otherwise `stderr`.
 
---user-path::
---user-path=<path>::
+`--user-path`::
+`--user-path=<path>`::
 	Allow {tilde}user notation to be used in requests.  When
 	specified with no parameter, a request to
 	git://host/{tilde}alice/foo is taken as a request to access
@@ -145,23 +145,23 @@ otherwise `stderr`.
 	taken as a request to access `<path>/foo` repository in
 	the home directory of user `alice`.
 
---verbose::
+`--verbose`::
 	Log details about the incoming connections and requested files.
 
---reuseaddr::
-	Use SO_REUSEADDR when binding the listening socket.
+`--reuseaddr`::
+	Use `SO_REUSEADDR` when binding the listening socket.
 	This allows the server to restart without waiting for
 	old connections to time out.
 
---detach::
-	Detach from the shell. Implies --syslog.
+`--detach`::
+	Detach from the shell. Implies `--syslog`.
 
---pid-file=<file>::
-	Save the process id in 'file'.  Ignored when the daemon
+`--pid-file=<file>`::
+	Save the process id in _<file>_.  Ignored when the daemon
 	is run under `--inetd`.
 
---user=<user>::
---group=<group>::
+`--user=<user>`::
+`--group=<group>`::
 	Change daemon's uid and gid before entering the service loop.
 	When only `--user` is given without `--group`, the
 	primary group ID for the user is used.  The values of
@@ -170,43 +170,44 @@ otherwise `stderr`.
 +
 Giving these options is an error when used with `--inetd`; use
 the facility of inet daemon to achieve the same before spawning
-'git daemon' if needed.
+`git daemon` if needed.
 +
 Like many programs that switch user id, the daemon does not reset
-environment variables such as `$HOME` when it runs git programs,
+environment variables such as `HOME` when it runs git programs,
 e.g. `upload-pack` and `receive-pack`. When using this option, you
 may also want to set and export `HOME` to point at the home
-directory of `<user>` before starting the daemon, and make sure any
-Git configuration files in that directory are readable by `<user>`.
+directory of _<user>_ before starting the daemon, and make sure any
+Git configuration files in that directory are readable by _<user>_.
 
---enable=<service>::
---disable=<service>::
+`--enable=<service>`::
+`--disable=<service>`::
 	Enable/disable the service site-wide per default.  Note
 	that a service disabled site-wide can still be enabled
 	per repository if it is marked overridable and the
 	repository enables the service with a configuration
 	item.
 
---allow-override=<service>::
---forbid-override=<service>::
+`--allow-override=<service>`::
+`--forbid-override=<service>`::
 	Allow/forbid overriding the site-wide default with per
 	repository configuration.  By default, all the services
 	may be overridden.
 
---[no-]informative-errors::
+`--informative-errors`::
+`--no-informative-errors`::
 	When informative errors are turned on, git-daemon will report
 	more verbose errors to the client, differentiating conditions
 	like "no such repository" from "repository not exported". This
 	is more convenient for clients, but may leak information about
 	the existence of unexported repositories.  When informative
 	errors are not enabled, all errors report "access denied" to the
-	client. The default is --no-informative-errors.
+	client. The default is `--no-informative-errors`.
 
---access-hook=<path>::
+`--access-hook=<path>`::
 	Every time a client connects, first run an external command
 	specified by the <path> with service name (e.g. "upload-pack"),
-	path to the repository, hostname (%H), canonical hostname
-	(%CH), IP address (%IP), and TCP port (%P) as its command-line
+	path to the repository, hostname (`%H`), canonical hostname
+	(`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line
 	arguments. The external command can decide to decline the
 	service by exiting with a non-zero status (or to allow it by
 	exiting with a zero status).  It can also look at the $REMOTE_ADDR
@@ -217,7 +218,7 @@ The external command can optionally write a single line to its
 standard output to be sent to the requestor as an error message when
 it declines the service.
 
-<directory>::
+_<directory>_::
 	The remaining arguments provide a list of directories. If any
 	directories are specified, then the `git-daemon` process will
 	serve a requested directory only if it is contained in one of
@@ -229,24 +230,24 @@ SERVICES
 
 These services can be globally enabled/disabled using the
 command-line options of this command.  If finer-grained
-control is desired (e.g. to allow 'git archive' to be run
+control is desired (e.g. to allow `git archive` to be run
 against only in a few selected repositories the daemon serves),
 the per-repository configuration file can be used to enable or
 disable them.
 
 upload-pack::
-	This serves 'git fetch-pack' and 'git ls-remote'
+	This serves `git fetch-pack` and `git ls-remote`
 	clients.  It is enabled by default, but a repository can
 	disable it by setting `daemon.uploadpack` configuration
 	item to `false`.
 
 upload-archive::
-	This serves 'git archive --remote'.  It is disabled by
+	This serves `git archive --remote`.  It is disabled by
 	default, but a repository can enable it by setting
 	`daemon.uploadarch` configuration item to `true`.
 
 receive-pack::
-	This serves 'git send-pack' clients, allowing anonymous
+	This serves `git send-pack` clients, allowing anonymous
 	push.  It is disabled by default, as there is _no_
 	authentication in the protocol (in other words, anybody
 	can push anything into the repository, including removal
@@ -300,7 +301,7 @@ default repository could be made as well.
 
 
 'git daemon' as regular daemon for virtual hosts::
-	To set up 'git daemon' as a regular, non-inetd service that
+	To set up `git daemon` as a regular, non-inetd service that
 	handles repositories for multiple virtual hosts based on
 	their IP addresses, start the daemon like this:
 +
@@ -317,7 +318,7 @@ Repositories can still be accessed by hostname though, assuming
 they correspond to these IP addresses.
 
 selectively enable/disable services per repository::
-	To enable 'git archive --remote' and disable 'git fetch' against
+	To enable `git archive --remote` and disable `git fetch` against
 	a repository, have the following in the configuration file in the
 	repository (that is the file 'config' next to `HEAD`, 'refs' and
 	'objects').
@@ -331,8 +332,8 @@ selectively enable/disable services per repository::
 
 ENVIRONMENT
 -----------
-'git daemon' will set REMOTE_ADDR to the IP address of the client
-that connected to it, if the IP address is available. REMOTE_ADDR will
+`git daemon` will set `REMOTE_ADDR` to the IP address of the client
+that connected to it, if the IP address is available. `REMOTE_ADDR` will
 be available in the environment of hooks called when
 services are performed.
 
-- 
2.48.0

[PATCH v3 2/4] git-{var,write-tree} docs: update mark-up of synopsis option descriptions

[Jean-Noël Avila]

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

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation for 'git var' and
'git write-tree' to

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

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-var.adoc        |  6 +++---
 Documentation/git-write-tree.adoc | 18 +++++++++---------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc
index 0680568dfd..909963b1c2 100644
--- a/Documentation/git-var.adoc
+++ b/Documentation/git-var.adoc
@@ -8,8 +8,8 @@ git-var - Show a Git logical variable
 
 SYNOPSIS
 --------
-[verse]
-'git var' (-l | <variable>)
+[synopsis]
+git var (-l | <variable>)
 
 DESCRIPTION
 -----------
@@ -18,7 +18,7 @@ no value.
 
 OPTIONS
 -------
--l::
+`-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
 	as well. (However, the configuration variables listing functionality
diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc
index f22041a9dc..4c7100ea1e 100644
--- a/Documentation/git-write-tree.adoc
+++ b/Documentation/git-write-tree.adoc
@@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index
 
 SYNOPSIS
 --------
-[verse]
-'git write-tree' [--missing-ok] [--prefix=<prefix>/]
+[synopsis]
+git write-tree [--missing-ok] [--prefix=<prefix>/]
 
 DESCRIPTION
 -----------
@@ -18,23 +18,23 @@ tree object is printed to standard output.
 
 The index must be in a fully merged state.
 
-Conceptually, 'git write-tree' sync()s the current index contents
+Conceptually, `git write-tree` sync()s the current index contents
 into a set of tree files.
 In order to have that match what is actually in your directory right
-now, you need to have done a 'git update-index' phase before you did the
-'git write-tree'.
+now, you need to have done a `git update-index` phase before you did the
+`git write-tree`.
 
 
 OPTIONS
 -------
---missing-ok::
-	Normally 'git write-tree' ensures that the objects referenced by the
+`--missing-ok`::
+	Normally `git write-tree` ensures that the objects referenced by the
 	directory exist in the object database.  This option disables this
 	check.
 
---prefix=<prefix>/::
+`--prefix=<prefix>/`::
 	Writes a tree object that represents a subdirectory
-	`<prefix>`.  This can be used to write the tree object
+	_<prefix>_.  This can be used to write the tree object
 	for a subproject that is in the named subdirectory.
 
 GIT
-- 
2.48.0

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

[Jean-Noël Avila]

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

To unify mark-up used in our documentation to a newer convention,
started by 22293895 (doc: apply synopsis simplification on git-clone
and git-init, 2024-09-24), update the documentation pages for 'git
verify-commit', 'git verify-tag', and 'git verify-pack' to

 * 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

[PATCH v3 4/4] git-var doc: fix usage of $ENV_VAR vs ENV_VAR

[Jean-Noël Avila]

When refering to environment variables in the documentation, use the
ENV_VARIABLE format instead of $ENV_VARIABLE. The latter is used in the
documentation to refer to the actual value of the variable, not the name
of the variable.

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

diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc
index 909963b1c2..b606c2d649 100644
--- a/Documentation/git-var.adoc
+++ b/Documentation/git-var.adoc
@@ -32,58 +32,56 @@ EXAMPLES
 
 VARIABLES
 ---------
-GIT_AUTHOR_IDENT::
+`GIT_AUTHOR_IDENT`::
     The author of a piece of code.
 
-GIT_COMMITTER_IDENT::
+`GIT_COMMITTER_IDENT`::
     The person who put a piece of code into Git.
 
-GIT_EDITOR::
+`GIT_EDITOR`::
     Text editor for use by Git commands.  The value is meant to be
     interpreted by the shell when it is used.  Examples: `~/bin/vi`,
     `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe"
-    --nofork`.  The order of preference is the `$GIT_EDITOR`
-    environment variable, then `core.editor` configuration, then
-    `$VISUAL`, then `$EDITOR`, and then the default chosen at compile
+    --nofork`.  The order of preference is `$GIT_EDITOR`, then
+    `core.editor` configuration value, then `$VISUAL`, then
+    `$EDITOR`, and then the default chosen at compile
     time, which is usually 'vi'.
 ifdef::git-default-editor[]
     The build you are using chose '{git-default-editor}' as the default.
 endif::git-default-editor[]
 
-GIT_SEQUENCE_EDITOR::
+`GIT_SEQUENCE_EDITOR`::
     Text editor used to edit the 'todo' file while running `git rebase
     -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by
-    the shell when it is used. The order of preference is the
-    `$GIT_SEQUENCE_EDITOR` environment variable, then
-    `sequence.editor` configuration, and then the value of `git var
-    GIT_EDITOR`.
+    the shell when it is used. The order of preference is
+    `$GIT_SEQUENCE_EDITOR`, then `sequence.editor` configuration value,
+    and then the value of `git var GIT_EDITOR`.
 
-GIT_PAGER::
+`GIT_PAGER`::
     Text viewer for use by Git commands (e.g., 'less').  The value
     is meant to be interpreted by the shell.  The order of preference
-    is the `$GIT_PAGER` environment variable, then `core.pager`
-    configuration, then `$PAGER`, and then the default chosen at
-    compile time (usually 'less').
+    is `$GIT_PAGER`, then the value of `core.pager` configuration, then
+    `$PAGER`, and then the default chosen at compile time (usually `less`).
 ifdef::git-default-pager[]
     The build you are using chose '{git-default-pager}' as the default.
 endif::git-default-pager[]
 
-GIT_DEFAULT_BRANCH::
+`GIT_DEFAULT_BRANCH`::
     The name of the first branch created in newly initialized repositories.
 
-GIT_SHELL_PATH::
+`GIT_SHELL_PATH`::
     The path of the binary providing the POSIX shell for commands which use the shell.
 
-GIT_ATTR_SYSTEM::
+`GIT_ATTR_SYSTEM`::
     The path to the system linkgit:gitattributes[5] file, if one is enabled.
 
-GIT_ATTR_GLOBAL::
+`GIT_ATTR_GLOBAL`::
     The path to the global (per-user) linkgit:gitattributes[5] file.
 
-GIT_CONFIG_SYSTEM::
+`GIT_CONFIG_SYSTEM`::
     The path to the system configuration file, if one is enabled.
 
-GIT_CONFIG_GLOBAL::
+`GIT_CONFIG_GLOBAL`::
     The path to the global (per-user) configuration files, if any.
 
 Most path values contain only one value. However, some can contain multiple
-- 
2.48.0