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

[Bradley M. Kuhn]

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. :)
-- 
   -- bkuhn
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter