This module allows you to write scripts which contain their own documentation internally using Pod markup.
The documentation can then be displayed to a user without having to write your own "print" statements, or duplication.
RequirementsNone. (Ships as part of Perl 5.8.)
Who Should Use ItAnybody who is writing complex command-line scripts which would benefit from included documentation, and who doesn't wish to describe the programs command line arguments more than once.
Bad PointsNone that I could tell.
Example
#!/usr/bin/perl -w
=head1 NAME
pod-usage - A simple program with its own documentation.
=head1 SYNOPSIS
pod-usage [options]
Help Options:
--help Show this scripts help information.
--manual Read this scripts manual.
--version Show the version number and exit.
=cut
=head1 OPTIONS
=over 8
=item B<--help>
Show the brief help information.
=item B<--manual>
Read the manual, with examples.
=item B<--version>
Show the version number and exit.
=back
=cut
=head1 EXAMPLES
The following is an example of this script:
pod-usage.pl --help
=cut
=head1 DESCRIPTION
This is a simple demonstration program for Pod::Usage, this text
will be displayed if the script is invoked with '--manual'.
=cut
=head1 AUTHOR
Steve
--
http://www.steve.org.uk/
$Id: pod-usage,v 1.79 2006/01/07 23:23:12 steve Exp $
=cut
use strict;
use Getopt::Long;
use Pod::Usage;
#
# Release number.
#
my $RELEASE = '0.8';
#
# Parse command line arguments. These override the values from the
# configuration file.
#
parseCommandLineArguments();
#
# Do more stuff ..
#
#
# All done
#
exit;
=head2 parseCommandLineArguments
Parse the arguments specified upon the command line.
=cut
sub parseCommandLineArguments
{
my $HELP = 0; # Show help overview.
my $MANUAL = 0; # Show manual
my $VERSION = 0; # Show version number and exit.
# Parse options.
#
GetOptions(
"help", \$HELP,
"manual", \$MANUAL,
"version", \$VERSION
);
pod2usage(1) if $HELP;
pod2usage(-verbose => 2 ) if $MANUAL;
if ( $VERSION )
{
my $REVISION = '$Id: pod-usage,v 1.79 2006/01/07 23:23:12 steve Exp $';
$VERSION = join (' ', (split (' ', $REVISION))[2]);
$VERSION =~ s/,v\b//;
$VERSION =~ s/(\S+)$/$1/;
print "pod-usage release $RELEASE - CVS: $VERSION\n";
exit;
}
}
Notes
Once I started using this module I found that it was incredible easy to start writing documentation for functions and little tutorials inside my code.
The fact that the '--manual' flag, (or whatever you like), can be made to display the Pod text from your script is very useful.
my $REVISION = '$Id: pod-usage,v 1.79 2006/01/07 23:23:12 steve Exp $';
$VERSION = join (' ', (split (' ', $REVISION))[2]);
$VERSION =~ s/,v\b//;
$VERSION =~ s/(\S+)$/$1/;
Ouch.
You might want to review this list of [http://ximbiot.com/cvs/manual/cvs-1.11.6/cvs_12.html#SEC99|CVS Keywords], I think you'll find $Revision$ handy
Classic case of my cutting and pasting some working code into a simpler example. (There's no way this code could be at revision 78!)
I'm aware of $Revision: $, but in my real code I display both date and revision and neglected to simplify this section.
Thanks for the tip anyway, I'm sure other people might appreciate the pointer :)
Ships as part of Perl 5.8
Actually, according to Module-CoreList, it's been part of the Perl distribution since 5.6
I use the module regularly and like it so much I even included it in a lightning talk :-)