The really nice thing about ReST is that it has provided generic syntax for extensions, one for inline text: :foo:`hello world` and for blocks:<p>.. extension::
hello world<p>In markdown, on the other hand, you have multiple, incompatible versions which have entirely different syntax because there is no generic extension mechanism.<p>ReST feels more well thought-out, generally.<p>That said, I've pretty much given up advocating it, because markdown seems to have won and has so much more tool support.
Pandoc is actually a really powerful tool for converting between different formats. As an example, I recently wrote a book using Markdown (Pandoc's version) and was easily able to export .html, .pdf and .epub from my markdown files. The addition of footnotes and built-in syntax highlighting (with optional line numbers, etc) was also very useful.<p>Pandoc can be as simple as `pandoc input.md output.pdf` but can also handle things like a Table of Contents, different highlighting styles, latex engines and fonts:<p><pre><code> pandoc --toc --variable version=0.0.1 -N --highlight-style=tango --latex-engine=xelatex --variable mainfont=Helvetica --variable monofont="Meslo LG L DZ" --chapters $(ls -d -1 `pwd`/_input/*.*) -o _output/book.pdf
</code></pre>
I tend to set the more complicated command as a build file or alias and I've been considering using local markdown files and then using pandoc to convert them to .html for my WordPress-based blog.
The Markdown ecosystem reminds me of shell scripts in a bad way. There are a bunch of subtly and not so subtly different dialects and environments out there, and not many people have a strong awareness of these while writing, so if something seems okay "on my computer" or in Markdown's case "on my preview" then off it goes.
Am I the only one who feels like they were teleported back to the early 1990s upon seeing these text files with code intermingled everywhere?<p>I am not bashing markdown and friends, as I understand there is a use for these tools in some cases, but I am surprised they are so widely embraced and loved.<p>To me they just evoke the days of typing an essay on dad's 386 with Word Perfect 5.1 installed, and having to hit "reveal codes" to figure out what is going on. MS Word won against WP when they completely did away with these codes.[1]<p>Now it's 2014 and we're loving building tables by hand-crafting ASCII art.<p>Am I the only who thinks we can do better?<p>[1] <a href="http://www.theoligarch.com/microsoft_vs_apple_history.htm" rel="nofollow">http://www.theoligarch.com/microsoft_vs_apple_history.htm</a>
Those ReST examples reminds me of the ASCII docs I'd write for my shareware software. Fairly typical for the time.<p>Not so different from the IEFT Document Conventions. <a href="http://www.rfc-editor.org/rfc/rfc3.txt" rel="nofollow">http://www.rfc-editor.org/rfc/rfc3.txt</a><p>Or the RFC guidelines. <a href="https://www.rfc-editor.org/rfc-style-guide/rfc-style" rel="nofollow">https://www.rfc-editor.org/rfc-style-guide/rfc-style</a><p>I wrote a markdown renderer for my web dev stack. And I've been "cross compiling" to markdown, screen scrapping docs and persisting it to markdown.<p>Now I realize choosing markdown was rather arbitrary (personal preference, familiarity). Any document structure would suffice.<p>Nice comparison, thanks.
Markdown has always looked limited and incomplete to me.<p>But I can't decide between ReST(+Sphinx) and AsciiDoc(+?) - ReST seems to me like it was better thought out, but somehow my AsciiDoc documents turn out looking better, even though I like ReST more.
For me Markdown wins just because I'm used to dealing with it daily on GitHub.<p>Sidenote: Wish Github Flavored Markdown would adopt some nice things from Pandoc, like multiline tables.
Pandoc and ReST are extensive, flexible, and simply complete. They are great. I have never understood the fetish behind Markdown and the cult-like fan-boyish approach to it. It was not needed. It would have been rather good to standardised an existing markup (or a combination of them) than copy the existing one and pretty much release it with a different name.
Always wondered how Pandoc MD, ReST compare when my document type is slightly more complex, for example: a question and answer session?<p>I ended up entering notes from such sessions into handwritten XML, which I am reconsidering. What is a good format to store one's notes? I am transcribing from handwritten text.
i am in the process of releasing "zen markup language".<p>it's "lighter" than all the other light-markup languages.<p>it's more _powerful_ than the others, including asciidoc.<p>it's also far more agile, and much easier to understand.<p>and i won't allow it to be fragmented, like markdown is.<p>i've coded converters in javascript and other languages.<p>the javascript minimizes well for inclusion in web-pages.<p>i have cross-plat apps, and a web-app converter with a.p.i.<p>output formats include .html, .epub, .mobi, .pdf, and more.<p>if there's anything i haven't thought of, do please tell me.<p>you can reach me at my e-mail address given in my profile.<p>-bowerbird