this space intentionally left blank

March 20, 2013

Filed under: tech»education


Working on my textbook continues to be a great opportunity to write interesting little snippets of interactive JavaScript. Today I'd like to draw your attention to a couple of new modules for doing annotated source walkthroughs that I'm calling Timelapse. They're located in the repo under js/meta/TimeLapse and js/meta/TLPlayer. There's also a demo history file located here.

There are lots of tools for doing diffs between two source files, but I'm not aware of any source control system (save Perforce, which we use at ArenaNet) that do a timeline view of all revisions since a file was first checked in, and none that store the entire revision history in a single, web-friendly format. This is a shame, because my goal for several parts of the textbook is to be able to "replay" the process of writing a script, to show how it develops from a few lines of simple code into larger and more functional units like functions and prototypes. It's possible that someone else has done something like this, but a cursory Google couldn't turn it up, so I made my own.

The syntax for the files that Timelapse uses is designed to be similar to a standard diff file, but to not collide with JavaScript for easy parsing. It's a line-by-line comparison format with two main types of line tags:

  • @x,y@ source line: In this case, the tagged line exists from revision x to revision y. Both x and y are optional--x defaults to the first revision, and leaving out y will mark the line as included through the end of the history.
  • @@c:x; comments @@: This tag marks a multiline comment for a single revision x. Everything between the semicolon and the closing @@ will be loaded but not shown with the rest of the source.

You don't have to write these files by hand, which is good, because they can get pretty nightmarish. Instead, I've written an authoring tool for putting in multiple revisions (or importing them, using the HTML5 file API), commenting them, and exporting them. Using Ace means the editor is friendly and includes source-highlighting, which is great. You also don't have to worry about writing an output parser: the TLPlayer module is not quite complete, but it's done enough to wire it up to a UI and let people flip through the file, with new lines highlighted in the output.

If you'd like to see a demo, I've started using it for the chapter on writing functions. My goal is to put at least one timelapse at the end of each chapter, so that readers can see the subject matter being used to build at least on real-world code script. By doing these as revision histories, I'm hoping to avoid the common textbook "dump a huge source example into the chapter" syndrome. I know when I see that, my eyes glaze over--I don't see any reason that it's any different for my students.

Although I don't have a license on the textbook files yet (they'll probably be MIT-licensed in the near future), you're welcome to use these two modules for your own projects, and feel free to submit patches (the serialization, in particular, could probably use some love with someone with a stronger parsing background). I'd love to see if this is useful for anyone else, and I'm hoping it will help make this textbook project much friendlier to new developers.

Future - Present - Past