Hypomnemata

I recently centralized and tallied up my personal source repository: something like 100kloc and about 80 directories.  This represents around a decade of evenings and weekends spent writing code, in everything from C to Haskell, in environments from my low-level Unix home to PalmOS.  The most recent stuff is arduino and processing, but it also includes OCaml-gtk and a bit of Objective C (written on OS X 10.0).  The common themes through all this diversity?  It’s all hastily written, poorly documented, and nigh-unreleasable code.

That said, my friend Kragen caught wind of this and suggested I release it all.  While I won’t release everything (some of it is still very nascent and/or mostly vapor), I will be working my way through, giving some things Makefiles and READMEs before kicking them out the door.

Tonight is the first installment of this src parade.  It’s actually something I released years ago, which has fallen into a bit of disrepair, but was still pretty cool: Marginalia.  Marginalia was a firefox extension that allowed you to annotate webpages in-place, and see the annotations others had left behind.  Its plugin description was “Collaborative annotation for FireFox,” which pretty well fits.

Viewing an annotation placed with marginalia

Why did I build this in the first place?

It was meant to allow the disruptiveness of the web to become even more pervasive.  Imagine if citizen journalists could leave links to alternate coverage of stories on CNN.com, or add links to previous statements by politicians to their latest contradictory interview.  It predates youtube; nowadays, it would definitely allow embedding youtube clips for this.

What did I learn in building it?

Javascript is hard.  No, really, it is.  If you want to build something like this, performance matters, and it’s non-trivial to get correct.

HTML/DOM is hard.  It was never intended to do things like this, and you really have to bend over backwards to make it happen.

Don’t give up so soon.  Marginalia was pretty freaking awesome, if I do say so myself.  I didn’t push hard enough for others to adopt it, and I let it die too early and too easily.  It could have been a big deal, but I didn’t care enough to keep at it.  In my defense, I was in the second to last semester of undergrad, which was pretty intense.  I was working 20-30 hours a week and had two majors, so it was either hack on this or spend time with my girlfriend.  (I got to play with marginalia on the clock, but only so far as it didn’t interfere with keeping the lights on.)

Where does it stand today?

Marginalia fell to the wayside at some point.  Most significantly, it needs retouching to work with the latest firefox/gecko.  It currently doesn’t install, but I’m pretty sure it’s more than just updating the compatibility ranges.  If you’re interested in the problem, I’d suggest looking at newer web annotation systems  Wikipedia has a good list at [[Web annotation]].  The hardest technical problem you’ll face is actually kind of silly: figuring out where to attach the note based on the user’s click.  Have a look at how marginalia does it to see one solution; I’m sure there are others which are just as good.  (Hint: marginalia bundles a pure-javascript SHA-1 implementation)

You’ll find more text and a download at the Marginalia homepage.  The source is part of the download, though it doesn’t look like it.  XPI is, like JAR, a strange way to say ZIP.  That is: you can download the XPI file (right-click, save as), then unzip it (you might need to rename it to be a .ZIP file).  The guts of things are in chrome/marginalia/content/marginalia.js

Would I do it again?

Probably not, actually.  This is mostly because others are solving the problem, but also a little bit because solving the problem is incredibly tedious.  Having written a handful of little firefox extensions, I now have zero urge to build on that platform any more.  I still love the idea of marginalia, but I would prefer to leave implementing it to someone else.