From: Jean-Noël Avila <jn.avila@free.fr>
Date: Wed, 21 Feb 2024 21:18:59 +0000 (+0000)
Subject: doc: clarify the format of placeholders
X-Git-Tag: v2.45.0-rc0~153^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0824639ddf9c8ea9d7857440fb2414e12349f51a;p=thirdparty%2Fgit.git

doc: clarify the format of placeholders

Add the new format rule when using placeholders in the description of
commands and options.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 65af8d82ce..15195cd976 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