1Pod::Simple(3pm)       Perl Programmers Reference Guide       Pod::Simple(3pm)
2
3
4

NAME

6       Pod::Simple - framework for parsing Pod
7

SYNOPSIS

9        TODO
10

DESCRIPTION

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
15       explained perlpod; the most common formatter is called "perldoc".
16
17       Pod formatters can use Pod::Simple to parse Pod documents and render
18       them into plain text, HTML, or any number of other formats. Typically,
19       such formatters will be subclasses of Pod::Simple, and so they will
20       inherit its methods, like "parse_file".
21
22       If you're reading this document just because you have a Pod-processing
23       subclass that you want to use, this document (plus the documentation
24       for the subclass) is probably all you need to read.
25
26       If you're reading this document because you want to write a formatter
27       subclass, continue reading it and then read Pod::Simple::Subclassing,
28       and then possibly even read perlpodspec (some of which is for parser-
29       writers, but much of which is notes to formatter-writers).
30

MAIN METHODS

32       "$parser = I<SomeClass>->new();"
33           This returns a new parser object, where "SomeClass" is a subclass
34           of Pod::Simple.
35
36       "$parser->output_fh( *OUT );"
37           This sets the filehandle that $parser's output will be written to.
38           You can pass *STDOUT, otherwise you should probably do something
39           like this:
40
41               my $outfile = "output.txt";
42               open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
43               $parser->output_fh(*TXTOUT);
44
45           ...before you call one of the "$parser->parse_I<whatever>" methods.
46
47       "$parser->output_string( \$somestring );"
48           This sets the string that $parser's output will be sent to, instead
49           of any filehandle.
50
51       "$parser->parse_file( I<$some_filename> );"
52       "$parser->parse_file( *INPUT_FH );"
53           This reads the Pod content of the file (or filehandle) that you
54           specify, and processes it with that $parser object, according to
55           however $parser's class works, and according to whatever parser
56           options you have set up for this $parser object.
57
58       "$parser->parse_string_document( I<$all_content> );"
59           This works just like "parse_file" except that it reads the Pod
60           content not from a file, but from a string that you have already in
61           memory.
62
63       "$parser->parse_lines( I<...@lines...>, undef );"
64           This processes the lines in @lines (where each list item must be a
65           defined value, and must contain exactly one line of content -- so
66           no items like "foo\nbar" are allowed).  The final "undef" is used
67           to indicate the end of document being parsed.
68
69           The other "parser_whatever" methods are meant to be called only
70           once per $parser object; but "parse_lines" can be called as many
71           times per $parser object as you want, as long as the last call (and
72           only the last call) ends with an "undef" value.
73
74       "$parser->content_seen"
75           This returns true only if there has been any real content seen for
76           this document.
77
78       "I<SomeClass>->filter( I<$filename> );"
79       "I<SomeClass>->filter( I<*INPUT_FH> );"
80       "I<SomeClass>->filter( I<\$document_content> );"
81           This is a shortcut method for creating a new parser object, setting
82           the output handle to STDOUT, and then processing the specified file
83           (or filehandle, or in-memory document). This is handy for one-
84           liners like this:
85
86             perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
87

SECONDARY METHODS

