{"thread":{"id":"60974","subject":"[PATCH] doc: clarify the format of placeholders","startedAt":"2024-02-21T21:19:02Z","lastAt":"2024-02-21T21:19:02Z","messageCount":1,"participants":["Jean-Noël Avila via GitGitGadget"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"489108","messageId":"pull.1671.git.1708550340094.gitgitgadget@gmail.com","threadId":"60974","inReplyTo":null,"subject":"[PATCH] doc: clarify the format of placeholders","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-02-21T21:18:59Z","receivedAt":"2024-02-21T21:19:02Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nAdd the new format rule when using placeholders in the description of\ncommands and options.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n    doc: clarify the format of placeholders\n    \n    Following the patch \"Doc placeholders\", there was a question about\n    adding a formal rule on writing placeholders in description paragraphs.\n    \n    One agreed output was that the placeholders in paragraph must be\n    surrounded by angle brackets and not set in literal with backticks.\n    \n    A new rule, to be accepted, is to force placeholders in paragraphs to be\n    italicized.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1671%2Fjnavila%2Fplaceholders_document_guidelines-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1671/jnavila/placeholders_document_guidelines-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1671\n\n Documentation/CodingGuidelines | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 578587a4715..a6a965609b5 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -666,6 +666,11 @@ Writing Documentation:\n    <new-branch-name>\n    --template=<template-directory>\n \n+ When a placeholder is cited in text paragraph, it is enclosed in angle\n+ brackets to remind the reader the reference in the synopsis section.\n+ For better visibility, the placeholder is typeset in italics:\n+   The _<file>_ to be added.\n+\n  Possibility of multiple occurrences is indicated by three dots:\n    <file>...\n    (One or more of <file>.)\n@@ -751,6 +756,8 @@ Writing Documentation:\n    Incorrect:\n       `\\--pretty=oneline`\n \n+A placeholder is not enclosed in backticks, as it is not a literal.\n+\n  If some place in the documentation needs to typeset a command usage\n  example with inline substitutions, it is fine to use +monospaced and\n  inline substituted text+ instead of `monospaced literal text`, and with\n\nbase-commit: 5fdd5b989cbe5096d44e89861a92b2dd47c279d9\n-- \ngitgitgadget\n"}]}