Subject: Version 1.00 of Pod::Parser and Pod::Usage Available on CPAN
From: [email-masked]
Date: 21 Aug 1996 01:02:43 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

Version 1.00 of my PodParser package is now available on CPAN as

    $CPAN/authors/id/BRADAPP/PodParser-1.00.tar.gz

where $CPAN is the leading path to your nearest CPAN site.

PLEASE NOTE that this release replaces my earlier version 0.01
"pre-release" of Pod::Filter, Pod::Usage, and Pod::PlainText.

Below is the appropriate excerpt from the README file. Of most
interest to the largest number of perl scripters will be Pod::Usage.
Folks interested in writing pod2xxxx translators will be interested
in Pod::Parser.

*****************************************************************************

 WHAT IS THIS?
 =============
 This software distribution contains the following packages for using
 Perl5 "pod" (Plain Old Documentation).  See the "perlpod" and "perlsyn"
 manual pages from your Perl5 distribution for more information about pod.

 PodParser
 ---------
   The Perl5 module "Pod::Parser" which provides a base class for
   parsing and selecting sections of pod documentation from an input
   stream.  Please see the pod documentation for this module (embedded
   in the file "Parser.pm") for more details.

 PodSelect
 ---------
   The Perl5 module "Pod::Select" which provides a function to dump
   selected sections of raw pod documentation from an input stream.
   Please see the pod documentation for this module and Pod::Parser for
   more details (embedded in the file "Select.pm").

 PodText
 -------
   A replacement for the Perl5 module "Pod::Text" and the corresponding
   "pod2text()" function. It is derived from the Pod::Parser class.
   Please see the pod documentation for this module and Pod::Parser for
   more details (embedded in the file "Text.pm").

 PodUsage
 --------
   The Perl5 module "Pod::Usage" which provides the function "pod2usage()"
   to print usage messages for a Perl script based on its embedded pod
   documentation.  Please see the pod documentation for this module
   (embedded in the file "Usage.pm") for more details. The pod2usage()
   function is probably the most generally useful function in this entire
   distribution since it is useful for just about any Perl5 script that is
   invoked from the command-line.

*****************************************************************************

Since Pod::Usage is probably the most generally useful of the above
modules, its documentation appears below:

NAME
    pod2usage - print a usage message using a script's embedded pod
                documentation

SYNOPSIS
        use Pod::Usage;
        pod2usage();
        pod2usage(2);
        pod2usage({EXIT => 2});
        pod2usage({EXIT => 2, VERBOSE => 0});
        pod2usage(EXIT => 1, VERBOSE => 2, OUTPUT=\*STDERR);
        pod2usage(VERBOSE => 2);

DESCRIPTION
    pod2usage will print a usage message for the invoking script (using its
    embedded pod documentation) and then exit the script with the specified
    exit value. It takes a single argument which is either a numeric value
    corresponding to the desired exit status (which defaults to 2), or a
    reference to a hash. If more than one argument is given then the entire
    argument list is assumed to be a hash. If a hash is supplied it should
    contain elements with one or more of the following keys:

    `EXIT'
        The desired exit status to pass to the exit() function.

    `VERBOSE'
        The desired level of "verboseness" to use when printing the usage
        message. If the corresponding value is 0, then only the "SYNOPSIS"
        section of the pod documentation is printed. If the corresponding
        value is 1, then the "SYNOPSIS" section, along with any section
        entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is
        printed. If the corresponding value is 2 or more then the entire
        manpage is printed.

    `OUTPUT'
        A reference to a filehandle, or the pathname of a file to which the
        usage message should be written. The default is `\*STDERR' unless
        the exit value is less than 2 (in which case the default is
        `\*STDOUT').

    `INPUT'
        A reference to a filehandle, or the pathname of a file from which
        the invoking script's pod documentation should be read. It defaults
        to the file indicated by `$0' (`$PROGRAM_NAME' for `use English;'
        users).

    If neither the exit value nor the verbose level is specified, then the
    default is to use an exit value of 2 with a verbose level of 0.

    If an exit value is specified but the verbose level is not, then the
    verbose level will default to 1 if the exit value is less than 2 and
    will default to 0 otherwise.

    If a verbose level is specified but an exit value is not, then the exit
    value will default to 2 if the verbose level is 0 and will default to 1
    otherwise.

EXAMPLE
    Most scripts should print some type of usage message to STDERR when a
    command line syntax error is detected. They should also provide an
    option (usually `-h' or `-help') to print a (possibly more verbose)
    usage message to STDOUT. Some scripts may even wish to go so far as to
    provide a means of printing their complete documentation to STDOUT
    (perhaps by allowing a `-man' option). The following example uses
    pod2usage in combination with Getopt::Long to do all of these things:

        use Pod::Usage;
        use Getopt::Long;

        GetOptions("help", "man")  ||  pod2usage(2);
        pod2usage(1)  if ($opt_help);
        pod2usage(VERBOSE => 2)  if ($opt_man);

CAVEATS
    By default, pod2usage() will use `$0' as the path to the pod input file.
    Unfortunately, not all systems on which Perl runs will set `$0' properly
    (although if `$0' isn't found, pod2usage() will search `$ENV{PATH}'). If
    this is the case for your system, you may need to explicitly specify the
    path to the pod docs for the invoking script using something similar to
    the following:

        `pod2usage(EXIT => 2, INPUT => "/path/to/your/pod/docs");'

AUTHOR
    Brad Appleton <[email-masked]>

    Based on code for Pod::Text::pod2text() written by Tom Christiansen
    <[email-masked]>

-- 
 [email-masked]   Motorola AIEG, Northbrook, IL USA
 "And miles to go before I sleep."     DISCLAIMER: I said it, not my employer!