Commit | Line | Data |
351625bd |
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 | |
69473a20 |
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 |
351625bd |
223 | |
224 | =cut |
225 | |
226 | |