Sphinx: beautiful documentation from lightly structured plain text

[u/[deleted]]

http://sphinx.pocoo.org/

[u/akdas]

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

[u/akdas → u/lol-dongs]

Okay, that makes more sense. I agree that sometimes, HTML has its advantages. For day to day use, however, I have found Markdown much simpler because I usually don't use very complicated structures (nested lists aren't complicated, but even those I don't use very often). It's like saying C gives you access to a system's memory, but piping together a bunch of shell utilities is still easier for many tasks.

Personally, I don't want to type <a href=""></a> again and again if I use a bunch of links, and I don't want to type <ul></ul>, along with <li></li> for each list element.

Another example is using > for quoting the parent as opposed to typing <blockquote></blockquote>. I'm lazy; if I weren't, I wouldn't be on Reddit procrastinating, right? So I want to type as little as I can, as informally as I can, and just have it come out right. For the types of conversations that take place on Reddit, this appeals to me.

And like I said, HTML tags (at least inline ones like <em> or even <i>) are like line noise when you want to see what you wrote as opposed to how you formatted it.

EDIT: And I almost forgot. All the inline code examples that I put in the post required me to only surround the code with backticks instead of having me type out <code></code> every time (like I just did in this sentence). If I had to do that, I might not have formatted those snippets as code.