On: ReStructuredText vs. Markdown for documentation

[slgeorge]

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.

[1wd → slgeorge]

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

[slgeorge → 1wd]

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