
 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.

 Pod::Parser
 -----------
   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.

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

 Pod::Parser
 ----------
   The Perl5 module "Pod::Parser", which provides a subclass of
   Pod::Parser and an exported function named "podparse()" that lets
   the programmer use callbacks instead of and/or in addition to
   inheritance+polymorphism. This module makes it much easier to
   use Pod::Parser with existing code, and with code that is not
   object-oriented . Please see the POD documentation for this
   module (embedded in the file "Parse.pm") and Pod::Parser for more
   details.

 Pod::Usage
 ----------
   The Perl5 module "Pod::Usage" which provides the function "pod2usage()"
   to print usage messages for a Perl script based on its embedded pod
   documentation. Pod::Usage is a subclass of Pod::PlainText. 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 to just about any Perl5 script that is invoked from the
   command-line.

 Pod::PlainText
 --------------
   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 "PlainText.pm").

   Pod::PlainText and pod2plaintext *can* peacefully co-exist with the
   the current Pod::Text and pod2text of your perl distribution. However,
   IF YOU WANT TO PHYSICALLY REPLACE Pod::Text on your system you can do
   this by making the following changes:

      - Replace 'PlainText' with 'Text' and 'plaintext' with 'text'
        in all *.pm and *.PL files in the PodParser package.

      - Rename 'PlainText.pm' to 'Text.pm' and 'pod2plaintext.PL' to
        'pod2text.PL'.

      - You should probably copy the existing Pod::Text and pod2text files
        in your perl distribution to a new name and/or location before
        overwriting them when you perform 'make install'
 
   YOU PROBABLY DO NOT WANT TO DO THIS!!!! Pod::PlainText only supports
   the subset of POD recognized by Perl 5.002. It DOES NOT yet know
   how to handle some of the newer additions (like =begin/=end). I
   hope to remedy this for a later release.

 AUTHORS/CONTRIBUTORS
 ====================
 Brad Appleton  <bradapp@enteract.com>  http://www.enteract.com/~bradapp/
 (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.

 * Steven McDougall <swmcd@world.std.com> for his help and patience with
   re-writing the manpage for Pod::Usage and Pod::Parser.


 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
 ========
 Please see the file named "MANIFEST" which should have been included
 in the PodParser distribution.


 REQUIREMENTS
 ============
 * Perl version 5.003 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
 <bradapp@enteract.com>.


 TO DO
 =====

 SHORT TERM
 ----------
 * Create a Pod/InputObjects.pm and move the details of input streams
   and interior sequences into appropriately named objects defined
   in this file. THIS MEANS THE INTERFACE TO THESE THINGS WILL CHANGE
   IN THE FUTURE. This shouldnt be too terrible because most people
   don't need to use them.

 * Add the ability to use callbacks _instead_ _of_ inheritance if so
   desired (or mix+match 'em as you wish). This means that there should
   be a way to use callbacks instead of inheritance for the equivalent
   of each of the abstract base class methods that do text processing
   (like preprocess_xxxxx and {begin,end}_xxxx and others). This will go
   into a module named Pod::Callbacks.

 * Do the Makefile.PL right using xsubpp!

 LONG TERM
 ---------
 * 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).

 * 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
 =======
 24-Sep-1997           Brad Appleton                   <bradapp@enteract.com>
 -----------------------------------------------------------------------------
 Version 1.03 (major revision)
 - SIGNIFICANT CHANGES
   * If a POD directive begins with '==' instead of '=', then that line
     is considered a paragraph by itself (you dont need a blank line
     before you begin the next paragraph). NOTE that this only works
     for the *beginning* of a paragraph!! If the '==' begins a line
     in the *middle* of a paragraph, then it receives no special treatment
     and is not considered to be the beginning of a new POD directive).
     If this added convenience seems confusing at first, just remember the
     following phrases:
        "LESS IS MORE" -- LESS equals signs need MORE newlines!
        "MORE IS LESS" -- MORE equals signs need LESS newlines!
     As long as you dont forget that the '=' on a POD directive always
     comes *before* the newline that ends the paragraph (so the '=' is
     associated with the first word of each phrase) you should be fine.

   * The '=pod' command *IS* *NOW* *PASSED* TO Pod::Parser::command()!

   * ALL INSTANCE DATA FIELDS HAVE BEEN RENAMED! Rather than using the new
     field names, you should use the newly provided field access methods to
     get/set private instance data. These are as follows:

         Accessor Method           Old Field Name
       -------------------      -------------------
         cutting()                   CUTTING
         output_file()               OUTFILE
         output_handle()             OUTPUT
         input_file()                INFILE
         input_handle()              INPUT
         total_lines()               LINE
         total_paragraphs()          PARAGRAPH
         input_streams()             INPUT_STACK
         top_stream()                INPUT_TOP
         sequence_commands()         SEQUENCES

   * The last parameter passed to the command() and interior_sequence()
     methods has changed. Please see the documentation!

   * The stack of interior sequences being processed is NO LONGER an
     array of text-strings. It is now an array of hash-refs!

   * Renamed my version of Pod::Text to Pod::PlainText to avoid some nasty
     problems it caused for CPAN.

   * The method Pod::Parser::interpolate() NO LONGER MODIFIES its first
     argument (which means the argument doesnt have to be an l-value)!
     This method is now a wrapper which invokes the new method named
     _interpolate_bottom_up(). This new method *is* recursive and *does*
     modify its first argument.

   * _interpolate_bottom_up() contains a small but ugly *hack* to allow
     '->' and '=>' to remain untouched inside of C<...> without having
     to use the E<gt> escape sequence PROVIDED THAT there is something
     to the left of it OTHER THAN another '-' or '='.

   * The 'select()' and 'want_section()' methods have moved from Pod::Parser
     into Pod::Select.

   * All callback and callback-related methods have moved into the new
     module Pod:::Callbacks (which is NOT YET FINISHED for this release).

 22-May-1997           Brad Appleton                   <bradapp@enteract.com>
 -----------------------------------------------------------------------------
 Version 1.02
 - Added the ability to register callbacks for =xxxx paragraphs and other
   paragraphs. This means that one could (for example) register a temporary
   callback after =item is seen to handle the very next paragraph and then
   unregister itself. The methods added were add_callbacks and rm_callbacks.
   Also, a private method invoke_callbacks was added to go about the business
   of invoking callbacks. The callback mechanism Ive implemented is extremely
   flexible and also way more complex than Id like (and hence requires lots
   more documentation than I would like). Also, the interfaces to add_callbacks
   and rm_callbacks tries to be very flexible in the number and type of
   arguments you can give it. This is probably too flexible to the point
   of being too difficult to figure out how to use. My callback mechanism
   is very powerful but I think the interface to it is lousy and far too
   complex. I am desperately in search of a way to make it smaller and
   simpler without removing too much functionality. If you have any ideas
   about how to do this PLEASE SHARE THEM WITH ME!

 - Got rid of =pod pragmas. P5P has decided to use =for, and =begin/=end
   instead and Ill just handle those like regular commands. NOTE THAT THIS
   MEANS THE command() METHOD SHOULD NOW EXPECT TO BE PASSED =pod COMMANDS.

 - Expanded the documentation for Pod::Usage to be (hopefully) a little less
   confusing regarding the various different invocation styles. Many thanks
   to Steven McDougall <swmcd@world.std.com> for spending many hours of
   assistance toward this goal.

 - Fixed Pod::Text to use the proper indentation for nested '=item' lists
   and to handle consecutive =item paragraphs. (Thank you to Diab Jerious
   <djerius@cfa.harvard.edu> for helping me with this one.)

 - Fixed a bug in Pod::Parser that was causing the argument to =over to be
   a newline instead of the empty string when no "over count" was given.

 05-Sep-1996           Brad Appleton                   <bradapp@enteract.com>
 -----------------------------------------------------------------------------
 Version 1.01
 - Commented out "use diagnostics" in all modules
 - Made use of "use vars"
 - Added the instance variables $self->{INPUT_STACK} and $self->{INPUT_TOP}
   to Pod::Parser and made it possible to use the parse_from_file() and
   parse_from_filehandle methods() to process "included" files (in addition
   to normal pods that dont "include" other files).
 - Added MSG option/key to pod2usage().

 19-Aug-1996           Brad Appleton                   <bradapp@enteract.com>
 -----------------------------------------------------------------------------
 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                   <bradapp@enteract.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).


