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>
Jason St. John committed
Nov 14, 2013 at 18:08 UTC
ca03c3682a45c9c10273cbdfaa48edea084ffd11
1 file changed
+31
-3
Documentation/CodingGuidelines
+31
-3
@@ -244,9 +244,11 @@ Writing Documentation:
244
245
Every user-visible change should be reflected in the documentation.
246
The same general rule as for code applies -- imitate the existing
247
- conventions. A few commented examples follow to provide reference
248
- when writing or modifying command usage strings and synopsis sections
249
- in the manual pages:
247
+ conventions.
248
+
249
+ A few commented examples follow to provide reference when writing or
250
+ modifying command usage strings and synopsis sections in the manual
251
+ pages:
252
253
Placeholders are spelled in lowercase and enclosed in angle brackets:
254
<file>
@@ -296,3 +298,29 @@ Writing Documentation:
298
Use 'git' (all lowercase) when talking about commands i.e. something
299
the user would type into a shell and use 'Git' (uppercase first letter)
300
when talking about the version control system and its properties.
301
+
302
+ A few commented examples follow to provide reference when writing or
303
+ modifying paragraphs or option/command explanations that contain options
304
+ or commands:
305
+
306
+ Literal examples (e.g. use of command-line options, command names, and
307
+ configuration variables) are typeset in monospace, and if you can use
308
+ `backticks around word phrases`, do so.
309
+ `--pretty=oneline`
310
+ `git rev-list`
311
+ `remote.pushdefault`
312
+
313
+ Word phrases enclosed in `backtick characters` are rendered literally
314
+ and will not be further expanded. The use of `backticks` to achieve the
315
+ previous rule means that literal examples should not use AsciiDoc
316
+ escapes.
317
+ Correct:
318
+ `--pretty=oneline`
319
+ Incorrect:
320
+ `\--pretty=oneline`
321
+
322
+ If some place in the documentation needs to typeset a command usage
323
+ example with inline substitutions, it is fine to use +monospaced and
324
+ inline substituted text+ instead of `monospaced literal text`, and with
325
+ the former, the part that should not get substituted must be
326
+ quoted/escaped.