doc: rework CodingGuidelines with new formatting rules
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
Mar 29, 2024 at 11:19 UTC
c42ea60495897884f2daff011026661c1819eb65
1 file changed
+85
-68
Documentation/CodingGuidelines
+85
-68
@@ -641,15 +641,15 @@ Writing Documentation:
641
- Prefer succinctness and matter-of-factly describing functionality
642
in the abstract. E.g.
643
644
- --short:: Emit output in the short-format.
644
+ `--short`:: Emit output in the short-format.
645
646
and avoid something like these overly verbose alternatives:
647
648
- --short:: Use this to emit output in the short-format.
649
- --short:: You can use this to get output in the short-format.
650
- --short:: A user who prefers shorter output could....
651
- --short:: Should a person and/or program want shorter output, he
652
- she/they/it can...
648
+ `--short`:: Use this to emit output in the short-format.
649
+ `--short`:: You can use this to get output in the short-format.
650
+ `--short`:: A user who prefers shorter output could....
651
+ `--short`:: Should a person and/or program want shorter output, he
652
+ she/they/it can...
653
654
This practice often eliminates the need to involve human actors in
655
your description, but it is a good practice regardless of the
@@ -659,12 +659,12 @@ Writing Documentation:
659
addressing the hypothetical user, and possibly "we" when
660
discussing how the program might react to the user. E.g.
661
662
- You can use this option instead of --xyz, but we might remove
662
+ You can use this option instead of `--xyz`, but we might remove
663
support for it in future versions.
664
665
while keeping in mind that you can probably be less verbose, e.g.
666
667
- Use this instead of --xyz. This option might be removed in future
667
+ Use this instead of `--xyz`. This option might be removed in future
668
versions.
669
670
- If you still need to refer to an example person that is
@@ -682,68 +682,118 @@ Writing Documentation:
682
The same general rule as for code applies -- imitate the existing
683
conventions.
684
685
- A few commented examples follow to provide reference when writing or
686
- modifying command usage strings and synopsis sections in the manual
687
- pages:
685
689
- Placeholders are spelled in lowercase and enclosed in angle brackets:
690
- <file>
691
- --sort=<key>
692
- --abbrev[=<n>]
686
+Markup:
687
+
688
+ Literal parts (e.g. use of command-line options, command names,
689
+ branch names, URLs, pathnames (files and directories), configuration and
690
+ environment variables) must be typeset as verbatim (i.e. wrapped with
691
+ backticks):
692
+ `--pretty=oneline`
693
+ `git rev-list`
694
+ `remote.pushDefault`
695
+ `http://git.example.com`
696
+ `.git/config`
697
+ `GIT_DIR`
698
+ `HEAD`
699
+ `umask`(2)
700
+
701
+ An environment variable must be prefixed with "$" only when referring to its
702
+ value and not when referring to the variable itself, in this case there is
703
+ nothing to add except the backticks:
704
+ `GIT_DIR` is specified
705
+ `$GIT_DIR/hooks/pre-receive`
706
+
707
+ Word phrases enclosed in `backtick characters` are rendered literally
708
+ and will not be further expanded. The use of `backticks` to achieve the
709
+ previous rule means that literal examples should not use AsciiDoc
710
+ escapes.
711
+ Correct:
712
+ `--pretty=oneline`
713
+ Incorrect:
714
+ `\--pretty=oneline`
715
+
716
+ Placeholders are spelled in lowercase and enclosed in
717
+ angle brackets surrounded by underscores:
718
+ _<file>_
719
+ _<commit>_
720
721
If a placeholder has multiple words, they are separated by dashes:
695
- <new-branch-name>
696
- --template=<template-directory>
722
+ _<new-branch-name>_
723
+ _<template-directory>_
724
+
725
+ A placeholder is not enclosed in backticks, as it is not a literal.
726
+
727
+ When needed, use a distinctive identifier for placeholders, usually
728
+ made of a qualification and a type:
729
+ _<git-dir>_
730
+ _<key-id>_
731
+
732
+ When literal and placeholders are mixed, each markup is applied for
733
+ each sub-entity. If they are stuck, a special markup, called
734
+ unconstrained formatting is required.
735
+ Unconstrained formating for placeholders is __<like-this>__
736
+ Unconstrained formatting for literal formatting is ++like this++
737
+ `--jobs` _<n>_
738
+ ++--sort=++__<key>__
739
+ __<directory>__++/.git++
740
+ ++remote.++__<name>__++.mirror++
741
+
742
+ caveat: ++ unconstrained format is not verbatim and may expand
743
+ content. Use Asciidoc escapes inside them.
744
698
- When a placeholder is cited in text paragraph, it is enclosed in angle
699
- brackets to remind the reader the reference in the synopsis section.
700
- For better visibility, the placeholder is typeset in italics:
701
- The _<file>_ to be added.
745
+Synopsis Syntax
746
+
747
+ Syntax grammar is formatted neither as literal nor as placeholder.
748
+
749
+ A few commented examples follow to provide reference when writing or
750
+ modifying command usage strings and synopsis sections in the manual
751
+ pages:
752
753
Possibility of multiple occurrences is indicated by three dots:
704
- <file>...
754
+ _<file>_...
755
(One or more of <file>.)
756
757
Optional parts are enclosed in square brackets:
708
- [<file>...]
758
+ [_<file>_...]
759
(Zero or more of <file>.)
760
711
- --exec-path[=<path>]
761
+ ++--exec-path++[++=++__<path>__]
762
(Option with an optional argument. Note that the "=" is inside the
763
brackets.)
764
715
- [<patch>...]
765
+ [_<patch>_...]
766
(Zero or more of <patch>. Note that the dots are inside, not
767
outside the brackets.)
768
769
Multiple alternatives are indicated with vertical bars:
720
- [-q | --quiet]
721
- [--utf8 | --no-utf8]
770
+ [`-q` | `--quiet`]
771
+ [`--utf8` | `--no-utf8`]
772
773
Use spacing around "|" token(s), but not immediately after opening or
774
before closing a [] or () pair:
725
- Do: [-q | --quiet]
726
- Don't: [-q|--quiet]
775
+ Do: [`-q` | `--quiet`]
776
+ Don't: [`-q`|`--quiet`]
777
778
Don't use spacing around "|" tokens when they're used to separate the
779
alternate arguments of an option:
730
- Do: --track[=(direct|inherit)]
731
- Don't: --track[=(direct | inherit)]
780
+ Do: ++--track++[++=++(`direct`|`inherit`)]`
781
+ Don't: ++--track++[++=++(`direct` | `inherit`)]
782
783
Parentheses are used for grouping:
734
- [(<rev> | <range>)...]
784
+ [(_<rev>_ | _<range>_)...]
785
(Any number of either <rev> or <range>. Parens are needed to make
786
it clear that "..." pertains to both <rev> and <range>.)
787
738
- [(-p <parent>)...]
788
+ [(`-p` _<parent>_)...]
789
(Any number of option -p, each with one <parent> argument.)
790
741
- git remote set-head <name> (-a | -d | <branch>)
791
+ `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
792
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
793
brackets) be provided.)
794
795
And a somewhat more contrived example:
746
- --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
796
+ `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
797
Here "=" is outside the brackets, because "--diff-filter=" is a
798
valid usage. "*" has its own pair of brackets, because it can
799
(optionally) be specified only when one or more of the letters is
@@ -754,39 +804,6 @@ Writing Documentation:
804
the user would type into a shell and use 'Git' (uppercase first letter)
805
when talking about the version control system and its properties.
806
757
- A few commented examples follow to provide reference when writing or
758
- modifying paragraphs or option/command explanations that contain options
759
- or commands:
760
-
761
- Literal examples (e.g. use of command-line options, command names,
762
- branch names, URLs, pathnames (files and directories), configuration and
763
- environment variables) must be typeset in monospace (i.e. wrapped with
764
- backticks):
765
- `--pretty=oneline`
766
- `git rev-list`
767
- `remote.pushDefault`
768
- `http://git.example.com`
769
- `.git/config`
770
- `GIT_DIR`
771
- `HEAD`
772
-
773
- An environment variable must be prefixed with "$" only when referring to its
774
- value and not when referring to the variable itself, in this case there is
775
- nothing to add except the backticks:
776
- `GIT_DIR` is specified
777
- `$GIT_DIR/hooks/pre-receive`
778
-
779
- Word phrases enclosed in `backtick characters` are rendered literally
780
- and will not be further expanded. The use of `backticks` to achieve the
781
- previous rule means that literal examples should not use AsciiDoc
782
- escapes.
783
- Correct:
784
- `--pretty=oneline`
785
- Incorrect:
786
- `\--pretty=oneline`
787
-
788
-A placeholder is not enclosed in backticks, as it is not a literal.
789
-
807
If some place in the documentation needs to typeset a command usage
808
example with inline substitutions, it is fine to use +monospaced and
809
inline substituted text+ instead of `monospaced literal text`, and with