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

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

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")?

The pathname templates/hooks--pre-commit is typeset just like any
body text?

Out of context, but "master" we see above should probably be
`master` here, to be in line with what you did in an earlier hunk.
So should "next" we see below in the pre-context of this hunk.

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

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.

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

Ditto.

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

 
- (3) Polish, refine, and re-send to the list and the people who
-     spend their time to improve your patch.  Go back to step (2).
+. The list forms consensus that the last round of your patch is
+  good.  Send it to the maintainer and cc the list.
 
- (4) The list forms consensus that the last round of your patch is
-     good.  Send it to the maintainer and cc the list.
-

By the way, to those of us who are interested in "readble diffs" may
find this hunk a bit interesting to study.  We should be able to
pair "-deleted" blocks of lines with corresponding "+added" blocks
more sensibly.

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

Hi,

On Mon, 30 Oct 2017, 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.

If you want to go into the direction of the web, AsciiDoc is actually the
wrong choice IMO, and Markdown would be the right choice. Basically
everybody on the web is either supporting Markdown or being asked by users
to do so.

Assuming that *that* is something we want to pursue, I would also suggest
to move the man pages away from AsciiDoc to Markdown (using e.g.
[ronn](https://rtomayko.github.io/ronn/ronn.1.html)).

Ciao,
Dscho

On Mon, Oct 30, 2017 at 1:35 PM, Johannes Schindelin
[off-list ref] wrote:

Hi,

On Mon, 30 Oct 2017, Junio C Hamano wrote:

quoted

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

If you want to go into the direction of the web, AsciiDoc is actually the
wrong choice IMO, and Markdown would be the right choice. Basically
everybody on the web is either supporting Markdown or being asked by users
to do so.

Assuming that *that* is something we want to pursue, I would also suggest
to move the man pages away from AsciiDoc to Markdown (using e.g.
[ronn](https://rtomayko.github.io/ronn/ronn.1.html)).

Nitpick, the right URL is: https://rtomayko.github.io/ronn/ronn.1.html
You put an extra ')' at the end and therefore I've got a scaring 404 error :-)

Ciao,
-- 
Paolo

Hi Paolo,

On Mon, 30 Oct 2017, Paolo Ciarrocchi wrote:

On Mon, Oct 30, 2017 at 1:35 PM, Johannes Schindelin
[off-list ref] wrote:

quoted

On Mon, 30 Oct 2017, Junio C Hamano wrote:

quoted

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

If you want to go into the direction of the web, AsciiDoc is actually the
wrong choice IMO, and Markdown would be the right choice. Basically
everybody on the web is either supporting Markdown or being asked by users
to do so.

Assuming that *that* is something we want to pursue, I would also suggest
to move the man pages away from AsciiDoc to Markdown (using e.g.
[ronn](https://rtomayko.github.io/ronn/ronn.1.html)).

Nitpick, the right URL is: https://rtomayko.github.io/ronn/ronn.1.html
You put an extra ')' at the end and therefore I've got a scaring 404 error :-)

The first closing parenthesis closes the link associated with the label
`ronn`, the second closing parenthesis closes the remark I started in the
previous line (beginning with the word "using").

Ciao,
Johannes

On Tue, Oct 31, 2017 at 6:21 PM, Johannes Schindelin
[off-list ref] wrote:

Hi Paolo,

On Mon, 30 Oct 2017, Paolo Ciarrocchi wrote:

quoted

On Mon, Oct 30, 2017 at 1:35 PM, Johannes Schindelin
[off-list ref] wrote:

quoted

On Mon, 30 Oct 2017, Junio C Hamano wrote:

quoted

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

If you want to go into the direction of the web, AsciiDoc is actually the
wrong choice IMO, and Markdown would be the right choice. Basically
everybody on the web is either supporting Markdown or being asked by users
to do so.

Assuming that *that* is something we want to pursue, I would also suggest
to move the man pages away from AsciiDoc to Markdown (using e.g.
[ronn](https://rtomayko.github.io/ronn/ronn.1.html)).

Nitpick, the right URL is: https://rtomayko.github.io/ronn/ronn.1.html
You put an extra ')' at the end and therefore I've got a scaring 404 error :-)

The first closing parenthesis closes the link associated with the label
`ronn`, the second closing parenthesis closes the remark I started in the
previous line (beginning with the word "using").

You are right. I've got confused by the fact that gmail fails to
properly handle that link.
Sorry for the noise.

Regards,
-- 
Paolo

On Mon, Oct 30, 2017 at 01:35:19PM +0100, Johannes Schindelin wrote:

If you want to go into the direction of the web, AsciiDoc is actually the
wrong choice IMO, and Markdown would be the right choice. Basically
everybody on the web is either supporting Markdown or being asked by users
to do so.

Assuming that *that* is something we want to pursue, I would also suggest
to move the man pages away from AsciiDoc to Markdown (using e.g.
[ronn](https://rtomayko.github.io/ronn/ronn.1.html)).

The thing I really like about AsciiDoc is that it works well for a
variety of output formats.  Markdown is designed for HTML, and only
HTML.  It may have converters to other formats, but then you can't use
any extension mechanisms in HTML.  Markdown also lacks features that
AsciiDoc has, like cross-references, named anchors, and the ability to
write the linkgit syntax.

AsciiDoc, via DocBook and the XSLT stylesheets, supports conversion to
PDF, DVI, PS, and ePub, among others.  The things I'm seeing for
Markdown to PDF involve either Pandoc or a browser engine such as
phantomjs.

Also, AsciiDoc has the benefit that it has only two implementations.
Markdown has so many variants that it's hard to write things like tables
in a portable way, so we're going to have at least as many problems
(between the website and the codebase) as we do now.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204

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