As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened,
visit the help center for guidance.
Closed 8 years ago.
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
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 <address@example.com> (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
You might also consider asciidoc
- 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
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.)
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...
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
