Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
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
Replies are listed 'Best First'.
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 pondering the Monastery: (16)
As of 2015-07-30 19:08 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The top three priorities of my open tasks are (in descending order of likelihood to be worked on) ...









    Results (273 votes), past polls