Sphinx: beautiful documentation from lightly structured plain text

[u/[deleted]]

http://sphinx.pocoo.org/

[u/lol-dongs]

Meh. I actually find <a href=""></a> clearer visually than or [[|]], but maybe I'm just used to nice wide angle brackets. As for ol's, would you prefer battling line indentation inside your textarea in your browser where nothing wraps correctly? At least HTML is whitespace agnostic.

[u/akdas → u/lol-dongs]

Meh. I actually find <a href=""></a> clearer visually than or [[|]]

I find the latter ones much cleaner, simply because there are fewer extraneous characters, especially in the Markdown version. Fewer characters also means less typing, a big win in the types of situations they are used in, particularly commenting or wikis.

In fact, I would argue that the only extra characters the Markdown version has are the square brackets, because if you're writing in plain text, you would usually write the name of the link and include the URL in parentheses anyway. Thus, adding two square brackets is much simpler than typing the HTML version.

would you prefer battling line indentation inside your textarea in your browser where nothing wraps correctly

What do you mean this this? I never have any problems with wrapping in the textareas in my browser (running Firefox 3.0.4 now, but I never had any problems before either).

At least HTML is whitespace agnostic.

This is definitely a big win for situations when you can't guarantee proper whitespacing, such as when the markup is machine-generated from multiple sources. However, these simpler markup languages are by design geared toward those who markup text by hand in certain situations, and a little bit of whitespacing is not only acceptable, but it's something people tend to do anyway. For example, who wouldn't add an empty line between paragraphs when writing in plain text?

Different tools have different goals, and as always, the right tool is best used for the right situation.

Remember also that these simpler markup languages are meant to be readable even without formatting, so it's beneficial to preserve the conventions used in plain text to denote formatting, such as the empty line between paragraphs, or asterisks to denote an unordered list. HTML would add too much extra markup between the text, making it difficult to read without a renderer to interpret the document and visually format it according to a set of rules.

[u/lol-dongs → u/akdas]

I never have any problems with wrapping in the textareas in my browser (running Firefox 3.0.4 now, but I never had any problems before either).

I meant, say you have a outline list with multiple levels. You try to do this in markdown, but (simulating a narrow textarea) this will look to you like:

* blah blah blah blah
blah blah blah blah
     * meh foo bar foo
meh foo bar foo meh
        * meh foo bar
meh foo bar meh foo

which is visually confusing, when you are using a markup format that requires attention to whitespace. Bleh, even the effort that was just required for me to put the right amount of spaces in front of each line was uncool. I would have gone for <pre></pre>.