doc: update the guidelines to reflect the current formatting rules
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
Sep 24, 2024 at 07:08 UTC
029eff9e34fcb622b6eabe9e695fa502a714df4f
1 file changed
+30
-28
Documentation/CodingGuidelines
+30
-28
@@ -738,78 +738,80 @@ Markup:
738
_<new-branch-name>_
739
_<template-directory>_
740
741
- A placeholder is not enclosed in backticks, as it is not a literal.
742
-
741
When needed, use a distinctive identifier for placeholders, usually
742
made of a qualification and a type:
743
_<git-dir>_
744
_<key-id>_
745
748
- When literal and placeholders are mixed, each markup is applied for
749
- each sub-entity. If they are stuck, a special markup, called
750
- unconstrained formatting is required.
751
- Unconstrained formating for placeholders is __<like-this>__
752
- Unconstrained formatting for literal formatting is ++like this++
753
- `--jobs` _<n>_
754
- ++--sort=++__<key>__
755
- __<directory>__++/.git++
756
- ++remote.++__<name>__++.mirror++
746
+ Git's Asciidoc processor has been tailored to treat backticked text
747
+ as complex synopsis. When literal and placeholders are mixed, you can
748
+ use the backtick notation which will take care of correctly typesetting
749
+ the content.
750
+ `--jobs <n>`
751
+ `--sort=<key>`
752
+ `<directory>/.git`
753
+ `remote.<name>.mirror`
754
+ `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
755
758
- caveat: ++ unconstrained format is not verbatim and may expand
759
- content. Use Asciidoc escapes inside them.
756
+As a side effect, backquoted placeholders are correctly typeset, but
757
+this style is not recommended.
758
759
Synopsis Syntax
760
763
- Syntax grammar is formatted neither as literal nor as placeholder.
761
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
762
+ formatted by the toolchain and does not need typesetting.
763
764
A few commented examples follow to provide reference when writing or
765
modifying command usage strings and synopsis sections in the manual
766
pages:
767
768
Possibility of multiple occurrences is indicated by three dots:
770
- _<file>_...
769
+ <file>...
770
(One or more of <file>.)
771
772
Optional parts are enclosed in square brackets:
774
- [_<file>_...]
773
+ [<file>...]
774
(Zero or more of <file>.)
775
777
- ++--exec-path++[++=++__<path>__]
776
+ An optional parameter needs to be typeset with unconstrained pairs
777
+ [<repository>]
778
+
779
+ --exec-path[=<path>]
780
(Option with an optional argument. Note that the "=" is inside the
781
brackets.)
782
781
- [_<patch>_...]
783
+ [<patch>...]
784
(Zero or more of <patch>. Note that the dots are inside, not
785
outside the brackets.)
786
787
Multiple alternatives are indicated with vertical bars:
786
- [`-q` | `--quiet`]
787
- [`--utf8` | `--no-utf8`]
788
+ [-q | --quiet]
789
+ [--utf8 | --no-utf8]
790
791
Use spacing around "|" token(s), but not immediately after opening or
792
before closing a [] or () pair:
791
- Do: [`-q` | `--quiet`]
792
- Don't: [`-q`|`--quiet`]
793
+ Do: [-q | --quiet]
794
+ Don't: [-q|--quiet]
795
796
Don't use spacing around "|" tokens when they're used to separate the
797
alternate arguments of an option:
796
- Do: ++--track++[++=++(`direct`|`inherit`)]`
797
- Don't: ++--track++[++=++(`direct` | `inherit`)]
798
+ Do: --track[=(direct|inherit)]
799
+ Don't: --track[=(direct | inherit)]
800
801
Parentheses are used for grouping:
800
- [(_<rev>_ | _<range>_)...]
802
+ [(<rev>|<range>)...]
803
(Any number of either <rev> or <range>. Parens are needed to make
804
it clear that "..." pertains to both <rev> and <range>.)
805
804
- [(`-p` _<parent>_)...]
806
+ [(-p <parent>)...]
807
(Any number of option -p, each with one <parent> argument.)
808
807
- `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
809
+ git remote set-head <name> (-a|-d|<branch>)
810
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
811
brackets) be provided.)
812
813
And a somewhat more contrived example:
812
- `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
814
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
815
Here "=" is outside the brackets, because "--diff-filter=" is a
816
valid usage. "*" has its own pair of brackets, because it can
817
(optionally) be specified only when one or more of the letters is