doc: clarify the format of placeholders

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