doc: clearer rule about formatting literals
Make the guideline text that we want for our documentation clearer. Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org> Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org> Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org> Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr> Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Tom Russello committed
Jun 8, 2016 at 00:35 UTC
41f5b21f84b4d7db8e8c6edb34682c0f840ad8c8
1 file changed
+10
-3
Documentation/CodingGuidelines
+10
-3
@@ -526,12 +526,19 @@ Writing Documentation:
526
modifying paragraphs or option/command explanations that contain options
527
or commands:
528
529
- Literal examples (e.g. use of command-line options, command names, and
530
- configuration variables) are typeset in monospace, and if you can use
531
- `backticks around word phrases`, do so.
529
+ Literal examples (e.g. use of command-line options, command names,
530
+ configuration and environment variables) must be typeset in monospace (i.e.
531
+ wrapped with backticks):
532
`--pretty=oneline`
533
`git rev-list`
534
`remote.pushDefault`
535
+ `GIT_DIR`
536
+
537
+ An environment variable must be prefixed with "$" only when referring to its
538
+ value and not when referring to the variable itself, in this case there is
539
+ nothing to add except the backticks:
540
+ `GIT_DIR` is specified
541
+ `$GIT_DIR/hooks/pre-receive`
542
543
Word phrases enclosed in `backtick characters` are rendered literally
544
and will not be further expanded. The use of `backticks` to achieve the