From: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: "Jean-Noël Avila" <jn.avila@free.fr>,
"Jean-Noël Avila" <jn.avila@free.fr>
Subject: [PATCH 1/4] doc: rework CodingGuidelines with new formatting rules
Date: Sun, 24 Mar 2024 22:18:56 +0000 [thread overview]
Message-ID: <d08e8bfd9bc548793f8fd403f12fd8126cec1f5d.1711318739.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1702.git.1711318739.gitgitgadget@gmail.com>
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
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 <jn.avila@free.fr>
---
Documentation/CodingGuidelines | 147 ++++++++++++++++++---------------
1 file changed, 79 insertions(+), 68 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 32e69f798ee..b9e4c7cc19d 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,112 @@ 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:
- <file>
- --sort=<key>
- --abbrev[=<n>]
+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`
+
+ 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:
+ _<file>_
+ _<commit>_
If a placeholder has multiple words, they are separated by dashes:
- <new-branch-name>
- --template=<template-directory>
+ _<new-branch-name>_
+ _<template-directory>_
+
+ 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:
+ _<git-dir>_
+ _<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:
+ `--jobs` _<n>_
+ `--sort=`{empty}__<key>__
+ __<directory>__{empty}`/.git`
+ `remote.`{empty}__<name>__{empty}`.mirror`
+
+Synopsis Syntax
- 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.
+ 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:
- <file>...
+ _<file>_...
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<file>...]
+ [_<file>_...]
(Zero or more of <file>.)
- --exec-path[=<path>]
+ `--exec-path`[`=`{empty}__<path>__]
(Option with an optional argument. Note that the "=" is inside the
brackets.)
- [<patch>...]
+ [_<patch>_...]
(Zero or more of <patch>. 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:
- [(<rev> | <range>)...]
+ [(_<rev>_ | _<range>_)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
- [(-p <parent>)...]
+ [(`-p` _<parent>_)...]
(Any number of option -p, each with one <parent> argument.)
- git remote set-head <name> (-a | -d | <branch>)
+ `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
(One and only one of "-a", "-d" or "<branch>" _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 +798,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
--
gitgitgadget
next prev parent reply other threads:[~2024-03-24 22:19 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-24 22:18 [PATCH 0/4] Doc new guidelines Jean-Noël Avila via GitGitGadget
2024-03-24 22:18 ` Jean-Noël Avila via GitGitGadget [this message]
2024-03-24 22:18 ` [PATCH 2/4] doc: allow literal and emphasis format in doc vs help tests Jean-Noël Avila via GitGitGadget
2024-03-28 10:06 ` Jeff King
2024-03-28 10:21 ` Eric Sunshine
2024-03-24 22:18 ` [PATCH 3/4] doc: git-init: apply new documentation formatting guidelines Jean-Noël Avila via GitGitGadget
2024-03-26 20:18 ` Martin Ågren
2024-03-26 20:26 ` Jean-Noël AVILA
2024-03-24 22:18 ` [PATCH 4/4] doc: git-clone: apply new documentation guidelines Jean-Noël Avila via GitGitGadget
2024-03-26 20:03 ` Martin Ågren
2024-03-26 20:20 ` Junio C Hamano
2024-03-26 20:49 ` Jean-Noël AVILA
2024-03-26 20:59 ` Junio C Hamano
2024-03-29 11:19 ` [PATCH v2 0/5] Doc new guidelines Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 1/5] doc: rework CodingGuidelines with new formatting rules Jean-Noël Avila via GitGitGadget
2024-03-29 18:42 ` Eric Sunshine
2024-03-30 17:36 ` Jean-Noël AVILA
2024-03-29 11:19 ` [PATCH v2 2/5] doc: allow literal and emphasis format in doc vs help tests Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 3/5] doc: git-init: apply new documentation formatting guidelines Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 4/5] doc: git-clone: " Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 5/5] doc: git-clone: do not autoreference the manpage in itself Jean-Noël Avila via GitGitGadget
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=d08e8bfd9bc548793f8fd403f12fd8126cec1f5d.1711318739.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=git@vger.kernel.org \
--cc=jn.avila@free.fr \
/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).