Plain Text markup (HTML, reST, markdown & co)

September 8th, 2010 by exhuma.twn

Two of my personal quests I’ve been on since I started to work are the hunt for a good note-taking system, and the hunt for a good programming font. This post is related to the former…

My preferred medium to write down notes of any kind has been plain-text for a long time. This feels to me like the digital equivalent of pencil & paper. Mostly…

The big advantage being, that it let’s you focus on what’s important. And that is content! But it has one important challenge. How do you represent section headers, bulleted lists, hyperlinks,… in plain text?

While writing plain text files is quick and easy, sometimes you still want to convert it to a more visually appealing style. Say for example you’d like to incorporate it into a web-page, then converting it to HTML would be nice.

Over the years I’ve dealt with quite a few systems used for plain-text markup. Without a question, the most widely known markup language is HTML. Other’s which come to mind are javadoc, phpdocumentor, ROBOdoc and doxygen. While these are meant to document code, I still count them as markup languages as they have constructs to add style or semantics to the content. All of these are pretty useless as tool to write notes as they are stubbornly assuming you are generating text for code.

About ten years back while writing my own CMS, I needed a way to allow users to markup content. Allowing HTML was not an option because it was hard to edit, and hard to explain for non tech-savvy users. Especially at that time, when the Internet was still something most people considered either “Magic” or the “The Work of The Devil”. I didn’t need much. So I concocted my own markup language, and with not even a one-page introduction, people got productive with it.

A few years later I found what I then considered “The Holy Grail” of markup: And that was markdown. It’s really well designed, and the resulting “source” plain text format is very concise and clean. There’s not a lot of “noise” in the document. It is a perfect candidate for a note-taking format. The only thing that is really missing are tables.

Only recently ( about two years back ) did I come across reST (reStructuredText). It’s been around for quite some time, and I’m surprised I didn’t hear from it earlier. And if I had to sum it up in one word, it would be, without any hesitation: Mature! The “source” you write is, very clean and readable. Some parts (f. ex.: section headings) are even cleaner as in markdown, whereas other areas are not (f. ex.: hyperlinks). But it is much more complete than markdown!

One thing neither markdown nor reST can do very well is interlinking of documents. This is where Sphinx comes in. Sphinx is a document generation system which uses a collection of reST files as input. To completely understand it’s inner workings is not very straight-forward. But easy enough. And it pays off. It generates downright beautiful HTML and PDF (through LaTeX) documents.

In summary I would say that I would in any case prefer reST to anything else. It’s simple for basic cases, but complete enough, when the document starts to grow. Unfortunately I have not yet found convincing parsers for PHP. So in that case I’d go with Markdown Extra. If I needed to write really large documents, I’d consider Sphinx. Primarily because the generated HTML pages have an offline JavaScript search included, and because of the nice default style 😉

Posted in Babble | No Comments »


Recent Posts