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

Ben Cotton bcotton at
Tue Aug 16 09:36:18 EDT 2016

On Tue, Aug 16, 2016 at 6:11 AM, Bradley M. Kuhn <bkuhn at> wrote:

> 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?
In addition to the footnote issue raised by Aaron, the big features
for me are the ability to easily do callouts (tips, warnings, etc).
For example:

    WARNING: Use of copyleft licenses has been shown to cause
increased awesomeness.

For book-ish documents, those are a killer feature. It also has things
like using (C) to insert a © and other formatting goodness.

> 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.
I fully agree on that. I take notes (particularly for classes and
training sessions) in Markdown because I can just write it without
devoting thought to the syntax, and can convert to HTML or PDF for
review later. It's definitely a bit of a tradeoff, because it makes it
harder for the writer but the finished product is better for the

> 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. :)
Aw, but I want to bikeshed this now. :-(


Ben Cotton

More information about the discuss mailing list