Perl Hacks

Hack #35. Write Demos from Tutorials

Give tutorial readers example code to run, tweak, and examine.

Reading code is one thing. Running code is another. Example code is wonderfully useful, but nothing beats playing with it—changing values, moving subroutines around, and seeing what happens if you touch just one more thing.

You'll never escape writing documentation. You can escape having to explain the basics over and over again if that documentation includes working, runnable code that people can customize for their needs. If you've already realized that including pure-POD modules is a great way to document programs, take the next step and make the tutorials themselves write out their examples.

The Hack

Writing a POD-only tutorial is easy. For example, the basic SDL::Tutorial shows how to create a screen using Perl and the SDL bindings:

use SDL::App;

# change these values as necessary
my  $title                   = 'My SDL App';
my ($width, $height, $depth) = ( 640, 480, 16 );

my $app = SDL::App->new(
    -width  => $width,
    -height => $height,
    -depth  => $depth,
    -title  => $title,
);

# your code here; remove the next line
sleep 2;

Running the Hack

Better yet, if you run the tutorial from the command line, it writes out this program to a file of your choosing:

$ perl -MSDL::Tutorial=sdl_demo.pl -e 1
            

Looking at the tutorial itself [Hack #2], it's only a use statement, a heredoc, and the documentation. How does Pod::ToDemo know to write the file and exit? Further, what if someone accidentally uses SDL::Tutorial ...