Upgrade to Pod-Simple-3.06
[p5sagit/p5-mst-13.2.git] / lib / Pod / Simple.pod
1
2 =head1 NAME
3
4 Pod::Simple - framework for parsing Pod
5
6 =head1 SYNOPSIS
7
8  TODO
9
10 =head1 DESCRIPTION
11
12 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
13 documentation") markup language that is typically used for writing
14 documentation for Perl and for Perl modules. The Pod format is explained
15 in the L<perlpod|perlpod> man page; the most common formatter is called
16 "perldoc".
17
18 Pod formatters can use Pod::Simple to parse Pod documents into produce
19 renderings of them in plain ASCII, in HTML, or in any number of other
20 formats. Typically, such formatters will be subclasses of Pod::Simple,
21 and so they will inherit its methods, like C<parse_file>.
22
23 If you're reading this document just because you have a Pod-processing
24 subclass that you want to use, this document (plus the documentation for
25 the subclass) is probably all you'll need to read.
26
27 If you're reading this document because you want to write a formatter
28 subclass, continue reading this document, and then read
29 L<Pod::Simple::Subclassing>, and then possibly even read L<perlpodspec>
30 (some of which is for parser-writers, but much of which is notes to
31 formatter-writers).
32
33
34 =head1 MAIN METHODS
35
36
37
38 =over
39
40 =item C<< $parser = I<SomeClass>->new(); >>
41
42 This returns a new parser object, where I<C<SomeClass>> is a subclass
43 of Pod::Simple.
44
45 =item C<< $parser->output_fh( *OUT ); >>
46
47 This sets the filehandle that C<$parser>'s output will be written to.
48 You can pass C<*STDOUT>, otherwise you should probably do something
49 like this:
50
51     my $outfile = "output.txt";
52     open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
53     $parser->output_fh(*TXTOUT);
54
55 ...before you call one of the C<< $parser->parse_I<whatever> >> methods.
56
57 =item C<< $parser->output_string( \$somestring ); >>
58
59 This sets the string that C<$parser>'s output will be sent to,
60 instead of any filehandle.
61
62
63 =item C<< $parser->parse_file( I<$some_filename> ); >>
64
65 =item C<< $parser->parse_file( *INPUT_FH ); >>
66
67 This reads the Pod content of the file (or filehandle) that you specify,
68 and processes it with that C<$parser> object, according to however
69 C<$parser>'s class works, and according to whatever parser options you
70 have set up for this C<$parser> object.
71
72 =item C<< $parser->parse_string_document( I<$all_content> ); >>
73
74 This works just like C<parse_file> except that it reads the Pod
75 content not from a file, but from a string that you have already
76 in memory.
77
78 =item C<< $parser->parse_lines( I<...@lines...>, undef ); >>
79
80 This processes the lines in C<@lines> (where each list item must be a
81 defined value, and must contain exactly one line of content -- so no
82 items like C<"foo\nbar"> are allowed).  The final C<undef> is used to
83 indicate the end of document being parsed.
84
85 The other C<parser_I<whatever>> methods are meant to be called only once
86 per C<$parser> object; but C<parse_lines> can be called as many times per
87 C<$parser> object as you want, as long as the last call (and only
88 the last call) ends with an C<undef> value.
89
90
91 =item C<< $parser->content_seen >>
92
93 This returns true only if there has been any real content seen
94 for this document.
95
96
97 =item C<< I<SomeClass>->filter( I<$filename> ); >>
98
99 =item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >>
100
101 =item C<< I<SomeClass>->filter( I<\$document_content> ); >>
102
103 This is a shortcut method for creating a new parser object, setting the
104 output handle to STDOUT, and then processing the specified file (or
105 filehandle, or in-memory document). This is handy for one-liners like
106 this:
107
108   perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
109
110 =back
111
112
113
114 =head1 SECONDARY METHODS
115
116 Some of these methods might be of interest to general users, as
117 well as of interest to formatter-writers.
118
119 Note that the general pattern here is that the accessor-methods
120 read the attribute's value with C<< $value = $parser->I<attribute> >>
121 and set the attribute's value with
122 C<< $parser->I<attribute>(I<newvalue>) >>.  For each accessor, I typically
123 only mention one syntax or another, based on which I think you are actually
124 most likely to use.
125
126
127 =over
128
129 =item C<< $parser->no_whining( I<SOMEVALUE> ) >>
130
131 If you set this attribute to a true value, you will suppress the
132 parser's complaints about irregularities in the Pod coding. By default,
133 this attribute's value is false, meaning that irregularities will
134 be reported.
135
136 Note that turning this attribute to true won't suppress one or two kinds
137 of complaints about rarely occurring unrecoverable errors.
138
139
140 =item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
141
142 If you set this attribute to a true value, you will stop the parser from
143 generating a "POD ERRORS" section at the end of the document. By
144 default, this attribute's value is false, meaning that an errata section
145 will be generated, as necessary.
146
147
148 =item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
149
150 If you set this attribute to a true value, it will send reports of
151 parsing errors to STDERR. By default, this attribute's value is false,
152 meaning that no output is sent to STDERR.
153
154 Note that errors can be noted in an errata section, or sent to STDERR,
155 or both, or neither. So don't think that turning on C<complain_stderr>
156 will turn off C<no_errata_section> or vice versa -- these are
157 independent attributes.
158
159
160 =item C<< $parser->source_filename >>
161
162 This returns the filename that this parser object was set to read from.
163
164
165 =item C<< $parser->doc_has_started >>
166
167 This returns true if C<$parser> has read from a source, and has seen
168 Pod content in it.
169
170
171 =item C<< $parser->source_dead >>
172
173 This returns true if C<$parser> has read from a source, and come to the
174 end of that source.
175
176 =back
177
178
179 =head1 CAVEATS
180
181 This is just a beta release -- there are a good number of things still
182 left to do.  Notably, support for EBCDIC platforms is still half-done,
183 an untested.
184
185
186 =head1 SEE ALSO
187
188 L<Pod::Simple::Subclassing>
189
190 L<perlpod|perlpod>
191
192 L<perlpodspec|perlpodspec>
193
194 L<Pod::Escapes|Pod::Escapes>
195
196 L<perldoc>
197
198
199 =head1 COPYRIGHT AND DISCLAIMERS
200
201 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
202
203 This library is free software; you can redistribute it and/or modify it
204 under the same terms as Perl itself.
205
206 This program is distributed in the hope that it will be useful, but
207 without any warranty; without even the implied warranty of
208 merchantability or fitness for a particular purpose.
209
210 =head1 AUTHOR
211
212 Original author: Sean M. Burke C<sburke@cpan.org>
213
214 Maintained by: 
215
216 =over
217
218 =item * Allison Randal C<allison@perl.org>
219
220 =item * Hans Dieter Pearcey C<hdp@cpan.org>
221
222 =back
223
224 =cut
225
226