Our take on presenting code

Back in March, Jim Weirich posted some notes on a clever technique for getting code into Keynote presentations. It struck a chord with me, because I've been suffering the same problem for a long time now. Eventually, the pain of putting together the Studio content with Mike Clark and Chad Fowler drove me to find a solution. (The pain wasn't working with Mike and Chad—it was creating and keeping up to date many hundreds of slides, most of which contained code.)

The solution we went with was based on the way we do code in the Bookshelf books. Rather than embedding the code in the slides, we write regular old programs. Then, in the slide material, we reference the source file (and optionally say which section of that source file), and the appropriate code gets dragged into the slide, syntax highlighted, and hyperlinked back to our editor. Here's how it works.

Create Your Material

We've given up using Keynote and Powerpoint. They're a pain with version control, and they make it easy to fall into the eye-candy trap, favoring glitz over content. Instead, we create our material is plain text files using Textile markup. Typically we use one file per major topic, and the use an index file to bring all these individual files together into a single overall presentation/

Within the material, we can include material from external files using the :code directive.

Here's the source for an individual slide:

h1. const_missing
Correctly handles nested modules
:code code/meta/const_missing.rb

and here's what appears on the screen:

The code gets inserted onto the slide and is syntax highlighted. The blue text below the box shows the file name (so attendees can find it in their collateral material). It's also a txmt: hyperlink—click it and the file opens in Textmate, so we can edit and run it.

Using Parts of a Source File

You often just want to show part of a larger source file. We do that by including START:tag and END:tag comments in the original source. (This works in any language, and not just Ruby source). In the slide markup, you indicate the part(s) you want to include in square brackets after the file name:

h1. method_missing

:code code/meta/my_ostruct.rb[impl class=code-small]

This says to look at the source file code/meta/my_ostruct.rb and only include on the slide the stuff between START:impl and comments. We'll also display it using the CSS class code-small.

The ability to include parts of code is invaluable when you're doing a sequence of slides that builds a solution: you can show each part of a source file in turn.

Building the Presentation

The toolchain that takes all this is remarkably simple, because most of the work is done for us. We use a simple Ruby script that takes our original slides, embeds the source code from external files, and then runs Textile to produce an HTML version. We then add a header to that HTML that drags in two incredibly useful Javascript libraries.

For the presentation itself, we use Eric Meyer's S5 system. It gives us nice looking slides, simple to use navigation, and lets us present in our own browsers or (potentially) on our students'.

For the syntax highlighting of code, we use SyntaxHighlighter. This clever piece of code doesn;t require you to mark up the code elements inthe HTML. Instead you just flag your <pre> blocks with an appropriate class and it does the parsing and highlighting in the browser. It means that really large decks can be a little slow to load (but the still beat Keynote on elaspsed time), but it also means your HTML is really clean.

Finally, we have a Rake task that lets us built the whole presentation or just individual chapters.

The whole thing took about 4 hours to get working, and probably another 4 hours on and off to tweak it based on experience. The code's not really in a state that can be released (so please don't ask), but it wouldn't take much to produce something you could do the same with.

It Actually Works in Practice!

So far, we've done two studios using this stuff (Advanced Ruby and Erlang), and I've used it in a number of conference presentations. I wouldn't switch back to regular presentation software for any code-based talk. (I'll still use Keynote for non-code slides, though.)

A Few More Slides

Here's the source:

h1. initialize_copy

Container wrappers such a OStruct have a potential problem

:code code/meta/my_ostruct_problem.rb[class=code-small]


h1. initialize_copy

:code code/meta/my_ostruct_ic.rb[impl class=code-small]

h1. const_missing

* Module method whenever undefined constant references in that module

** (Module is a module, and acts as a global place for @const_missing@)

* Mostly used to autoload classes

