diff options
author | Junio C Hamano <gitster@pobox.com> | 2013-12-03 23:41:43 +0400 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2013-12-03 23:41:44 +0400 |
commit | f0c9253ef9b8ddbb81ad2a060db52fd5a646137f (patch) | |
tree | 0bec94b6493d86d2b4e9f23101b08caa431933d0 | |
parent | a2cb44c61de8e1dba4a0b758141b522b2b258e9a (diff) | |
parent | ca03c3682a45c9c10273cbdfaa48edea084ffd11 (diff) |
Merge branch 'jj/doc-markup-hints-in-coding-guidelines'
* jj/doc-markup-hints-in-coding-guidelines:
State correct usage of literal examples in man pages in the coding standards
-rw-r--r-- | Documentation/CodingGuidelines | 34 |
1 files changed, 31 insertions, 3 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a600e35c81..ef67b53f72 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -260,9 +260,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> @@ -312,3 +314,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. |