Pandoc Markdown and ReST Compared (2013) | Hacker News Reader

Pandoc Markdown and ReST Compared (2013)

unexpected-vortices.com

43 pointshidden-markov26 comments

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:

.. extension:: hello world

In markdown, on the other hand, you have multiple, incompatible versions which have entirely different syntax because there is no generic extension mechanism.

ReST feels more well thought-out, generally.

That said, I've pretty much given up advocating it, because markdown seems to have won and has so much more tool support.

I like ReST as well. With Sphinx, it is great for producing documentation. A project that I work with has converted hundreds of pages of books of technical documentation over to Sphinx and a custom Sphinx extension.

I like ReST as well.

It's more powerful and looks much cleaner

// e.g. how do you write footnotes in markdown? And how do you do this in markdown?

  +------------+------------+-----------+
  | Header 1   | Header 2   | Header 3  |
  +============+============+===========+
  | body row 1 | column 2   | column 3  |
  +------------+------------+-----------+
  | body row 2 | Cells may span columns.|
  +------------+------------+-----------+
  | body row 3 | Cells may  | - Cells   |
  +------------+ span rows. | - contain |
  | body row 4 |            | - blocks. |
  +------------+------------+-----------+

in pandoc-markdown a footnote[^1] would be written like this.

[^1]: My footnote here

Here's a link to pandoc's markdown flavor, which includes tables: http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markd...

Since basic Markdown is so basic, multiple incompatible flavours of Markdown have cropped up, including Pandoc-Markdown, which can do footnotes.

> ReST feels more well thought-out, generally.

It's certainly set up for extensibility, although some areas are a pain (e.g. blank lines may be ignored entirely, change vertical spacing or change semantics, that can be annoying).

The toolchain is also fairly complex and very badly documented (Sphinx itself is better documented than docutils, but either way you end up wading through piles of code to understand what happens, why, and what's available in the applicative context of your extension)

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.

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:

    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

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?

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.

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]

Now it's 2014 and we're loving building tables by hand-crafting ASCII art.

Am I the only who thinks we can do better?

[1] http://www.theoligarch.com/microsoft_vs_apple_history.htm

The big gain is that is all just text and can be handled very well by the same version control system as the code is.

I can easily glance at what has happened to the docs just by looking at a diff, much like I do with all code my team produces already.

And being represented by all text doesn't mean this is what you give your customers. With a bit of work with pandoc etc. you can get a really slick and impressive end result.

Most the tools we have for WYSIWYG document creation lacks determinism and portability. For the latter, one could argue that there are open formats, but still, there should be a program that can interpret the format; whereas with plain text, such a need is void, as it is possible to view the document on any decent system. For the former, the argument might be that the modern word processors provide the facilities to deterministically lay out a document through the user interfaces they sport, but then because the formats they save are either are endemic to themselves or badly supported in other software* this feature is not of much use.

I can open a Markdown/ReST/Textile/... file with any text editor, including Notepad, Vim, Emacs etc., and also view it through more or less programs, or just cat them. I can pass them through head or tail; search them with common utilities and even edit them with some others. I am not bound to any programs in order to edit my program. If, on a computer I have to use, there is no Word, or Writer or Pages, I can still edit/read the document. I can read it online, via a browser. I can use programs that are decades old, and I also will be able to read the file decades later. When I send the file to someone else, I can be sure that they will be able to read it. Any usable operating system has a text editor bundled. This level of portability is just a dream for WYSIWYG editors. For these advantaged, I happily trade editing convenience off.

* Last summer, my cousins needed to use my computer for editing a docx document that was important for their undergraduate education. I was running Ubuntu OS at the time, so I told them to use the LibreOffice's word processor. The experience was bad; the document did not render properly, editing was problematic. This is the only case I can provide as an example to support my argument, as it has been multiple years since I used a word processor program.

I agree with what you said. I understand the advantages of markdown and why it is adopted (particularly in dev environments).

But you seem to agree with me that the markdown editing experience leaves a little to be desired ("...I happily trade editing convenience off").

What I don't get is why that editing experience doesn't annoy people more. There are tons of markdown-powered blogging platforms, editors, commenting forms coming out every day, but you almost never see projects that try to solve the original problem.

Desirability of the editing experience is a function of the kind of editing one does: I mostly write text-heavy stuff, blog posts, README's and similar stuff. For these stuff, I am quite happy with markdown, vim and the general workflow of mine around these tools; and I like that workflow. I do not need a piece of text to be red, or be centred, or wrapped around an image. Still, me and alike are the minority; normal people want these kinds of stuff.

