Merge branch 'sn/diff-doc'

* sn/diff-doc:
docs: clarify git diff modes of operation
diff,difftool: Don't use the {0,2} notation in usage strings
CodingGuidelines: Add a section on writing documentation

diff --combined Documentation/CodingGuidelines
index 46f8a3fab13f71623ef6dbc4239067e8daa9dc59,5aa2d34f8b48f998d851fc8bab17c0186c90df8d..1b1c45df5ce3ef30e588555bbd5ab404c2b7397c
--- 1/Documentation/CodingGuidelines
--- 2/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@@ -31,10 -31,6 +31,10 @@@ But if you must have a list of rules, h
  
  For shell scripts specifically (not exhaustive):
  
 + - We use tabs for indentation.
 +
 + - Case arms are indented at the same depth as case and esac lines.
 +
   - We prefer $( ... ) for command substitution; unlike ``, it
     properly nests.  It should have been the way Bourne spelled
     it from day one, but unfortunately isn't.
@@@ -143,3 -139,55 +143,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.