From 0824639ddf9c8ea9d7857440fb2414e12349f51a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jean-No=C3=ABl=20Avila?= Date: Wed, 21 Feb 2024 21:18:59 +0000 Subject: [PATCH] doc: clarify the format of placeholders MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Add the new format rule when using placeholders in the description of commands and options. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 65af8d82ce..15195cd976 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -666,6 +666,11 @@ Writing Documentation: --template= + 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 __ to be added. + Possibility of multiple occurrences is indicated by three dots: ... (One or more of .) @@ -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 -- 2.11.4.GIT