From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx>
Add the new format rule when using placeholders in the description of
commands and options.
Signed-off-by: Jean-Noël Avila <jn.avila@xxxxxxx>
---
doc: clarify the format of placeholders
Following the patch "Doc placeholders", there was a question about
adding a formal rule on writing placeholders in description paragraphs.
One agreed output was that the placeholders in paragraph must be
surrounded by angle brackets and not set in literal with backticks.
A new rule, to be accepted, is to force placeholders in paragraphs to be
italicized.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1671%2Fjnavila%2Fplaceholders_document_guidelines-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1671/jnavila/placeholders_document_guidelines-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1671
Documentation/CodingGuidelines | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 578587a4715..a6a965609b5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -666,6 +666,11 @@ Writing Documentation:
<new-branch-name>
--template=<template-directory>
+ When a placeholder is cited in text paragraph, it is enclosed in angle
+ brackets to remind the reader the reference in the synopsis section.
+ For better visibility, the placeholder is typeset in italics:
+ The _<file>_ to be added.
+
Possibility of multiple occurrences is indicated by three dots:
<file>...
(One or more of <file>.)
@@ -751,6 +756,8 @@ Writing Documentation:
Incorrect:
`\--pretty=oneline`
+A placeholder is not enclosed in backticks, as it is not a literal.
+
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
base-commit: 5fdd5b989cbe5096d44e89861a92b2dd47c279d9
--
gitgitgadget
