[PATCH] doc: clarify the format of placeholders

Jean-Noël Avila via GitGitGadget· Feb 21, 2024, 21:18 UTC · lore

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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>
---
    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(+)

Show changes to Documentation/CodingGuidelines +7 −0

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

patchdoc: clarify the format of placeholders