diff options
author | Junio C Hamano <gitster@pobox.com> | 2013-12-17 11:36:10 -0800 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2013-12-17 11:36:10 -0800 |
commit | 5712dcb209b074a99e1c935eadc8e80d56eaf5b4 (patch) | |
tree | 2cc30c0670bc412a869c949e54586137933875fb /Documentation | |
parent | Merge branch 'jj/log-doc' into maint (diff) | |
parent | State correct usage of literal examples in man pages in the coding standards (diff) | |
download | tgif-5712dcb209b074a99e1c935eadc8e80d56eaf5b4.tar.xz |
Merge branch 'jj/doc-markup-hints-in-coding-guidelines' into maint
* jj/doc-markup-hints-in-coding-guidelines:
State correct usage of literal examples in man pages in the coding standards
Diffstat (limited to 'Documentation')
-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. |