[PATCH 0/2] Doc fixes

[PATCH 0/2] Doc fixes

[Jean-Noël Avila via GitGitGadget]

While translating this session, some translators and I found inconsistencies
in the manpages text. The fixes were grouped together in this series.

Jean-Noël Avila (2):
  doc: format alternatives in synopsis
  doc: fix some placeholders formating

 Documentation/fetch-options.txt          | 2 +-
 Documentation/git-interpret-trailers.txt | 6 +++---
 Documentation/git-pull.txt               | 4 ++--
 Documentation/git-rebase.txt             | 2 +-
 Documentation/git-send-email.txt         | 8 +++++---
 Documentation/git.txt                    | 2 +-
 Documentation/rev-list-options.txt       | 6 +++---
 builtin/interpret-trailers.c             | 2 +-
 8 files changed, 17 insertions(+), 15 deletions(-)


base-commit: 4f9b731bdeccffa1b13e5edf4bc0428b8d49704e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1697%2Fjnavila%2Fdoc_fixes-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1697/jnavila/doc_fixes-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1697
-- 
gitgitgadget

[PATCH 1/2] doc: format alternatives in synopsis

[Jean-Noël Avila via GitGitGadget]

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

This is a list of various fixes on malformed alternative in commands
and option syntax.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/fetch-options.txt  | 2 +-
 Documentation/git-pull.txt       | 4 ++--
 Documentation/git-rebase.txt     | 2 +-
 Documentation/git-send-email.txt | 8 +++++---
 4 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 54ebb4452e9..e22b217fba9 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -202,7 +202,7 @@ endif::git-pull[]
 	destination of an explicit refspec; see `--prune`).
 
 ifndef::git-pull[]
---recurse-submodules[=yes|on-demand|no]::
+--recurse-submodules[=(yes|on-demand|no)]::
 	This option controls if and under what conditions new commits of
 	submodules should be fetched too. When recursing through submodules,
 	`git fetch` always attempts to fetch "changed" submodules, that is, a
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 0e14f8b5b25..b2ae496e488 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -87,7 +87,7 @@ OPTIONS
 --verbose::
 	Pass --verbose to git-fetch and git-merge.
 
---[no-]recurse-submodules[=yes|on-demand|no]::
+--[no-]recurse-submodules[=(yes|on-demand|no)]::
 	This option controls if new commits of populated submodules should
 	be fetched, and if the working trees of active submodules should be
 	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
@@ -105,7 +105,7 @@ Options related to merging
 include::merge-options.txt[]
 
 -r::
---rebase[=false|true|merges|interactive]::
+--rebase[=(false|true|merges|interactive)]::
 	When true, rebase the current branch on top of the upstream
 	branch after fetching. If there is a remote-tracking branch
 	corresponding to the upstream branch and the upstream branch
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index e7e725044db..03d5e9936a0 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 	[--onto <newbase> | --keep-base] [<upstream> [<branch>]]
 'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
 	--root [<branch>]
-'git rebase' (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch)
+'git rebase' (--continue|--skip|--abort|--quit|--edit-todo|--show-current-patch)
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 8264f873809..c5d664f4519 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -9,7 +9,7 @@ git-send-email - Send a collection of patches as emails
 SYNOPSIS
 --------
 [verse]
-'git send-email' [<options>] <file|directory>...
+'git send-email' [<options>] (<file>|<directory>)...
 'git send-email' [<options>] <format-patch-options>
 'git send-email' --dump-aliases
 
@@ -278,7 +278,7 @@ must be used for each option.
 	if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),
 	then authentication is not attempted.
 
---smtp-debug=0|1::
+--smtp-debug=(0|1)::
 	Enable (1) or disable (0) debug output. If enabled, SMTP
 	commands and replies will be printed. Useful to debug TLS
 	connection and authentication problems.
@@ -301,7 +301,9 @@ must be used for each option.
 Automating
 ~~~~~~~~~~
 
---no-[to|cc|bcc]::
+--no-to::
+--no-cc::
+--no-bcc::
 	Clears any list of "To:", "Cc:", "Bcc:" addresses previously
 	set via config.
 
-- 
gitgitgadget

[PATCH 2/2] doc: fix some placeholders formating

[Jean-Noël Avila via GitGitGadget]

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

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-interpret-trailers.txt | 6 +++---
 Documentation/git.txt                    | 2 +-
 Documentation/rev-list-options.txt       | 6 +++---
 builtin/interpret-trailers.c             | 2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 418265f044d..d9dfb75fef5 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git interpret-trailers' [--in-place] [--trim-empty]
-			[(--trailer (<key>|<keyAlias>)[(=|:)<value>])...]
+			[(--trailer (<key>|<key-alias>)[(=|:)<value>])...]
 			[--parse] [<file>...]
 
 DESCRIPTION
@@ -67,9 +67,9 @@ key: value
 This means that the trimmed <key> and <value> will be separated by
 `': '` (one colon followed by one space).
 
-For convenience, a <keyAlias> can be configured to make using `--trailer`
+For convenience, a <key-alias> can be configured to make using `--trailer`
 shorter to type on the command line. This can be configured using the
-'trailer.<keyAlias>.key' configuration variable. The <keyAlias> must be a prefix
+'trailer.<key-alias>.key' configuration variable. The <keyAlias> must be a prefix
 of the full <key> string, although case sensitivity does not matter. For
 example, if you have
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index e6b766d5c3a..7a1b112a3e7 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -960,7 +960,7 @@ will never be returned from the commit-graph at the cost of performance.
 `GIT_PROTOCOL`::
 	For internal use only.  Used in handshaking the wire protocol.
 	Contains a colon ':' separated list of keys with optional values
-	'key[=value]'.  Presence of unknown keys and values must be
+	'<key>[=<value>]'.  Presence of unknown keys and values must be
 	ignored.
 +
 Note that servers may need to be configured to allow this variable to
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 408d9314d08..00ccf687441 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -316,12 +316,12 @@ list.
 With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
 this causes the output to have two extra lines of information
 taken from the reflog.  The reflog designator in the output may be shown
-as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
-reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
+as `ref@{<Nth>}` (where _<Nth>_ is the reverse-chronological index in the
+reflog) or as `ref@{<timestamp>}` (with the _<timestamp>_ for that entry),
 depending on a few rules:
 +
 --
-1. If the starting point is specified as `ref@{Nth}`, show the index
+1. If the starting point is specified as `ref@{<Nth>}`, show the index
    format.
 +
 2. If the starting point was specified as `ref@{now}`, show the
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 11f4ce9e4a2..8768bfea3c4 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -15,7 +15,7 @@
 
 static const char * const git_interpret_trailers_usage[] = {
 	N_("git interpret-trailers [--in-place] [--trim-empty]\n"
-	   "                       [(--trailer (<key>|<keyAlias>)[(=|:)<value>])...]\n"
+	   "                       [(--trailer (<key>|<key-alias>)[(=|:)<value>])...]\n"
 	   "                       [--parse] [<file>...]"),
 	NULL
 };
-- 
gitgitgadget

Re: [PATCH 0/2] Doc fixes

[Taylor Blau]

On Sat, Mar 16, 2024 at 03:21:39PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> While translating this session, some translators and I found inconsistencies
> in the manpages text. The fixes were grouped together in this series.
>
> Jean-Noël Avila (2):
>   doc: format alternatives in synopsis
>   doc: fix some placeholders formating

Both look great, thanks.

    Acked-by: Taylor Blau <me@ttaylorr.com>

Thanks,
Taylor