[v2,0/9] doc: fix grammar rules in commands' syntax

Message ID	pull.1066.v2.git.1635438124.gitgitgadget@gmail.com (mailing list archive)
Headers	show Return-Path: <git-owner@kernel.org> Message-Id: <pull.1066.v2.git.1635438124.gitgitgadget@gmail.com> In-Reply-To: <pull.1066.git.1635261072531.gitgitgadget@gmail.com> References: <pull.1066.git.1635261072531.gitgitgadget@gmail.com> From: " =?utf-8?q?Jean-No=C3=ABl?= Avila via GitGitGadget" <gitgitgadget@gmail.com> Date: Thu, 28 Oct 2021 16:21:55 +0000 Subject: [PATCH v2 0/9] doc: fix grammar rules in commands' syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fcc: Sent To: git@vger.kernel.org Cc: Martin =?utf-8?b?w4VncmVu?= <martin.agren@gmail.com>, Eric Sunshine <sunshine@sunshineco.com>, =?utf-8?q?Jean-No=C3=ABl?= Avila <jn.avila@free.fr> Precedence: bulk
Series	doc: fix grammar rules in commands' syntax \| expand [v2,0/9] doc: fix grammar rules in commands' syntax [v2,1/9] doc: fix git credential synopsis [v2,2/9] doc: split placeholders as individual tokens [v2,3/9] doc: express grammar placeholders between angle brackets [v2,4/9] doc: use only hyphens as word separators in placeholders [v2,5/9] doc: git-ls-files: express options as optional alternatives [v2,6/9] doc: use three dots for indicating repetition instead of star [v2,7/9] doc: uniformize <URL> placeholders' case [v2,8/9] doc: git-http-push: describe the refs as pattern pairs [v2,9/9] doc: git-init: clarify file modes in octal.

