Arnt Gulbrandsen
About meAbout this blog
2009-11-24

The überprogrammer

Every programmer has bad days. Days on which no code wants to be written, days spent tinkering with the CSS of a blog noone reads, or posting something to said blog.

Every programmer can do that. It takes a very special kind to ☑ finish a long posting on a subject which interests noone ☑ post it to a blog which noone can read, due to the sad state of IPv6 ☑ tinker with the CSS of that blog ☑ — using CSS3 text-justify, which no browsers support ☑ and finally to reconfigure the blog to withstand heavy load, as if IPv6 deployment were to happen before 2011. All on one day.

Output formats for generated documentation

The four major output formats (long print, piecemeal print, ASCII on screen and hypertext) all have their fans, all have their uses, the ideal system would support all four, but it isn't possible to support all four really well.

Writing, designing or encoding for plain ASCII just isn't the same as writing for pages. One of the books I read ages ago had a very nice example, showing two pages of text vs. one screen of text. The pages allowed boxes that didn't intrude on reading the regular text, fine graphics, and easy overview of a lot of data. In all, around six times as much information in front of the reader's eyes. (more…)

2009-11-12

Exceptions, and exceptions, and exceptions

Exceptions are such a pain. They look as if someone thought they could solve many disparate problems with one tool, and in the end, the tool doesn't look terribly elegant, and people don't use it terribly well. (more…)

2009-11-11

Literate programming failed. Why?

Donald Knuth invented literate programming and published the TexBook as an example. The book is great, or so I've heard from many people who've read it. So why is literate programming is practically unused today, at least the kind Knuth invented? (more…)

2009-11-04

Kinds of literate programming

The TeXbook employs something called literate programming: Knuth wrote code and text together, effectively writing a narrative about that code, with that code as part of the narrative.

Knuth could do that, he's a genius. He was able to write a sizable program practically without bugs, in a note-book. Mortals like myself could not. I'd have to go back and rewrite earlier bits, and before long the narrative would stink. (more…)

Writing (mostly) to write

Most people who talk about literate programming seem to care mostly about the output. The written documentation. I care more about the actual writing, and the result of the writing process.

When you write something, when you explain it, you gain a deeper insight yourself. That's a cliché, to be sure, but it can be leveraged to write better code. There are two parts to it: Helping yourself and having your tool help you. (more…)

Bashing Microsoft

Scientists have proven that eighty-four per cent of Microsoft-bashing is ridiculously wrong, and that all that rubbish makes valid criticism of Microsoft look bad.

2009-11-02

API documentation using literate tools

API documentation is a particular subclass of literate programming. What makes it special?

First, its audience is diverse. Some readers know almost as much as the maintainers about the subject, others are rank beginners. Many know quite a bit about some parts of the subject and are almost ignorant of other parts. Some readers like to point and click, others prefer dead flat trees, others again prefer on-screen plain text such as man pages (I do, because I can type much faster than I can point and click). (more…)