
 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 just about any Perl5 script that is
   invoked from the command-line.


 AUTHORS/CONTRIBUTORS
 ====================
 Brad Appleton  <Brad_Appleton-GBDA001@email.mot.com>
 (derived from Pod::Text by Tom Christiansen <tchrist@mox.perl.com>)


 ACKNOWLEDGEMENTS
 ================
 Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126) for his
 extensive assistance with the design and interface of Pod::Parser.

  * Kenneth is currently working on a "Pod::Simplify" module (among
    other things) which is presently available on CPAN although it is
    not yet completed.  Pod::Simplify (formerly "Pod::Parse") is loaded
    with *lots* of goodies for formatting and translation heuristics for
    converting pod docs into other documentation formats.  If it seems
    feasible, Kenneth and Brad will try to have Pod::Simplify be a
    subclass of Pod::Parser when it is completed.


 COPY/REUSE POLICY
 =================
 Copyright (C) 1996 Tom Christiansen. All rights reserved.

 PodParser is free software; you can redistribute it and/or modify it
 under the terms of the Artistic License distributed with Perl version
 5.000 or (at your option) any later version. Please refer to the
 Artistic License that came with your Perl distribution for more
 details.

 The Artistic License should have been included in your distribution of
 Perl. It resides in the file named "Artistic" at the top-level of the
 Perl source tree (where Perl was downloaded/unpacked -- ask your
 system administrator if you dont know where this is).  Alternatively,
 the current version of the Artistic License distributed with Perl can
 be viewed on-line on the World-Wide Web (WWW) from the following URL:

      http://www.perl.com/perl/misc/Artistic.html

 The latest version of Perl can be obtained on the World-Wide web (WWW)
 from the following URL:

      http://www.perl.com/CPAN/src/latest.tar.gz


 DISCLAIMER
 ===========
 This software is distributed in the hope that it will be useful, but
 is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or
 implied, INCLUDING, without limitation, the implied warranties of
 MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.

 The ENTIRE RISK as to the quality and performance of the software
 IS WITH YOU (the holder of the software).  Should the software prove
 defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
 CORRECTION.

 IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE,
 MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO
 ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even
 if they arise from known or unknown flaws in the software).

 Please refer to the Artistic License that came with your Perl
 distribution for more details.


 CONTENTS
 ========
 README       -- This file
 Makefile.PL  -- Perl Makefile template
 Parser.pm    -- The Pod::Parser module source
 Select.pm    -- The Pod::Select module source
 Text.pm      -- The Pod::Text module source
 Usage.pm     -- The Pod::Usage module source
 podselect.PL -- Script to print selected sections of pod docs in raw pod
                 format (a command-line interface to podselect()).
 pod2usage.PL -- Script to print usage from a file's embeded pod docs
                 (a command-line interface to pod2usage()).

 *PLEASE* *NOTE* that no pod2text.PL replacement script is provided since
 the original pod2text.PL provided with Perl5 will continue to work with
 this new version of Pod::Text.


 REQUIREMENTS
 ============
 * Perl version 5.002 or later

 * Getopt::Long version 2.13 or later (podselect.PL and pod2usage.PL only)


 BUILDING & INSTALLING
 =====================
 Please see the perl "ExtUtils::MakeMaker" manpage for how to build and
 install using the Makefile.PL template.  In a nutshell, simply typing:

      perl Makefile.PL

 should build a Makefile with the usual targets like "all", "clean",
 "test", and "install".


 BUGS
 ====
 Please send all bug reports to Brad Appleton
 <Brad_Appleton-GBDA001@email.mot.com>.


 TO DO
 =====
 * Try and get pod2html and pod2man and the other pod2xxx translators to
   use Pod::Parser (so they will all use the same uniform and consistent
   pod parsing engine).

 * Document "=pod" pragmas in the perlpod manpage and implement them for
   Pod::Text, Pod::HTML, etc. ... (or maybe the order of those two should
   be reversed).

 * When and if pod syntax provides some type of file inclusion mechanism
   (like '=include' perhaps) then Pod::Parser will need to perform it,
   and will also need instance data to provide a stack of the current
   filehandles, filenames, line numbers, and paragraph numbers of all
   files that are in the middle of being processed.

 * Make changes necessary to accomodate Kenneth Albanowski's Pod::Simplify
   module so that it may be a subclass of Pod::Parser.

 * See about providing the ability (perhaps via constructor options) to turn
   off certain unwanted Pod::Parser features in order to improve performance
   (things like calling preprocess_xxx() methods and/or some other "virtual"
   member function calls that a subclass might not want to make use of).

 * Try to allow the user to provide a callback function/method which could
   be used in place of the parse_paragraph() method and/or the command(),
   verbatim(), and textblock() methods.  Such a callback might be provided
   as a constructor argument to Pod::Parser.  Perhaps it might be possible
   to pass the callback method an array of lines or of paragraphs (rather
   than one input block at a time) if certain options are specified.


 HISTORY
 =======
 19-Aug-1996           Brad Appleton     <Brad_Appleton-GDBA001@email.mot.com>
 -----------------------------------------------------------------------------
 Released version 1.00 (first "official" release):
  - Renamed Pod::Filter to Pod::Parser at Kenneth Albanowski's recommendation.
  - Moved podselect() into its own separate module Pod::Select to avoid
    unnecessary namespace pollution in Pod::Parser.
  - Renamed several methods and added another preprocessing method in
    Parser.pm.
  - Pod::Parser now keeps track of the current line and paragraph number
    and the current input and output file names.
  - Fixed parse_from_filehandle() to recognize a line matching /^\s+$/ as a
    paragraph terminator.
  - Included Pod::Usage and Pod::Text as part of the PodParser distribution
    rather then packing and releasing each module separately.
  - Removed pod2text.PL and added pod2usage.PL


 07-Aug-1996           Brad Appleton     <Brad_Appleton-GDBA001@email.mot.com>
 -----------------------------------------------------------------------------
 Initial release of version 0.01 to garner some feedback. This release was
 actually three separate "initial" releases of Pod::Parser, Pod::Text, and
 Pod::Usage which were originally named Pod::Filter, Pod::PlainText, and
 Pod::Usage (respectively).


