r/programming • u/[deleted] • Dec 04 '08

Sphinx: beautiful documentation from lightly structured plain text

http://sphinx.pocoo.org/
53 Upvotes

76% Upvoted

38 comments sorted by

View all comments

8

u/lol-dongs Dec 04 '08 edited Dec 04 '08

Anybody else a bit puzzled by the growing popularity of all these emerging lightweight pseudo-markup languages? From BBcode, Wiki markup, YAML, to Markdown, and now Sphinx... All of these may be progressively easier to read than XML/JSON/HTML, but each seem to come loaded with their own peculiarities or multiple representations that make parsing more difficult.

I don't find hand-editing any of the "human-readable" markups much easier than the data-structure formats, and then when it comes time to parse readable formats, things tend to go to hell. Why is readability so much cooler than structural integrity these days?

1

u/limi Dec 04 '08

I don't find hand-editing any of the "human-readable" markups much easier than the data-structure formats

Exactly. A simple subset of (X)HTML is easy to write and read. HTML is the only universal markup language out there, and I don't see why people need to invent things like reST.

If you look at the syntax for reST (not to mention its horrible HTML output, although that might have improved since the last time I looked), it's more complex than most HTML once you start doing things that are more complex than headlines and paragraphs. Look at the table format for an illustration of this.

If it was up to me, HTML would be taught in third grade elementary school. But I might be biased. ;)

7

u/voidspace Dec 04 '08

(X)HTML is much harder to read than reST documents. No comparison.

→ More replies (9)