4 ms·

Pandoc can also process reStructuredText [1], which looks similar to Markdown, but has more features and a single non-ambiguous specification. Me and my co-auth

Pandoc can also process reStructuredText [1], which looks similar to Markdown, but has more features and a single non-ambiguous specification. Me and my co-author rejected Markdown for our book about internet memes [2][3] after a short evaluation, mainly due to ambiguities [4] and lack of features. [1] https://en.wikipedia.org/wiki/ReStructuredText https://en.wikipedia.org/wiki/ReStructuredText [2] The book can be downloaded for free: http://internetmeme.de http://internetmeme.de [3] About the writing process: https://news.ycombinator.com/item?id=12311546 https://news.ycombinator.com/item?id=12311546 [4] http://roopc.net/posts/2014/eval-stmd/ http://roopc.net/posts/2014/eval-stmd/

talideon 10y ago
I know. Personally, I prefer reST, but Markdown is more approachable than reST for a lot of people. I wouldn't say reST is all that similar looking to Markdown though: they have very different philosophies, and really only coincide on the fact that they're used for marking up plaintext documents.
- erlehmann_ 10y ago
  What do you mean with “more approachable” ? Markdown surely is more popular – but which constructs differ much in usability?
  - talideon 10y ago
    Off the top of my head, the complaints I've gotten have referred to directives, the link syntax, roles, not being able to nest inline markup. None of this bothers me, and directives and roles the source of much of reST's extensibility and power, but apparently those are the things that make reST a bit intimidating compared to the likes of Markdown.
    - erlehmann_ 10y ago
      Please elaborate on the complaints. What about the directives do users consider problematic?
      - talideon 10y ago
        The two nicest things about directives once you get the point behind them are that they're consistent and flexible: once you know the syntax for one directive, you know most of the syntax for the rest. The problem with that is that the syntax is comparatively heavyweight. Part of this is due to reST's alignment rules and partly down to the generality of directives. Let's take 'image' as an example. The simple way to embed an image in reST is this: .. image:: foo.png And in Markdown: ![](foo.png) And with some alt text: .. image:: foo.png :alt: Foo! And in Markdown: ![Foo!](foo.png) I've had people struggle with image directives simply because it doesn't sink in that the `:alt:` attribute has to be aligned with the directive name, whereas the rough equivalent in Markdown has no such issues. OTOH, once you know how to embed an image in reST, you're 90% of the way to knowing how to embed a code block, whereas in Markdown you need to learn a little bit more syntax. The downside of that is that this: .. code:: print("Hello, world!") Is more heavyweight than: `` print("Hello, world!") `` And people prefer the latter as it's less to type to the former, even if the former introduces no special-purpose syntax. This is where Markdown's ad hoc nature has benefits over reST's more structured nature: if you want to embed an image in Markdown, you learn how to embed an image; in reST, you learn the directive syntax so you can embed images. That gives Markdown and reST different learning curves. Markdown gives you lots of little easy-to-learn tools, but requires that you be constantly learning new tools as you go along, whereas reST gives you fewer, slightly more complex tools you have to learn up front, and all the new stuff you learn later is based off of those. Moreover, Markdown has less impact on the text due to its ad hoc markup being more compact, unlike reST, which takes the route of being more general at the cost of being more verbose. Somebody starting out confronted with either reST or Markdown will look at both and see that the latter looks more like plain text than the former, and thus there is less of an initial barrier to entry. That's why the likes of MkDocs exist in spite of the likes of Sphinx existing long before MkDocs and its ilk did. TL;DR: Markdown makes easy stuff super easy and hard stuff possible; reST makes the easy stuff a little harder than Markdown, but lets you lift mountains. Edit: s/codeblock/code/
sevensor 10y ago
I always like to go back to the figure from the pandoc homepage showing input and output formats. I think it gets taller every time I look at it: http://pandoc.org http://pandoc.org (scroll down past the text). Personally, I like that Markdown gives me so little control over formatting. It forces me to focus on the text instead, which is why I moved away from LaTeX. Formatting is something I'd rather do after the writing is done. If you're using LaTeX or HTML, you can embed formatting directly, and if you're using another intermediate format, Pandoc gives you a lot of control over how it's generated.

talideon 10y ago

I know. Personally, I prefer reST, but Markdown is more approachable than reST for a lot of people. I wouldn't say reST is all that similar looking to Markdown though: they have very different philosophies, and really only coincide on the fact that they're used for marking up plaintext documents.

erlehmann_ 10y ago
What do you mean with “more approachable” ? Markdown surely is more popular – but which constructs differ much in usability?
- talideon 10y ago
  Off the top of my head, the complaints I've gotten have referred to directives, the link syntax, roles, not being able to nest inline markup. None of this bothers me, and directives and roles the source of much of reST's extensibility and power, but apparently those are the things that make reST a bit intimidating compared to the likes of Markdown.
  - erlehmann_ 10y ago
    Please elaborate on the complaints. What about the directives do users consider problematic?
    - talideon 10y ago
      The two nicest things about directives once you get the point behind them are that they're consistent and flexible: once you know the syntax for one directive, you know most of the syntax for the rest. The problem with that is that the syntax is comparatively heavyweight. Part of this is due to reST's alignment rules and partly down to the generality of directives. Let's take 'image' as an example. The simple way to embed an image in reST is this: .. image:: foo.png And in Markdown: ![](foo.png) And with some alt text: .. image:: foo.png :alt: Foo! And in Markdown: ![Foo!](foo.png) I've had people struggle with image directives simply because it doesn't sink in that the `:alt:` attribute has to be aligned with the directive name, whereas the rough equivalent in Markdown has no such issues. OTOH, once you know how to embed an image in reST, you're 90% of the way to knowing how to embed a code block, whereas in Markdown you need to learn a little bit more syntax. The downside of that is that this: .. code:: print("Hello, world!") Is more heavyweight than: `` print("Hello, world!") `` And people prefer the latter as it's less to type to the former, even if the former introduces no special-purpose syntax. This is where Markdown's ad hoc nature has benefits over reST's more structured nature: if you want to embed an image in Markdown, you learn how to embed an image; in reST, you learn the directive syntax so you can embed images. That gives Markdown and reST different learning curves. Markdown gives you lots of little easy-to-learn tools, but requires that you be constantly learning new tools as you go along, whereas reST gives you fewer, slightly more complex tools you have to learn up front, and all the new stuff you learn later is based off of those. Moreover, Markdown has less impact on the text due to its ad hoc markup being more compact, unlike reST, which takes the route of being more general at the cost of being more verbose. Somebody starting out confronted with either reST or Markdown will look at both and see that the latter looks more like plain text than the former, and thus there is less of an initial barrier to entry. That's why the likes of MkDocs exist in spite of the likes of Sphinx existing long before MkDocs and its ilk did. TL;DR: Markdown makes easy stuff super easy and hard stuff possible; reST makes the easy stuff a little harder than Markdown, but lets you lift mountains. Edit: s/codeblock/code/

sevensor 10y ago

I always like to go back to the figure from the pandoc homepage showing input and output formats. I think it gets taller every time I look at it: http://pandoc.org http://pandoc.org (scroll down past the text). Personally, I like that Markdown gives me so little control over formatting. It forces me to focus on the text instead, which is why I moved away from LaTeX. Formatting is something I'd rather do after the writing is done. If you're using LaTeX or HTML, you can embed formatting directly, and if you're using another intermediate format, Pandoc gives you a lot of control over how it's generated.