Comment by 1wd | Hacker News Reader

Comment by 1wd | Hacker News Reader

Parent Full thread

RST has some great ideas (as mentioned in the article, roles and directives are fantastic ideas). But it also has quite a lot of unnecessary complexity built in. It's also great that it (kind of) has a specification, not just a bunch of hand waving. But even with the specification there seems to be no independent re-implementation, so I wonder if the specification is really complete. It also makes some syntax choices that just make no sense at all to me. Making the most basic and important feature (bullet lists, titles) annoying to use was not a smart move.

The (only) good thing about Markdown is it's (allegedly) simple. IMO it's on the one hand not simple enough (e.g. HTML has got to go) and on the other hand it's too simplistic.

Ideally I would like to have a tiny core specification with a clean and simple standardized mechanism for extensions like roles and directives. With a bunch of standardized but optional extensions. Only the most important features (90% of usage) should get special syntax (bold, bullet lists, titles, roles, directives). For everything else (90% of features) there should be a named role or directive.

Trac actually uses a similar system. linkExtensionName:content, [[extensionName(content)]] or {{{#!extensionName multiline-content }}} is all you need to remember. Could be simplified a bit, but it's quite usable.

This has also been my experience of RST: it adds a huge headache of complexity. I've also found its documentation and tooling to be very poor. Tastes may vary, but my experience was that almost every feature ended up with an obtuse name that needed a tremendous amount of searching for, the docs had inexplicable & glaring lacunae, and that the error messages that the tools omitted were infuriatingly unhelpful. Writing RST was an exercise in pain for my team. For the problem domain it was built for, Markdown works, works well, and works with few enough moving parts that you can actually figure out where your errors are, should you drop any in. This is very much not true of RST: the tools hate you with a seething, brooding hatred that will make you waste an hour trying to track down the one line in file X that's making the compiler emit a cryptic error about file Y. RST has some good ideas, but as far as I can tell, no-one involved with it takes usability seriously at all, which in turn means that they produce software artifacts that express a shrieking, gleefully sadistic hatred for the user.

I've used a lot of RST and from my experience the specification is very accurate. If there is some inconsistency, it should probably be considered as a bug and reported to Python docutils. What exactly is the problem with bullet lists? AFAICS they are pretty much the same in Markdown and RST.

In RST you must have a blank line between parent bullet and child bullet. This really discourages adding small child bullets.

In RST you must indent child bullets exactly to the indentation level where the text starts in the parent bullet.

a. In RST you must have a blank line between parent bullet and child bullet. I don't think that's correct, this works:

# Remove the spaces at the start to put in a file (HN rendering)

  * Bullet 1
      * Sub-bullet 2
  * Bullet 2

# Both worked fine:

  $ rst2html --verbose test.rst test.html
  $ pandoc --output test.html test.rst

b. In RST you must indent child bullets exactly to the indentation level where the text starts in the parent bullet.

Also untrue as far as I can see. Vim does do automatic indents for me so they have to be consistent AFAIK, but not to the `exact` same level as where the text starts in the parent bullet.

a. That's not a child bullet, it's a paragraph continuation. This exactly demonstrates the problem with RST.

Check the specification: http://docutils.sourceforge.net/docs/ref/rst/restructuredtex... See "examples of incorrectly formatted bullet lists", or http://docutils.sourceforge.net/docs/dev/rst/problems.html#b... or http://docutils.sourceforge.net/FAQ.html#could-the-requireme... It's a well known problem.

b. Check the spec. It must be exactly aligned. If it's not exact it's not a child list. It's just an independent list with random indentation.

See e.g. http://stackoverflow.com/questions/5550089/how-to-create-a-n...

oh wow, didn't know that. Arg! all my personal notes have list that will have to be re-formatted that!

Reply on news.ycombinator.com