Compare and contrast the lightweight markup languages

Documentation Markdown Markup Restructuredtext Textile

Documentation Problem Overview

Please identify the most popular lightweight markup languages and compare their strengths and weaknesses. These languages should be general-purpose markup for technical prose, such as for documentation (for example, Haml doesn't count).

Documentation Solutions

Solution 1 - Documentation

I know of three main languages used commonly in the greater programming and tech community: Textile, Markdown, and reStructuredText. All three can be learned in a couple of hours or "winged" with the cheat sheet nearby.

Textile

Used by Redmine and the Ruby community
113 questions currently tagged on Stack Overflow
The most similar to HTML, but least readable source
Easiest nested lists of all three languages
Not understandable to non-programmers or the HTML-ignorant
Ideal for complex short documents (with links, nested lists, code, custom HTML); for example: short documentation, how-tos, blog or CMS content
Syntax reference

Markdown

Doesn't seem to have a home language "community" but...
1274 questions tagged on Stack Overflow*
Emphasizes source code readability, similar to email traditions
Straightforward HTML embedding (you just type the tags out)
No way to make tables besides embedding HTML
You know it already if you know Stack Overflow
Easy to learn if you already know reStructuredText
Automatic email address obfuscation for the format <[email protected]> (with angle brackets)
Syntax reference

reStructuredText (A.K.A. ReST)

Popular in the Python community
285 questions tagged on Stack Overflow
A bit persnickety about whitespace and alignment if you ask me
Lists (especially nested lists) and paragraphs always seem to get in fights
Readable by non-programmers
Only format which can build a table of contents (via an extension in the Python reference implementation)
Directly converts to other formats like PDF and XML
Ideal for large documents with lots of prose (e.g. an alternative to docbook for a user manual)
Syntax reference

Solution 2 - Documentation

You might also consider http://www.methods.co.nz/asciidoc/">asciidoc</a>

relatively readable markup
straightforward command-line use
some might perceive it as relatively 'picky' (vs. flexible) with respect to syntax
docbook and (x)html output

Solution 3 - Documentation

The Wikipedia page on lightweight markup languages has a good comparison between the various options, as well as showing syntax for common uses (headings, bold, italics, etc.)

Solution 4 - Documentation

I am attempting to cover all the various lightweight markup languages here:

http://www.subspacefield.org/~travis/static_blog_generators.html

As you can see, it started with "how can I make a secure blog" - i.e. one that generates static HTML, and I found myself ensnared in markup languages, templating systems, etc.

Update

I refocused only on LWMLs with python implementations, and theyre here:

http://www.subspacefield.org/~travis/python_lightweight_markup_languages.html

So far I've tried markdown and ReST, and I like the latter better for anything but HTML snippets embedded in other pages. Tables, cross refs, indirect links, etc...

Solution 5 - Documentation

for documentation? how about doxygen?
I've use it for some of c/c++ project that I need to documentize. Even you can 'abuse' it just like doxygen author uses for doxygen documentation

Content Type	Original Author	Original Content on Stackoverflow
Question	JasonSmith	View Question on Stackoverflow
Solution 1 - Documentation	JasonSmith	View Answer on Stackoverflow
Solution 2 - Documentation	dat	View Answer on Stackoverflow
Solution 3 - Documentation	technomalogical	View Answer on Stackoverflow
Solution 4 - Documentation	Travis H.	View Answer on Stackoverflow
Solution 5 - Documentation	mhd	View Answer on Stackoverflow