1Pod::Checker(3)       User Contributed Perl Documentation      Pod::Checker(3)
2
3
4

NAME

6       Pod::Checker - check pod documents for syntax errors
7

SYNOPSIS

9         use Pod::Checker;
10
11         $syntax_okay = podchecker($filepath, $outputpath, %options);
12
13         my $checker = Pod::Checker->new(%options);
14         $checker->parse_from_file($filepath, \*STDERR);
15

OPTIONS/ARGUMENTS

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
23   podchecker()
24       This function can take a hash of options:
25
26       -warnings => val
27           Turn warnings on/off. val is usually 1 for on, but higher values
28           trigger additional warnings. See "Warnings".
29
30       -quiet => val
31           If "val" is true, do not print any errors/warnings.
32

DESCRIPTION

34       podchecker will perform syntax checking of Perl5 POD format
35       documentation.
36
37       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
41       The following checks are currently performed:
42
43       •   Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and
44           unterminated interior sequences.
45
46       •   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
50       •   Check for proper nesting and balancing of "=over", "=item" and
51           "=back".
52
53       •   Check for same nested interior-sequences (e.g.  "L<...L<...>...>").
54
55       •   Check for malformed or non-existing entities "E<...>".
56
57       •   Check for correct syntax of hyperlinks "L<...>". See perlpod for
58           details.
59
60       •   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

DIAGNOSTICS

