Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery


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.


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.

#!/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: --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 -- $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; } }

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.

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/;


    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 :)

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.

Log In?

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

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (5)
As of 2023-03-27 07:25 GMT
Find Nodes?
    Voting Booth?
    Which type of climate do you prefer to live in?

    Results (63 votes). Check out past polls.