summaryrefslogtreecommitdiff
path: root/Documentation/CodingGuidelines
diff options
context:
space:
mode:
authorJason St. John <jstjohn@purdue.edu>2013-11-14 23:08:45 (GMT)
committerJunio C Hamano <gitster@pobox.com>2013-11-18 21:30:51 (GMT)
commitca03c3682a45c9c10273cbdfaa48edea084ffd11 (patch)
tree5c2832d915a4692f0ed2abde7e38fef32b2d92bb /Documentation/CodingGuidelines
parentd7d2c87955f7700289c5b516f12579a5be4b879d (diff)
downloadgit-ca03c3682a45c9c10273cbdfaa48edea084ffd11.zip
git-ca03c3682a45c9c10273cbdfaa48edea084ffd11.tar.gz
git-ca03c3682a45c9c10273cbdfaa48edea084ffd11.tar.bz2
State correct usage of literal examples in man pages in the coding standards
The man pages contain inconsistent usage of backticks vs. single quotes around options, commands, etc. that are in paragraphs. This commit states that backticks should always be used around literal examples. This commit states that "--" and friends should not be escaped (e.g. use `--pretty=oneline` instead of `\--pretty=oneline`). This commit also states correct usage for typesetting command usage examples with inline substitutions. Thanks-to: Ramkumar Ramachandra <artagnon@gmail.com> Thanks-to: Stuart Rackham <srackham@gmail.com> Thanks-to: Junio C Hamano <gitster@pobox.com> Signed-off-by: Jason St. John <jstjohn@purdue.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/CodingGuidelines')
-rw-r--r--Documentation/CodingGuidelines34
1 files changed, 31 insertions, 3 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 559d5f9..4b9d59e 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -244,9 +244,11 @@ 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:
+ 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 spelled in lowercase and enclosed in angle brackets:
<file>
@@ -296,3 +298,29 @@ Writing Documentation:
Use 'git' (all lowercase) when talking about commands i.e. something
the user would type into a shell and use 'Git' (uppercase first letter)
when talking about the version control system and its properties.
+
+ A few commented examples follow to provide reference when writing or
+ modifying paragraphs or option/command explanations that contain options
+ or commands:
+
+ Literal examples (e.g. use of command-line options, command names, and
+ configuration variables) are typeset in monospace, and if you can use
+ `backticks around word phrases`, do so.
+ `--pretty=oneline`
+ `git rev-list`
+ `remote.pushdefault`
+
+ Word phrases enclosed in `backtick characters` are rendered literally
+ and will not be further expanded. The use of `backticks` to achieve the
+ previous rule means that literal examples should not use AsciiDoc
+ escapes.
+ Correct:
+ `--pretty=oneline`
+ Incorrect:
+ `\--pretty=oneline`
+
+ If some place in the documentation needs to typeset a command usage
+ example with inline substitutions, it is fine to use +monospaced and
+ inline substituted text+ instead of `monospaced literal text`, and with
+ the former, the part that should not get substituted must be
+ quoted/escaped.