summaryrefslogtreecommitdiff
path: root/Documentation/CodingGuidelines
diff options
context:
space:
mode:
authorŠtěpán Němec <stepnem@gmail.com>2010-11-04 18:12:48 +0100
committerJunio C Hamano <gitster@pobox.com>2010-11-05 10:03:17 -0700
commitc455bd8950e0e5593949b746ad96d1449bbbf9d5 (patch)
treec664bda9ebeb837cc12e70daed5127ca33459525 /Documentation/CodingGuidelines
parentca209065f3cc3462eb0ae6090f6b13f38aa2114c (diff)
downloadgit-c455bd8950e0e5593949b746ad96d1449bbbf9d5.tar.gz
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/CodingGuidelines')
-rw-r--r--Documentation/CodingGuidelines52
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.