Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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.


In reply to Pod::Usage by skx

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others perusing the Monastery: (6)
    As of 2020-02-17 09:03 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      What numbers are you going to focus on primarily in 2020?










      Results (71 votes). Check out past polls.

      Notices?