Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Pod::Usage

by skx (Parson)
on Jan 08, 2006 at 13:40 UTC ( #521812=modulereview: print w/ replies, xml ) Need Help??

Item Description: print a usage message from embedded pod documentation

Review Synopsis:

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.

Requirements

None. (Ships as part of Perl 5.8 5.6.)

Who Should Use It

Anybody 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 Points

None 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 ste +ve 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.

Comment on Pod::Usage
Download Code
Re: Pod::Usage
by hossman (Prior) on Jan 08, 2006 at 20:04 UTC
    my $REVISION = '$Id: pod-usage,v 1.79 2006/01/07 23:23:12 steve E +xp $'; $VERSION = join (' ', (split (' ', $REVISION))[2]); $VERSION =~ s/,v\b//; $VERSION =~ s/(\S+)$/$1/;

    Ouch.

    You might want to review this list of 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 :)

      Steve
      --
Re: Pod::Usage
by grantm (Parson) on Jan 09, 2006 at 03:09 UTC
    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 :-)

      Cheers for that, I've updated the node.

      Steve
      --

Back to Reviews

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: modulereview [id://521812]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others surveying the Monastery: (6)
As of 2014-11-27 07:03 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My preferred Perl binaries come from:














    Results (180 votes), past polls