Provide a few examples on argument and option notation in usage strings and command synopses. Signed-off-by: ÅtÄpÃn NÄmec <stepnem@xxxxxxxxx> --- Jonathan Nieder <jrnieder@xxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html