Presenting Code - { |one, step, back| }

{ |one, step, back| }

1 of 1 article

• Wiki • Syndicate: full/short

Presenting Code 23 Mar 08

[ print link all ]

This exchange on twitter got me thinking…

Twittering …

I noticed the following twitter conversation this evening between objo and superchris:

superchris: any good recommendations on showing code samples in OpenOffice Impress?

objo: @superchris yeah, get a mac and use Keynote

objo: otherwise, I would screenshot emacs

superchris: @objo.. ya know, i almost added “And I’ll smack anyone who says get a Mac” but ran out of space

superchris: @objo… but actually your idea of using NetBeans screenshots is pretty good

objo: @superchris you never listen …. EMACS not netbeans. Come on man.

superchris: @objo just being helpful by translating for you.. :)

superchris: planning to code with NetBeans on linux forever for no other reason but to annoy @objo

ScreenShots … Yuck!

The problem Chris is trying to solve is putting code snippets into a presentation. There just isn’t a good way to do this in modern presentation programs.

In the old days, I would generate my presentation completely in HTML from a simple text markup file. The generation process was controlled by rake. This allowed me to changed the code, run the unit tests and rebuild the presentation all with a simple rake command. Eventually, I got up to speed with CSS and could make some really nice looking presentations, all from HTML.

Although I could get nice looking slides with CSS, it was a lot of work getting it to work just so. Eventually, I abandoned that approach and swithed to a modern slide presentation program (Keynote in my case).

Although generating the slides is a bit easier in Keynote (or PowerPoint, or Open Office Impress), reproducing code for technical talks is much harder. You generally have two choices:

Cut and paste the code text into Keynote losing any syntax highlighting you might have had, or
Take a screen shot of the code in your fancy editor, preserving the syntax highlighting but losing the “text” nature of the code.

Neither option is pleasant. The former punishes the audience by making the code harder to read, the latter punishes you making the presentation hard to change. (I once saw Dave Thomas giving a Ruby talk and he noticed that he had a minor typo in the code. He switched to edit mode in Keynote with the intent of fixing it on the spot, then he realized that the code was in a graphic image and was uneditable).

Of the two options, I’ve been using the text cut’n’paste technique for most things. In the twitter conversation above, Chris is considering the edit snapshot technique.

Other Options?

I’ve heard rumors of someone working on a script that will insert code snippets into the Keynote data file directly. Unfortunately, as far as I know, they are still rumors at this time.

But here’s another idea. I’ve prototyped this, and think it will work. But be warned I haven’t tried this on a really presentation yet.

Presenting Code … A Proof of Concept

While perusing the options in Keynote, I noticed an insert option called “Web View”

It turns out that this option allows you to include a web page in your presentation. For example, here is my blog inserted directly into the presentation. Clicking on the “web view” object will show an “update” button that will refresh that page from the web.

So, all I have to do is get the code onto a web page, formatted nicely with syntax highlighting, and Keynote will suck it into the presentation, more or less automatically for me. Cool.

Getting it formatted is easy. That’s just a small little Rake task with a good syntax highlighting library. I used Syntax (its a gem, docs on Rubyforge), but there are other options out there.

Here’s the rakefile:

#!/usr/bin/env ruby

require "rake/clean" 

CLOBBER.include('*.html')

task :default => :extract
task :extract => "hello.html" 

file "hello.html" => "hello.rb" do
  extract "hello.html", "hello.rb" 
end

and here is the rakelib/extract.rake library:

#!/usr/bin/env ruby

require 'syntax/convertors/html'

