1Pod::Checker(3) User Contributed Perl Documentation Pod::Checker(3)
2
6 Pod::Checker, podchecker() - check pod documents for syntax errors
7
9 use Pod::Checker;
10 $num_errors = 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:
25 -warnings => val
27 Turn warnings on/off. val is usually 1 for on, but higher values
28 trigger additional warnings. See "Warnings".
29
31 podchecker will perform syntax checking of Perl5 POD format
32 documentation.
33 Curious/ambitious users are welcome to propose additional features they
35 wish to see in Pod::Checker and podchecker and verify that the checks
36 are consistent with perlpod.
37 The following checks are currently performed:
39 · Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and
41 unterminated interior sequences.
42 · Check for proper balancing of "=begin" and "=end". The contents of
44 such a block are generally ignored, i.e. no syntax checks are
45 performed.
46 · Check for proper nesting and balancing of "=over", "=item" and
48 "=back".
49 · Check for same nested interior-sequences (e.g. "L<...L<...>...>").
51 · Check for malformed or non-existing entities "E<...>".
53 · Check for correct syntax of hyperlinks "L<...>". See perlpod for
55 details.
56 · Check for unresolved document-internal links. This check may also
58 reveal misspelled links that seem to be internal links but should
59 be links to something else.
60
62 Errors
63 · empty =headn
64 A heading ("=head1" or "=head2") without any text? That ain't no
66 heading!
67 · =over on line N without closing =back
69 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
76 An "=item" or "=back" command has been found outside a
78 "=over"/"=back" block.
79 · No argument for =begin
81 A "=begin" command was found that is not followed by the formatter
83 specification.
84 · =end without =begin
86 A standalone "=end" command was found.
88 · Nested =begin's
90 There were at least two consecutive "=begin" commands without the
92 corresponding "=end". Only one "=begin" may be active at a time.
93 · =for without formatter specification
95 There is no specification of the formatter after the "=for"
97 command.
98 · Apparent command =foo not preceded by blank line
100 A command which has ended up in the middle of a paragraph or other
102 command, such as
103 =item one
105 =item two <-- bad
106 · unresolved internal link NAME
108 The given link to NAME does not have a matching node in the current
110 POD. This also happened when a single word node name is not
111 enclosed in "".
112 · Unknown command "CMD"
114 An invalid POD command has been found. Valid are "=head1",
116 "=head2", "=head3", "=head4", "=over", "=item", "=back", "=begin",
117 "=end", "=for", "=pod", "=cut"
118 · Unknown interior-sequence "SEQ"
120 An invalid markup command has been encountered. Valid are: "B<>",
122 "C<>", "E<>", "F<>", "I<>", "L<>", "S<>", "X<>", "Z<>"
123 · nested commands CMD<...CMD<...>...>
125 Two nested identical markup commands have been found. Generally
127 this does not make sense.
128 · garbled entity STRING
130 The STRING found cannot be interpreted as a character entity.
132 · Entity number out of range
134 An entity specified by number (dec, hex, oct) is out of range
136 (1-255).
137 · malformed link L<>
139 The link found cannot be parsed because it does not conform to the
141 syntax described in perlpod.
142 · nonempty Z<>
144 The "Z<>" sequence is supposed to be empty.
146 · empty X<>
148 The index entry specified contains nothing but whitespace.
150 · Spurious text after =pod / =cut
152 The commands "=pod" and "=cut" do not take any arguments.
154 · Spurious =cut command
156 A "=cut" command was found without a preceding POD paragraph.
158 · Spurious =pod command
160 A "=pod" command was found after a preceding POD paragraph.
162 · Spurious character(s) after =back
164 The "=back" command does not take any arguments.
166 Warnings
168 These may not necessarily cause trouble, but indicate mediocre style.
169 · multiple occurrence of link target name
171 The POD file has some "=item" and/or "=head" commands that have the
173 same text. Potential hyperlinks to such a text cannot be unique
174 then. This warning is printed only with warning level greater than
175 one.
176 · line containing nothing but whitespace in paragraph
178 There is some whitespace on a seemingly empty line. POD is very
180 sensitive to such things, so this is flagged. vi users switch on
181 the list option to avoid this problem.
182 · previous =item has no contents
184 There is a list "=item" right above the flagged line that has no
186 text contents. You probably want to delete empty items.
187 · preceding non-item paragraph(s)
189 A list introduced by "=over" starts with a text or verbatim
191 paragraph, but continues with "=item"s. Move the non-item paragraph
192 out of the "=over"/"=back" block.
193 · =item type mismatch (one vs. two)
195 A list started with e.g. a bullet-like "=item" and continued with a
197 numbered one. This is obviously inconsistent. For most translators
198 the type of the first "=item" determines the type of the list.
199 · N unescaped "<>" in paragraph
201 Angle brackets not written as "<lt>" and "<gt>" can potentially
203 cause errors as they could be misinterpreted as markup commands.
204 This is only printed when the -warnings level is greater than 1.
205 · Unknown entity
207 A character entity was found that does not belong to the standard
209 ISO set or the POD specials "verbar" and "sol".
210 · No items in =over
212 The list opened with "=over" does not contain any items.
214 · No argument for =item
216 "=item" without any parameters is deprecated. It should either be
218 followed by "*" to indicate an unordered list, by a number
219 (optionally followed by a dot) to indicate an ordered (numbered)
220 list or simple text for a definition list.
221 · empty section in previous paragraph
223 The previous section (introduced by a "=head" command) does not
225 contain any text. This usually indicates that something is missing.
226 Note: A "=head1" followed immediately by "=head2" does not trigger
227 this warning.
228 · Verbatim paragraph in NAME section
230 The NAME section ("=head1 NAME") should consist of a single
232 paragraph with the script/module name, followed by a dash `-' and a
233 very short description of what the thing is good for.
234 · =headn without preceding higher level
236 For example if there is a "=head2" in the POD file prior to a
238 "=head1".
239 Hyperlinks
241 There are some warnings with respect to malformed hyperlinks:
242 · ignoring leading/trailing whitespace in link
244 There is whitespace at the beginning or the end of the contents of
246 L<...>.
247 · (section) in '$page' deprecated
249 There is a section detected in the page name of L<...>, e.g.
251 "L<passwd(2)>". POD hyperlinks may point to POD documents only.
252 Please write "C<passwd(2)>" instead. Some formatters are able to
253 expand this to appropriate code. For links to (builtin) functions,
254 please say "L<perlfunc/mkdir>", without ().
255 · alternative text/node '%s' contains non-escaped | or /
257 The characters "|" and "/" are special in the L<...> context.
259 Although the hyperlink parser does its best to determine which "/"
260 is text and which is a delimiter in case of doubt, one ought to
261 escape these literal characters like this:
262 / E<sol>
264 | E<verbar>
265
267 podchecker returns the number of POD syntax errors found or -1 if there
268 were no POD commands at all found in the file.
269
271 See "SYNOPSIS"
272
274 While checking, this module collects document properties, e.g. the
275 nodes for hyperlinks ("=headX", "=item") and index entries ("X<>").
276 POD translators can use this feature to syntax-check and get the nodes
277 in a first pass before actually starting to convert. This is expensive
278 in terms of execution time, but allows for very robust conversions.
279 Since PodParser-1.24 the Pod::Checker module uses only the poderror
281 method to print errors and warnings. The summary output (e.g. "Pod
282 syntax OK") has been dropped from the module and has been included in
283 podchecker (the script). This allows users of Pod::Checker to control
284 completely the output behavior. Users of podchecker (the script) get
285 the well-known behavior.
286 "Pod::Checker->new( %options )"
288 Return a reference to a new Pod::Checker object that inherits from
289 Pod::Parser and is used for calling the required methods later. The
290 following options are recognized:
291 "-warnings => num"
293 Print warnings if "num" is true. The higher the value of "num",
294 the more warnings are printed. Currently there are only levels 1
295 and 2.
296 "-quiet => num"
298 If "num" is true, do not print any errors/warnings. This is
299 useful when Pod::Checker is used to munge POD code into plain text
300 from within POD formatters.
301 "$checker->poderror( @args )"
303 "$checker->poderror( {%opts}, @args )"
304 Internal method for printing errors and warnings. If no options are
305 given, simply prints "@_". The following options are recognized and
306 used to form the output:
307 -msg
309 A message to print prior to @args.
311 -line
313 The line number the error occurred in.
315 -file
317 The file (name) the error occurred in.
319 -severity
321 The error level, should be 'WARNING' or 'ERROR'.
323 "$checker->num_errors()"
325 Set (if argument specified) and retrieve the number of errors
326 found.
327 "$checker->num_warnings()"
329 Set (if argument specified) and retrieve the number of warnings
330 found.
331 "$checker->name()"
333 Set (if argument specified) and retrieve the canonical name of POD
334 as found in the "=head1 NAME" section.
335 "$checker->node()"
337 Add (if argument specified) and retrieve the nodes (as defined by
338 "=headX" and "=item") of the current POD. The nodes are returned in
339 the order of their occurrence. They consist of plain text, each
340 piece of whitespace is collapsed to a single blank.
341 "$checker->idx()"
343 Add (if argument specified) and retrieve the index entries (as
344 defined by "X<>") of the current POD. They consist of plain text,
345 each piece of whitespace is collapsed to a single blank.
346 "$checker->hyperlink()"
348 Add (if argument specified) and retrieve the hyperlinks (as defined
349 by "L<>") of the current POD. They consist of a 2-item array: line
350 number and "Pod::Hyperlink" object.
351
353 Please report bugs using <http://rt.cpan.org>.
354 Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal
356 <marekr@cpan.org>
357 Based on code for Pod::Text::pod2text() written by Tom Christiansen
359 <tchrist@mox.perl.com>
360 Pod::Checker is part of the Pod-Checker distribution, and is based on
362 Pod::Parser.
363perl v5.16.3 2013-01-27 Pod::Checker(3)