[PATCH] doc/SubmittingPatches: improve text formatting
- From
Todd Zullinger <tmz@pobox.com>
- Date
- Jan 2, 2018, 15:33 UTC
- Message-ID
- <20180102153350.11723-1-tmz@pobox.com>
049e64aa50 ("Documentation: convert SubmittingPatches to AsciiDoc", 2017-11-12) changed the `git blame` and `git shortlog` examples given in the section on sending your patches.
In order to italicize the `$path` argument the commands are enclosed in plus characters as opposed to backticks. The difference between the quoting methods is that backtick enclosed text is not subject to further expansion. This formatting makes reading SubmittingPatches in a git clone a little more difficult. In addition to the underscores around `$path` the `--` chars in `git shortlog --no-merges` must be replaced with `{litdd}`.
Use backticks to quote these commands. The italicized `$path` is lost from the html version but the commands can be read (and copied) more easily by users reading the text version. These readers are more likely to use the commands while submitting patches. Make it easier for them.
Signed-off-by: Todd Zullinger <tmz@pobox.com> ---
I missed this in the initial discussion. It was mentioned by Junio and brian explained the reasoning for using it in <20171031012710.jfemqb6ybiog4sbz@genre.crustytoothpaste.net>:
Show 8 quoted lines
> > The +fixed width with _italics_ mixed in+ mark-up is something not > > exactly new, but it is rarely used in our documentation set, so I > > had to double check by actually seeing how it got rendered, and it > > looked alright. > > I thought it provided some hint to the reader that this wasn't meant to > be typed literally. It's a preference of mine and I think it aids in > readability, but it can be changed if we want.
That's what I had guessed before I looked back at the list archives. I understand the desire to make it clear that $path isn't a literal value. I think that it's worth losing that subtle hint in order to make the plain text SubmittingPatches file a little easier to read.
Whether the people most likely to be considering sending a patch for git.git are will read the document from a git clone or the rendered html output is the main question. Though even readers of the installed text file in their packaged git will suffer a bit.
It's great having the document in HTML to aid in sharing it's guidance with others, no doubt. I've wanted to symlink to portions of the document numerous times. I hope a small change to make it more legible to those who also like plain text will be welcome.
I considered using backticks for the commands and then +_$path_+ for the argument. Maybe that's a reasonable compromise? I.e.:
-+git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to +`git blame` +_$path_+ and `git shortlog --no-merges` +_$path_+ would help to
The text version is still a bit strange with that method, but it certainly separates "$path" from the rest of the command in both the text and html output. :)
Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3ef30922ec..a1d0feca36 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -261,7 +261,7 @@ not a text/plain, it's something else. Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the output from -+git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to +`git blame $path` and `git shortlog --no-merges $path` would help to identify them), to solicit comments and reviews. :1: footnote:[The current maintainer: gitster@pobox.com]
-- 2.16.0.rc0