George V. Reilly

reStructuredText

reStructuredText

I hate composing anything longer than a couple of paragraphs in an online HTML editor. Specif­i­cal­ly, I hate writing posts for this blog online. I’d much rather write in Vim and upload HTML. But I don’t want to compose in raw HTML either.

I use re­Struc­tured­Text (reST), an un­ob­tru­sive plaintext markup language popular in the Python world. reST can generate HTML, LaTeX, native PDF, ODF, and other formats. The picture at right shows a draft of this document in MacVim; reST is, as you can see, quite readable (though I work with a larger font). I use restview to preview the HTML locally and Pygments for syntax high­light­ing of code. Vim has its own syntax high­light­ing for reST and I’ve developed a set of keyboard macros for my own use.

The weak link in this scheme is posting to the blog. Right now, I have a little wrapper that generates HTML, extracts the body, and copies it to the pasteboard (clipboard). I then manually paste that into a raw HTML textarea in the blog’s editor. Someday, I have to adapt mtsend or Firedrop2 to make this less painful. Or I could hack dasBlog to support reST in IronPython, or switch over to a blog that supports reST natively. Someday.

For a long time, I used VST (Vim re­Struc­tured­Text) to generate HTML from reST. As I began using Python more and more, I realized that I was far better off with the real thing, which is well designed and quite fast. The VimL scripting language is not that good and VST pushes it to its limits.

As of the recent Python 2.6 release, all the official Python doc­u­men­ta­tion is in reST format. Sphinx is a doc­u­men­ta­tion build system that wraps a collection of reST documents into a larger navigable entity.

There are many other light­weight markup languages, such as Textile, Markdown, and AsciiDoc. No doubt they have their strengths, but I now have a sig­nif­i­cant investment in reST and it’s well supported by the Python community.

blog comments powered by Disqus
Review: Field of Blood » « Shaun the Sheep