For instance, I've deployed (!) a couple WordPress blogs and a PhpBB forum for a friend (yes, I'd touch none of these for my projects). When it was time to test-post in the forum, I started explaining him the markup for PhpBB. His reaction was this: "But in vBulletin, there is a text editor. I think I'll pay them $400 for that." He wants to centre the text, and emphasise phrases via colouring them red. Because he can. He is a normal person.

While I like my workflow, with markdown, vim, and a static site generator; I do not find markdown and alike useful for any major inscription, e.g. papers and books and alike. I'd rather use a suitable tool that takes away the burden of manually writing the markup, and allow me to focus on content for such work. iA Writer makes me horny, but unfortunately I do not own a Mac. I admit that I'd go nuts should I need to write a book in, say, LaTeX (or however it is spelled). Yet, the problem of portability of files is a superior problem than lack of convenience while editing. If I write my book with iA, and if it goes next year, what'll I do?

Thank-you for the thoughtful response.

Yes, clearly the markdown thing is natural for developers. After all devs spend all their time in cryptic text files that get transformed into something more useful and beautiful That's their (our) thing.

And since developers are the ones who create forum software, blogging platforms, one can only expect that their personal preferences would bleed over into these projects.

But it's unfortunate because in the meantime we're not really advancing the art of editing content, which is something the "normals" would appreciate. (And I think even a number of developer-types would appreciate writing content without markdown if you gave them something that actually worked and worked with static site generators.)

Regarding IA, I don't have it but it says that it saves files as plain text?

let me try again.

if you have _specifics_ on "the art of editing content", and the interface you want, i would like to hear them...

-bowerbird

my intention is to solve the problems, all of them.

so i would appreciate a thoughtful write-up of them. i know many of them, probably most. but i'm curious.

my target is writers, not programmers, but my intent is to create the best possible tool for those writers. not just a "suitable" tool -- the _best_one_possible_.

-bowerbird

Those ReST examples reminds me of the ASCII docs I'd write for my shareware software. Fairly typical for the time.

Not so different from the IEFT Document Conventions. http://www.rfc-editor.org/rfc/rfc3.txt

Or the RFC guidelines. https://www.rfc-editor.org/rfc-style-guide/rfc-style

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.

Now I realize choosing markdown was rather arbitrary (personal preference, familiarity). Any document structure would suffice.

Nice comparison, thanks.

Markdown has always looked limited and incomplete to me.

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.

Note that this article compares Pandoc Markdown to ReST; Pandoc adds a lot of features that vanilla Markdown lacks.

Of course, this is one of the big problems with Markdown; there are a bunch of different implementations, each of which adds its own extensions. Actually, if you take a look at the Pandoc homepage, you'll see that it implements 5 different Markdown flavors: http://johnmacfarlane.net/pandoc/

"Incomplete" depends on the application. Markdown is intentionally a small and simple language, so it's fine for e.g. comments, but too limited for e.g. a full documentation.

(and as a result, it's tended up to spring numerous incompatible extensions e.g. TFA talks about Pandoc Markdown which adds tables, footnotes and a bunch of other stuff, not "Original" Markdown).

> somehow my AsciiDoc documents turn out looking better

Maybe it's just the default style of the Asciidoc HTML renderer, something like that?

For me Markdown wins just because I'm used to dealing with it daily on GitHub.

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.

" I have never understood the fetish behind Markdown"

For one, there are multiple (and good) implementations of Markdown in Javascript, so it's trivial to embed Markdown in web pages and do all the processing client-side -> faster and better user experience + much lower server load.

Pandoc a) only runs locally/server-side and b) requires a 200 MB Haskell install before it will work.

Always wondered how Pandoc MD, ReST compare when my document type is slightly more complex, for example: a question and answer session?

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".

it's "lighter" than all the other light-markup languages.

it's more _powerful_ than the others, including asciidoc.

it's also far more agile, and much easier to understand.

and i won't allow it to be fragmented, like markdown is.

i've coded converters in javascript and other languages.

the javascript minimizes well for inclusion in web-pages.

i have cross-plat apps, and a web-app converter with a.p.i.

output formats include .html, .epub, .mobi, .pdf, and more.

if there's anything i haven't thought of, do please tell me.

you can reach me at my e-mail address given in my profile.

-bowerbird

I Looked at the site for z.m.l (http://www.z-m-l.com/). It doesn't seem to do math, so it's a nonstarter.

BTW, Pandoc (which does do LaTeX math) really needs no improvement, only more widespread implementation (e.g., an online site, and/or a chrome extension coded in javascript.) I suppose its being written in Haskell has been an impediment.

Reply on news.ycombinator.com