From: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: "Martin Ågren" <martin.agren@gmail.com>,
"Eric Sunshine" <sunshine@sunshineco.com>,
"Jean-Noël Avila" <jn.avila@free.fr>,
"Jean-Noël Avila" <jn.avila@free.fr>
Subject: [PATCH v2 3/9] doc: express grammar placeholders between angle brackets
Date: Thu, 28 Oct 2021 16:21:58 +0000 [thread overview]
Message-ID: <4d2d198f57294d8307453bda784bf5efe5905f45.1635438124.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1066.v2.git.1635438124.gitgitgadget@gmail.com>
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
This rules discerns user inputs from verbatim options in the
synopsis.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-cherry-pick.txt | 6 ++--
Documentation/git-config.txt | 46 +++++++++++++--------------
Documentation/git-cvsexportcommit.txt | 4 +--
Documentation/git-gui.txt | 2 +-
Documentation/git-help.txt | 6 ++--
Documentation/git-http-fetch.txt | 2 +-
Documentation/git-init.txt | 2 +-
Documentation/git-pack-objects.txt | 4 +--
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-reflog.txt | 4 +--
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-stage.txt | 2 +-
12 files changed, 41 insertions(+), 41 deletions(-)
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 5d750314b29..78dcc9171fb 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits
SYNOPSIS
--------
[verse]
-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
+'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]
[-S[<keyid>]] <commit>...
'git cherry-pick' (--continue | --skip | --abort | --quit)
@@ -81,8 +81,8 @@ OPTIONS
described above, and `-r` was to disable it. Now the
default is not to do `-x` so this option is a no-op.
--m parent-number::
---mainline parent-number::
+-m <parent-number>::
+--mainline <parent-number>::
Usually you cannot cherry-pick a merge because you do not know which
side of the merge should be considered the mainline. This
option specifies the parent number (starting from 1) of
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 992225f6129..0e58970289b 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -9,20 +9,20 @@ git-config - Get and set repository or global options
SYNOPSIS
--------
[verse]
-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]
-'git config' [<file-option>] [--type=<type>] --add name value
-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]
-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL
-'git config' [<file-option>] [--fixed-value] --unset name [value-pattern]
-'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern]
-'git config' [<file-option>] --rename-section old_name new_name
-'git config' [<file-option>] --remove-section name
+'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
+'git config' [<file-option>] [--type=<type>] --add <name> <value>
+'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
+'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
+'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
+'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
+'git config' [<file-option>] --rename-section <old-name> <new-name>
+'git config' [<file-option>] --remove-section <name>
'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list
-'git config' [<file-option>] --get-color name [default]
-'git config' [<file-option>] --get-colorbool name [stdout-is-tty]
+'git config' [<file-option>] --get-color <name> [<default>]
+'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
'git config' [<file-option>] -e | --edit
DESCRIPTION
@@ -102,9 +102,9 @@ OPTIONS
in which section and variable names are lowercased, but subsection
names are not.
---get-urlmatch name URL::
+--get-urlmatch <name> <URL>::
When given a two-part name section.key, the value for
- section.<url>.key whose <url> part matches the best to the
+ section.<URL>.key whose <URL> part matches the best to the
given URL is returned (if no such key exists, the value for
section.key is used as a fallback). When given just the
section as name, do so for all the keys in the section and
@@ -145,7 +145,7 @@ See also <<FILES>>.
read from or written to if `extensions.worktreeConfig` is
present. If not it's the same as `--local`.
--f config-file::
+-f <config-file>::
--file config-file::
For writing options: write to the specified file rather than the
repository `.git/config`.
@@ -155,7 +155,7 @@ available files.
+
See also <<FILES>>.
---blob blob::
+--blob <blob>::
Similar to `--file` but use the given blob instead of a file. E.g.
you can use 'master:.gitmodules' to read values from the file
'.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
@@ -246,18 +246,18 @@ Valid `<type>`'s include:
all queried config options with the scope of that value
(local, global, system, command).
---get-colorbool name [stdout-is-tty]::
+--get-colorbool <name> [<stdout-is-tty>]::
- Find the color setting for `name` (e.g. `color.diff`) and output
- "true" or "false". `stdout-is-tty` should be either "true" or
+ Find the color setting for `<name>` (e.g. `color.diff`) and output
+ "true" or "false". `<stdout-is-tty>` should be either "true" or
"false", and is taken into account when configuration says
- "auto". If `stdout-is-tty` is missing, then checks the standard
+ "auto". If `<stdout-is-tty>` is missing, then checks the standard
output of the command itself, and exits with status 0 if color
is to be used, or exits with status 1 otherwise.
When the color setting for `name` is undefined, the command uses
`color.ui` as fallback.
---get-color name [default]::
+--get-color <name> [<default>]::
Find the color configured for `name` (e.g. `color.diff.new`) and
output it as the ANSI color escape sequence to the standard
@@ -281,7 +281,7 @@ Valid `<type>`'s include:
--default <value>::
When using `--get`, and the requested variable is not found, behave as if
- <value> were the value assigned to the that variable.
+ `<value>` were the value assigned to the that variable.
CONFIGURATION
-------------
diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt
index 00154b6c85a..41c8a8a05c1 100644
--- a/Documentation/git-cvsexportcommit.txt
+++ b/Documentation/git-cvsexportcommit.txt
@@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout
SYNOPSIS
--------
[verse]
-'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]
- [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID
+'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]
+ [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>
DESCRIPTION
diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt
index c9d7e96214f..e8f3ccb4337 100644
--- a/Documentation/git-gui.txt
+++ b/Documentation/git-gui.txt
@@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git
SYNOPSIS
--------
[verse]
-'git gui' [<command>] [arguments]
+'git gui' [<command>] [<arguments>]
DESCRIPTION
-----------
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 96d5f598b4b..44ea63cc6d3 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -9,14 +9,14 @@ SYNOPSIS
--------
[verse]
'git help' [-a|--all [--[no-]verbose]]
- [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
+ [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
'git help' [-g|--guides]
'git help' [-c|--config]
DESCRIPTION
-----------
-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
+With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
command and a list of the most commonly used Git commands are printed
on the standard output.
@@ -33,7 +33,7 @@ variables.
If an alias is given, git shows the definition of the alias on
standard output. To get the manual page for the aliased command, use
-`git COMMAND --help`.
+`git <command> --help`.
Note that `git --help ...` is identical to `git help ...` because the
former is internally converted into the latter.
diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt
index 9fa17b60e43..fa4bb6cbc3e 100644
--- a/Documentation/git-http-fetch.txt
+++ b/Documentation/git-http-fetch.txt
@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP
SYNOPSIS
--------
[verse]
-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
DESCRIPTION
-----------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index b611d80697d..7781d0b3545 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git init' [-q | --quiet] [--bare] [--template=<template_directory>]
[--separate-git-dir <git dir>] [--object-format=<format>]
[-b <branch-name> | --initial-branch=<branch-name>]
- [--shared[=<permissions>]] [directory]
+ [--shared[=<permissions>]] [<directory>]
DESCRIPTION
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index dbfd1f90175..f8344e1e5ba 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -13,8 +13,8 @@ SYNOPSIS
[--no-reuse-delta] [--delta-base-offset] [--non-empty]
[--local] [--incremental] [--window=<n>] [--depth=<n>]
[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
- [--stdout [--filter=<filter-spec>] | base-name]
- [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list
+ [--stdout [--filter=<filter-spec>] | <base-name>]
+ [--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>
DESCRIPTION
diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt
index f2869da5728..ee7034b5e52 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.txt
@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
SYNOPSIS
--------
[verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >
+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
DESCRIPTION
-----------
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index ff487ff77d3..5ced7ad4f8b 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -17,12 +17,12 @@ The command takes various subcommands, and different options
depending on the subcommand:
[verse]
-'git reflog' ['show'] [log-options] [<ref>]
+'git reflog' ['show'] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
[--rewrite] [--updateref] [--stale-fix]
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
'git reflog delete' [--rewrite] [--updateref]
- [--dry-run | -n] [--verbose] ref@\{specifier\}...
+ [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}...
'git reflog exists' <ref>
Reference logs, or "reflogs", record when the tips of branches and
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 42056ee9ff9..9a78dd721e8 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -11,7 +11,7 @@ given by a list of patterns.
SYNOPSIS
--------
[verse]
-'git sparse-checkout <subcommand> [options]'
+'git sparse-checkout <subcommand> [<options>]'
DESCRIPTION
diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
index 25bcda936db..2f6aaa75b9a 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.txt
@@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area
SYNOPSIS
--------
[verse]
-'git stage' args...
+'git stage' <arg>...
DESCRIPTION
--
gitgitgadget
next prev parent reply other threads:[~2021-10-28 16:22 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-26 15:11 [PATCH] doc: fix grammar rules in commands'syntax Jean-Noël Avila via GitGitGadget
2021-10-26 18:21 ` Eric Sunshine
2021-10-27 13:01 ` Jean-Noël Avila
2021-10-27 18:56 ` Martin Ågren
2021-10-27 20:08 ` Eric Sunshine
2021-10-28 9:31 ` Jean-Noël Avila
2021-10-28 18:47 ` Martin Ågren
2021-10-28 16:21 ` [PATCH v2 0/9] doc: fix grammar rules in commands' syntax Jean-Noël Avila via GitGitGadget
2021-10-28 16:21 ` [PATCH v2 1/9] doc: fix git credential synopsis Jean-Noël Avila via GitGitGadget
2021-10-28 16:21 ` [PATCH v2 2/9] doc: split placeholders as individual tokens Jean-Noël Avila via GitGitGadget
2021-10-28 18:45 ` Martin Ågren
2021-10-28 16:21 ` Jean-Noël Avila via GitGitGadget [this message]
2021-10-28 17:46 ` [PATCH v2 3/9] doc: express grammar placeholders between angle brackets Eric Sunshine
2021-10-28 19:36 ` Junio C Hamano
2021-10-28 16:21 ` [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders Jean-Noël Avila via GitGitGadget
2021-10-28 18:47 ` Martin Ågren
2021-10-28 19:35 ` Junio C Hamano
2021-10-31 18:58 ` Eli Schwartz
2021-10-31 20:23 ` Jean-Noël AVILA
2021-11-01 6:47 ` Junio C Hamano
2021-11-03 12:46 ` Jean-Noël Avila
2021-11-03 16:28 ` Junio C Hamano
2021-11-04 0:38 ` Johannes Schindelin
2021-11-04 17:36 ` Junio C Hamano
2021-11-07 12:40 ` Eli Schwartz
2021-10-28 16:22 ` [PATCH v2 5/9] doc: git-ls-files: express options as optional alternatives Jean-Noël Avila via GitGitGadget
2021-10-28 16:22 ` [PATCH v2 6/9] doc: use three dots for indicating repetition instead of star Jean-Noël Avila via GitGitGadget
2021-10-28 16:22 ` [PATCH v2 7/9] doc: uniformize <URL> placeholders' case Jean-Noël Avila via GitGitGadget
2021-10-28 17:53 ` Junio C Hamano
2021-10-28 16:22 ` [PATCH v2 8/9] doc: git-http-push: describe the refs as pattern pairs Jean-Noël Avila via GitGitGadget
2021-10-28 17:55 ` Junio C Hamano
2021-10-28 16:22 ` [PATCH v2 9/9] doc: git-init: clarify file modes in octal Jean-Noël Avila via GitGitGadget
2021-10-28 17:17 ` Junio C Hamano
2021-10-28 17:25 ` Junio C Hamano
2021-10-28 19:22 ` [PATCH v2 0/9] doc: fix grammar rules in commands' syntax Junio C Hamano
2021-11-06 18:48 ` [PATCH v3 00/10] " Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 01/10] doc: fix git credential synopsis Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 02/10] doc: split placeholders as individual tokens Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 03/10] doc: express grammar placeholders between angle brackets Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 04/10] doc: use only hyphens as word separators in placeholders Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 05/10] doc: git-ls-files: express options as optional alternatives Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 06/10] doc: use three dots for indicating repetition instead of star Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 07/10] doc: uniformize <URL> placeholders' case Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 08/10] doc: git-http-push: describe the refs as pattern pairs Jean-Noël Avila
2021-11-06 18:48 ` [PATCH v3 09/10] doc: git-init: clarify file modes in octal Jean-Noël Avila
2021-11-07 13:20 ` Johannes Altmanninger
2021-11-06 18:48 ` [PATCH v3 10/10] init doc: --shared=0xxx does not give umask but perm bits Jean-Noël Avila
2021-11-07 13:22 ` Johannes Altmanninger
2021-11-09 17:32 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4d2d198f57294d8307453bda784bf5efe5905f45.1635438124.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=git@vger.kernel.org \
--cc=jn.avila@free.fr \
--cc=martin.agren@gmail.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).