On: ReStructuredText vs. Markdown for documentation

[1wd]

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.

[slgeorge → 1wd]

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!