tadhg.com
tadhg.com
 

reStructuredText

23:30 Thu 11 Oct 2007. Updated: 23:13 28 Jul 2009
[, , , ]

A colleague gave a presentation at work today on Pylons, a web framework for python. I was curious about the slides he was using, because they looked like they could be in S5, which I like. So afterwards I asked him, and he said that he wrote them in “rest”, which confused me at first because I thought of the REST approach to Web architecture. He was in fact talking about reStructuredText, a plaintext markup system that I’d never encountered before.

He showed me some of the source, and said that he used a utility to turn it into slides. I mentioned S5, and he said that in fact the utility he used was an reSt-to-S5 converter. This made me quite interested indeed, as it indicated some promising things about reStructuredText: strong structural components to support easy section-into-slide conversion, and a high level of support among people who like to write conversion utilities to various formats.

I don’t see a need for it specifically to write slides, as I’m entirely comfortable writing in HTML, but a plaintext markup format has plenty of other advantages, and the ability to convert to a variety of other formats is quite enticing.

So I spent some time this evening researching it. It appears to be extremely well supported in the python community, and has been around for at least five years. It’s used in python documentation quite a lot, making it possible to extract code documentation directly from the files and generate HTML (or some other output format). It appears to be relatively easy to read, although I haven’t tested it yet myself. jEdit comes with an editing mode for it, which is definitely a plus. It appears to be intended for documents (rather than snippets)—I consider this an advantage for the most part, although I see how it might be the wrong thing sometimes.

I’ll probably try using it, although there is some question as to what application I really have for it (even if I think it’s cool) outside of python code documentation. My standard mode of editing is plain text with HTML where I need it. This blog nominally uses Markdown (via a plugin), another plaintext markup system that’s a lot lighter than reStructuredText, but in practice the only feature I really use is its understanding that lines of text surrounded by blank lines are paragraphs, and that line breaks inside paragraphs should be turned into <br /> tags. Very occasionally I use its list syntax, but that often doesn’t work quite the way I want (I suspect that’s a problem with the plugin). For just about everything else, I use actual (X)HTML.

When I write in TiddlyWiki, I use its syntax, a variant of WikiText, and that usually works fine. I like how it handles a number of things, including links, but I don’t like that it converts “–” to strikethrough, rather than to an em dash, and there are other annoyances. Most of the systems I’ve encountered have some minor issues—and then it’s an issue in itself, in my opinion, that there are so many of them, and that they’re frequently not interoperable, such that conventions in one mean something very different in another. I feel as if there needs to be an accepted standard for this, but can’t see that happening too soon.

I’ll try reStructuredText out, but I have a hard time seeing myself writing

I visit BoingBoing_ too often.
.. _BoingBoing: http://boingboing.net

instead of

I visit <a href="http://boingboing.net">BoingBoing</a> too often.

It might not be too hard to write a converter that takes my HTML for links and turns it into reStructuredText, but somehow that strikes me as an additional step that’s too annoying, and I find the HTML link syntax much more readable.

It should be a rule that when the markup for something is harder than doing that something in (X)HTML, the markup parser should be able to parse the HTML as an alternative to its own syntax. I’m sure that’s extremely challenging technically, but I still want it as a feature, at least for the really common cases (like links). I am of course biased in this as someone whose native text format is (X)HTML plus the paragraphs-are-paragraphs-and-line-breaks-are-line-breaks features mentioned above.

I like the fact that reStructuredText has directives and substitutions, which seem like quite powerful features.

Link-based gripes aside, I will look into reStructuredText further, and see if I might have uses for it.

One Response to “reStructuredText”

  1. Aaron Maenpaa Says:

    Maybe you would prefer the inline link syntax:
    `BoingBoing <http://boingboing.net&gt;`_

    Cheers,
    Aaron

Leave a Reply