@@ -650,8 +650,8 @@ Writing Documentation:
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<extra>]
- (Zero or one <extra>.)
+ [<file>...]
+ (Zero or more of <file>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
@@ -665,6 +665,16 @@ Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
+ Don't use spacing around "|" tokens when they're used to seperate the
+ alternate arguments of an option:
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
+
Parentheses are used for grouping:
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
Edit the section which explains how to create a good SYNOPSIS section for clarity and accuracy, it was mostly introduced in c455bd8950e (CodingGuidelines: Add a section on writing documentation, 2010-11-04): * Change "extra" example to "file", which now naturally follows from previous "<file>..." example (one or more) to "[<file>...]" (zero or more). * Explain how we prefer spacing around "[]()" tokens and "|" alternatives, this is not a new policy, but just codifies what's already the pattern in the most wide use in the documentation. Having a space around " | " for flags, but not for flag values is inconsistent, but this style guide codifies existing patterns. Grepping shows that we don't have any instance matching the second "Don't" example: git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/ Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- Documentation/CodingGuidelines | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-)