89       Some of these methods might be of interest to general users, as well as
90       of interest to formatter-writers.
91
92       Note that the general pattern here is that the accessor-methods read
93       the attribute's value with "$value = $parser->I<attribute>" and set the
94       attribute's value with "$parser->I<attribute>(I<newvalue>)".  For each
95       accessor, I typically only mention one syntax or another, based on
96       which I think you are actually most likely to use.
97
98       "$parser->no_whining( I<SOMEVALUE> )"
99           If you set this attribute to a true value, you will suppress the
100           parser's complaints about irregularities in the Pod coding. By
101           default, this attribute's value is false, meaning that
102           irregularities will be reported.
103
104           Note that turning this attribute to true won't suppress one or two
105           kinds of complaints about rarely occurring unrecoverable errors.
106
107       "$parser->no_errata_section( I<SOMEVALUE> )"
108           If you set this attribute to a true value, you will stop the parser
109           from generating a "POD ERRORS" section at the end of the document.
110           By default, this attribute's value is false, meaning that an errata
111           section will be generated, as necessary.
112
113       "$parser->complain_stderr( I<SOMEVALUE> )"
114           If you set this attribute to a true value, it will send reports of
115           parsing errors to STDERR. By default, this attribute's value is
116           false, meaning that no output is sent to STDERR.
117
118           Setting "complain_stderr" also sets "no_errata_section".
119
120       "$parser->source_filename"
121           This returns the filename that this parser object was set to read
122           from.
123
124       "$parser->doc_has_started"
125           This returns true if $parser has read from a source, and has seen
126           Pod content in it.
127
128       "$parser->source_dead"
129           This returns true if $parser has read from a source, and come to
130           the end of that source.
131
132       "$parser->strip_verbatim_indent( I<SOMEVALUE> )"
133           The perlpod spec for a Verbatim paragraph is "It should be
134           reproduced exactly...", which means that the whitespace you've used
135           to indent your verbatim blocks will be preserved in the output.
136           This can be annoying for outputs such as HTML, where that
137           whitespace will remain in front of every line. It's an unfortunate
138           case where syntax is turned into semantics.
139
140           If the POD your parsing adheres to a consistent indentation policy,
141           you can have such indentation stripped from the beginning of every
142           line of your verbatim blocks. This method tells Pod::Simple what to
143           strip. For two-space indents, you'd use:
144
145             $parser->strip_verbatim_indent('  ');
146
147           For tab indents, you'd use a tab character:
148
149             $parser->strip_verbatim_indent("\t");
150
151           If the POD is inconsistent about the indentation of verbatim
152           blocks, but you have figured out a heuristic to determine how much
153           a particular verbatim block is indented, you can pass a code
154           reference instead. The code reference will be executed with one
155           argument, an array reference of all the lines in the verbatim
156           block, and should return the value to be stripped from each line.
157           For example, if you decide that you're fine to use the first line
158           of the verbatim block to set the standard for indentation of the
159           rest of the block, you can look at the first line and return the
160           appropriate value, like so:
161
162             $new->strip_verbatim_indent(sub {
163                 my $lines = shift;
164                 (my $indent = $lines->[0]) =~ s/\S.*//;
165                 return $indent;
166             });
167
168           If you'd rather treat each line individually, you can do that, too,
169           by just transforming them in-place in the code reference and
170           returning "undef". Say that you don't want any lines indented. You
171           can do something like this:
172
173             $new->strip_verbatim_indent(sub {
174                 my $lines = shift;
175                 sub { s/^\s+// for @{ $lines },
176                 return undef;
177             });
178

CAVEATS

180       This is just a beta release -- there are a good number of things still
181       left to do.  Notably, support for EBCDIC platforms is still half-done,
182       an untested.
183

SEE ALSO

185       Pod::Simple::Subclassing
186
187       perlpod
188
189       perlpodspec
190
191       Pod::Escapes
192
193       perldoc
194

SUPPORT

196       Questions or discussion about POD and Pod::Simple should be sent to the
197       pod-people@perl.org mail list. Send an empty email to
198       pod-people-subscribe@perl.org to subscribe.
199
200       This module is managed in an open GitHub repository,
201       <http://github.com/theory/pod-simple/>. Feel free to fork and
202       contribute, or to clone <git://github.com/theory/pod-simple.git> and
203       send patches!
204
205       Patches against Pod::Simple are welcome. Please send bug reports to
206       <bug-pod-simple@rt.cpan.org>.
207
209       Copyright (c) 2002 Sean M. Burke.
210
211       This library is free software; you can redistribute it and/or modify it
212       under the same terms as Perl itself.
213
214       This program is distributed in the hope that it will be useful, but
215       without any warranty; without even the implied warranty of
216       merchantability or fitness for a particular purpose.
217

AUTHOR

219       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
220       bother him, he's retired.
221
222       Pod::Simple is maintained by:
223
224       ·   Allison Randal "allison@perl.org"
225
226       ·   Hans Dieter Pearcey "hdp@cpan.org"
227
228       ·   David E. Wheeler "dwheeler@cpan.org"
229
230
231
232perl v5.10.1                      2017-03-22                  Pod::Simple(3pm)
Impressum