1Pod::Checker(3) User Contributed Perl Documentation Pod::Checker(3)
2
6 Pod::Checker - check pod documents for syntax errors
7
9 use Pod::Checker;
10 $syntax_okay = podchecker($filepath, $outputpath, %options);
12 my $checker = Pod::Checker->new(%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 -quiet => val
31 If "val" is true, do not print any errors/warnings.
32
34 podchecker will perform syntax checking of Perl5 POD format
35 documentation.
36 Curious/ambitious users are welcome to propose additional features they
38 wish to see in Pod::Checker and podchecker and verify that the checks
39 are consistent with perlpod.
40 The following checks are currently performed:
42 · Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and
44 unterminated interior sequences.
45 · Check for proper balancing of "=begin" and "=end". The contents of
47 such a block are generally ignored, i.e. no syntax checks are
48 performed.
49 · Check for proper nesting and balancing of "=over", "=item" and
51 "=back".
52 · Check for same nested interior-sequences (e.g. "L<...L<...>...>").
54 · Check for malformed or non-existing entities "E<...>".
56 · Check for correct syntax of hyperlinks "L<...>". See perlpod for
58 details.
59 · Check for unresolved document-internal links. This check may also
61 reveal misspelled links that seem to be internal links but should
62 be links to something else.
63
65 Errors
66 · empty =headn
67 A heading ("=head1" or "=head2") without any text? That ain't no
69 heading!
70 · =over on line N without closing =back
72 · You forgot a '=back' before '=headN'
74 · =over is the last thing in the document?!
76 The "=over" command does not have a corresponding "=back" before
78 the next heading ("=head1" or "=head2") or the end of the file.
79 · '=item' outside of any '=over'
81 · =back without =over
83 An "=item" or "=back" command has been found outside a
85 "=over"/"=back" block.
86 · Can't have a 0 in =over N
88 You need to indent a strictly positive number of spaces, not 0.
90 · =over should be: '=over' or '=over positive_number'
92 Either have an argumentless =over, or have its argument a strictly
94 positive number.
95 · =begin TARGET without matching =end TARGET
97 A "=begin" command was found that has no matching =end command.
99 · =begin without a target?
101 A "=begin" command was found that is not followed by the formatter
103 specification.
104 · =end TARGET without matching =begin.
106 A standalone "=end" command was found.
108 · '=end' without a target?
110 '=end' directives need to have a target, just like =begin
112 directives.
113 · '=end TARGET' is invalid.
115 TARGET needs to be one word
117 · =end CONTENT doesn't match =begin TARGET
119 CONTENT needs to match =begin's TARGET.
121 · =for without a target?
123 There is no specification of the formatter after the "=for"
125 command.
126 · unresolved internal link NAME
128 The given link to NAME does not have a matching node in the current
130 POD. This also happened when a single word node name is not
131 enclosed in "".
132 · Unknown directive: CMD
134 An invalid POD command has been found. Valid are "=head1",
136 "=head2", "=head3", "=head4", "=over", "=item", "=back", "=begin",
137 "=end", "=for", "=pod", "=cut"
138 · Deleting unknown formatting code SEQ
140 An invalid markup command has been encountered. Valid are: "B<>",
142 "C<>", "E<>", "F<>", "I<>", "L<>", "S<>", "X<>", "Z<>"
143 · Unterminated SEQ<> sequence
145 An unclosed formatting code
147 · An E<...> surrounding strange content
149 The STRING found cannot be interpreted as a character entity.
151 · An empty E<>
153 · An empty "L<>"
155 · An empty X<>
157 There needs to be content inside E, L, and X formatting codes.
159 · A non-empty Z<>
161 The "Z<>" sequence is supposed to be empty.
163 · Spurious text after =pod / =cut
165 The commands "=pod" and "=cut" do not take any arguments.
167 · =back doesn't take any parameters, but you said =back ARGUMENT
169 The "=back" command does not take any arguments.
171 · =pod directives shouldn't be over one line long! Ignoring all N
173 lines of content
174 Self explanatory
176 · =cut found outside a pod block.
178 A '=cut' directive found in the middle of non-POD
180 · Invalid =encoding syntax: CONTENT
182 Syntax error in =encoding directive
184 Warnings
186 These may not necessarily cause trouble, but indicate mediocre style.
187 · nested commands CMD<...CMD<...>...>
189 Two nested identical markup commands have been found. Generally
191 this does not make sense.
192 · multiple occurrences (N) of link target name
194 The POD file has some "=item" and/or "=head" commands that have the
196 same text. Potential hyperlinks to such a text cannot be unique
197 then. This warning is printed only with warning level greater than
198 one.
199 · line containing nothing but whitespace in paragraph
201 There is some whitespace on a seemingly empty line. POD is very
203 sensitive to such things, so this is flagged. vi users switch on
204 the list option to avoid this problem.
205 · =item has no contents
207 There is a list "=item" that has no text contents. You probably
209 want to delete empty items.
210 · You can't have =items (as at line N) unless the first thing after
212 the =over is an =item
213 A list introduced by "=over" starts with a text or verbatim
215 paragraph, but continues with "=item"s. Move the non-item paragraph
216 out of the "=over"/"=back" block.
217 · Expected '=item EXPECTED VALUE'
219 · Expected '=item *'
221 · Possible =item type mismatch: 'x' found leading a supposed
223 definition =item
224 A list started with e.g. a bullet-like "=item" and continued with a
226 numbered one. This is obviously inconsistent. For most translators
227 the type of the first "=item" determines the type of the list.
228 · You have '=item x' instead of the expected '=item N'
230 Erroneous numbering of =item numbers; they need to ascend
232 consecutively.
233 · Unknown E content in E<CONTENT>
235 A character entity was found that does not belong to the standard
237 ISO set or the POD specials "verbar" and "sol". Currently, this
238 warning only appears if a character entity was found that does not
239 have a Unicode character. This should be fixed to adhere to the
240 original warning.
241 · empty =over/=back block
243 The list opened with "=over" does not contain anything.
245 · empty section in previous paragraph
247 The previous section (introduced by a "=head" command) does not
249 contain any valid content. This usually indicates that something is
250 missing. Note: A "=head1" followed immediately by "=head2" does not
251 trigger this warning.
252 · Verbatim paragraph in NAME section
254 The NAME section ("=head1 NAME") should consist of a single
256 paragraph with the script/module name, followed by a dash `-' and a
257 very short description of what the thing is good for.
258 · =headn without preceding higher level
260 For example if there is a "=head2" in the POD file prior to a
262 "=head1".
263 Hyperlinks
265 There are some warnings with respect to malformed hyperlinks:
266 · ignoring leading/trailing whitespace in link
268 There is whitespace at the beginning or the end of the contents of
270 L<...>.
271 · alternative text/node '%s' contains non-escaped | or /
273 The characters "|" and "/" are special in the L<...> context.
275 Although the hyperlink parser does its best to determine which "/"
276 is text and which is a delimiter in case of doubt, one ought to
277 escape these literal characters like this:
278 / E<sol>
280 | E<verbar>
281 Note that the line number of the error/warning may refer to the line
283 number of the start of the paragraph in which the error/warning exists,
284 not the line number that the error/warning is on. This bug is present
285 in errors/warnings related to formatting codes. This should be fixed.
286
288 podchecker returns the number of POD syntax errors found or -1 if there
289 were no POD commands at all found in the file.
290
292 See "SYNOPSIS"
293
295 The podchecker script that comes with this distribution is a lean
296 wrapper around this module. See the online manual with
297 podchecker -help
299 podchecker -man
300
302 While checking, this module collects document properties, e.g. the
303 nodes for hyperlinks ("=headX", "=item") and index entries ("X<>").
304 POD translators can use this feature to syntax-check and get the nodes
305 in a first pass before actually starting to convert. This is expensive
306 in terms of execution time, but allows for very robust conversions.
307 Since v1.24 the Pod::Checker module uses only the poderror method to
309 print errors and warnings. The summary output (e.g. "Pod syntax OK")
310 has been dropped from the module and has been included in podchecker
311 (the script). This allows users of Pod::Checker to control completely
312 the output behavior. Users of podchecker (the script) get the well-
313 known behavior.
314 v1.45 inherits from Pod::Simple as opposed to all previous versions
316 inheriting from Pod::Parser. Do not use Pod::Simple's interface when
317 using Pod::Checker unless it is documented somewhere on this page. I
318 repeat, DO NOT USE POD::SIMPLE'S INTERFACE.
319 "Pod::Checker->new( %options )"
321 Return a reference to a new Pod::Checker object that inherits from
322 Pod::Simple and is used for calling the required methods later. The
323 following options are recognized:
324 "-warnings => num"
326 Print warnings if "num" is true. The higher the value of "num",
327 the more warnings are printed. Currently there are only levels 1
328 and 2.
329 "-quiet => num"
331 If "num" is true, do not print any errors/warnings. This is
332 useful when Pod::Checker is used to munge POD code into plain text
333 from within POD formatters.
334 "$checker->poderror( @args )"
336 "$checker->poderror( {%opts}, @args )"
337 Internal method for printing errors and warnings. If no options are
338 given, simply prints "@_". The following options are recognized and
339 used to form the output:
340 -msg
342 A message to print prior to @args.
344 -line
346 The line number the error occurred in.
348 -file
350 The file (name) the error occurred in. Defaults to the name of the
352 current file being processed.
353 -severity
355 The error level, should be 'WARNING' or 'ERROR'.
357 "$checker->num_errors()"
359 Set (if argument specified) and retrieve the number of errors
360 found.
361 "$checker->num_warnings()"
363 Set (if argument specified) and retrieve the number of warnings
364 found.
365 "$checker->name()"
367 Set (if argument specified) and retrieve the canonical name of POD
368 as found in the "=head1 NAME" section.
369 "$checker->node()"
371 Add (if argument specified) and retrieve the nodes (as defined by
372 "=headX" and "=item") of the current POD. The nodes are returned in
373 the order of their occurrence. They consist of plain text, each
374 piece of whitespace is collapsed to a single blank.
375 "$checker->idx()"
377 Add (if argument specified) and retrieve the index entries (as
378 defined by "X<>") of the current POD. They consist of plain text,
379 each piece of whitespace is collapsed to a single blank.
380 "$checker->hyperlinks()"
382 Retrieve an array containing the hyperlinks to things outside the
383 current POD (as defined by "L<>").
384 Each is an instance of a class with the following methods:
386 line()
388 Returns the approximate line number in which the link was
389 encountered
390 type()
392 Returns the type of the link; one of: "url" for things like
393 "http://www.foo", "man" for man pages, or "pod".
394 page()
396 Returns the linked-to page or url.
397 node()
399 Returns the anchor or node within the linked-to page, or an empty
400 string ("") if none appears in the link.
401
403 Please report bugs using <http://rt.cpan.org>.
404 Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal
406 <marekr@cpan.org>, Marc Green <marcgreen@cpan.org> (port to
407 Pod::Simple) Ricardo Signes <rjbs@cpan.org> (more porting to
408 Pod::Simple) Karl Williamson <khw@cpan.org> (more porting to
409 Pod::Simple)
410 Based on code for Pod::Text::pod2text() written by Tom Christiansen
412 <tchrist@mox.perl.com>
413perl v5.30.1 2020-01-30 Pod::Checker(3)