README
1
2 WHAT IS THIS?
3 =============
4 This software distribution contains the following packages for using
5 Perl5 "pod" (Plain Old Documentation). See the "perlpod" and "perlsyn"
6 manual pages from your Perl5 distribution for more information about pod.
7
8 DISCLAIMER
9 ----------
10 This package is considered to be legacy - it has been superseded by
11 Pod::Simple which brings more robustness, unicode and various other
12 benefits. If you are building anything new, please consider using
13 Pod::Simple, not this package.
14
15 Pod::Parser
16 -----------
17 The Perl5 module "Pod::Parser", which provides a base class for
18 parsing and selecting sections of POD documentation from an input
19 stream. Please see the POD documentation for this module (embedded
20 in the file "Parser.pm") for more details.
21
22 Pod::Select
23 -----------
24 The Perl5 module "Pod::Select", which provides a subclass of
25 Pod::Parser and an exported function named "podselect()" to dump
26 selected sections of raw pod documentation from an input stream.
27 Please see the POD documentation for this module (embedded in the
28 file "Select.pm") and Pod::Parser for more details.
29
30 Pod::PlainText
31 --------------
32 A replacement for the Perl5 module "Pod::Text" and the corresponding
33 "pod2text()" function. It is derived from the Pod::Parser class.
34 Please see the POD documentation for this module and Pod::Parser for
35 more details (embedded in the file "PlainText.pm").
36
37 *NOTE*: As of perl 5.00_58, Pod::PlainText has been re-written by
38 Russ Allbery, and has been renamed to Pod::Text in the core Perl
39 distribution (replacing the previous implementation of Pod::Text).
40 The Pod::PlainText module is still provided with Pod::Parser on CPAN
41 solely for backward compatibility. Once Perl 5.6 becomes the latest
42 stable version of Perl, then Pod::PlainText will be removed from the
43 Pod-Parser distribution!!
44
45 Pod::InputObjects
46 -----------------
47 Some input objects needed by Pod::Parser, and for advanced users of
48 Pod::Parser that need more about a command besides its name and text.
49
50 Pod::ParseUtils
51 ---------------
52 A module with several object-oriented helpers for POD parsing and
53 processing. Probably the most important is Pod::Hyperlink for
54 parsing and expanding POD hyperlinks L<...>.
55
56
57 AUTHORS/CONTRIBUTORS
58 ====================
59 Marek Rouchal <marekr@cpan.org>
60 Brad Appleton <bradapp@enteract.com> http://www.enteract.com/~bradapp/
61 Russ Allbery <rra@standford.edu>
62
63
64 ACKNOWLEDGEMENTS
65 ================
66 * Kenneth Albanowski for his extensive assistance with the design and
67 interface of Pod::Parser.
68
69 * Steven McDougall for his help and patience with re-writing the manpage
70 for Pod::Usage and Pod::Parser.
71
72 * Achim Bonnet for helping me get the regression test-suite into a form
73 that works with 'make test' generated by MakeMaker
74
75 * Nick Ing-Simmons, for his considerable time and effort spent trying to
76 make pre-release versions of Pod::Parser work with code and giving me
77 feedback on the implementation and design.
78
79 * Russ Allbery for re-writing Pod::PlainText from scratch and getting it
80 to replace Pod::Text in the core for perl 5.00_58!
81
82 COPY/REUSE POLICY
83 =================
84 Except where explicitly stated otherwise within the contents of a file,
85 this distribution and all the files in it are Copyright (C) 1996-1999
86 by Brad Appleton. All rights reserved.
87
88 Pod-Parser is free software; you can redistribute it and/or modify it
89 under the terms of the Artistic License distributed with Perl version
90 5.000 or (at your option) any later version. Please refer to the
91 Artistic License that came with your Perl distribution for more
92 details. If your version of Perl was not distributed under the
93 terms of the Artistic License, than you may distribute Pod-Parser
94 under the same terms as Perl itself.
95
96 The Artistic License should have been included in your distribution of
97 Perl. It resides in the file named "Artistic" at the top-level of the
98 Perl source tree (where Perl was downloaded/unpacked -- ask your
99 system administrator if you dont know where this is). Alternatively,
100 the current version of the Artistic License distributed with Perl can
101 be viewed on-line on the World-Wide Web (WWW) from the following URL:
102
103 http://www.perl.com/perl/misc/Artistic.html
104
105 The latest version of Perl can be obtained on the World-Wide web (WWW)
106 from the following URL:
107
108 http://www.perl.com/CPAN/src/latest.tar.gz
109
110
111 DISCLAIMER pt 2
112 ===============
113 This software is distributed in the hope that it will be useful, but
114 is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or
115 implied, INCLUDING, without limitation, the implied warranties of
116 MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.
117
118 The ENTIRE RISK as to the quality and performance of the software
119 IS WITH YOU (the holder of the software). Should the software prove
120 defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
121 CORRECTION.
122
123 IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE,
124 MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO
125 ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even
126 if they arise from known or unknown flaws in the software).
127
128 Please refer to the Artistic License that came with your Perl
129 distribution for more details.
130
131
132 CONTENTS
133 ========
134 Please see the file named "MANIFEST" which should have been included
135 in the Pod-Parser distribution.
136
137
138 REQUIREMENTS
139 ============
140 * Perl version 5.005 or later
141
142 * File::Spec from CPAN (already bundled in Perl 5.005)
143 at least version 0.82, previous ones lack some functions needed here
144
145
146 BUILDING & INSTALLING
147 =====================
148 Please see the perl "ExtUtils::MakeMaker" manpage for how to build and
149 install using the Makefile.PL template. In a nutshell, simply typing:
150
151 perl Makefile.PL
152
153 should build a Makefile with the usual targets like "all", "clean",
154 "test", and "install".
155
156
157 BUGS
158 ====
159 Please use the CPAN bug tracking to report bugs:
160 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pod-Parser
161
162 TO DO
163 =====
164 Please see the file named "TODO" which should have been included
165 in the Pod-Parser distribution.
166
167 HISTORY
168 =======
169 Please see the file named "CHANGES" which should have been included
170 in the Pod-Parser distribution.
171
172