ReStructured Text?
It seems to me that if you do anything moderately interesting with ReST (anything outside of docstrings or just plain header/subheader/sub-subheader stuff in a separate file), it's no longer very readable at all as plain text. It's basically as noisy as things that aren't meant to be readable as plain text. And at that point, what's wrong with Docbook-XML or HTML, or hell, even LaTeX? These have very strong toolchain support.
Not to say that ReST doesn't have any toolchain support but I tried using rst-mode in Emacs this evening and with font-lock on I could type much faster than it could render and my CPU usage was at 100% as I did so. With font-lock off, it worked. But that's just no fun. I don't think I can't handle that long-term, and it'l be a cold day in hell before I switch to something to edit text with other than Emacs. I think I need some sort of syntax highlighting or I'll go mad, as ReST's input idioms are not obvious, especially when targeting things like Sphinx . I really like Sphinx's feature set and output options; I just wish the input format wasn't ReST. :-(
Do others have success stories using ReST + Emacs that I'm just missing here?
UPDATE: setting (setq rst-mode-lazy nil) in .emacs gives me some syntax highlighting without the insane speed hit. Much better.
yeah.
But the unrendered ReST at http://svn.repoze.org/repoze.who/trunk/README.txt doesn't seem much more readable to me than the unrendered Docbook-XML at http://svn.supervisord.org/supervisor_manual/trunk/chapters/introduction.xml . In Docbook-XML, documenting HTML is mostly just adding lots of CDATA sections, I imagine. It would be hard to document HTML in HTML, though, yup.
I still mostly document in non-restructured text, as much as folks say they hate it, it sure is pretty dang readable when unrendered. But the rendering toolchain really sucks for larger doc projects, thus, my investigations.
I don't get it either
reStructuredText crosses far, far over into markup-land, and occupies this strange space of not quite being as capable as HTML, but every bit as complex. Just look at the default link syntax, wow. Anyway, I'm sure it works well for programmers and other people that like learning new syntax and juggle a few of them in their heads, but it's an absolute disaster among "normal people", whereas Structured Text and Markdown both work pretty well for these people.
And reST's HTML output is exceptionally bad. No, really:
http://article.gmane.org/gmane.comp.web.zope.plone.documentation/1498
Ah, feels good to get that rant off my chest. Again. ;-)
PS: Of course, I'm of the opinion that basic XHTML should be a mandatory language for fourth-graders. It's the only universal markup language! :-)
Replies to this comment
Trac wiki syntax
I'd love to see a Trac wiki (MoinMoin) markup option in Plone :)
The linking in reST is pretty awful, but otherwise I don't really have any problems, nor does it seem that unreadable. Well, the distinction between single and double backquotes can be confusing, and double backquotes can get excessive.