Compare and contrast the lightweight markup languages [closed]

Question

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

See also: Markdown versus ReStructuredText

Oralle

See also superuser.com/questions/209897/text-formatter-tools/… – Kalif

Answer 1

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

Oralle

For users of ReST, sphinx.pocoo.org looks like a very nice tool for large tree-structured collections of reference documentation. – Autocrat

I don't have any problem with lists and paragraphs in reStructuredText when I hard-wrap things in Emacs. In fact, they function exactly like I would expect them to :-) – Chicago

There are extensions to Markdown that allow composing tables in ASCII. – Stidham

ReST has excellent tool support too: E.g. the browser based notex.ch is a good tool the experiment with, learn and use ReST (based on the sphinx.pocoo.org backend). – Bleed

Answer 2

You might also consider asciidoc:

• relatively readable markup
• support for a wide variety of document elements (e.g., bibliography, footnotes, . . .)
• some might perceive it as relatively 'picky' (vs. flexible) with respect to syntax

asciidoctor supports output to:

• DocBook
• HTML
• man pages
• PDF
• EPUB

The Awesome AsciiDoc page provides a nice list of associated resources.

Upbeat

Unfortunately asciidoc has a horrible syntax for list items with multiple paragraphs: You have to separate them with a single line containing only a plus-sign (yes, a "+"). – Chicago

@Martin: Are multi-paragraph list items really that important? If you need more than one paragraph, wouldn't headings/sections be more appropriate than a list? – Thetic

The biggest advantage of AsciiDoc is that it supports much more features. It can create books, have tip sections, many outputs... powerman.name/doc/asciidoc – Garboil

Answer 3

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

Braid

Answer 4

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

Dashiell

Answer 5

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

Jensen