5 ms·

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

by biztos 10y ago

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.

copperx 10y ago
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.
- r0muald 10y ago
  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.
  - copperx 10y ago
    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.
- biztos 10y ago
  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?

by biztos 10y ago

copperx 10y ago

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.

r0muald 10y ago
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.
- copperx 10y ago
  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.
biztos 10y ago
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?