From: Jean-Noël Avila via GitGitGadget Date: Fri, 29 Mar 2024 11:19:36 GMT Subject: [PATCH v2 0/5] Doc new guidelines Message-ID: In-Reply-To: This version is a simplification of the markup. The behavior is variable, depending on versions of asciidoc[tor], but at least, it works both on my station and in github-ci. @Martin, please check on your platform. Changes since v1: * use unconstrained markup ++ for verbatim stuck to emphasis, instead of {empty} trickery * document and apply markup on man page references * split git-clone commit into markup and non-autoreference Jean-Noël Avila (5): doc: rework CodingGuidelines with new formatting rules doc: allow literal and emphasis format in doc vs help tests doc: git-init: apply new documentation formatting guidelines doc: git-clone: apply new documentation formatting guidelines doc: git-clone: do not autoreference the manpage in itself Documentation/CodingGuidelines | 153 ++++++++++++++++++--------------- Documentation/config/clone.txt | 20 +++-- Documentation/config/init.txt | 4 +- Documentation/git-clone.txt | 120 +++++++++++++------------- Documentation/git-init.txt | 56 ++++++------ Documentation/urls.txt | 44 +++++----- t/t0450-txt-doc-vs-help.sh | 4 +- 7 files changed, 216 insertions(+), 185 deletions(-) base-commit: 11c821f2f2a31e70fb5cc449f9a29401c333aad2 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1702%2Fjnavila%2Fdoc_new_Guidelines-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1702/jnavila/doc_new_Guidelines-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1702 Range-diff vs v1: 1: d08e8bfd9bc ! 1: 8a25ab1c3b6 doc: rework CodingGuidelines with new formatting rules @@ Documentation/CodingGuidelines: Writing Documentation: + `.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 @@ Documentation/CodingGuidelines: Writing Documentation: + __ + + When literal and placeholders are mixed, each markup is applied for -+ each sub-entity. If they are stuck, a special markup, with an {empty} -+ entity is needed: ++ 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=`{empty}____ -+ ____{empty}`/.git` -+ `remote.`{empty}____{empty}`.mirror` ++ ++--sort=++____ ++ ____++/.git++ ++ ++remote.++____++.mirror++ + -+Synopsis Syntax ++ 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 @@ Documentation/CodingGuidelines: Writing Documentation: (Zero or more of .) - --exec-path[=] -+ `--exec-path`[`=`{empty}____] ++ ++--exec-path++[++=++____] (Option with an optional argument. Note that the "=" is inside the brackets.) @@ Documentation/CodingGuidelines: Writing Documentation: alternate arguments of an option: - Do: --track[=(direct|inherit)] - Don't: --track[=(direct | inherit)] -+ Do: `--track`[`=`(`direct`|`inherit`)]` -+ Don't: `--track`[`=`(`direct` | `inherit`)] ++ Do: ++--track++[++=++(`direct`|`inherit`)]` ++ Don't: ++--track++[++=++(`direct` | `inherit`)] Parentheses are used for grouping: - [( | )...] 2: 202ed891463 ! 2: 1a4feff2aea doc: allow literal and emphasis format in doc vs help tests @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () { /^$/d; /^\[verse\]$/d; - -+ s/{empty}\|_\|`//g; ++ s/_//g; ++ s/++//g; ++ s/`//g; s/{litdd}/--/g; s/'\''\(git[ a-z-]*\)'\''/\1/g; 3: 310f09fc81c ! 3: ad7986e4c39 doc: git-init: apply new documentation formatting guidelines @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti - [--ref-format=] - [-b | --initial-branch=] - [--shared[=]] [] -+`git init` [`-q` | `--quiet`] [`--bare`] [`--template=`{empty}____] -+ [`--separate-git-dir` __] [`--object-format=`{empty}____] -+ [`--ref-format=`{empty}____] -+ [`-b` __ | `--initial-branch=`{empty}____] -+ [`--shared`[`=`{empty}____]] [__] ++`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++____] ++ [`--separate-git-dir` __] [++--object-format=++____] ++ [++--ref-format=++____] ++ [`-b` __ | ++--initial-branch=++____] ++ [++--shared++[++=++____]] [__] DESCRIPTION @@ Documentation/git-init.txt: the repository to another place if `--separate-git-d current working directory. ---object-format=:: -+`--object-format=`{empty}____:: ++++--object-format=++____:: Specify the given object __ (hash algorithm) for the repository. The valid values are `sha1` and (if enabled) `sha256`. `sha1` is the default. @@ Documentation/git-init.txt: the repository to another place if `--separate-git-d include::object-format-disclaimer.txt[] ---ref-format=:: -+`--ref-format=`{empty}____:: ++++--ref-format=++____:: Specify the given ref storage __ for the repository. The valid values are: + include::ref-storage-format.txt[] ---template=:: -+`--template=`{empty}____:: ++++--template=++____:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=:: -+`--separate-git-dir=`{empty}____:: ++++--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 @@ Documentation/git-init.txt: repository. --b :: ---initial-branch=:: +`-b` __:: -+`--initial-branch=`{empty}____:: ++++--initial-branch=++____:: Use __ for the initial branch in the newly created repository. If not specified, fall back to the default name (currently @@ Documentation/git-init.txt: repository. customized via the `init.defaultBranch` configuration variable). ---shared[=(false|true|umask|group|all|world|everybody|)]:: -+`--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 -@@ Documentation/git-init.txt: The option can have the following values, defaulting to `group` if no value + 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: + -- @@ Documentation/git-init.txt: The option can have the following values, defaulting +`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 ++Use permissions reported by `umask`(2). The default, when `--shared` is not specified. -group:: @@ Documentation/git-init.txt: The option can have the following values, defaulting +`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 ++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 -@@ Documentation/git-init.txt: permission bits (e.g. if umask is `0022`, using `group` will not remove read +-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. @@ Documentation/git-init.txt: permission bits (e.g. if umask is `0022`, using `gro +__:: __ 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)` ++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 4: 5ae83d3f799 ! 4: 54c2012429d doc: git-clone: apply new documentation guidelines @@ Metadata Author: Jean-Noël Avila ## Commit message ## - doc: git-clone: apply new documentation guidelines - - Heavily apply literal and placeholder markup everywhere. + doc: git-clone: apply new documentation formatting guidelines Signed-off-by: Jean-Noël Avila @@ Documentation/config/clone.txt -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 -+ `origin`. -+ifdef::git-clone[] -+ It can be overridden by passing the `--origin` command-line -+ option. -+endif::[] -+ifndef::git-clone[] -+ It can be overridden by passing the `--origin` command-line + `origin`, and can be overridden by passing the `--origin` command-line option to linkgit:git-clone[1]. -+endif::[] -+`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. -+ifndef::git-clone[] -+ See linkgit:git-clone[1] -+endif::[] -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.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 @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory - [--[no-]remote-submodules] [--jobs ] [--sparse] [--[no-]reject-shallow] - [--filter= [--also-filter-submodules]] [--] - [] -+`git clone` [`--template=`{empty}____] ++`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`[`=`{empty}____]] [`--`[`no-`]`shallow-submodules`] ++ [++--recurse-submodules++[++=++____]] [`--`[`no-`]`shallow-submodules`] + [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse`] [`--`[`no-`]`reject-shallow`] -+ [`--filter=`{empty}____] [`--also-filter-submodules`]] [`--`] __ ++ [++--filter=++____] [`--also-filter-submodules`]] [`--`] __ + [__] DESCRIPTION @@ Documentation/git-clone.txt: objects from the source repository into a pack in t standard error stream is not directed to a terminal. ---server-option=