65   Errors
66       •   empty =headn
67
68           A heading ("=head1" or "=head2") without any text? That ain't no
69           heading!
70
71       •   =over on line N without closing =back
72
73       •   You forgot a '=back' before '=headN'
74
75       •   =over is the last thing in the document?!
76
77           The "=over" command does not have a corresponding "=back" before
78           the next heading ("=head1" or "=head2") or the end of the file.
79
80       •   '=item' outside of any '=over'
81
82       •   =back without =over
83
84           An "=item" or "=back" command has been found outside a
85           "=over"/"=back" block.
86
87       •   Can't have a 0 in =over N
88
89           You need to indent a strictly positive number of spaces, not 0.
90
91       •   =over should be: '=over' or '=over positive_number'
92
93           Either have an argumentless =over, or have its argument a strictly
94           positive number.
95
96       •   =begin TARGET without matching =end TARGET
97
98           A "=begin" command was found that has no matching =end command.
99
100       •   =begin without a target?
101
102           A "=begin" command was found that is not followed by the formatter
103           specification.
104
105       •   =end TARGET without matching =begin.
106
107           A standalone "=end" command was found.
108
109       •   '=end' without a target?
110
111           '=end' directives need to have a target, just like =begin
112           directives.
113
114       •   '=end TARGET' is invalid.
115
116           TARGET needs to be one word
117
118       •   =end CONTENT doesn't match =begin TARGET
119
120           CONTENT needs to match =begin's TARGET.
121
122       •   =for without a target?
123
124           There is no specification of the formatter after the "=for"
125           command.
126
127       •   unresolved internal link NAME
128
129           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
133       •   Unknown directive: CMD
134
135           An invalid POD command has been found. Valid are "=head1",
136           "=head2", "=head3", "=head4", "=over", "=item", "=back", "=begin",
137           "=end", "=for", "=pod", "=cut"
138
139       •   Deleting unknown formatting code SEQ
140
141           An invalid markup command has been encountered. Valid are: "B<>",
142           "C<>", "E<>", "F<>", "I<>", "L<>", "S<>", "X<>", "Z<>"
143
144       •   Unterminated SEQ<> sequence
145
146           An unclosed formatting code
147
148       •   An E<...> surrounding strange content
149
150           The STRING found cannot be interpreted as a character entity.
151
152       •   An empty E<>
153
154       •   An empty "L<>"
155
156       •   An empty X<>
157
158           There needs to be content inside E, L, and X formatting codes.
159
160       •   Spurious text after =pod / =cut
161
162           The commands "=pod" and "=cut" do not take any arguments.
163
164       •   =back doesn't take any parameters, but you said =back ARGUMENT
165
166           The "=back" command does not take any arguments.
167
168       •   =pod directives shouldn't be over one line long!  Ignoring all N
169           lines of content
170
171           Self explanatory
172
173       •   =cut found outside a pod block.
174
175           A '=cut' directive found in the middle of non-POD
176
177       •   Invalid =encoding syntax: CONTENT
178
179           Syntax error in =encoding directive
180
181   Warnings
182       These may not necessarily cause trouble, but indicate mediocre style.
183
184       •   nested commands CMD<...CMD<...>...>
185
186           Two nested identical markup commands have been found. Generally
187           this does not make sense.
188
189       •   multiple occurrences (N) of link target name
190
191           The POD file has some "=item" and/or "=head" commands that have the
192           same text. Potential hyperlinks to such a text cannot be unique
193           then.  This warning is printed only with warning level greater than
194           one.
195
196       •   line containing nothing but whitespace in paragraph
197
198           There is some whitespace on a seemingly empty line. POD is very
199           sensitive to such things, so this is flagged. vi users switch on
200           the list option to avoid this problem.
201
202       •   =item has no contents
203
204           There is a list "=item" that has no text contents. You probably
205           want to delete empty items.
206
207       •   You can't have =items (as at line N) unless the first thing after
208           the =over is an =item
209
210           A list introduced by "=over" starts with a text or verbatim
211           paragraph, but continues with "=item"s. Move the non-item paragraph
212           out of the "=over"/"=back" block.
213
214       •   Expected '=item EXPECTED VALUE'
215
216       •   Expected '=item *'
217
218       •   Possible =item type mismatch: 'x' found leading a supposed
219           definition =item
220
221           A list started with e.g. a bullet-like "=item" and continued with a
222           numbered one. This is obviously inconsistent. For most translators
223           the type of the first "=item" determines the type of the list.
224
225       •   You have '=item x' instead of the expected '=item N'
226
227           Erroneous numbering of =item numbers; they need to ascend
228           consecutively.
229
230       •   Unknown E content in E<CONTENT>
231
232           A character entity was found that does not belong to the standard
233           ISO set or the POD specials "verbar" and "sol". Currently, this
234           warning only appears if a character entity was found that does not
235           have a Unicode character. This should be fixed to adhere to the
236           original warning.
237
238       •   empty =over/=back block
239
240           The list opened with "=over" does not contain anything.
241
242       •   empty section in previous paragraph
243
244           The previous section (introduced by a "=head" command) does not
245           contain any valid content. This usually indicates that something is
246           missing. Note: A "=head1" followed immediately by "=head2" does not
247           trigger this warning.
248
249       •   Verbatim paragraph in NAME section
250
251           The NAME section ("=head1 NAME") should consist of a single
252           paragraph with the script/module name, followed by a dash `-' and a
253           very short description of what the thing is good for.
254
255       •   =headn without preceding higher level
256
257           For example if there is a "=head2" in the POD file prior to a
258           "=head1".
259
260       •   A non-empty Z<>
261
262           The "Z<>" sequence is supposed to be empty. Caveat: this issue is
263           detected in Pod::Simple and will be flagged as an ERROR by any
264           client code; any contents of "Z<...>" will be disregarded, anyway.
265
266   Hyperlinks
267       There are some warnings with respect to malformed hyperlinks:
268
269       •   ignoring leading/trailing whitespace in link
270
271           There is whitespace at the beginning or the end of the contents of
272           L<...>.
273
274       •   alternative text/node '%s' contains non-escaped | or /
275
276           The characters "|" and "/" are special in the L<...> context.
277           Although the hyperlink parser does its best to determine which "/"
278           is text and which is a delimiter in case of doubt, one ought to
279           escape these literal characters like this:
280
281             /     E<sol>
282             |     E<verbar>
283
284       Note that the line number of the error/warning may refer to the line
285       number of the start of the paragraph in which the error/warning exists,
286       not the line number that the error/warning is on. This bug is present
287       in errors/warnings related to formatting codes. This should be fixed.
288

RETURN VALUE

290       podchecker returns the number of POD syntax errors found or -1 if there
291       were no POD commands at all found in the file.
292

EXAMPLES

294       See "SYNOPSIS"
295

SCRIPTS

297       The podchecker script that comes with this distribution is a lean
298       wrapper around this module. See the online manual with
299
300         podchecker -help
301         podchecker -man
302

INTERFACE

304       While checking, this module collects document properties, e.g. the
305       nodes for hyperlinks ("=headX", "=item") and index entries ("X<>").
306       POD translators can use this feature to syntax-check and get the nodes
307       in a first pass before actually starting to convert. This is expensive
308       in terms of execution time, but allows for very robust conversions.
309
310       Since v1.24 the Pod::Checker module uses only the poderror method to
311       print errors and warnings. The summary output (e.g.  "Pod syntax OK")
312       has been dropped from the module and has been included in podchecker
313       (the script). This allows users of Pod::Checker to control completely
314       the output behavior. Users of podchecker (the script) get the well-
315       known behavior.
316
317       v1.45 inherits from Pod::Simple as opposed to all previous versions
318       inheriting from Pod::Parser. Do not use Pod::Simple's interface when
319       using Pod::Checker unless it is documented somewhere on this page. I
320       repeat, DO NOT USE POD::SIMPLE'S INTERFACE.
321
322       The following list documents the overrides to Pod::Simple, primarily to
323       make Pod::Coverage happy:
324
325       end_B
326       end_C
327       end_Document
328       end_F
329       end_I
330       end_L
331       end_Para
332       end_S
333       end_X
334       end_fcode
335       end_for
336       end_head
337       end_head1
338       end_head2
339       end_head3
340       end_head4
341       end_item
342       end_item_bullet
343       end_item_number
344       end_item_text
345       handle_pod_and_cut
346       handle_text
347       handle_whiteline
348       hyperlink
349       scream
350       start_B
351       start_C
352       start_Data
353       start_F
354       start_I
355       start_L
356       start_Para
357       start_S
358       start_Verbatim
359       start_X
360       start_fcode
361       start_for
362       start_head
363       start_head1
364       start_head2
365       start_head3
366       start_head4
367       start_item_bullet
368       start_item_number
369       start_item_text
370       start_over
371       start_over_block
372       start_over_bullet
373       start_over_empty
374       start_over_number
375       start_over_text
376       whine
377       "Pod::Checker->new( %options )"
378           Return a reference to a new Pod::Checker object that inherits from
379           Pod::Simple and is used for calling the required methods later. The
380           following options are recognized:
381
382           "-warnings => num"
383             Print warnings if "num" is true. The higher the value of "num",
384           the more warnings are printed. Currently there are only levels 1
385           and 2.
386
387           "-quiet => num"
388             If "num" is true, do not print any errors/warnings. This is
389           useful when Pod::Checker is used to munge POD code into plain text
390           from within POD formatters.
391
392       "$checker->poderror( @args )"
393       "$checker->poderror( {%opts}, @args )"
394           Internal method for printing errors and warnings. If no options are
395           given, simply prints "@_". The following options are recognized and
396           used to form the output:
397
398             -msg
399
400           A message to print prior to @args.
401
402             -line
403
404           The line number the error occurred in.
405
406             -file
407
408           The file (name) the error occurred in. Defaults to the name of the
409           current file being processed.
410
411             -severity
412
413           The error level, should be 'WARNING' or 'ERROR'.
414
415       "$checker->num_errors()"
416           Set (if argument specified) and retrieve the number of errors
417           found.
418
419       "$checker->num_warnings()"
420           Set (if argument specified) and retrieve the number of warnings
421           found.
422
423       "$checker->name()"
424           Set (if argument specified) and retrieve the canonical name of POD
425           as found in the "=head1 NAME" section.
426
427       "$checker->node()"
428           Add (if argument specified) and retrieve the nodes (as defined by
429           "=headX" and "=item") of the current POD. The nodes are returned in
430           the order of their occurrence. They consist of plain text, each
431           piece of whitespace is collapsed to a single blank.
432
433       "$checker->idx()"
434           Add (if argument specified) and retrieve the index entries (as
435           defined by "X<>") of the current POD. They consist of plain text,
436           each piece of whitespace is collapsed to a single blank.
437
438       "$checker->hyperlinks()"
439           Retrieve an array containing the hyperlinks to things outside the
440           current POD (as defined by "L<>").
441
442           Each is an instance of a class with the following methods:
443
444       line()
445           Returns the approximate line number in which the link was
446           encountered
447
448       type()
449           Returns the type of the link; one of: "url" for things like
450           "http://www.foo", "man" for man pages, or "pod".
451
452       page()
453           Returns the linked-to page or url.
454
455       node()
456           Returns the anchor or node within the linked-to page, or an empty
457           string ("") if none appears in the link.
458

AUTHOR

460       Please report bugs using <http://rt.cpan.org>.
461
462       Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal
463       <marekr@cpan.org>, Marc Green <marcgreen@cpan.org> (port to
464       Pod::Simple) Ricardo Signes <rjbs@cpan.org> (more porting to
465       Pod::Simple) Karl Williamson <khw@cpan.org> (more porting to
466       Pod::Simple)
467
468       Based on code for Pod::Text::pod2text() written by Tom Christiansen
469       <tchrist@mox.perl.com>
470
471
472
473perl v5.34.0                      2021-07-22                   Pod::Checker(3)