{"thread":{"id":"35327","subject":"[PATCH] State correct usage of backticks for options in man pages in the coding guidelines","startedAt":"2013-11-13T04:21:41Z","lastAt":"2013-11-13T17:21:38Z","messageCount":3,"participants":["Jason St. John","Ramkumar Ramachandra","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"230549","messageId":"1384316501-27965-1-git-send-email-jstjohn@purdue.edu","threadId":"35327","inReplyTo":null,"subject":"[PATCH] State correct usage of backticks for options in man pages in the coding guidelines","fromName":"Jason St. John","fromEmail":"jstjohn@purdue.edu","sentAt":"2013-11-13T04:21:41Z","receivedAt":"2013-11-13T04:21:41Z","isPatch":true,"sender":{"key":"jstjohn@purdue.edu","avatar":"https://avatars.githubusercontent.com/u/1393510?v=4"},"body":"The man pages contain inconsistent usage of backticks vs. single quotes\naround options and commands that are in paragraphs. This commit states\nthat backticks should always be used around options and commands.\n\nThis commit also states that \"--\" and friends should be left unescaped\n(e.g. use `--pretty=oneline` instead of `\\--pretty=oneline`).\n\nSigned-off-by: Jason St. John <jstjohn@purdue.edu>\n---\nThis was discussed here:\nhttp://marc.info/?l=git&m=138419319223845&w=2\nhttp://marc.info/?l=git&m=138424552300662&w=2\n\n\n Documentation/CodingGuidelines | 22 +++++++++++++++++++---\n 1 file changed, 19 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex a600e35..b335d48 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -260,9 +260,11 @@ Writing Documentation:\n \n  Every user-visible change should be reflected in the documentation.\n  The same general rule as for code applies -- imitate the existing\n- conventions.  A few commented examples follow to provide reference\n- when writing or modifying command usage strings and synopsis sections\n- in the manual pages:\n+ conventions.\n+\n+ A few commented examples follow to provide reference when writing or\n+ modifying command usage strings and synopsis sections in the manual\n+ pages:\n \n  Placeholders are spelled in lowercase and enclosed in angle brackets:\n    <file>\n@@ -312,3 +314,17 @@ Writing Documentation:\n    Use 'git' (all lowercase) when talking about commands i.e. something\n    the user would type into a shell and use 'Git' (uppercase first letter)\n    when talking about the version control system and its properties.\n+\n+ A few commented examples follow to provide reference when writing or\n+ modifying paragraphs or option/command explanations that contain options\n+ or commands:\n+\n+ Backticks are used around options or commands:\n+   `--pretty=oneline`\n+   `git rev-list`\n+\n+ Options or commands should use unescaped AsciiDoc:\n+   Correct:\n+      `--pretty=oneline`\n+   Incorrect:\n+      `\\--pretty=oneline`\n-- \n1.8.4.2\n"},{"id":"230561","messageId":"CALkWK0nD4aYQYVdfP=Dbb+XhYOHz=Ffvb_EzdgyYU86yXcXdjg@mail.gmail.com","threadId":"35327","inReplyTo":"1384316501-27965-1-git-send-email-jstjohn@purdue.edu","subject":"Re: [PATCH] State correct usage of backticks for options in man pages in the coding guidelines","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-11-13T10:04:55Z","receivedAt":"2013-11-13T10:04:55Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Jason St. John wrote:\n> + Backticks are used around options or commands:\n> +   `--pretty=oneline`\n> +   `git rev-list`\n\nYou might want to include configuration variables like\n`remote.pushdefault` here.\n"},{"id":"230569","messageId":"xmqq61rwfc9p.fsf@gitster.dls.corp.google.com","threadId":"35327","inReplyTo":"1384316501-27965-1-git-send-email-jstjohn@purdue.edu","subject":"Re: [PATCH] State correct usage of backticks for options in man pages in the coding guidelines","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-11-13T17:21:38Z","receivedAt":"2013-11-13T17:21:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jason St. John\" <jstjohn@purdue.edu> writes:\n\n> + Backticks are used around options or commands:\n> +   `--pretty=oneline`\n> +   `git rev-list`\n\nI'd prefer to see the objective stated before a particular means to\nachieve it.  I.e. not \"backticks around options and commands\", but\n\"literal examples (e.g. use of command line options, command names\nand configuration variables) are typeset monospaced, and if you can\nuse `backticks around word phrase`, do so.\".\n\n> + Options or commands should use unescaped AsciiDoc:\n> +   Correct:\n> +      `--pretty=oneline`\n> +   Incorrect:\n> +      `\\--pretty=oneline`\n\nI think it is wrong to single out \"options or commands\" here, and\nalso it is wrong to say \"unescaped\".  The \"unescaped\" is merely a\nconsequence of combination between:\n\nhttp://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html#_text_formatting\n\n    Word phrases `enclosed in backtick characters` (grave accents)\n    are also rendered in a monospaced font but in this case the\n    enclosed text is rendered literally and is not subject to\n    further expansion.\n\nand the use of `backticks` to achieve \"literal examples are typeset\nmonospaced\" rule.\n\nIf some place in the documentation needs to typeset a command use\nexample with inline substitutions, it is fine to use +monospaced and\ninline substituted text+ instead of `monospaced literal text`, and\nwith the former, we do need to quote the part we do not want to get\nsubstituted.\n\nThanks.\n"}]}