From: Štěpán Němec <stepnem@gmail.com>
Date: Sun, 24 Oct 2010 15:51:22 GMT
Subject: [PATCH] CodingGuidelines: Add a section on writing documentation
Message-ID: <20101024155121.GA9503@headley>
In-Reply-To: <20101021222129.GA13262@burratino>

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>
---
Jonathan Nieder <jrnieder@gmail.com> writes:

> Štěpán Němec wrote:

[...]

>> I can try to compile an initial version of such a document, based on the
>> commit message of the original single-patch version
>> (<http://article.gmane.org/gmane.comp.version-control.git/158467>) and
>> including some more cases/examples.
>> 
>> Where do you think would be the most appropriate place for it?
>> Just add a section to CodingGuidelines, or a separate
>> Documentation/WritingGuidelines or something?
>
> Sorry for the slow response.  Documentation/CodingGuidelines makes sense
> to me, since it affects the usage strings in code.

Thanks, here's a patch.

 Documentation/CodingGuidelines |   53 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 53 insertions(+), 0 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 09ffc46..0ac7aac 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -139,3 +139,56 @@ 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.)
+
+ Parentheses are used for grouping, often combined with vertical bar
+ to indicate alternatives:
+   [(<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.)
+
+ Specific number of occurences is indicated as follows:
+   <commit>{0,2}
+   (Up to two <commit>s.)
+
+ 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.
-- 
1.7.3.rc2.221.gbf93f.dirty