1Pod::Checker(3pm) Perl Programmers Reference Guide Pod::Checker(3pm)
2
6 Pod::Checker, podchecker() - check pod documents for syntax errors
7
9 use Pod::Checker;
10 $syntax_okay = podchecker($filepath, $outputpath, %options);
12 my $checker = new Pod::Checker %options;
14 $checker->parse_from_file($filepath, \*STDERR);
15
17 $filepath is the input POD to read and $outputpath is where to write
18 POD syntax error messages. Either argument may be a scalar indicating a
19 file-path, or else a reference to an open filehandle. If unspecified,
20 the input-file it defaults to "\*STDIN", and the output-file defaults
21 to "\*STDERR".
22 podchecker()
24 This function can take a hash of options:
26 -warnings => val
28 Turn warnings on/off. val is usually 1 for on, but higher values
29 trigger additional warnings. See "Warnings".
30
32 podchecker will perform syntax checking of Perl5 POD format documenta‐
33 tion.
34 Curious/ambitious users are welcome to propose additional features they
36 wish to see in Pod::Checker and podchecker and verify that the checks
37 are consistent with perlpod.
38 The following checks are currently performed:
40 · Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and
42 unterminated interior sequences.
43 · Check for proper balancing of "=begin" and "=end". The contents of
45 such a block are generally ignored, i.e. no syntax checks are per‐
46 formed.
47 · Check for proper nesting and balancing of "=over", "=item" and
49 "=back".
50 · Check for same nested interior-sequences (e.g. "L<...L<...>...>").
52 · Check for malformed or nonexisting entities "E<...>".
54 · Check for correct syntax of hyperlinks "L<...>". See perlpod for
56 details.
57 · Check for unresolved document-internal links. This check may also
59 reveal misspelled links that seem to be internal links but should
60 be links to something else.
61
63 Errors
64 * empty =headn
66 A heading ("=head1" or "=head2") without any text? That ain't no
67 heading!
68 * =over on line N without closing =back
70 The "=over" command does not have a corresponding "=back" before
71 the next heading ("=head1" or "=head2") or the end of the file.
72 * =item without previous =over
74 * =back without previous =over
75 An "=item" or "=back" command has been found outside a
76 "=over"/"=back" block.
77 * No argument for =begin
79 A "=begin" command was found that is not followed by the formatter
80 specification.
81 * =end without =begin
83 A standalone "=end" command was found.
84 * Nested =begin's
86 There were at least two consecutive "=begin" commands without the
87 corresponding "=end". Only one "=begin" may be active at a time.
88 * =for without formatter specification
90 There is no specification of the formatter after the "=for" com‐
91 mand.
92 * unresolved internal link NAME
94 The given link to NAME does not have a matching node in the current
95 POD. This also happend when a single word node name is not enclosed
96 in "".
97 * Unknown command "CMD"
99 An invalid POD command has been found. Valid are "=head1",
100 "=head2", "=head3", "=head4", "=over", "=item", "=back", "=begin",
101 "=end", "=for", "=pod", "=cut"
102 * Unknown interior-sequence "SEQ"
104 An invalid markup command has been encountered. Valid are: "B<>",
105 "C<>", "E<>", "F<>", "I<>", "L<>", "S<>", "X<>", "Z<>"
106 * nested commands CMD<...CMD<...>...>
108 Two nested identical markup commands have been found. Generally
109 this does not make sense.
110 * garbled entity STRING
112 The STRING found cannot be interpreted as a character entity.
113 * Entity number out of range
115 An entity specified by number (dec, hex, oct) is out of range
116 (1-255).
117 * malformed link L<>
119 The link found cannot be parsed because it does not conform to the
120 syntax described in perlpod.
121 * nonempty Z<>
123 The "Z<>" sequence is supposed to be empty.
124 * empty X<>
126 The index entry specified contains nothing but whitespace.
127 * Spurious text after =pod / =cut
129 The commands "=pod" and "=cut" do not take any arguments.
130 * Spurious character(s) after =back
132 The "=back" command does not take any arguments.
133 Warnings
135 These may not necessarily cause trouble, but indicate mediocre style.
137 * multiple occurrence of link target name
139 The POD file has some "=item" and/or "=head" commands that have the
140 same text. Potential hyperlinks to such a text cannot be unique
141 then. This warning is printed only with warning level greater than
142 one.
143 * line containing nothing but whitespace in paragraph
145 There is some whitespace on a seemingly empty line. POD is very
146 sensitive to such things, so this is flagged. vi users switch on
147 the list option to avoid this problem.
148 * previous =item has no contents
150 There is a list "=item" right above the flagged line that has no
151 text contents. You probably want to delete empty items.
152 * preceding non-item paragraph(s)
154 A list introduced by "=over" starts with a text or verbatim para‐
155 graph, but continues with "=item"s. Move the non-item paragraph out
156 of the "=over"/"=back" block.
157 * =item type mismatch (one vs. two)
159 A list started with e.g. a bulletted "=item" and continued with a
160 numbered one. This is obviously inconsistent. For most translators
161 the type of the first "=item" determines the type of the list.
162 * N unescaped "<>" in paragraph
164 Angle brackets not written as "<lt>" and "<gt>" can potentially
165 cause errors as they could be misinterpreted as markup commands.
166 This is only printed when the -warnings level is greater than 1.
167 * Unknown entity
169 A character entity was found that does not belong to the standard
170 ISO set or the POD specials "verbar" and "sol".
171 * No items in =over
173 The list opened with "=over" does not contain any items.
174 * No argument for =item
176 "=item" without any parameters is deprecated. It should either be
177 followed by "*" to indicate an unordered list, by a number (option‐
178 ally followed by a dot) to indicate an ordered (numbered) list or
179 simple text for a definition list.
180 * empty section in previous paragraph
182 The previous section (introduced by a "=head" command) does not
183 contain any text. This usually indicates that something is missing.
184 Note: A "=head1" followed immediately by "=head2" does not trigger
185 this warning.
186 * Verbatim paragraph in NAME section
188 The NAME section ("=head1 NAME") should consist of a single para‐
189 graph with the script/module name, followed by a dash `-' and a
190 very short description of what the thing is good for.
191 * =headn without preceding higher level
193 For example if there is a "=head2" in the POD file prior to a
194 "=head1".
195 Hyperlinks
197 There are some warnings wrt. malformed hyperlinks.
199 * ignoring leading/trailing whitespace in link
201 There is whitespace at the beginning or the end of the contents of
202 L<...>.
203 * (section) in '$page' deprecated
205 There is a section detected in the page name of L<...>, e.g.
206 "L<passwd(2)>". POD hyperlinks may point to POD documents only.
207 Please write "C<passwd(2)>" instead. Some formatters are able to
208 expand this to appropriate code. For links to (builtin) functions,
209 please say "L<perlfunc/mkdir>", without ().
210 * alternative text/node '%s' contains non-escaped ⎪ or /
212 The characters "⎪" and "/" are special in the L<...> context.
213 Although the hyperlink parser does its best to determine which "/"
214 is text and which is a delimiter in case of doubt, one ought to
215 escape these literal characters like this:
216 / E<sol>
218 ⎪ E<verbar>
219
221 podchecker returns the number of POD syntax errors found or -1 if there
222 were no POD commands at all found in the file.
223
225 See "SYNOPSIS"
226
228 While checking, this module collects document properties, e.g. the
229 nodes for hyperlinks ("=headX", "=item") and index entries ("X<>").
230 POD translators can use this feature to syntax-check and get the nodes
231 in a first pass before actually starting to convert. This is expensive
232 in terms of execution time, but allows for very robust conversions.
233 Since PodParser-1.24 the Pod::Checker module uses only the poderror
235 method to print errors and warnings. The summary output (e.g. "Pod
236 syntax OK") has been dropped from the module and has been included in
237 podchecker (the script). This allows users of Pod::Checker to control
238 completely the output behaviour. Users of podchecker (the script) get
239 the well-known behaviour.
240 "Pod::Checker->new( %options )"
242 Return a reference to a new Pod::Checker object that inherits from
243 Pod::Parser and is used for calling the required methods later. The
244 following options are recognized:
245 "-warnings => num"
247 Print warnings if "num" is true. The higher the value of "num",
248 the more warnings are printed. Currently there are only levels 1
249 and 2.
250 "-quiet => num"
252 If "num" is true, do not print any errors/warnings. This is use‐
253 ful when Pod::Checker is used to munge POD code into plain text
254 from within POD formatters.
255 "$checker->poderror( @args )"
257 "$checker->poderror( {%opts}, @args )"
258 Internal method for printing errors and warnings. If no options are
259 given, simply prints "@_". The following options are recognized and
260 used to form the output:
261 -msg
263 A message to print prior to @args.
265 -line
267 The line number the error occurred in.
269 -file
271 The file (name) the error occurred in.
273 -severity
275 The error level, should be 'WARNING' or 'ERROR'.
277 "$checker->num_errors()"
279 Set (if argument specified) and retrieve the number of errors
280 found.
281 "$checker->num_warnings()"
283 Set (if argument specified) and retrieve the number of warnings
284 found.
285 "$checker->name()"
287 Set (if argument specified) and retrieve the canonical name of POD
288 as found in the "=head1 NAME" section.
289 "$checker->node()"
291 Add (if argument specified) and retrieve the nodes (as defined by
292 "=headX" and "=item") of the current POD. The nodes are returned in
293 the order of their occurrence. They consist of plain text, each
294 piece of whitespace is collapsed to a single blank.
295 "$checker->idx()"
297 Add (if argument specified) and retrieve the index entries (as
298 defined by "X<>") of the current POD. They consist of plain text,
299 each piece of whitespace is collapsed to a single blank.
300 "$checker->hyperlink()"
302 Add (if argument specified) and retrieve the hyperlinks (as defined
303 by "L<>") of the current POD. They consist of a 2-item array: line
304 number and "Pod::Hyperlink" object.
305
307 Please report bugs using <http://rt.cpan.org>.
308 Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal
310 <marekr@cpan.org>
311 Based on code for Pod::Text::pod2text() written by Tom Christiansen
313 <tchrist@mox.perl.com>
314perl v5.8.8 2001-09-21 Pod::Checker(3pm)