Merge branch 'ja/doc-placeholders-markup-rules' into HEAD

The way placeholders are to be marked-up in documentation have been
specified; use "_<placeholder>_" to typeset the word inside a pair
of <angle-brakets> emphasized.

* ja/doc-placeholders-markup-rules:
  doc: clarify the format of placeholders

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 578587a47155e929457e12862cd648c9fdf81acd..a6a965609b5bc09d9db6e201ca9f18e3bca10538 100644 (file)
--- 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