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       ·   A non-empty Z<>
161
162           The "Z<>" sequence is supposed to be empty.
163
164       ·   Spurious text after =pod / =cut
165
166           The commands "=pod" and "=cut" do not take any arguments.
167
168       ·   =back doesn't take any parameters, but you said =back ARGUMENT
169
170           The "=back" command does not take any arguments.
171
172       ·   =pod directives shouldn't be over one line long!  Ignoring all N
173           lines of content
174
175           Self explanatory
176
177       ·   =cut found outside a pod block.
178
179           A '=cut' directive found in the middle of non-POD
180
181       ·   Invalid =encoding syntax: CONTENT
182
183           Syntax error in =encoding directive
184
185   Warnings
186       These may not necessarily cause trouble, but indicate mediocre style.
187
188       ·   nested commands CMD<...CMD<...>...>
189
190           Two nested identical markup commands have been found. Generally
191           this does not make sense.
192
193       ·   multiple occurrences (N) of link target name
194
195           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
200       ·   line containing nothing but whitespace in paragraph
201
202           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
206       ·   =item has no contents
207
208           There is a list "=item" that has no text contents. You probably
209           want to delete empty items.
210
211       ·   You can't have =items (as at line N) unless the first thing after
212           the =over is an =item
213
214           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
218       ·   Expected '=item EXPECTED VALUE'
219
220       ·   Expected '=item *'
221
222       ·   Possible =item type mismatch: 'x' found leading a supposed
223           definition =item
224
225           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
229       ·   You have '=item x' instead of the expected '=item N'
230
231           Erroneous numbering of =item numbers; they need to ascend
232           consecutively.
233
234       ·   Unknown E content in E<CONTENT>
235
236           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
242       ·   empty =over/=back block
243
244           The list opened with "=over" does not contain anything.
245
246       ·   empty section in previous paragraph
247
248           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
253       ·   Verbatim paragraph in NAME section
254
255           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
259       ·   =headn without preceding higher level
260
261           For example if there is a "=head2" in the POD file prior to a
262           "=head1".
263
264   Hyperlinks
265       There are some warnings with respect to malformed hyperlinks:
266
267       ·   ignoring leading/trailing whitespace in link
268
269           There is whitespace at the beginning or the end of the contents of
270           L<...>.
271
272       ·   alternative text/node '%s' contains non-escaped | or /
273
274           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
279             /     E<sol>
280             |     E<verbar>
281
282       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

RETURN VALUE

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

EXAMPLES

292       See "SYNOPSIS"
293

SCRIPTS

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

INTERFACE

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
308       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
315       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
320       "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
325           "-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
330           "-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
335       "$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
341             -msg
342
343           A message to print prior to @args.
344
345             -line
346
347           The line number the error occurred in.
348
349             -file
350
351           The file (name) the error occurred in. Defaults to the name of the
352           current file being processed.
353
354             -severity
355
356           The error level, should be 'WARNING' or 'ERROR'.
357
358       "$checker->num_errors()"
359           Set (if argument specified) and retrieve the number of errors
360           found.
361
362       "$checker->num_warnings()"
363           Set (if argument specified) and retrieve the number of warnings
364           found.
365
366       "$checker->name()"
367           Set (if argument specified) and retrieve the canonical name of POD
368           as found in the "=head1 NAME" section.
369
370       "$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
376       "$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
381       "$checker->hyperlinks()"
382           Retrieve an array containing the hyperlinks to things outside the
383           current POD (as defined by "L<>").
384
385           Each is an instance of a class with the following methods:
386
387       line()
388           Returns the approximate line number in which the link was
389           encountered
390
391       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
395       page()
396           Returns the linked-to page or url.
397
398       node()
399           Returns the anchor or node within the linked-to page, or an empty
400           string ("") if none appears in the link.
401

AUTHOR

403       Please report bugs using <http://rt.cpan.org>.
404
405       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
411       Based on code for Pod::Text::pod2text() written by Tom Christiansen
412       <tchrist@mox.perl.com>
413
414
415
416perl v5.30.1                      2020-01-30                   Pod::Checker(3)
Impressum