diff options
Diffstat (limited to 'Documentation')
107 files changed, 1595 insertions, 442 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b8bf618a30..1b1c45df5c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -31,25 +31,36 @@ But if you must have a list of rules, here they are. 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. - - We use ${parameter-word} and its [-=?+] siblings, and their - colon'ed "unset or null" form. + - We use POSIX compliant parameter substitutions and avoid bashisms; + namely: - - We use ${parameter#word} and its [#%] siblings, and their - doubled "longest matching" form. + - We use ${parameter-word} and its [-=?+] siblings, and their + colon'ed "unset or null" form. - - We use Arithmetic Expansion $(( ... )). + - We use ${parameter#word} and its [#%] siblings, and their + doubled "longest matching" form. - - No "Substring Expansion" ${parameter:offset:length}. + - No "Substring Expansion" ${parameter:offset:length}. - - No shell arrays. + - No shell arrays. - - No strlen ${#parameter}. + - No strlen ${#parameter}. - - No regexp ${parameter/pattern/string}. + - No pattern replacement ${parameter/pattern/string}. + + - We use Arithmetic Expansion $(( ... )). + + - Inside Arithmetic Expansion, spell shell variables with $ in front + of them, as some shells do not grok $((x)) while accepting $(($x)) + just fine (e.g. dash older than 0.5.4). - We do not use Process Substitution <(list) or >(list). @@ -132,3 +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. diff --git a/Documentation/Makefile b/Documentation/Makefile index e117bc4315..36989b7f65 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -63,35 +63,28 @@ endif # # For asciidoc ... -# -7.1.2, no extra settings are needed. -# 8.0-, set ASCIIDOC8. +# -7.1.2, set ASCIIDOC7 +# 8.0-, no extra settings are needed # # # For docbook-xsl ... -# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) -# 1.69.0, no extra settings are needed? +# -1.68.1, no extra settings are needed? +# 1.69.0, set ASCIIDOC_ROFF? # 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? -# 1.71.1, no extra settings are needed? +# 1.71.1, set ASCIIDOC_ROFF? # 1.72.0, set DOCBOOK_XSL_172. -# 1.73.0-, set ASCIIDOC_NO_ROFF +# 1.73.0-, no extra settings are needed # -# -# If you had been using DOCBOOK_XSL_172 in an attempt to get rid -# of 'the ".ft C" problem' in your generated manpages, and you -# instead ended up with weird characters around callouts, try -# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). -# - -ifdef ASCIIDOC8 +ifndef ASCIIDOC7 ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff MANPAGE_XSL = manpage-1.72.xsl else - ifdef ASCIIDOC_NO_ROFF + ifndef ASCIIDOC_ROFF # docbook-xsl after 1.72 needs the regular XSL, but will not # pass-thru raw roff codes from asciidoc.conf, so turn them off. |