[v2,0/5] Doc new guidelines

Message

Philippe Blain via GitGitGadget March 29, 2024, 11:19 a.m. UTC

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:
      +   _<key-id>_
      +
      + 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 __<like-this>__
     ++ Unconstrained formatting for literal formatting is ++like this++
      +   `--jobs` _<n>_
     -+   `--sort=`{empty}__<key>__
     -+   __<directory>__{empty}`/.git`
     -+   `remote.`{empty}__<name>__{empty}`.mirror`
     ++   ++--sort=++__<key>__
     ++   __<directory>__++/.git++
     ++   ++remote.++__<name>__++.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 _<file>_ 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 <file>.)
       
      -   --exec-path[=<path>]
     -+   `--exec-path`[`=`{empty}__<path>__]
     ++   ++--exec-path++[++=++__<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:
      -   [(<rev> | <range>)...]
 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=<format>]
      -	  [-b <branch-name> | --initial-branch=<branch-name>]
      -	  [--shared[=<permissions>]] [<directory>]
     -+`git init` [`-q` | `--quiet`] [`--bare`] [`--template=`{empty}__<template-directory>__]
     -+	  [`--separate-git-dir` _<git-dir>_] [`--object-format=`{empty}__<format>__]
     -+	  [`--ref-format=`{empty}__<format>__]
     -+	  [`-b` _<branch-name>_ | `--initial-branch=`{empty}__<branch-name>__]
     -+	  [`--shared`[`=`{empty}__<permissions>__]] [_<directory>_]
     ++`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
     ++	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
     ++	  [++--ref-format=++__<format>__]
     ++	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
     ++	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
       
       
       DESCRIPTION
     @@ Documentation/git-init.txt: the repository to another place if `--separate-git-d
       current working directory.
       
      ---object-format=<format>::
     -+`--object-format=`{empty}__<format>__::
     ++++--object-format=++__<format>__::
       
       Specify the given object _<format>_ (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=<format>::
     -+`--ref-format=`{empty}__<format>__::
     ++++--ref-format=++__<format>__::
       
       Specify the given ref storage _<format>_ for the repository. The valid values are:
       +
       include::ref-storage-format.txt[]
       
      ---template=<template-directory>::
     -+`--template=`{empty}__<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=`{empty}__<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.
      --b <branch-name>::
      ---initial-branch=<branch-name>::
      +`-b` _<branch-name>_::
     -+`--initial-branch=`{empty}__<branch-name>__::
     ++++--initial-branch=++__<branch-name>__::
       
       Use _<branch-name>_ 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|<perm>)]::
     -+`--shared`[`=`(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
     ++++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
       
       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
      +_<perm>_::
       
       _<perm>_ is a 3-digit octal number prefixed with `0` and each file
     - will have mode _<perm>_. _<perm>_ will override users'`umask(2)`
     +-will have mode _<perm>_. _<perm>_ will override users'`umask(2)`
     ++will have mode _<perm>_. _<perm>_ 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 <[e-mail]>
      
       ## 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 <[e-mail]>
      
     @@ 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 <n>] [--sparse] [--[no-]reject-shallow]
      -	  [--filter=<filter> [--also-filter-submodules]] [--] <repository>
      -	  [<directory>]
     -+`git clone` [`--template=`{empty}__<template-directory>__]
     ++`git clone` [++--template=++__<template-directory>__]
      +	  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
      +	  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
      +	  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
      +	  [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]
     -+	  [`--recurse-submodules`[`=`{empty}__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
     ++	  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
      +	  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]
     -+	  [`--filter=`{empty}__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
     ++	  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
      +	  [_<directory>_]
       
       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=<option>::
     -+`--server-option=`{empty}__<option>__::
     ++++--server-option=++__<option>__::
       	Transmit the given string to the server when communicating using
       	protocol version 2.  The given string must not contain a NUL or LF
       	character.  The server's handling of server options, including
       	unknown ones, is server-specific.
      -	When multiple `--server-option=<option>` are given, they are all
     -+	When multiple `--server-option=`{empty}__<option>__ are given, they are all
     ++	When multiple ++--server-option=++__<option>__ are given, they are all
       	sent to the other side in the order listed on the command line.
       
      --n::
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	working directory as needed.
       
      ---filter=<filter-spec>::
     -+`--filter=`{empty}__<filter-spec>__::
     ++++--filter=++__<filter-spec>__::
       	Use the partial clone feature and request that the server sends
       	a subset of reachable objects according to a given object filter.
       	When using `--filter`, the supplied _<filter-spec>_ is used for
       	the partial clone filter. For example, `--filter=blob:none` will
       	filter out all blobs (file contents) until needed by Git. Also,
      -	`--filter=blob:limit=<size>` will filter out all blobs of size
     -+	`--filter=blob:limit=`{empty}__<size>__ will filter out all blobs of size
     ++	++--filter=blob:limit=++__<size>__ will filter out all blobs of size
       	at least _<size>_. For more details on filter specifications, see
       	the `--filter` option in linkgit:git-rev-list[1].
       
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	run on the other end.
       
      ---template=<template-directory>::
     -+`--template=`{empty}__<template-directory>__::
     ++++--template=++__<template-directory>__::
       	Specify the directory from which templates will be used;
       	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
       
      --c <key>=<value>::
      ---config <key>=<value>::
     -+`-c` __<key>__{empty}`=`{empty}__<value>__::
     -+`--config` __<key>__{empty}`=`{empty}__<value>__::
     ++`-c` __<key>__++=++__<value>__::
     ++`--config` __<key>__++=++__<value>__::
       	Set a configuration variable in the newly-created repository;
       	this takes effect immediately after the repository is
       	initialized, but before the remote history is fetched or any
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       variables do not take effect until after the initial fetch and checkout.
       Configuration variables known to not take effect are:
      -`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the
     -+`remote.`{empty}__<name>__{empty}`.mirror` and `remote.`{empty}__<name>__{empty}`.tagOpt`.  Use the
     ++++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
       corresponding `--mirror` and `--no-tags` options instead.
       
      ---depth <depth>::
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	also pass `--shallow-submodules`.
       
      ---shallow-since=<date>::
     -+`--shallow-since=`{empty}__<date>__::
     ++++--shallow-since=++__<date>__::
       	Create a shallow clone with a history after the specified time.
       
      ---shallow-exclude=<revision>::
     -+`--shallow-exclude=`{empty}__<revision>__::
     ++++--shallow-exclude=++__<revision>__::
       	Create a shallow clone with a history, excluding commits
       	reachable from a specified remote branch or tag.  This option
       	can be specified multiple times.
     @@ Documentation/git-clone.txt: the clone is finished. This option is ignored if th
       	in the bundle will be stored under the hidden `refs/bundle/*`
      
       ## Documentation/urls.txt ##
     +@@ Documentation/urls.txt: should be used with caution on unsecured networks.
     + 
     + The following syntaxes may be used with them:
     + 
     +-- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
     +-- git://host.xz{startsb}:port{endsb}/path/to/repo.git/
     +-- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
     +-- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
     ++- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     ++- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
     ++- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     ++- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     + 
     + An alternative scp-like syntax may also be used with the ssh protocol:
     + 
     +-- {startsb}user@{endsb}host.xz:path/to/repo.git/
     ++- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
     + 
     + This syntax is only recognized if there are no slashes before the
     + first colon. This helps differentiate a local path that contains a
     +@@ Documentation/urls.txt: colon. For example the local path `foo:bar` could be specified as an
     + absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
     + url.
     + 
     +-The ssh and git protocols additionally support ~username expansion:
     ++The ssh and git protocols additionally support ++~++__<username>__ expansion:
     + 
     +-- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
     +-- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
     +-- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/
     ++- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
     ++- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
     ++- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
     + 
     + For local repositories, also supported by Git natively, the following
     + syntaxes may be used:
     + 
     +-- /path/to/repo.git/
     +-- \file:///path/to/repo.git/
     ++- `/path/to/repo.git/`
     ++- ++file:///path/to/repo.git/++
     + 
     + ifndef::git-clone[]
     + These two syntaxes are mostly equivalent, except when cloning, when
      @@ Documentation/urls.txt: endif::git-clone[]
       accept a suitable bundle file. See linkgit:git-bundle[1].
       
 -:  ----------- > 5:  38bd78c92eb doc: git-clone: do not autoreference the manpage in itself