Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc

On Mon, Oct 30, 2017 at 01:28:05PM +0900, Junio C Hamano wrote:

"brian m. carlson" [off-list ref] writes:

Thanks.  I personally prefer the plain-text original, but I do
understand the need to have a version with ids that you can tell
others to visit in their browsers.  Assuming that this goes in the
right direction, here are a few comments.

quoted

@@ -58,8 +65,9 @@ differs substantially from the prior version, are all good things
 to have.
 
 Make sure that you have tests for the bug you are fixing.  See
-t/README for guidance.
+'t/README' for guidance.

I am guessing that, from the way you updated 'next' to `next'
etc. in the previous hunk, you are typesetting in <tt> anything a
reader may type literally without substitution.

Should this be `t/README`, as it is a part of something a reader may
type literally (as in "less t/README")?

So this syntax provides italicized paths, but I agree that the <tt> is
better here.  I'll make those changes throughout, and fix up the
instances of that you mentioned.

quoted

-(4) Sending your patches.
+[[send-patches]]
+=== Sending your patches.
+:1: footnote:[The current maintainer: gitster@pobox.com]
+:2: footnote:[The mailing list: git@vger.kernel.org]

Having to see these footnotes upfront is somewhat distracting for
those of us who prefer to use this file as a text document.  I see
these become part of the footnotes section at the very end of the
document (as opposed to the end of this section), so even with the
rendered output it does not look ideal.

I am not sure how much these two points matter, though.

AsciiDoc requires that the attributes appear before their references.  I
can move the attributes just before the paragraph they refer to, or I
can inline the footnotes.  I could also just turn them into links if
that works better.

This is actually one thing that I think Markdown does better.

quoted

@@ -191,7 +212,7 @@ not ready to be applied but it is for discussion, [PATCH v2],

..
 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 --no-merges $path" would help to
++git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to
 identify them), to solicit comments and reviews.

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.

quoted

 After the list reached a consensus that it is a good idea to apply the
-patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
-list [*2*] for inclusion.
+patch, re-send it with "To:" set to the maintainer{1} and "cc:" the
+list{2} for inclusion.
 
 Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
 "Tested-by:" lines as necessary to credit people who helped your
 patch.

Should these "Foo-by:" all be `Foo-by:`?

I'll make these changes as well.

quoted

-An ideal patch flow
+[[patch-flow]]
+== An ideal patch flow
 
 Here is an ideal patch flow for this project the current maintainer
 suggests to the contributors:
 
- (0) You come up with an itch.  You code it up.
+. You come up with an itch.  You code it up.
 
- (1) Send it to the list and cc people who may need to know about
-     the change.
+. Send it to the list and cc people who may need to know about
+  the change.
++
+The people who may need to know are the ones whose code you
+are butchering.  These people happen to be the ones who are
+most likely to be knowledgeable enough to help you, but
+they have no obligation to help you (i.e. you ask for help,
+don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would
+help you find out who they are.
 
-     The people who may need to know are the ones whose code you
-     are butchering.  These people happen to be the ones who are
-     most likely to be knowledgeable enough to help you, but
-     they have no obligation to help you (i.e. you ask for help,
-     don't demand).  "git log -p -- $area_you_are_modifying" would
-     help you find out who they are.
+. You get comments and suggestions for improvements.  You may
+  even get them in a "on top of your change" patch form.
 
- (2) You get comments and suggestions for improvements.  You may
-     even get them in a "on top of your change" patch form.
+. Polish, refine, and re-send to the list and the people who
+  spend their time to improve your patch.  Go back to step (2).

Not a complaint, but it is a shame that we have to spell out (2)
even though we are using auto-numbering feature here.

It is.  I'll see if there's a way I can refer to an element of a list,
but I don't think there is.

quoted

@@ -452,23 +475,24 @@ should come after the three-dash line that signals the end of the

...
+=== Pine
 
 (Johannes Schindelin)
 
+....
 I don't know how many people still use pine, but for those poor
 souls it may be good to mention that the quell-flowed-text is
 needed for recent versions.
 
 ... the "no-strip-whitespace-before-send" option, too. AFAIK it
 was introduced in 4.60.
+....
 (Linus Torvalds)
 
 And 4.58 needs at least this.

This line alone in the entire section for pine is done in regular
text, which looked somewhat strange.

Ah, yes.  I misinterpreted that as not being part of Linus's email, but
I suppose it probably was.

Since these are emails, I can turn them into quote blocks with
attribution if that makes things more readable.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204