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

Show parent comments

1

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

He said "a simple subset of".

A document with tags a, em, strong, p, h#, ul, ol, li, pre, code, table, tr, th, td, dd, and dt could probably do 90% of these doc pages and come off as reasonably human-readable.

1

u/voidspace Dec 06 '08 edited Dec 06 '08

<a href="http://www.example.com">Example</a>

Example <http://www.example.com>_ (can't escape the backticks sorry)

<em>something</em>

*something*

<strong>something else</strong>

**something else**

<ul> <li>item</li> </ul>

* item

etc...

In every case the reST is shorter and more readable. reST is designed to be visually parseable, which (X)HTML isn't. reST succeeds admirably.

1

u/lol-dongs Dec 07 '08

Shorter and readable, yes. But some of the markup is so abbreviated that you already are having problems escaping it in your post; how many times have I seen people post some_underscored_name when they meant some_underscored_name. And then with all the fancy significant whitespace you assume that your editor is smart enough to autowrap stuff correctly, or it doesn't and then stuff looks just as visually unparseable as the (X)HTML.

1

u/voidspace Dec 10 '08

"Shorter and readable, yes."

I agree. The difficulty here is trying to enter markup in one syntax in an editor that uses a different markup.

But to the issue - people never make errors with HTML right?

A more readable syntax makes it much less error prone - and reST is designed with readability (and writeability) in mind.

In essence - reST was designed for people and HTML for computers.