{"thread":{"id":"47523","subject":"[PATCH] doc/SubmittingPatches: improve text formatting","startedAt":"2018-01-02T15:33:59Z","lastAt":"2018-01-04T19:00:26Z","messageCount":3,"participants":["Todd Zullinger","brian m. carlson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"335616","messageId":"20180102153350.11723-1-tmz@pobox.com","threadId":"47523","inReplyTo":null,"subject":"[PATCH] doc/SubmittingPatches: improve text formatting","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2018-01-02T15:33:50Z","receivedAt":"2018-01-02T15:33:59Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"049e64aa50 (\"Documentation: convert SubmittingPatches to AsciiDoc\",\n2017-11-12) changed the `git blame` and `git shortlog` examples given in\nthe section on sending your patches.\n\nIn order to italicize the `$path` argument the commands are enclosed in\nplus characters as opposed to backticks.  The difference between the\nquoting methods is that backtick enclosed text is not subject to further\nexpansion.  This formatting makes reading SubmittingPatches in a git\nclone a little more difficult.  In addition to the underscores around\n`$path` the `--` chars in `git shortlog --no-merges` must be replaced\nwith `{litdd}`.\n\nUse backticks to quote these commands.  The italicized `$path` is lost\nfrom the html version but the commands can be read (and copied) more\neasily by users reading the text version.  These readers are more likely\nto use the commands while submitting patches.  Make it easier for them.\n\nSigned-off-by: Todd Zullinger <tmz@pobox.com>\n---\n\nI missed this in the initial discussion.  It was mentioned by\nJunio and brian explained the reasoning for using it in\n<20171031012710.jfemqb6ybiog4sbz@genre.crustytoothpaste.net>:\n\n> > The +fixed width with _italics_ mixed in+ mark-up is something not\n> > exactly new, but it is rarely used in our documentation set, so I\n> > had to double check by actually seeing how it got rendered, and it\n> > looked alright.\n>\n> I thought it provided some hint to the reader that this wasn't meant to\n> be typed literally.  It's a preference of mine and I think it aids in\n> readability, but it can be changed if we want.\n\nThat's what I had guessed before I looked back at the list\narchives.  I understand the desire to make it clear that $path\nisn't a literal value.  I think that it's worth losing that subtle\nhint in order to make the plain text SubmittingPatches file a\nlittle easier to read.\n\nWhether the people most likely to be considering sending a patch\nfor git.git are will read the document from a git clone or the\nrendered html output is the main question.  Though even readers of\nthe installed text file in their packaged git will suffer a bit.\n\nIt's great having the document in HTML to aid in sharing it's\nguidance with others, no doubt.  I've wanted to symlink to\nportions of the document numerous times.  I hope a small change to\nmake it more legible to those who also like plain text will be\nwelcome.\n\nI considered using backticks for the commands and then +_$path_+\nfor the argument.  Maybe that's a reasonable compromise?  I.e.:\n\n-+git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to\n+`git blame` +_$path_+ and `git shortlog --no-merges` +_$path_+ would help to\n\nThe text version is still a bit strange with that method, but it\ncertainly separates \"$path\" from the rest of the command in both\nthe text and html output. :)\n\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 3ef30922ec..a1d0feca36 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -261,7 +261,7 @@ not a text/plain, it's something else.\n \n Send your patch with \"To:\" set to the mailing list, with \"cc:\" listing\n people who are involved in the area you are touching (the output from\n-+git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to\n+`git blame $path` and `git shortlog --no-merges $path` would help to\n identify them), to solicit comments and reviews.\n \n :1: footnote:[The current maintainer: gitster@pobox.com]\n-- \n2.16.0.rc0\n\n"},{"id":"335804","messageId":"20180103235625.GB817655@genre.crustytoothpaste.net","threadId":"47523","inReplyTo":"20180102153350.11723-1-tmz@pobox.com","subject":"Re: [PATCH] doc/SubmittingPatches: improve text formatting","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2018-01-03T23:56:26Z","receivedAt":"2018-01-03T23:56:36Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Tue, Jan 02, 2018 at 10:33:50AM -0500, Todd Zullinger wrote:\n> 049e64aa50 (\"Documentation: convert SubmittingPatches to AsciiDoc\",\n> 2017-11-12) changed the `git blame` and `git shortlog` examples given in\n> the section on sending your patches.\n> \n> In order to italicize the `$path` argument the commands are enclosed in\n> plus characters as opposed to backticks.  The difference between the\n> quoting methods is that backtick enclosed text is not subject to further\n> expansion.  This formatting makes reading SubmittingPatches in a git\n> clone a little more difficult.  In addition to the underscores around\n> `$path` the `--` chars in `git shortlog --no-merges` must be replaced\n> with `{litdd}`.\n> \n> Use backticks to quote these commands.  The italicized `$path` is lost\n> from the html version but the commands can be read (and copied) more\n> easily by users reading the text version.  These readers are more likely\n> to use the commands while submitting patches.  Make it easier for them.\n\nI think this change is fine.  I don't have a strong opinion either way\nand if others think the change makes the plain text more readable, I'm\nall for it.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\nhttps://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"335835","messageId":"xmqqa7xtfnzx.fsf@gitster.mtv.corp.google.com","threadId":"47523","inReplyTo":"20180103235625.GB817655@genre.crustytoothpaste.net","subject":"Re: [PATCH] doc/SubmittingPatches: improve text formatting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-01-04T19:00:18Z","receivedAt":"2018-01-04T19:00:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> On Tue, Jan 02, 2018 at 10:33:50AM -0500, Todd Zullinger wrote:\n>> 049e64aa50 (\"Documentation: convert SubmittingPatches to AsciiDoc\",\n>> 2017-11-12) changed the `git blame` and `git shortlog` examples given in\n>> the section on sending your patches.\n>> \n>> In order to italicize the `$path` argument the commands are enclosed in\n>> plus characters as opposed to backticks.  The difference between the\n>> quoting methods is that backtick enclosed text is not subject to further\n>> expansion.  This formatting makes reading SubmittingPatches in a git\n>> clone a little more difficult.  In addition to the underscores around\n>> `$path` the `--` chars in `git shortlog --no-merges` must be replaced\n>> with `{litdd}`.\n>> \n>> Use backticks to quote these commands.  The italicized `$path` is lost\n>> from the html version but the commands can be read (and copied) more\n>> easily by users reading the text version.  These readers are more likely\n>> to use the commands while submitting patches.  Make it easier for them.\n>\n> I think this change is fine.  I don't have a strong opinion either way\n> and if others think the change makes the plain text more readable, I'm\n> all for it.\n\nI too would prefer to move towards plain text that reads easier,\nespecially if it does not make the resulting typeset version\nunreadable; thanks, both.\n"}]}