def extract(outfile, infile)
  open(outfile, "w") do |out|
    out.puts "<html>" 
    out.puts "  <head>" 
    out.puts "    <style type=\"text/css\">" 
    out.puts %(
.ruby { font-size: 24pt; font-weight: bold; }
.ruby .normal {}
.ruby .comment { color: #888; font-style: italic; }
.ruby .keyword { color: #A00; font-weight: bold; }
.ruby .method { color: #077; }
.ruby .class { color: #074; }
.ruby .module { color: #050; }
.ruby .punct { color: #447; font-weight: bold; }
.ruby .symbol { color: #099; }
.ruby .string { color: #944; }
.ruby .char { color: #F07; }
.ruby .ident { color: #004; }
.ruby .constant { color: #07F; }
.ruby .regex { color: #B66; }
.ruby .number { color: #D55; }
.ruby .attribute { color: #377; }
.ruby .global { color: #3B7; }
.ruby .expr { color: #227; })
    out.puts "    </style>" 
    out.puts "  </head>" 
    out.puts "  <body>" 
    out.puts "    <pre class=\"ruby\">" 
    code = open(infile) { |f| f.read }
    convertor = Syntax::Convertors::HTML.for_syntax("ruby")
    html = convertor.convert(code)
    out.puts html
    out.puts "    </pre>" 
    out.puts "  </body>" 
    out.puts "</html>" 
  end
end

Edit the CSS styles above to tweek the output to exactly the colors you want. I’ve added a large font-size line to make the code big enough for teh presentation (I hate small code fonts in presentations, you can ask objo about my rants on that topic.)

Now we need to get the code on a web page. No need to get fancy here. I have a script called servefiles that will start a webrick process that serves files from the current directory. Just start it up with “servefiles 3333” (the 3333 is the port to use). Servefiles will display its URL in its startup message, like so:

$ servefiles 3333
URL: http://tardis.local:3333
[2008-03-23 00:47:37] INFO  WEBrick 1.3.1
[2008-03-23 00:47:37] INFO  ruby 1.8.6 (2008-03-03) [i686-darwin9.2.0]
[2008-03-23 00:47:37] INFO  WEBrick::HTTPServer#start: pid=874 port=3333

Here’s the code for servefiles:

#!/usr/bin/env ruby
require 'webrick'
include WEBrick

dir = Dir::pwd
port = (ARGV.first || (12000 + (dir.hash % 1000))).to_i

puts "URL: http://#{Socket.gethostname}:#{port}" 

s = HTTPServer.new(
  :Port            => port,
  :DocumentRoot    => dir
)

trap("INT"){ s.shutdown }
s.start

Now all we have to do is cut and paste the URL given by servefiles into keynote and append the HTML file name we wish to add to our presentation:

Now, to update the code in the presentation, I need to:

Edit the original code base (and run unit tests against it).
Run rake
Press the “Update Now” button in Keynote.

Not bad.

It’s Just a Proof of Concept

Just be warned, I haven’t tried this in a real presentation yet. I’ve just spent an hour or so seeing if all the pieces would work together. There are some obvious things to explore.

The extraction code could be enhanced to pull snippets from files based on tags. Or even better, being able to say “Extract Method m from Class C”.

I’m using a fixed font size, but extract could easily take the font size as an argument or even calculate the proper font size given the amount of text found in the snippet.

I’ve not played with the “Update automatically” checkbox in the Keynote dialog. I’m not sure when it automatically updates, but it is possible that using it might mean you don’t even need step three above.

I will probably experiment some more with then in my next code heavy presentation. Let me know if you try this and how it work for you.

UPDATE

Cédric Beust points out that cutting and pasting from Eclipse to PowerPoint does preserve syntax highlighting. I verified the same is true for Eclipse and Keynote. However all the other IDEs and editors I tried (NetBeans, Coda, TextMate, Emacs) will paste as plain, uncolored text in Keynote. So, if you are going the cut and paste route, you might want to consider using Eclipse for the cut source.

Just for kicks I tried the presentation software in OpenOffice with the same result. Eclipse copies will preserve highlighting, none of the others will.

So, there you have it.

Welcome to ...

Jim Weirich’s blog on Ruby, OO, Programming, whatever.

EMail: jim@weirichhouse.org

Speaking At...

Aug 15-17, 2008 -- erubycon

Sep 04-06, 2008 -- Lone Star Ruby Conf

Dec 02-05, 2008 -- OSDC

Recent Tweets