There are command expressions which do not follow the grammar syntax rules. According to the coding guidelines, the placeholders must: * be in small letters * enclosed in angle brackets * use hyphens as spaces They also must represent tokens' meaning as atomic entities. Some fixups for git-credential, git-ls-files, git-init and git-http-push. changes since v1: * split changes across simpler commits Signed-off-by: Jean-Noël Avila jn.avila@free.fr Jean-Noël Avila (9): doc: fix git credential synopsis doc: split placeholders as individual tokens doc: express grammar placeholders between angle brackets doc: use only hyphens as word separators in placeholders doc: git-ls-files: express options as optional alternatives doc: use three dots for indicating repetition instead of star doc: uniformize <URL> placeholders' case doc: git-http-push: describe the refs as pattern pairs doc: git-init: clarify file modes in octal. Documentation/date-formats.txt | 4 +-- Documentation/git-archimport.txt | 14 ++++---- Documentation/git-checkout.txt | 36 +++++++++---------- Documentation/git-cherry-pick.txt | 6 ++-- Documentation/git-clone.txt | 8 ++--- Documentation/git-config.txt | 46 ++++++++++++------------ Documentation/git-credential.txt | 2 +- Documentation/git-cvsexportcommit.txt | 4 +-- Documentation/git-cvsimport.txt | 8 ++--- Documentation/git-diff-files.txt | 2 +- Documentation/git-diff-index.txt | 2 +- Documentation/git-diff-tree.txt | 2 +- Documentation/git-fsck.txt | 2 +- Documentation/git-gui.txt | 2 +- Documentation/git-help.txt | 6 ++-- Documentation/git-http-fetch.txt | 2 +- Documentation/git-http-push.txt | 15 ++++---- Documentation/git-init-db.txt | 2 +- Documentation/git-init.txt | 26 +++++++------- Documentation/git-log.txt | 8 ++--- Documentation/git-ls-files.txt | 6 ++-- Documentation/git-merge-index.txt | 2 +- Documentation/git-p4.txt | 8 ++--- Documentation/git-pack-objects.txt | 4 +-- Documentation/git-pack-redundant.txt | 2 +- Documentation/git-reflog.txt | 4 +-- Documentation/git-remote.txt | 8 ++--- Documentation/git-request-pull.txt | 8 ++--- Documentation/git-shortlog.txt | 8 ++--- Documentation/git-sparse-checkout.txt | 2 +- Documentation/git-stage.txt | 2 +- Documentation/git-svn.txt | 2 +- Documentation/git-web--browse.txt | 2 +- Documentation/gitcredentials.txt | 4 +-- Documentation/gitsubmodules.txt | 2 +- Documentation/gitworkflows.txt | 6 ++-- Documentation/pretty-formats.txt | 52 +++++++++++++-------------- Documentation/urls-remotes.txt | 8 ++--- builtin/credential.c | 2 +- 39 files changed, 165 insertions(+), 164 deletions(-) base-commit: 9d530dc0024503ab4218fe6c4395b8a0aa245478 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1066%2Fjnavila%2Ffix_manpages_placeholders-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1066/jnavila/fix_manpages_placeholders-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1066 Range-diff vs v1: -: ----------- > 1: 4d1fa80d471 doc: fix git credential synopsis -: ----------- > 2: 0045fe6faea doc: split placeholders as individual tokens 1: 605236f6d49 ! 3: 4d2d198f572 doc: fix grammar rules in commands'syntax @@ Metadata Author: Jean-Noël Avila <jn.avila@free.fr> ## Commit message ## - doc: fix grammar rules in commands'syntax + doc: express grammar placeholders between angle brackets - According to the coding guidelines, the placeholders must: - * be in small letters - * enclosed in angle brackets - - Some other rules are also applied. + This rules discerns user inputs from verbatim options in the + synopsis. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> - ## Documentation/git-archimport.txt ## -@@ Documentation/git-archimport.txt: git-archimport - Import a GNU Arch repository into Git - SYNOPSIS - -------- - [verse] --'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] -- <archive/branch>[:<git-branch>] ... -+'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>] -+ <archive>/<branch>[:<git-branch>]... - - DESCRIPTION - ----------- - - ## Documentation/git-checkout.txt ## -@@ Documentation/git-checkout.txt: SYNOPSIS - 'git checkout' [-q] [-f] [-m] [<branch>] - 'git checkout' [-q] [-f] [-m] --detach [<branch>] - 'git checkout' [-q] [-f] [-m] [--detach] <commit> --'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] -+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] - 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>... - 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul] - 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] -@@ Documentation/git-checkout.txt: You could omit `<branch>`, in which case the command degenerates to - rather expensive side-effects to show only the tracking information, - if exists, for the current branch. - --'git checkout' -b|-B <new_branch> [<start point>]:: -+'git checkout' -b|-B <new-branch> [<start-point>]:: - - Specifying `-b` causes a new branch to be created as if - linkgit:git-branch[1] were called and then checked out. In -@@ Documentation/git-checkout.txt: as `ours` (i.e. "our shared canonical history"), while what you did - on your side branch as `theirs` (i.e. "one contributor's work on top - of it"). - ---b <new_branch>:: -+-b <new-branch>:: - Create a new branch named `<new_branch>` and start it at - `<start_point>`; see linkgit:git-branch[1] for details. - ---B <new_branch>:: -+-B <new-branch>:: - Creates the branch `<new_branch>` and start it at `<start_point>`; - if it already exists, then reset it to `<start_point>`. This is - equivalent to running "git branch" with "-f"; see - ## Documentation/git-cherry-pick.txt ## @@ Documentation/git-cherry-pick.txt: git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS @@ Documentation/git-config.txt: OPTIONS ---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 ++ 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 @@ Documentation/git-config.txt: See also <<FILES>>. read from or written to if `extensions.worktreeConfig` is present. If not it's the same as `--local`. @@ Documentation/git-config.txt: Valid `<type>`'s include: ---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 -@@ Documentation/git-config.txt: Valid `<type>`'s include: +- 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. @@ Documentation/git-config.txt: Valid `<type>`'s include: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard - - ## Documentation/git-credential.txt ## -@@ Documentation/git-credential.txt: git-credential - Retrieve and store user credentials - SYNOPSIS - -------- - ------------------ --git credential <fill|approve|reject> -+git credential [fill|approve|reject] - ------------------ +@@ Documentation/git-config.txt: Valid `<type>`'s include: - DESCRIPTION + --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 + ------------- ## Documentation/git-cvsexportcommit.txt ## @@ Documentation/git-cvsexportcommit.txt: git-cvsexportcommit - Export a single commit to a CVS checkout @@ Documentation/git-cvsexportcommit.txt: git-cvsexportcommit - Export a single com DESCRIPTION - ## Documentation/git-cvsimport.txt ## -@@ Documentation/git-cvsimport.txt: git-cvsimport - Salvage your data out of another SCM people love to hate - SYNOPSIS - -------- - [verse] --'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] -+'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] - [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] -- [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] -+ [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] - [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] -- [-r <remote>] [-R] [<CVS_module>] -+ [-r <remote>] [-R] [<CVS-module>] - - - DESCRIPTION -@@ Documentation/git-cvsimport.txt: OPTIONS - -v:: - Verbosity: let 'cvsimport' report what it is doing. - ---d <CVSROOT>:: -+-d <cvsroot>:: - The root of the CVS archive. May be local (a simple path) or remote; - currently, only the :local:, :ext: and :pserver: access methods - are supported. If not given, 'git cvsimport' will try to read it - from `CVS/Root`. If no such file exists, it checks for the - `CVSROOT` environment variable. - --<CVS_module>:: -+<CVS-module>:: - The CVS module you want to import. Relative to <CVSROOT>. - If not given, 'git cvsimport' tries to read it from - `CVS/Repository`. - - ## Documentation/git-fsck.txt ## -@@ Documentation/git-fsck.txt: SYNOPSIS - 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] - [--[no-]full] [--strict] [--verbose] [--lost-found] - [--[no-]dangling] [--[no-]progress] [--connectivity-only] -- [--[no-]name-objects] [<object>*] -+ [--[no-]name-objects] [<object>...] - - DESCRIPTION - ----------- - ## Documentation/git-gui.txt ## @@ Documentation/git-gui.txt: git-gui - A portable graphical interface to Git SYNOPSIS @@ Documentation/git-http-fetch.txt: git-http-fetch - Download from a remote Git re DESCRIPTION ----------- - ## Documentation/git-http-push.txt ## -@@ Documentation/git-http-push.txt: of such patterns separated by a colon ":" (this means that a ref name - cannot have a colon in it). A single pattern '<name>' is just a - shorthand for '<name>:<name>'. - --Each pattern pair consists of the source side (before the colon) --and the destination side (after the colon). The ref to be --pushed is determined by finding a match that matches the source --side, and where it is pushed is determined by using the --destination side. -+Each pattern pair '<src>:<dst>' consists of the source side (before -+the colon) and the destination side (after the colon). The ref to be -+pushed is determined by finding a match that matches the source side, -+and where it is pushed is determined by using the destination side. - -- - It is an error if <src> does not match exactly one of the -+ - It is an error if '<src>' does not match exactly one of the - local refs. - -- - If <dst> does not match any remote ref, either -+ - If '<dst>' does not match any remote ref, either - - * it has to start with "refs/"; <dst> is used as the - destination literally in this case. - - ## Documentation/git-init-db.txt ## -@@ Documentation/git-init-db.txt: git-init-db - Creates an empty Git repository - SYNOPSIS - -------- - [verse] --'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] -+'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]] - - - DESCRIPTION - ## Documentation/git-init.txt ## -@@ Documentation/git-init.txt: git-init - Create an empty Git repository or reinitialize an existing one - SYNOPSIS - -------- - [verse] --'git init' [-q | --quiet] [--bare] [--template=<template_directory>] -- [--separate-git-dir <git dir>] [--object-format=<format>] -+'git init' [-q | --quiet] [--bare] [--template=<template-directory>] -+ [--separate-git-dir <git-dir>] [--object-format=<format>] +@@ Documentation/git-init.txt: 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 -@@ Documentation/git-init.txt: values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. - + - include::object-format-disclaimer.txt[] - ----template=<template_directory>:: -+--template=<template-directory>:: - - Specify the directory from which templates will be used. (See the "TEMPLATE - DIRECTORY" section below.) - ----separate-git-dir=<git dir>:: -+--separate-git-dir=<git-dir>:: - - Instead of initializing the repository as a directory to either `$GIT_DIR` or - `./.git/`, create a text file there containing the path to the actual -@@ Documentation/git-init.txt: repository. If not specified, fall back to the default name (currently - `master`, but this is subject to change in the future; the name can be - customized via the `init.defaultBranch` configuration variable). - ----shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: -+--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]:: - - Specify that the Git repository is to be shared amongst several users. This - allows users belonging to the same group to push into that -@@ Documentation/git-init.txt: the repository permissions. - - Same as 'group', but make the repository readable by all users. - --'0xxx':: -+'0<octal>':: - --'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will --override users' umask(2) value (and not only loosen permissions as 'group' and --'all' does). '0640' will create a repository which is group-readable, but not --group-writable or accessible to others. '0660' will create a repo that is --readable and writable to the current user and group, but inaccessible to others. -+'0<octal>' is an octal number and each file will have mode -+'0<octal>'. '0<octal>' will override users' umask(2) value (and not -+only loosen permissions as 'group' and 'all' does). '0640' will create -+a repository which is group-readable, but not group-writable or -+accessible to others. '0660' will create a repo that is readable and -+writable to the current user and group, but inaccessible to others. - -- - - By default, the configuration flag `receive.denyNonFastForwards` is enabled - - ## Documentation/git-log.txt ## -@@ Documentation/git-log.txt: git-log - Show commit logs - SYNOPSIS - -------- - [verse] --'git log' [<options>] [<revision range>] [[--] <path>...] -+'git log' [<options>] [<revision-range>] [[--] <path>...] - - DESCRIPTION - ----------- -@@ Documentation/git-log.txt: produced by `--stat`, etc. - - include::line-range-options.txt[] - --<revision range>:: -+<revision-range>:: - Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to `HEAD` (i.e. the - whole history leading to the current commit). `origin..HEAD` - - ## Documentation/git-ls-files.txt ## -@@ Documentation/git-ls-files.txt: SYNOPSIS - -------- - [verse] - 'git ls-files' [-z] [-t] [-v] [-f] -- (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* -- (-[c|d|o|i|s|u|k|m])* -+ [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...] -+ [-(c|d|o|i|s|u|k|m)...] - [--eol] - [--deduplicate] - [-x <pattern>|--exclude=<pattern>] - - ## Documentation/git-merge-index.txt ## -@@ Documentation/git-merge-index.txt: git-merge-index - Run a merge for files needing merging - SYNOPSIS - -------- - [verse] --'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) -+'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) ) - - DESCRIPTION - ----------- - - ## Documentation/git-p4.txt ## -@@ Documentation/git-p4.txt: git-p4 - Import from and submit to Perforce repositories - SYNOPSIS - -------- - [verse] --'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... --'git p4 sync' [<sync options>] [<p4 depot path>...] -+'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>... -+'git p4 sync' [<sync-options>] [<p4-depot-path>...] - 'git p4 rebase' --'git p4 submit' [<submit options>] [<master branch name>] -+'git p4 submit' [<submit-options>] [<master-branch-name>] - - DESCRIPTION ## Documentation/git-pack-objects.txt ## @@ Documentation/git-pack-redundant.txt: git-pack-redundant - Find redundant pack f -------- [verse] -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > -+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... ) ++'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... ) DESCRIPTION ----------- @@ Documentation/git-reflog.txt: The command takes various subcommands, and differe Reference logs, or "reflogs", record when the tips of branches and - ## Documentation/git-shortlog.txt ## -@@ Documentation/git-shortlog.txt: git-shortlog - Summarize 'git log' output - SYNOPSIS - -------- - [verse] --'git shortlog' [<options>] [<revision range>] [[--] <path>...] -+'git shortlog' [<options>] [<revision-range>] [[--] <path>...] - git log --pretty=short | 'git shortlog' [<options>] - - DESCRIPTION -@@ Documentation/git-shortlog.txt: counts both authors and co-authors. - If width is `0` (zero) then indent the lines of the output without wrapping - them. - --<revision range>:: -+<revision-range>:: - Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to `HEAD` (i.e. the - whole history leading to the current commit). `origin..HEAD` - ## Documentation/git-sparse-checkout.txt ## @@ Documentation/git-sparse-checkout.txt: given by a list of patterns. SYNOPSIS -------- [verse] -'git sparse-checkout <subcommand> [options]' -+'git sparse-checkout <subcommand> [<options>...]' ++'git sparse-checkout <subcommand> [<options>]' DESCRIPTION @@ Documentation/git-stage.txt: git-stage - Add file contents to the staging area DESCRIPTION - - ## Documentation/git-web--browse.txt ## -@@ Documentation/git-web--browse.txt: git-web--browse - Git helper script to launch a web browser - SYNOPSIS - -------- - [verse] --'git web{litdd}browse' [<options>] <url|file>... -+'git web{litdd}browse' [<options>] (<url>|<file>)... - - DESCRIPTION - ----------- -: ----------- > 4: 984b6d687a2 doc: use only hyphens as word separators in placeholders -: ----------- > 5: 8e078e6ea17 doc: git-ls-files: express options as optional alternatives -: ----------- > 6: 0c7b1d53808 doc: use three dots for indicating repetition instead of star -: ----------- > 7: 8f85da3bb4a doc: uniformize <URL> placeholders' case -: ----------- > 8: 20900b019f8 doc: git-http-push: describe the refs as pattern pairs -: ----------- > 9: 7eef3538f3c doc: git-init: clarify file modes in octal.

[v2,0/9] doc: fix grammar rules in commands' syntax

Message

Comments