format will change from LaTeX -> (CommonMark|AsciiDoc): which should we chose?

[Aaron Wolf]

On 08/16/2016 03:11 AM, Bradley M. Kuhn wrote:
> Thanks to those of you who gave quick responses on this thread.  Now
> that a few have responded, I'll start giving my actual own opinions:
> 
> Ben Cotton wrote at 19:07 (CEST) on Monday:
>>> * My view of Markdown and similar languages is that it lacks the
>>> semantic richness to really do long-form materials well. I think it's
>>> great for short, self-contained content, but not for book-like
>>> material.
> 
> Ben, since you raised this issue, I would appreciate if you can say more
> about this.  I've done substantial editing in both in Asciidoc and
> Markdown, and other than the footnote issue (discussed below), I've not
> seen anything where the semantics of Asciidoc seemed stronger, but I've
> admittedly not written anything book-length in any formatting language
> but LaTeX.  Can you explain more?
> 
> Now, to finally say my own opinion: I struggle most with a simple issue:
> I find Asciidoc harder to read in source form.  Markdown-ish versions
> are really designed to make the text easily readable even without
> running it through the formatter.
> 
> (Of course, I don't have this problem in LaTeX, since after 25 years of
> writing in LaTeX, I "see" the formatted version in my mind's eye, but
> that's surely not the case for those other than science academics.)
> 
> So, I slightly favor the Markdown-ish formats because I find it smoother
> to read, but I realize that if I start working in Asciidoc all the time,
> I'll slowly but surely start to see it formatted properly in my minds'
> eye too, so that's not a huge deal.  But I was taken aback by the value
> in Markdown that it was so easily "looked right" even in its source
> form.
> 
> That said, Markdown "punts" to HTML any time the formatting gets complex
> (e.g., multi-column cell tables).  And, HTML is no more
> minds-eye-format-able than LaTeX is.
> 
> So, all this leaves me sitting like Hamlet saying "To Markdown or
> Asciidoc -- that is the question", which is why I asked all of you for
> opinions.
> 
> BTW, "fun fact" I left out of my last email, Jon Corbet is pushing
> Asciidoc as the future solution for Linux documentation:
>     https://lkml.org/lkml/2016/2/13/96 (and also his talk at LCA)
> 
> I don't think cross-over between Linux technical documentation
> contributors and the Guide is high, so it's just a data point.
> 
> Aaron Wolf wrote at 19:24 (CEST) on Monday:
>> I'd have voted for CommonMark but I can't see any reference to
>> footnotes, and I would favor a system that supports
>> footnotes. Pandoc's Markdown has that. I was expecting and hoping to
>> see footnote support in CommonMark.
> 
> Yes, I've used the pandoc-flavored footnotes for Markdown in other
> contexts, and I didn't even notice that pandoc's Markdown footnote
> system wasn't supported in CommonMark, because John MacFarlane (pandoc's
> maintainer) is one of the drafters of the CommonMark spec, so I simply
> assumed he'd added it.
> 
> So, I guess we'd be deciding between Asciidoc and pandoc-flavor-Markdown
> rather than CommonMark.
> 
> BTW, Aaron, I don't think Zack was suggesting we use Github-flavored
> Markdown, but that we use something *like* the Github documentation
> system (i.e., a Markdown-ish system) because that's what people know.
> 
> Allison Randal wrote at 21:04 (CEST) on Monday:
>>>> You shouldn't need to do it by hand, something like Pandoc will give
>>>> you a reasonable first approximation of a conversion from LaTeX,
>>>> possibly requiring some minor manual cleanups.
> 
> Yes, I didn't mean it would be a 100% manual process, but I suspect I
> want to go paragraph-by-paragraph anyway -- using a formatter and
> committing changes -- for other reasons.  There is another set of
> content-organization changes I want to make simultaneously with the
> format change, but I'll wait to expand on that point until we've
> sufficiently bikeshed Asciidoc vs. Markdown-ish. :)
> 

Okay, if the option is Pandoc's Markdown rather than CommonMark, here's
one thorough unqualified vote for Pandoc. It has bunches of references
to LaTeX even (though I've not used that capacity), and besides
footnotes and greater options for different sorts of lists, it has some
full table options even.