Generously funded by Matt Dorn

The Pleasure of the (reStructured) Text

without comments

Every item that you read on this site was composed not by tediously applying HTML angle brackets to delineate the paragraphs appropriately or create hyperlinks, nor by selecting elements and clicking icons using a "WYSIWYG" editor that may or may not generate valid XHTML, but by using a plain old text editor (e.g., Notepad for Windows users) and a free text standard called reStructuredText (RST). Plone, the Content Management System (CMS) on which this site runs, has RST to HTML capability out-of-the-box, but it wouldn’t be difficult to include such functionality in any CMS as at all.

The short version: RST enables you to produce a 100% human-readable plain text document which is totally free of arcane markup, but which provides a set of features for determining the structure of a document as well as elements for applying formatting such as boldface and italics and tagging items with hyperlinks. reStructured Text emerged from the documentation efforts of the team working on the Python programming language–the idea was to be able to provide fully readable inline documentation for programmers while maintaining the ability to use the exact same text for producing pretty, printable manuals, or documentation in any other format that happens to be useful. But its utility is in no way restricted to technical projects. I’m planning to use it, in conjunction with a set of tools that I’m currently researching (notably LaTeX and related programs), to compose virtually everything I write, which currently consists mainly of papers for classes in international relations.

So what are the advantages?

First of all, reStructuredText allows you concentrate on the content and structure of your document rather than its final appearance. A related advantage follows from this: As suggested by the motivations, mentioned above, of the Python team, when used with the right tools, a reStructuredText document can serve as a single source: for an HTML page, a nicely formatted and highly readable PDF file, an article in a printed newsletter, etc. All derive from your one lone RST document. If you want to make a change, you only need to make the change to the RST source and you can automatically regenerate the other documents.

Additionally, programs that convert RST to other formats, such as HTML for Web pages, typically include parsers to validate your RST. In the case of the HTML converter, if you care about things such as Web Standards, this helps ensure that your documents will be valid XHTML when the conversion is performed. Indeed, the RST concept shares much in common with the separation of content from presentation that derives from the application of Web standards with XHTML and CSS.

Some other advantages may be more personal–speed of composition, for example. It goes without saying that composing raw HTML markup will slow down anyone’s composition considerably. But I personally find word processor-like WYSIWYG interfaces to be tedious as well–selecting text and clicking icons can end up being more time-consuming than simply sticking with the keyboard during the composition process. Not to mention the fact that you can compose your RST documents virtually anywhere where you have a plain text editor available–the same won’t always be the case if you’re reliant on a particular WYSIWYG editor.

Finally, I can’t help but feel that the philosophy behind reStructuredText contributes, in some way, to informational hygiene in a world made sloppy by the mindless dumping of content onto the global net. It’s just a hunch–I may have to take some time to further explore this notion in the pages of this site.

Written by mdorn

September 19th, 2005 at 7:43 pm

Posted in technology

Tagged with ,

Leave a Reply