doc: clarify the format of placeholders
PATCH 1/1 doc: clarify the format of placeholders
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Add the new format rule when using placeholders in the description of commands and options.
---
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(+)
Documentation/CodingGuidelines +7 -0
@@ -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
Signature · 1 line
gitgitgadget