Self help in Perl
Archive - Originally posted on "The Horse's Mouth" - 2006-06-14 08:13:11 - Graham EllisPerl's POD (Plain Old Documentation) system provides the programmer with the ability to add user documentation into his programs - allowing a single source file to include:
* The program itself
* Comments for future programmers who read the source
* Documentation for the user
Convertors such as pod2html and pod2man extract the POD documentation from a Perl program and produce HTML and manual pages as required ... and there are other convertors too supplied with Perl or available for download from the CPAN.
Here's an idea for using POD (and the text conversion of it) to provide a usage line and documentation for a perl program also using pod ... a program that generates its own documentation, just using the standard elements of the Perl distribution to do so.
#!/usr/bin/perl
$usage = @ARGV; # Modify this line to suit allowed command line parameters
if ($usage) {
print STDERR "\nUsage: %body% [-h]\n\n";
die `pod2text %body%`;
}
print "normal operation\n";
__END__
=head1 A program that documents itself
Here's a program that gives you a full
scale usage report when you run it ...
=cut