News for hackers. Stuff that matters.
Re:ReStructuredText vs. Markdown for documentation by biztos on Friday June 17, 2016 @12:50PM (#11923707)
I looked into these recently and found AsciiDoc the most promising for lightweight technical documentation, but I'm still having a very hard time getting myself to use it instead of Markdown.

AsciiDoc has some very newbie-hostile quirks, at least as of now it more or less requires asciidoctor, and even then its output HTML is terrible. Terrible as in Wrong, as in...

    <div class="paragraph"><p>Oh no...</p></div>
In fact, since I have not yet found an asciidoc converter that produces decent HTML, and I don't have time to write one, I may yet fall back into the "everything sorta supports Markdown" trap.
Re:ReStructuredText vs. Markdown for documentation by copperx on Friday June 17, 2016 @12:59PM (#11923782)
Markdown is one of those "worse is better" computer pop culture things that raise to the top, despite the existence of better tools.

I dare anyone to write a scientific paper or book using Markdown. In Asciidoc it's doable. And before you say that a markup language is the wrong tool for the job, let me remind you that nowadays authors might want to produce different formats (HTML, ePub, text-only) from the same source file which is difficult with LaTeX.

Re:ReStructuredText vs. Markdown for documentation by r0muald on Friday June 17, 2016 @01:09PM (#11923869)
If you consider Markdown on its own, I agree that it's rather difficult, but you should really try Pandoc, any output is possible, including scientific papers (pandoc-citeproc is fantastic) and books. Without Pandoc, Markdown would be very limited for my use cases.
Re:ReStructuredText vs. Markdown for documentation by copperx on Friday June 17, 2016 @01:30PM (#11924081)
I had forgotten about PanDoc! That's true, for some time I was pondering going Asciidoc vs Markdown+Pandoc. I liked the "purity" of Asciidoc (most things you will ever want to do are built-in), and Pandoc felt like it was a non-portable collection of hacks to get Markdown to do useful things.

I wish I had time to evaluate them in more detail, but so far I've stayed with LaTeX, which I feel is not the right tool for the job for material that's not going to be printed on paper.

Re:ReStructuredText vs. Markdown for documentation by biztos on Friday June 17, 2016 @01:58PM (#11924323)
I think it's more the case that there is no good general-purpose solution yet, and a bunch of people use Markdown because it's easy within a very limited scope, so now you have to deal with Markdown's near-ubiquity if you suggest something else.

I would never try to write a book in Markdown, no matter how extended; but considering the HTML produced by asciidoc|tor, you might also say "don't use AsciiDoc for simple Web publishing."

What I find much more fascinating is the question why there is no good general-purpose format that works equally well for blogging and for scientific papers and for books?

Is it really that hard a problem?