Merge branch 'jj/doc-markup-hints-in-coding-guidelines'
authorJunio C Hamano <gitster@pobox.com>
Tue, 3 Dec 2013 19:41:43 +0000 (11:41 -0800)
committerJunio C Hamano <gitster@pobox.com>
Tue, 3 Dec 2013 19:41:44 +0000 (11:41 -0800)
* jj/doc-markup-hints-in-coding-guidelines:
State correct usage of literal examples in man pages in the coding standards

1  2 
Documentation/CodingGuidelines
index a600e35c810b74848062dee8d74e573192c09e2c,4b9d59e7ae5ec4261f045956ab4c5eebb14351eb..ef67b53f721f28e5442c00273dec5f1582f555be
@@@ -145,14 -145,6 +145,14 @@@ For C programs
     they were describing changes.  Often splitting a function
     into two makes the intention of the code much clearer.
  
 + - Multi-line comments include their delimiters on separate lines from
 +   the text.  E.g.
 +
 +      /*
 +       * A very long
 +       * multi-line comment.
 +       */
 +
   - Double negation is often harder to understand than no negation
     at all.
  
@@@ -250,19 -242,13 +250,21 @@@ Writing Documentation
   processed into HTML and manpages (e.g. git.html and git.1 in the
   same directory).
  
 + The documentation liberally mixes US and UK English (en_US/UK)
 + norms for spelling and grammar, which is somewhat unfortunate.
 + In an ideal world, it would have been better if it consistently
 + used only one and not the other, and we would have picked en_US
 + (if you wish to correct the English of some of the existing
 + documentation, please see the documentation-related advice in the
 + Documentation/SubmittingPatches file).
 +
   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>
     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.