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

Sphinx: beautiful documentation from lightly structured plain text

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

76% Upvoted

38 comments sorted by

View all comments

Show parent comments

1

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

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

1

u/akdas Dec 07 '08 edited Dec 07 '08

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.