AsciiDoc

It turns out I've been reinventing a wheel. A few posts ago I spoke of creating a script that converts a text file to HTML, where the text file itself is highly readable. With clever ASCII usage, headings should look like headings, emphasized words should look like emphasized words, and so on, and there should be no ugly tags peppered throughout.

I came across AsciiDoc, which does exactly this, and is far better, older, and more capable than my simple script. Interestingly, the format I came up with does not differ that much.

I've converted a few pages on my homepage to AsciiDoc. This format makes the most sense to me. HTML files with their space-hogging outlandish tags are unpleasant to read. Text files convey the same information, are easy on the eyes, and can be converted to HTML in no time.

Also, why should I spend so much time making sure I'm using the right tag, and that my tags are nested properly and so on? Computers are supposed to do the mundane stuff for us. Generally speaking, computers should automate as much as possible so long as it is efficient and the process does not hamper human comprehension.

Automating Automounting

Newer, friendlier Linux distributions such as Ubuntu must surely make it easy to use CDs, CompactFlash and SD card readers, USB drives, external hard disks and so on. But I'm old-fashioned, and like to do things the hard way, that is, edit /etc/fstab and run mount and umount manually so various devices end up at places I like in my directory.

The problem is hot-pluggable devices get assigned different names in the /dev directory all the time. So I followed the first part of this guide that assigns the same name (that you choose) to the same device every time. Once this is done, you can modify /etc/fstab in the usual way.

While there, you might want to use the "noatime" mount option, or at least "relatime". See this Slashdot article.

Git Magic

As I promised in a previous post, I'd write more on tricks one can perform with Git. I had so much to say that I made a site out of it: Git Magic.

It was also a great opportunity to practice my salesmanship, as can be seen from some of section titles: Ultimate Backups, Light-Speed Multitasking, Guerrilla Version Control, Uninterrupted Workflow. It was a probably a lot more fun to write than it is to read.

I'm hoping it will be useful to those new to version control, not just those new to Git. I took pains to explain the effects of Git branching. I had trouble understanding this from the official Git documentation, though it's probably better by now.

Wiki Formats

For years I've dealt with raw HTML for a lot of my web pages. After some experience with various wiki sites, I've finally realized that it's a lot easier to maintain a bunch of simple text files marked up in some wiki format, and use clever scripts to convert them to HTML for publishing.

Source code should always be readable, and HTML does not quite make the cut. Reading documentation in raw HTML form is painful. Inspired by the Inform 7 language, I want my text file marked up with wiki to as close to a real document as possible. In other words, I want the source to be a pretty text file that you can read even if you don't have the HTML version. A bit like txt2html, but I want more control. Compare my homepage with it's wiki source.

And if you do need complex HTML, it's easy enough to provide a mechanism to temporarily disregard wiki tags.

I wrote a script that takes converts a text file, marked up in a certain way, and converts it to HTML with these goals in mind, and it's kept in a Git repository at

• http://cs.stanford.edu/~blynn/scrap/wiki.git

[20090608: updated link]
I'll have to write instructions one day, but basically, headings are designated with equal signs around the heading, two single quotes are italics, asterisks are used to mark text as bold, a minus sign and indentation for lists. Other indentations mean text that should be displayed unformatted and as fixed width.

I'm gradually converting all my HTML to this wiki format, as it's easier to edit and maintain. An added bonus is that I can easily write scripts to output a different format, such as DocBook.