However, that doesn't mean you can't have a version number in your POD. I often use CVS to do my version control, and with CVS, you can tell it to stick in a version number. Something as simple as the following will do:

    =head1 VERSION

      $Revision: $
[download]

To get the version number inside a variable, I use something like:

    our ($VERSION) = q $Revision: $ =~ /[\d.]+/g;
[download]

The easiest thing is probably to filter the source file before feeding it to pod2html. Use Module::Info to extract the version, then either replace some keyword like __VERSION__ in the Pod, or insert a brand new version section in the Pod, then send it on to pod2html.

This is a little on the kludgy side, but one approach I take for $work POD is to post-parse and process (whew! A lot of 'P's!) the pod2html output. I have a little CGI script that does a real-time pod2html conversion (it is pretty fast) for whatever module a user picks out of a list and then edits the resulting HTML on the fly before presenting it. I tweak things like the title displayed and add in default text when the POD is incomplete or flawed.

my $version_pod = <<'=cut';
=pod

=head1 NAME

HTML::Template::Compiled - Template System [...]

=head1 VERSION

our $VERSION = "0.57";

=cut
# doesn't work with make tardist
our $VERSION = ($version_pod =~ m/^our \$VERSION = "(\d+(?:\.\d+)+)"/m
+) ? $1 : "0.01";
[download]

my reason for this was to always have the version visible in the pod and up-to-date with the $VERSION variable (and not using the cvs revision). to address this, i wrote a test-script that compares the two strings, so i'm always safe when the testsuite succeeds.

That's exactly what I was looking for!

All of the solutions provided are interesting, but this one in particular is perfect for what we are trying to do.

Thanks for the input everyone!