Pandoc Markdown and ReST Compared (2013)

#1

Post by hidden-markov » Sat, Mar 08, 2014, 11:44 AM UTC

Pandoc Markdown and ReST Compared (2013)
unexpected-vortices.com

Re: Pandoc Markdown and ReST Compared (2013)

#2

Post by egh » Sat, Mar 08, 2014, 1:34 PM UTC

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.

Re: Pandoc Markdown and ReST Compared (2013)

#3

Post by BruceM » Sat, Mar 08, 2014, 2:49 PM UTC

egh wrote: post #2

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 advocati…

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.

Re: Pandoc Markdown and ReST Compared (2013)

#4

Post by beagle3 » Sat, Mar 08, 2014, 2:59 PM UTC

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.

Re: Pandoc Markdown and ReST Compared (2013)

#5

Post by lambda » Sat, Mar 08, 2014, 3:40 PM UTC

beagle3 wrote: post #4

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/

Re: Pandoc Markdown and ReST Compared (2013)

#6

Post by specialist » Sat, Mar 08, 2014, 3:59 PM UTC

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.

Re: Pandoc Markdown and ReST Compared (2013)

#7

Post by teleclimber » Sat, Mar 08, 2014, 6:35 PM UTC

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

Re: Pandoc Markdown and ReST Compared (2013)

#8

Post by fprintf » Sat, Mar 08, 2014, 7:02 PM UTC

BruceM wrote: post #3

egh wrote: post #2

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 advocati…

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

Re: Pandoc Markdown and ReST Compared (2013)

#9

Post by biscarch » Sat, Mar 08, 2014, 7:13 PM UTC

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.

Re: Pandoc Markdown and ReST Compared (2013)

#10

Post by biscarch » Sat, Mar 08, 2014, 7:16 PM UTC

fprintf wrote: post #8

BruceM wrote: post #3

Earlier quoted context omitted.

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.| +------------+------------+-----------+ |…

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