diff options
author | Štěpán Němec <stepnem@gmail.com> | 2010-11-04 20:12:48 +0300 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2010-11-05 20:03:17 +0300 |
commit | c455bd8950e0e5593949b746ad96d1449bbbf9d5 (patch) | |
tree | c664bda9ebeb837cc12e70daed5127ca33459525 /Documentation | |
parent | ca209065f3cc3462eb0ae6090f6b13f38aa2114c (diff) |
CodingGuidelines: Add a section on writing documentation
Provide a few examples on argument and option notation in usage strings
and command synopses.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/CodingGuidelines | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 09ffc46563..5aa2d34f8b 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -139,3 +139,55 @@ For C programs: - When we pass <string, length> pair to functions, we should try to pass them in that order. + +Writing Documentation: + + Every user-visible change should be reflected in the 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 enclosed in angle brackets: + <file> + --sort=<key> + --abbrev[=<n>] + + Possibility of multiple occurences is indicated by three dots: + <file>... + (One or more of <file>.) + + Optional parts are enclosed in square brackets: + [<extra>] + (Zero or one <extra>.) + + --exec-path[=<path>] + (Option with an optional argument. Note that the "=" is inside the + brackets.) + + [<patch>...] + (Zero or more of <patch>. Note that the dots are inside, not + outside the brackets.) + + Multiple alternatives are indicated with vertical bar: + [-q | --quiet] + [--utf8 | --no-utf8] + + Parentheses are used for grouping: + [(<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>)...] + (Any number of option -p, each with one <parent> argument.) + + 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)...[*]] + 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 + also provided. |