[PATCH] doc/SubmittingPatches: improve text formatting

[PATCH] doc/SubmittingPatches: improve text formatting

[Todd Zullinger]

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>:

> > 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

Re: [PATCH] doc/SubmittingPatches: improve text formatting

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1333 bytes --]

On Tue, Jan 02, 2018 at 10:33:50AM -0500, Todd Zullinger wrote:
> 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.

I think this change is fine.  I don't have a strong opinion either way
and if others think the change makes the plain text more readable, I'm
all for it.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 867 bytes --]

Re: [PATCH] doc/SubmittingPatches: improve text formatting

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On Tue, Jan 02, 2018 at 10:33:50AM -0500, Todd Zullinger wrote:
>> 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.
>
> I think this change is fine.  I don't have a strong opinion either way
> and if others think the change makes the plain text more readable, I'm
> all for it.

I too would prefer to move towards plain text that reads easier,
especially if it does not make the resulting typeset version
unreadable; thanks, both.