ReSTful Sphinx
No, not the speech recognition software - even if it's nerdy enough that I'd write about it.
This one?
No, not the one at Giza, though it's pretty well rested, methinks. ReSTful Sphinx! I'll split it up for ya:
ReST
I'm a freshly graduated senior, I should be resting, right? Okay, I'll stop the puns.
ReST (or, more appropriately RST) stands for ReStructured Text: a markup method for (especially) documentation files. It's restructured because the Structured Text standard apparently had gaping holes in it that caused many use cases to break, and even more to be very awkward to program.
Remember when you first learned what XML was? How it's basically just start tags and end tags and attributes and stuff in between? ReST is easier than that. Look:
My Research Paper ================= Procedure --------- The quick brown fox jumped over the lazy dog. All work and no play makes Jack a dull boy. `Quidquid Latine dictum sit altum viditur.` ~ Oscar Wilde Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce lobortis blandit risus lacinia dignissim. Quisque eros justo, sodales eget convallis sit amet, blandit quis sem. Vestibulum gravida convallis eleifend. Sed eu lectus augue, eget posuere tellus. Quisque mattis felis sed mauris vehicula at tempor odio sagittis. Pellentesque odio ligula, euismod in mattis eget, luctus at tellus. Quisque porttitor, nisi eget ultricies ornare, lectus leo vestibulum urna, eget iaculis purus mi sed felis: 1. Light Emitting Diode #. Czechoslovakia #. Manbearpig #. ... #. Profit! Results ------- ...
Aside from some weirdness like the carets, it's plaintext formatting! It's much better than using <p>, <blockquote>, <ol>, and <li>, right? It gets better, when...
Sphinx
... comes in to the picture. Sphinx takes ReST and turns it into pretty HTML, PDF, LaTeX, etc. that the century we live in actually wants. It can turn ReST files into a manual complete with an auto-generated table of contents, glossary, and index. It can figure out all the formatting needed, render LaTeX mathematic expressions into PNGs, and, with a bit of tinkering, can be subjected to any number of page templates written by your own hand.
But, since I'm sadly still just a beginner, I'll just give you a sample of what it does. As a preview, I will show you a snippet of Jeff Elkner 's Python Book (note from Jeff: "modern browser required." Translation: "IE doesn't work here"). The Sphinx version of it has not been released yet, and he did not authorize me to show you this, but his book is open source, so...
Image under Creative Commons Attribution-Noncommercial-Share-Alike License
... sucks for him! Anyway: this is the ReSTful source code this is the page it compiles into. The links are broken because I didn't include his entire book.
Now, some food for thought. ReST is much much easier for people not talented at computers to work with: it's basically plain text! What can be done with this piece of info? Online books? Easier blogging without technology knowledge requirement (and would that be a plus)? Should I rewrite my blog engine to use ReST and Sphinx for rendering? Or, is word processing so advanced that people would much rather use it than just type files that then take a million shortcuts to be flexible and generate stuff so you don't have to? And, a question that came up earlier today: would a solution like this put some grunt-work typists out of jobs?
