Hack Diary: Documenting snippets for Vim
Wrote a very short and sweet little hack this morning using Ruby. I maintain a little project called scala-vim-snippets which is a snippet file for SnipMate. SnipMate allows Vim users to emulate TextMate’s wonderful snippets functionality.
Which is fine, but I don’t actually remember to use the snippets and I don’t necessarily remember the snippets themselves. It seems that what I want is something like a cheat sheet. Documentation, eh? Boring. Nobody likes writing documentation. So I wrote a Ruby script which goes through the snippets file and parses out JavaDoc style annotations from before each snippet. Currently, it is just a short comment before each snippet. There’s also a YAML file called metadata.yml that contains some metadata that gets added like the name of the programming language, the author and e-mail contact for the script. I may also add ‘doc-exclude’ to it so you can specify a list of snippet names that will be excluded from the doc generator.
SmDoc generates an HTML file that uses a definition list to list out all the snippets with the brief annotation. The HTML is a bit hacky - it certainly isn’t the most semantically beautiful markup I’ve ever written. But the HTML here is just a means to an end. That end is a nice printable PDF.
A decent HTML to PDF workflow is something we’ve all wanted. There’s htmldoc - but that isn’t exactly perfect. It doesn’t even do CSS. There is Prince XML, but that is proprietary, adds watermarks and expensive! Enter wkpdf - a wonderful little Ruby gem that uses the WebKit renderer (including the full CSS and JavaScript stack) to turn out PDFs. Sadly, it is OS X only. There’s an equivalent for Linux called wkhtmltopdf. I’d love it if someone who has the time and patience to do so could merge these together - I can’t imagine it would be too difficult. Go cross-platform HTML-to-PDF generation!
The code for SmDoc is in the Git repository for scala-vim-snippets. I’ll probably split it out into a separate repository and make it into a standalone command line utility.
And, yes, before the snarks creep in, I do realise the irony in writing a Ruby script to print out a piece of paper so I can write Scala more efficiently. As I’m not a language troll, I do not find the situation difficult to live with. (Ruby is a pretty nice language for writing these Perl/bash style scripts. But when I need something less like Perl+Smalltalk and more like Java+Haskell, Scala rocks.)
Anyway, here is what the print-out looks like:
It isn’t the prettiest thing in the world, but I’ll work on styling it and making it nicer as time goes on. I may split out the CSS into a separate file - which, of course, you can put elsewhere on the ‘net.
Patches welcome for both the HTML, CSS and the snippets themselves, of course. If you maintain a SnipMate file for another language, why not try out SmDoc? (If you haven’t got OS X, I am happy - within the bounds of reasonableness - to run the PDF generation for you.)
If you are doing documentation generation, do look at wkpdf/wkhtmltopdf. It really is a ridiculously simple and fun way to generate PDFs from a language that most people in a position to need to do that sort of thing know: HTML. And that is any sort of HTML: tag soupy crud, XHTML, HTML5 whatever.
A super-useful Greasemonkey script: Flickr new photo page title mover. Flickr, for some reason, now put the title below the image. This moves it back to being in the right place.
Unadulterated capitalism: this iPod touch case doesn’t suck
I finally found an iPod touch case that doesn’t suck. This is such a big thing that I should probably post about it. It is ridiculously cheap: 2.95 UKP. I have yet to find any shortcomings with it: if it sucks, it sucks significantly less than any other iPod touch case I’ve found. Including the one I had to raise my voice about in the Apple Store to get a refund under the Sale of Goods Act. (Goddamn Apple hipsters may be friggin’ geniuses with the iPhones but they don’t know shit about the statutory rights of UK consumers.)
Basically, it is a simple silicon sleeve with a relatively tight fit around the device. It has buttony bits on the volume control, the top switch and the menu button. You can even squeeze the iPod into the dock with it on.
Amazon.co.uk has it. And, yes, it is an affiliate link. Hence the “unadulterated capitalism”. I’ll get all of ten pence or something.
With curated computing, the least we can expect is some damn testing
I’ve got an iPod touch (as a previous post today kind of points out). I like it well enough, and have the usual nerd disdain for the App Store’s closedness - but, you know, I put up with it.
I upgraded to iOS 4 and I’ve been finding all sorts of problems - the problems actually almost outweigh the advantages for me. The key advantage is app grouping - that’s pretty nice.
The key disadvantage is stuff crashes. There’s one or two apps that crash on me quite frequently. Also, the music player has a sort of ‘blip’ when you go back to the main screen from the music app.
I had a thought about how Apple could manage this better given the nature of the iOS platform. With Xcode, they would bundle a simple macro recorder. Once you’d finished your app, you’d record testing macros with it. You could even record them from the device: it’d boot up the app on the device, and then you’d basically push the relevant screen areas on the device and it would get transferred back to the computer what buttons you are pushing. You could then produce a little test for each piece of functionality in your app. You wouldn’t have to get to 100%, but you’d record these steps. For each step, you then describe the sequences - how you could compose those sequences together.
Then provide a performance-accurate VM for each of the iOS devices: the iPhone 2G, 3G, 3GS and 4th gen., the iPod touch 2nd gen. and 3rd gen. and the iPad models. The developers could run their tests on their machine at home and get performance-accurate tests back from them. But here is the awesome bit: because you describe the relationships between the steps, you can then run them in a more random order.
Now, here is the important bit. When you submit your app to Apple, you send the tests along with the binary. They keep all these test scripts there for all the versions of the app. As well as it doing a human review, Apple can run these automated tests. And when Apple come up with a new version of the OS - or a new device - they’ve got a reasonably comprehensive test suite for every app in their store! They can run the crap out of the top x% of app tests and see which apps crash on all the different combos of device and platform.
I’m not an iOS developer - just a user and a developer on other platforms - but it seems to me that if people are jumping to the idea of “curated computing” (and the Stallmanite angel sitting on my shoulder is quite furious about the idea and is whispering me to resist the seductive advances of the iPad), the least they can expect is that the curator uses as many technical means as they have available to see that the platform is well curated.
Of course, Apple have a much simpler solution: buy a new iOS device. The apps won’t crash on there. Sorry, but no.
