From c42ea60495897884f2daff011026661c1819eb65 Mon Sep 17 00:00:00 2001 From: Jean-Noël Avila Date: Fri, 29 Mar 2024 11:19:37 +0000 Subject: doc: rework CodingGuidelines with new formatting rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Literal and placeholder formatting is more heavily enforced, with some asciidoc magic. Basically, the markup is preserved everywhere. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 153 +++++++++++++++++++++++------------------ 1 file changed, 85 insertions(+), 68 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 32e69f798e..ab39509d59 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -641,15 +641,15 @@ Writing Documentation: - Prefer succinctness and matter-of-factly describing functionality in the abstract. E.g. - --short:: Emit output in the short-format. + `--short`:: Emit output in the short-format. and avoid something like these overly verbose alternatives: - --short:: Use this to emit output in the short-format. - --short:: You can use this to get output in the short-format. - --short:: A user who prefers shorter output could.... - --short:: Should a person and/or program want shorter output, he - she/they/it can... + `--short`:: Use this to emit output in the short-format. + `--short`:: You can use this to get output in the short-format. + `--short`:: A user who prefers shorter output could.... + `--short`:: Should a person and/or program want shorter output, he + she/they/it can... This practice often eliminates the need to involve human actors in your description, but it is a good practice regardless of the @@ -659,12 +659,12 @@ Writing Documentation: addressing the hypothetical user, and possibly "we" when discussing how the program might react to the user. E.g. - You can use this option instead of --xyz, but we might remove + You can use this option instead of `--xyz`, but we might remove support for it in future versions. while keeping in mind that you can probably be less verbose, e.g. - Use this instead of --xyz. This option might be removed in future + Use this instead of `--xyz`. This option might be removed in future versions. - If you still need to refer to an example person that is @@ -682,68 +682,118 @@ Writing Documentation: The same general rule as for code applies -- imitate the existing conventions. - A few commented examples follow to provide reference when writing or - modifying command usage strings and synopsis sections in the manual - pages: - Placeholders are spelled in lowercase and enclosed in angle brackets: - - --sort= - --abbrev[=] +Markup: + + Literal parts (e.g. use of command-line options, command names, + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset as verbatim (i.e. wrapped with + backticks): + `--pretty=oneline` + `git rev-list` + `remote.pushDefault` + `http://git.example.com` + `.git/config` + `GIT_DIR` + `HEAD` + `umask`(2) + + An environment variable must be prefixed with "$" only when referring to its + value and not when referring to the variable itself, in this case there is + nothing to add except the backticks: + `GIT_DIR` is specified + `$GIT_DIR/hooks/pre-receive` + + Word phrases enclosed in `backtick characters` are rendered literally + and will not be further expanded. The use of `backticks` to achieve the + previous rule means that literal examples should not use AsciiDoc + escapes. + Correct: + `--pretty=oneline` + Incorrect: + `\--pretty=oneline` + + Placeholders are spelled in lowercase and enclosed in + angle brackets surrounded by underscores: + __ + __ If a placeholder has multiple words, they are separated by dashes: - - --template= + __ + __ + + A placeholder is not enclosed in backticks, as it is not a literal. + + When needed, use a distinctive identifier for placeholders, usually + made of a qualification and a type: + __ + __ + + When literal and placeholders are mixed, each markup is applied for + each sub-entity. If they are stuck, a special markup, called + unconstrained formatting is required. + Unconstrained formating for placeholders is ____ + Unconstrained formatting for literal formatting is ++like this++ + `--jobs` __ + ++--sort=++____ + ____++/.git++ + ++remote.++____++.mirror++ + + caveat: ++ unconstrained format is not verbatim and may expand + content. Use Asciidoc escapes inside them. - When a placeholder is cited in text paragraph, it is enclosed in angle - brackets to remind the reader the reference in the synopsis section. - For better visibility, the placeholder is typeset in italics: - The __ to be added. +Synopsis Syntax + + Syntax grammar is formatted neither as literal nor as placeholder. + + A few commented examples follow to provide reference when writing or + modifying command usage strings and synopsis sections in the manual + pages: Possibility of multiple occurrences is indicated by three dots: - ... + __... (One or more of .) Optional parts are enclosed in square brackets: - [...] + [__...] (Zero or more of .) - --exec-path[=] + ++--exec-path++[++=++____] (Option with an optional argument. Note that the "=" is inside the brackets.) - [...] + [__...] (Zero or more of . Note that the dots are inside, not outside the brackets.) Multiple alternatives are indicated with vertical bars: - [-q | --quiet] - [--utf8 | --no-utf8] + [`-q` | `--quiet`] + [`--utf8` | `--no-utf8`] Use spacing around "|" token(s), but not immediately after opening or before closing a [] or () pair: - Do: [-q | --quiet] - Don't: [-q|--quiet] + Do: [`-q` | `--quiet`] + Don't: [`-q`|`--quiet`] Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: - Do: --track[=(direct|inherit)] - Don't: --track[=(direct | inherit)] + Do: ++--track++[++=++(`direct`|`inherit`)]` + Don't: ++--track++[++=++(`direct` | `inherit`)] Parentheses are used for grouping: - [( | )...] + [(__ | __)...] (Any number of either or . Parens are needed to make it clear that "..." pertains to both and .) - [(-p )...] + [(`-p` __)...] (Any number of option -p, each with one argument.) - git remote set-head (-a | -d | ) + `git remote set-head` __ (`-a` | `-d` | __) (One and only one of "-a", "-d" or "" _must_ (no square brackets) be provided.) And a somewhat more contrived example: - --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]` Here "=" is outside the brackets, because "--diff-filter=" is a valid usage. "*" has its own pair of brackets, because it can (optionally) be specified only when one or more of the letters is @@ -754,39 +804,6 @@ Writing Documentation: the user would type into a shell and use 'Git' (uppercase first letter) when talking about the version control system and its properties. - A few commented examples follow to provide reference when writing or - modifying paragraphs or option/command explanations that contain options - or commands: - - Literal examples (e.g. use of command-line options, command names, - branch names, URLs, pathnames (files and directories), configuration and - environment variables) must be typeset in monospace (i.e. wrapped with - backticks): - `--pretty=oneline` - `git rev-list` - `remote.pushDefault` - `http://git.example.com` - `.git/config` - `GIT_DIR` - `HEAD` - - An environment variable must be prefixed with "$" only when referring to its - value and not when referring to the variable itself, in this case there is - nothing to add except the backticks: - `GIT_DIR` is specified - `$GIT_DIR/hooks/pre-receive` - - Word phrases enclosed in `backtick characters` are rendered literally - and will not be further expanded. The use of `backticks` to achieve the - previous rule means that literal examples should not use AsciiDoc - escapes. - Correct: - `--pretty=oneline` - Incorrect: - `\--pretty=oneline` - -A placeholder is not enclosed in backticks, as it is not a literal. - If some place in the documentation needs to typeset a command usage example with inline substitutions, it is fine to use +monospaced and inline substituted text+ instead of `monospaced literal text`, and with -- cgit 1.2.3-korg From 71d9f5a19f8e6be893c4a0dfb43443f7bc545235 Mon Sep 17 00:00:00 2001 From: Jean-Noël Avila Date: Fri, 29 Mar 2024 11:19:38 +0000 Subject: doc: allow literal and emphasis format in doc vs help tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As the new formatting of literal and placeholders is introduced, the synopsis in the man pages can now hold additional markup with respect to the command help. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- t/t0450-txt-doc-vs-help.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh index cd3969e852..69917d7b84 100755 --- a/t/t0450-txt-doc-vs-help.sh +++ b/t/t0450-txt-doc-vs-help.sh @@ -59,7 +59,9 @@ txt_to_synopsis () { -e '/^\[verse\]$/,/^$/ { /^$/d; /^\[verse\]$/d; - + s/_//g; + s/++//g; + s/`//g; s/{litdd}/--/g; s/'\''\(git[ a-z-]*\)'\''/\1/g; -- cgit 1.2.3-korg From 5cf7dfe93ed69b2a9c4826c1ee8bf980bd44e66b Mon Sep 17 00:00:00 2001 From: Jean-Noël Avila Date: Fri, 29 Mar 2024 11:19:39 +0000 Subject: doc: git-init: apply new documentation formatting guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- Documentation/config/init.txt | 4 ++-- Documentation/git-init.txt | 56 +++++++++++++++++++++---------------------- 2 files changed, 30 insertions(+), 30 deletions(-) diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt index dd1d833273..af03acdbcb 100644 --- a/Documentation/config/init.txt +++ b/Documentation/config/init.txt @@ -3,8 +3,8 @@ ifndef::git-init[] :see-git-init: (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) endif::[] -init.templateDir:: +`init.templateDir`:: Specify the directory from which templates will be copied. {see-git-init} -init.defaultBranch:: +`init.defaultBranch`:: Allows overriding the default branch name e.g. when initializing a new repository. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 2f864e11ed..daff93bd16 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -9,11 +9,11 @@ git-init - Create an empty Git repository or reinitialize an existing one SYNOPSIS -------- [verse] -'git init' [-q | --quiet] [--bare] [--template=] - [--separate-git-dir ] [--object-format=] - [--ref-format=] - [-b | --initial-branch=] - [--shared[=]] [] +`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++____] + [`--separate-git-dir` __] [++--object-format=++____] + [++--ref-format=++____] + [`-b` __ | ++--initial-branch=++____] + [++--shared++[++=++____]] [__] DESCRIPTION @@ -41,35 +41,35 @@ the repository to another place if `--separate-git-dir` is given). OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Only print error and warning messages; all other output will be suppressed. ---bare:: +`--bare`:: Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. ---object-format=:: +++--object-format=++____:: Specify the given object __ (hash algorithm) for the repository. The valid values are `sha1` and (if enabled) `sha256`. `sha1` is the default. + include::object-format-disclaimer.txt[] ---ref-format=:: +++--ref-format=++____:: Specify the given ref storage __ for the repository. The valid values are: + include::ref-storage-format.txt[] ---template=:: +++--template=++____:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=:: +++--separate-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 @@ -78,53 +78,53 @@ repository. + If this is a reinitialization, the repository will be moved to the specified path. --b :: ---initial-branch=:: +`-b` __:: +++--initial-branch=++____:: Use __ for the initial branch in the newly created 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|)]:: +++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|__)]:: Specify that the Git repository is to be shared amongst several users. This allows users belonging to the same group to push into that repository. When specified, the config variable `core.sharedRepository` is set so that files and directories under `$GIT_DIR` are created with the requested permissions. When not specified, Git will use permissions reported -by `umask(2)`. +by `umask`(2). + The option can have the following values, defaulting to `group` if no value is given: + -- -umask:: -false:: +`umask`:: +`false`:: -Use permissions reported by umask(2). The default, when `--shared` is not +Use permissions reported by `umask`(2). The default, when `--shared` is not specified. -group:: -true:: +`group`:: +`true`:: -Make the repository group-writable, (and g+sx, since the git group may not be +Make the repository group-writable, (and `g+sx`, since the git group may not be the primary group of all users). This is used to loosen the permissions of an -otherwise safe umask(2) value. Note that the umask still applies to the other +otherwise safe `umask`(2) value. Note that the umask still applies to the other permission bits (e.g. if umask is `0022`, using `group` will not remove read privileges from other (non-group) users). See `0xxx` for how to exactly specify the repository permissions. -all:: -world:: -everybody:: +`all`:: +`world`:: +`everybody`:: Same as `group`, but make the repository readable by all users. -:: +__:: __ is a 3-digit octal number prefixed with `0` and each file -will have mode __. __ will override users'`umask(2)` +will have mode __. __ will override users' `umask`(2) value (and not only loosen permissions as `group` and `all` do). `0640` will create a repository which is group-readable, but not group-writable or accessible to others. `0660` will create a repo -- cgit 1.2.3-korg From 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc Mon Sep 17 00:00:00 2001 From: Jean-Noël Avila Date: Fri, 29 Mar 2024 11:19:40 +0000 Subject: doc: git-clone: apply new documentation formatting guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- Documentation/config/clone.txt | 6 +-- Documentation/git-clone.txt | 120 ++++++++++++++++++++--------------------- Documentation/urls.txt | 44 +++++++-------- 3 files changed, 86 insertions(+), 84 deletions(-) diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index d037b57f72..71a967f262 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -1,13 +1,13 @@ -clone.defaultRemoteName:: +`clone.defaultRemoteName`:: The name of the remote to create when cloning a repository. Defaults to `origin`, and can be overridden by passing the `--origin` command-line option to linkgit:git-clone[1]. -clone.rejectShallow:: +`clone.rejectShallow`:: Reject cloning a repository if it is a shallow one; this can be overridden by passing the `--reject-shallow` option on the command line. See linkgit:git-clone[1] -clone.filterSubmodules:: +`clone.filterSubmodules`:: If a partial clone filter is provided (see `--filter` in linkgit:git-rev-list[1]) and `--recurse-submodules` is used, also apply the filter to submodules. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f90977a851..5de18de2ab 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,15 +9,15 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git clone' [--template=] - [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] - [-o ] [-b ] [-u ] [--reference ] - [--dissociate] [--separate-git-dir ] - [--depth ] [--[no-]single-branch] [--no-tags] - [--recurse-submodules[=]] [--[no-]shallow-submodules] - [--[no-]remote-submodules] [--jobs ] [--sparse] [--[no-]reject-shallow] - [--filter= [--also-filter-submodules]] [--] - [] +`git clone` [++--template=++____] + [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] + [`-o` __] [`-b` __] [`-u` __] [`--reference` __] + [`--dissociate`] [`--separate-git-dir` __] + [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tags`] + [++--recurse-submodules++[++=++____]] [`--`[`no-`]`shallow-submodules`] + [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`] + [++--filter=++____] [`--also-filter-submodules`]] [`--`] __ + [__] DESCRIPTION ----------- @@ -31,7 +31,7 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any (this is untrue when "--single-branch" +current master branch, if any (this is untrue when `--single-branch` is given; see below). This default configuration is achieved by creating references to @@ -42,12 +42,12 @@ configuration variables. OPTIONS ------- --l:: ---local:: +`-l`:: +`--local`:: When the repository to clone from is on a local machine, this flag bypasses the normal "Git aware" transport mechanism and clones the repository by making a copy of - HEAD and everything under objects and refs directories. + `HEAD` and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked to save space when possible. + @@ -67,14 +67,14 @@ links. source repository, similar to running `cp -r src dst` while modifying `src`. ---no-hardlinks:: +`--no-hardlinks`:: Force the cloning process from a repository on a local filesystem to copy the files under the `.git/objects` directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository. --s:: ---shared:: +`-s`:: +`--shared`:: When the repository to clone is on the local machine, instead of using hard links, automatically setup `.git/objects/info/alternates` to share the objects @@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on its source repository, you can simply run `git repack -a` to copy all objects from the source repository into a pack in the cloned repository. ---reference[-if-able] :: +`--reference`[`-if-able`] __:: If the reference __ is on the local machine, automatically setup `.git/objects/info/alternates` to obtain objects from the reference __. Using @@ -115,7 +115,7 @@ objects from the source repository into a pack in the cloned repository. *NOTE*: see the NOTE for the `--shared` option, and also the `--dissociate` option. ---dissociate:: +`--dissociate`:: Borrow the objects from reference repositories specified with the `--reference` options only to reduce network transfer, and stop borrowing from them after a clone is made @@ -126,43 +126,43 @@ objects from the source repository into a pack in the cloned repository. same repository, and this option can be used to stop the borrowing. --q:: ---quiet:: +`-q`:: +`--quiet`:: Operate quietly. Progress is not reported to the standard error stream. --v:: ---verbose:: +`-v`:: +`--verbose`:: Run verbosely. Does not affect the reporting of progress status to the standard error stream. ---progress:: +`--progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---server-option=