[v3,2/3] doc: update the guidelines to reflect the current formatting rules

Commit Message

Jean-Noël Avila Aug. 11, 2024, 3:20 p.m. UTC

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[e-mail]>

Signed-off-by: Jean-Noël Avila <[e-mail]>
---
 Documentation/CodingGuidelines | 54 ++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 26 deletions(-)

Comments

Eric Sunshine Aug. 11, 2024, 11:56 p.m. UTC | #1

On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget
<[e-mail]> wrote:
> Signed-off-by: Jean-Noël Avila <[e-mail]>
> ---
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> @@ -746,70 +746,72 @@ Markup:
>   When literal and placeholders are mixed, each markup is applied for
> + each sub-entity. If the formatting is becoming too hairy, you can use the
> + s:["foo"] formatting macro and let it format the groups for you.
> +   `--jobs` _<n>_ or s:["--jobs <n>"]
> +   s:["--sort=<key>
> +   s:["<directory>/.git"]
> +   s:["remote.<name>.mirror"]
> +   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
> +
> +Note that the double-quotes are required by the macro.

The closing `"]` is missing from the --sort example. Is that intentional?

Jean-Noël Avila Aug. 12, 2024, 6:18 a.m. UTC | #2

Le 12/08/2024 à 01:56, Eric Sunshine a écrit :
> On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget
> <[e-mail]> wrote:
>> Signed-off-by: Jean-Noël Avila <[e-mail]>
>> ---
>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
>> @@ -746,70 +746,72 @@ Markup:
>>   When literal and placeholders are mixed, each markup is applied for
>> + each sub-entity. If the formatting is becoming too hairy, you can use the
>> + s:["foo"] formatting macro and let it format the groups for you.
>> +   `--jobs` _<n>_ or s:["--jobs <n>"]
>> +   s:["--sort=<key>
>> +   s:["<directory>/.git"]
>> +   s:["remote.<name>.mirror"]
>> +   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
>> +
>> +Note that the double-quotes are required by the macro.
> 
> The closing `"]` is missing from the --sort example. Is that intentional?

Not at all. Will fix it.

Thanks

Patch

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1d92b2da03e..1c2d2ecbea9 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -746,70 +746,72 @@  Markup:
    _<key-id>_
 
  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 __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
-   `--jobs` _<n>_
-   ++--sort=++__<key>__
-   __<directory>__++/.git++
-   ++remote.++__<name>__++.mirror++
-
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+ each sub-entity. If the formatting is becoming too hairy, you can use the
+ s:["foo"] formatting macro and let it format the groups for you.
+   `--jobs` _<n>_ or s:["--jobs <n>"]
+   s:["--sort=<key>
+   s:["<directory>/.git"]
+   s:["remote.<name>.mirror"]
+   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
+
+Note that the double-quotes are required by the macro.
 
 Synopsis Syntax
 
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
 
  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>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+   [<repository>]
+
+   --exec-path[=<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