Quill News, 5 Sep 2014

Since last week’s release of Quill v0.2.0, I’ve been working on the documentation; which is more involved than you might think.

See, I first encountered HTML probably around September of 1993, which when Mosaic was first released for the Macintosh. I was already an old hand with hypertext; around 1989 or 1989 I wrote a program (in awk for the Unix geeks in my readership) to process documentation for some C libraries I was working on. The program took the documentation, written in a format I’d divised, and produced LaTeX code for the LaTeX typesetting program and input for a DOS program called HyperHelper (or possibly HypertextHelper) which seems to have been lost. HyperHelper let you create your own hypertext documents and display them and jump around in them; and it included a “terminate-and-stay-resident” (TSR) mode so that you could pop it up on top of whatever DOS program you were using.

I even had my editor (Brief) set up so that I could press a key and it would pop up the hypertext help for the C function under the cursor.

So when I learned about HTML, I was quick to jump on it. I could write my own documentation in HTML, save it to disk, and then be able to browse it in Mosaic (later, Netscape) while working in my text editor. Younger readers and non-programmers probably have no idea how totally cool that was. And the resulting documentation looked nice (that is, you could use boldface and italics on your gray background) and you could link docs together, and all-in-all I was in love.

But there was a problem: HTML is annoyingly verbose, and it has no abstraction mechanisms, by which I mean that you can write pages but you can’t write subroutines. To my mind, HTML was (and is!) crying out for an extension language to let you define your own tags. I had recently discovered TCL/TK, and my first major project was a program called “Expand” that more or less did just that. I could write an HTML file with embedded TCL code; when I write the file through Expand>, it would replace the TCL code with the text it returned.

Someone else did this with a language they made up and called PHP; it’s still pretty popular, I hear.

I first got my own domain on the internet so that I could use Expand to build web pages for it. I needed something to write about, and so I started a proto-blog, reviewing the books I was reading. It’s really not too farfetched to say that I’m writing at Patheos now because I wanted to play with HTML back then.

Since then, it seems to me that I’ve spent an inordinate amount of my life coming up with different schemes for converting easily-writable documentation into HTML. I’m now working on the latest go-round of these schemes for Quill. First, there’s a processor for writing Unix-style man pages (i.e., reference documentation) that based on an earlier effort I made a few years ago, with some significant improvements; and a new processor for writing more traditional documents with numbered sections and cross-references. Both processors consume an HTML-like language with support for abstraction (they support many of the same “tags”), and both produce reasonably nice looking HTML.

It seems somewhat hubristic, even to me, to produce a new programmer’s documentation format in 2014, when there are so many choices already available, in a dizzying array of flavors; but at least I’ve been at for twenty years, and I like to think I’ve learned a thing or two.