This rant covers some acid tests I did on the various text markup languages. I wrote it while doing the acid tests in question. It may not be optimally polite, but I hope you find it amusing.
It turns out I hate all text markup formats, each for their own reason.
Markdown is the format that I'm using now; it's sort of the "default" format for ikiwiki. Don't be fooled; it still sucks.
I discovered Markdown's suckage first, and its suckage prompted me to examine other text formatting options. I was typing away at a todo list without rendering it, and lo and behold! When I looked at the results, they were not correctly nested.
The problem was that I tend to write my lists like this:
* a * b * c * d * e * f * g
But Markdown strips off a "layer" (defined as a tab, or four spaces) from each, so what it sees instead is:
* a * b * c * d * e * f * g
So what should be:
Instead looks like:
Useless. And by the time you've indented your text correctly, you're halfway across the screen!
I consider this broken-as-designed, but I recognize that Markdown can't just peek ahead to the next bullet point, or the next non-whitespace, to see how much to strip -- can it?
Textile I hate less, mostly because although it's ugly, at least it makes sense. Here's a nested list in textile:
* a ** b *** c **** d
Etc. OK, so it's impossible to read anything with all those asterisks, but at least it's a sensible system. Unfortunately you can't (as far as I can tell) extend list elements:
* a Try to continue, biatch!
fails to render a closing tag on either the list item or the list itself. Nice!
reStructured Text sucks too, but in many ways it sucks less than Markdown or Textile. Here's a nested list:
* a * b * c * d Blah..
In this example, "Blah" will be part of the same item as "d", but a different paragraph.
This isn't too bad. You don't have to indent too much. (In fact, reST matches indentation to the text on the last line, much like Python's indentation rules.) You have to insert blank lines to seperate items, which takes up too much vertical space, but it's kind of helpful, visually.
Here's my second acid test, how to handle preprocessed text:
:: * asterisks here have no meaning! * your power is gone, punctuation, muahaa * a * b
God, I'm getting sick of indenting large blocks of text. You can use emacs to increase indent on blocks of text. Emacs has an rst-mode, but it doesn't have any binding like this; as far as I can tell, rst-mode is merely a wrapper for text-mode.
reST also has a syntax for tables and for footnotes (Markdown has neither), but footnotes are (unpleasantly) pushed to the bottom of the page. Textile lets you put them whereever you want.
Turns out reST isn't optimally supported by ikiwiki at this time. Anyone want to look at prest and see what needs to be done to maintain it?