5 ms·
I've had the markdown vs rst discussion with a few people a few times and the pro-markdown people always cite this, saying rst is much harder to use or the core
by corndoge 7y ago
I've had the markdown vs rst discussion with a few people a few times and the pro-markdown people always cite this, saying rst is much harder to use or the core syntax is awkward in comparison. I don't really understand this, the same markup you get from markdown has about the same surface area in terms of syntax in rst. `code` vs ``code``, or just an indented block (in rst just add :: before the block start), emph is still emph, you can still use = and - for headers, bullet lists are the same as markdown, and so on. Inline hyperlinks are about the only thing that aren't visually nice like they are in markdown, (text)[link] vs <text `link`>_ or w/e it is (I use sphinx refs so I don't recall exactly). Actually in a way rst is better for links since the common thing in markdown is to reference links like this[0], in RST with _ instead that actually works and this becomes a hyperlink. Like the basic features are mostly identical. But then when you start needing features for big documents like cross references, highlighted syntax blocks, images, ToC, figures, etc it RST has all that built in and you don't have to reach for some markdown superset (although I guess you could argue Sphinx is that for RST). I dunno, I've done both and I just have a much better time with RST once the project size gets past a single doc.
I still use md for READMEs and gists and whatnot, I guess my point is, different tools for different jobs, if you have to pull weeds in your garden use a spade, if you have to do it for a field use a machine, or something.
- oefrha 7y agoPlease enlighten me on how to produce [`code`](https://example.com https://example.com) in reST. Hint: This is rhetorical. https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible https://docutils.sourceforge.io/FAQ.html#is-nested-inline-ma...
- corndoge 7y agoI saw your other comment as well. I don't know what to say, you're correct, RST is deficient here.
- JoBrad 7y agoIs there a syntactical reason this method couldn’t be supported in rST?
- oefrha 7y agoNo. Quote FAQ: > Not currently, no. It's on the to-do list (details here), and hopefully will be part of the reStructuredText parser soon. At that time, markup like this will become possible: Here is some *emphasized text containing a `hyperlink`_ and ``inline literals``*. So absolutely valid syntax just doesn’t work. Aaaand that todo list entry dates back to 2001. (I know, I know, instead of complaining I should submit a fucking patch. Unfortunately fixing reST is one of the least urgent things on my should-submit-a-patch list.)
- benhurmarcel 7y ago> you can still use = and - for headers You can't make section headers with ##, no? More importantly in RST you can't easily manage several levels of headings. You're limited to 2 or 3, and have to remember which underline character you used for that level.
- njharman 7y agoI countb at least 5, from memory. = - ^ ~
- WorldMaker 7y agoIn rST there are three choices of "line-style": underline, overline, both under and overline. Then there's dozens of possible symbols ("printing nonalphanumeric 7-bit ASCII character"), and the documentation/primer narrows that to a suggested interesting looking 14 options of ASCII symbols. That's a total of 42 suggested options for heading levels, and not even the "limit". There remains the practical limit that Markdown also inherits that HTML only has 6 levels. There's not a suggested or standard order, so yes there's some mental overhead in deciding which header styles you want to be which level, but a lot of projects tend to have a "lint" guide for that at this point. For instance a lot of projects (and Sphinx recommends) follow the Python Style Guide: # with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections ", for paragraphs (You may be confusing Markdown's/CommonMark's own less popular Setext-style headers which only support underline and = for first level and - for second level header.)