* Not as easy as it looks (Rails' @dependencies.rb@ is 500 lines long)

h1. const_missing

:code code/meta/const_missing_autoload.rb[class=code-small]

And here are the resulting slides:

Comments

[Jim Weirich]

Prior to keynote, I used a very similar technique. There certainly are advantages to it. It certainly made publishing the results on the web much nicer. After reading this, I'm tempted to return to it.

Just two questions:

(1) How do you handle printing? Can you do the 4-up style printouts used in the studios?

(2) Are you going to release your build scripts? (hint hint)

[Dave Thomas]

Jim:

I have a print css that does 90% of what we need. My big problem is that page-break-inside support seems poor to non-existent, so we sometimes break slides across pages.

The problem with releasing anything is that it's nowhere close to being packaged up, and I don't have time to make it tidy enough not to be embarrassing.

[Dr Nic]

I think the common quote I see these days in answer to (2) is:

"I've thrown the code up on github but its not finished..."

[Xavier Noria]

Indeed, I've always avoided software for presentations that involve code. In retrospective most of my presentations have used some small hack hand made for them.

For example, my Perl classes (http://zeus.maia.ub.es/~fxn/cursos/lds/2007-2008/apunts/, in Catalan) are done via a small CGI that automates code display with syntax highlighting together with input fields that let me execute the code at runtime and get back the output into the page. It has been a good pedagogical aid for me because the slide is responsive and you can play with the code by passing different inputs.

I've done presentations with TextMate as well, I explained the setup I used in the Conferencia Rails Hispana 2006 here where I used TextMate and the Apple remote: http://advogato.org/person/fxn/diary/452.html. I think DHH has presented with TextMate as well.

An editor is great for code-centered presentations because you get syntax-highlighting out of the box, as much scroll as you need... and is everything trivially put together if having the code cut into some files feels right.

Scrolling is important: I don't want the size of a slice to influence the amount of code I decide some topic deserves to be well explained.

[Dave Thomas]

Xavier:

I've done Textmate only too, but for 3-day courses, people want notes, and I need some structure :)

Nic: right now I just don't have time to extract and package it. Perhaps one day soon.

[Phil]

Nice to see someone else taking advantage of plain-text for something like this; I'm surprised how many hackers simply toss out best practices for something like that just because "it's not code". Being able to write in Emacs and keep things in version control is a huge win.

[TwP]

Dave, I'd be very interested in integrating this support into Webby -- http://webby.rubyforge.org

Bruce Williams is using Webby to maintain his codefluency website. Generating presentation slides is a very natural fit. Webby also provides support for TeX, Graphviz, UltraViolet syntax highlighting and a few other goodies.

If you would be willing to share the source file extraction code, it would be quick work to include it into Webby as an ERb method or as a custom Textile tag.

Blessings,
TwP

[Dave Thomas]

OK, I give in...

http://pragdave.blogs.pragprog.com/pragdave/2008/05/code-in-present.html

[Dr Nic]

Yay for peer pressure!

[Gerald Bauer]

I have created an open source free Ruby gem called slideshow (S9) a while ago as a free web alternative to KeyNote and PowerPoint. The latest gem update now also includes code syntax highlighting using the Ultraviolet gem. More @ http://slideshow.rubyforge.org

[Dave Thomas]

Gerald:

Thanks to some sterling work by Dr Nic, we have a Gem too:

gem install codex

It's still rough, but it works.

[Gerald Bauer]

Great news about the codex gem. Now codex also has a support group/mailing list ;-) I've created a group on Google for "Free Web Slide Show Alternatives - S5, S9, FullerScreen, Codex - of course - and Friends" and sent out a posting introducing Codex to get the discussion started. Join us. More @ http://groups.google.com/group/webslideshow

[Jim White]

I'm working on a WYSIWYG tool for this sort of thing called Wings, a sort of like Mathematica but for any language. At the moment it only works in OpenOffice (StarOffice/NeoOffice) for text documents (and is dandy for things like tutorials and books), but Impress as well as web browser capability are planned. Any language with a JSR-223 Scripting API engine should be fine and the examples include Ruby (using JRuby).

http://www.ifcx.org/

[fall flags]

Thanks for the useful information

Thanks
fall flags

[Kirill Ishanov]

Can you, please, share the styles which you've used on example slides?

Thanks.