4 ms·

A big difference between ReST and Markdown is that it's very easy to accidentally write ReST that is either invalid or doesn't mean what you think it means. The

A big difference between ReST and Markdown is that it's very easy to accidentally write ReST that is either invalid or doesn't mean what you think it means. The Julia manual used to be written in ReST and even people (or maybe especially people) who were pretty deep down the ReST features rabbithole, regularly committed ReST that was just wrong – quotes where code was intended; incorrect hyperlinks (why is the hyperlink format in ReST so damned complicated and non-uniform – it's basically impossible to remember); bullets or lists that aren't actually bullets or lists. This is possible in Markdown, but it's much harder: by design, things almost always mean what they look like they mean. That's a huge benefit. The Julia docs are now in Markdown and accidentally broken markup is hardly ever a problem anymore.

prodigal_erik 10y ago
This. Markdown is good for non-technical people who struggle with a real markup language, but reStructuredText is so fiddly that I can't figure out who's better off using it over DocBook, or HTML, or LaTeX, or even nroff. This is `a footnote`_? Seriously? .. _a footnote: http://example.com/
1wd 10y ago
I agree that ReST is needlessly complicated. But Markdown isn't really that much better. Maybe it's because I'm more used to Wikipedia-style link syntax. As for bullets: Since some Markdown implementations annoyingly insist on four spaces, while others work fine without that, I'd say it's about even. But these are all minor annoying details of either. The win of ReST is standardized extensions for anything. The win of Markdown is there's half an implementation running anywhere.
jrk 10y ago
Related: my immediate thought was that this totally ignores basic aesthetics and readability. This is partly a matter of taste, but to say that the only virtue of Markdown is popularity ignores why Markdown became so popular, when ReST, Textile, and others were varyingly widespread in all of Markdown's current niches before Markdown existed. Markdown was designed above all to be pleasant to write and read in the common case of relatively simple structure and markup, and it mostly succeeds. This is a huge advantage in practice.
kevin_thibedeau 10y ago
And yet markdown has no standard way to add captions to images. The internal docutils DOM is almost trivially mappable to a large subset of Docbook which can be done with rst2xml and some XSLT. Markdown is basically designed to map into older versions of HTML and has no hope of ever having such semantic expressiveness due to its fractured ecosystem.

prodigal_erik 10y ago

This. Markdown is good for non-technical people who struggle with a real markup language, but reStructuredText is so fiddly that I can't figure out who's better off using it over DocBook, or HTML, or LaTeX, or even nroff. This is `a footnote`_? Seriously? .. _a footnote: http://example.com/

1wd 10y ago

I agree that ReST is needlessly complicated. But Markdown isn't really that much better. Maybe it's because I'm more used to Wikipedia-style link syntax. As for bullets: Since some Markdown implementations annoyingly insist on four spaces, while others work fine without that, I'd say it's about even. But these are all minor annoying details of either. The win of ReST is standardized extensions for anything. The win of Markdown is there's half an implementation running anywhere.

jrk 10y ago

Related: my immediate thought was that this totally ignores basic aesthetics and readability. This is partly a matter of taste, but to say that the only virtue of Markdown is popularity ignores why Markdown became so popular, when ReST, Textile, and others were varyingly widespread in all of Markdown's current niches before Markdown existed. Markdown was designed above all to be pleasant to write and read in the common case of relatively simple structure and markup, and it mostly succeeds. This is a huge advantage in practice.

kevin_thibedeau 10y ago

And yet markdown has no standard way to add captions to images. The internal docutils DOM is almost trivially mappable to a large subset of Docbook which can be done with rst2xml and some XSLT. Markdown is basically designed to map into older versions of HTML and has no hope of ever having such semantic expressiveness due to its fractured ecosystem.