| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Pod::Checker 3perl" |
| 58 |
.TH Pod::Checker 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Pod::Checker \- check pod documents for syntax errors |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Pod::Checker; |
| 69 |
\& |
| 70 |
\& $syntax_okay = podchecker($filepath, $outputpath, %options); |
| 71 |
\& |
| 72 |
\& my $checker = Pod::Checker\->new(%options); |
| 73 |
\& $checker\->parse_from_file($filepath, \e*STDERR); |
| 74 |
.Ve |
| 75 |
.SH OPTIONS/ARGUMENTS |
| 76 |
.IX Header "OPTIONS/ARGUMENTS" |
| 77 |
\&\f(CW$filepath\fR is the input POD to read and \f(CW$outputpath\fR is |
| 78 |
where to write POD syntax error messages. Either argument may be a scalar |
| 79 |
indicating a file-path, or else a reference to an open filehandle. |
| 80 |
If unspecified, the input-file it defaults to \f(CW\*(C`\e*STDIN\*(C'\fR, and |
| 81 |
the output-file defaults to \f(CW\*(C`\e*STDERR\*(C'\fR. |
| 82 |
.SS \fBpodchecker()\fP |
| 83 |
.IX Subsection "podchecker()" |
| 84 |
This function can take a hash of options: |
| 85 |
.IP "\fB\-warnings\fR => \fIval\fR" 4 |
| 86 |
.IX Item "-warnings => val" |
| 87 |
Turn warnings on/off. \fIval\fR is usually 1 for on, but higher values |
| 88 |
trigger additional warnings. See "Warnings". |
| 89 |
.IP "\fB\-quiet\fR => \fIval\fR" 4 |
| 90 |
.IX Item "-quiet => val" |
| 91 |
If \f(CW\*(C`val\*(C'\fR is true, do not print any errors/warnings. |
| 92 |
.SH DESCRIPTION |
| 93 |
.IX Header "DESCRIPTION" |
| 94 |
\&\fBpodchecker\fR will perform syntax checking of Perl5 POD format documentation. |
| 95 |
.PP |
| 96 |
Curious/ambitious users are welcome to propose additional features they wish |
| 97 |
to see in \fBPod::Checker\fR and \fBpodchecker\fR and verify that the checks are |
| 98 |
consistent with perlpod. |
| 99 |
.PP |
| 100 |
The following checks are currently performed: |
| 101 |
.IP \(bu 4 |
| 102 |
Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, |
| 103 |
and unterminated interior sequences. |
| 104 |
.IP \(bu 4 |
| 105 |
Check for proper balancing of \f(CW\*(C`=begin\*(C'\fR and \f(CW\*(C`=end\*(C'\fR. The contents of such |
| 106 |
a block are generally ignored, i.e. no syntax checks are performed. |
| 107 |
.IP \(bu 4 |
| 108 |
Check for proper nesting and balancing of \f(CW\*(C`=over\*(C'\fR, \f(CW\*(C`=item\*(C'\fR and \f(CW\*(C`=back\*(C'\fR. |
| 109 |
.IP \(bu 4 |
| 110 |
Check for same nested interior-sequences (e.g. |
| 111 |
\&\f(CW\*(C`L<...L<...>...>\*(C'\fR). |
| 112 |
.IP \(bu 4 |
| 113 |
Check for malformed or non-existing entities \f(CW\*(C`E<...>\*(C'\fR. |
| 114 |
.IP \(bu 4 |
| 115 |
Check for correct syntax of hyperlinks \f(CW\*(C`L<...>\*(C'\fR. See perlpod |
| 116 |
for details. |
| 117 |
.IP \(bu 4 |
| 118 |
Check for unresolved document-internal links. This check may also reveal |
| 119 |
misspelled links that seem to be internal links but should be links |
| 120 |
to something else. |
| 121 |
.SH DIAGNOSTICS |
| 122 |
.IX Header "DIAGNOSTICS" |
| 123 |
.SS Errors |
| 124 |
.IX Subsection "Errors" |
| 125 |
.IP \(bu 4 |
| 126 |
empty =headn |
| 127 |
.Sp |
| 128 |
A heading (\f(CW\*(C`=head1\*(C'\fR or \f(CW\*(C`=head2\*(C'\fR) without any text? That ain't no |
| 129 |
heading! |
| 130 |
.IP \(bu 4 |
| 131 |
=over on line \fIN\fR without closing =back |
| 132 |
.IP \(bu 4 |
| 133 |
You forgot a '=back' before '=head\fIN\fR' |
| 134 |
.IP \(bu 4 |
| 135 |
=over is the last thing in the document?! |
| 136 |
.Sp |
| 137 |
The \f(CW\*(C`=over\*(C'\fR command does not have a corresponding \f(CW\*(C`=back\*(C'\fR before the |
| 138 |
next heading (\f(CW\*(C`=head1\*(C'\fR or \f(CW\*(C`=head2\*(C'\fR) or the end of the file. |
| 139 |
.IP \(bu 4 |
| 140 |
\&'=item' outside of any '=over' |
| 141 |
.IP \(bu 4 |
| 142 |
=back without =over |
| 143 |
.Sp |
| 144 |
An \f(CW\*(C`=item\*(C'\fR or \f(CW\*(C`=back\*(C'\fR command has been found outside a |
| 145 |
\&\f(CW\*(C`=over\*(C'\fR/\f(CW\*(C`=back\*(C'\fR block. |
| 146 |
.IP \(bu 4 |
| 147 |
Can't have a 0 in =over \fIN\fR |
| 148 |
.Sp |
| 149 |
You need to indent a strictly positive number of spaces, not 0. |
| 150 |
.IP \(bu 4 |
| 151 |
=over should be: '=over' or '=over positive_number' |
| 152 |
.Sp |
| 153 |
Either have an argumentless =over, or have its argument a strictly positive number. |
| 154 |
.IP \(bu 4 |
| 155 |
=begin \fITARGET\fR without matching =end \fITARGET\fR |
| 156 |
.Sp |
| 157 |
A \f(CW\*(C`=begin\*(C'\fR command was found that has no matching =end command. |
| 158 |
.IP \(bu 4 |
| 159 |
=begin without a target? |
| 160 |
.Sp |
| 161 |
A \f(CW\*(C`=begin\*(C'\fR command was found that is not followed by the formatter |
| 162 |
specification. |
| 163 |
.IP \(bu 4 |
| 164 |
=end \fITARGET\fR without matching =begin. |
| 165 |
.Sp |
| 166 |
A standalone \f(CW\*(C`=end\*(C'\fR command was found. |
| 167 |
.IP \(bu 4 |
| 168 |
\&'=end' without a target? |
| 169 |
.Sp |
| 170 |
\&'=end' directives need to have a target, just like =begin directives. |
| 171 |
.IP \(bu 4 |
| 172 |
\&'=end \fITARGET\fR' is invalid. |
| 173 |
.Sp |
| 174 |
\&\fITARGET\fR needs to be one word |
| 175 |
.IP \(bu 4 |
| 176 |
=end \fICONTENT\fR doesn't match =begin \fITARGET\fR |
| 177 |
.Sp |
| 178 |
\&\fICONTENT\fR needs to match =begin's \fITARGET\fR. |
| 179 |
.IP \(bu 4 |
| 180 |
=for without a target? |
| 181 |
.Sp |
| 182 |
There is no specification of the formatter after the \f(CW\*(C`=for\*(C'\fR command. |
| 183 |
.IP \(bu 4 |
| 184 |
unresolved internal link \fINAME\fR |
| 185 |
.Sp |
| 186 |
The given link to \fINAME\fR does not have a matching node in the current |
| 187 |
POD. This also happened when a single word node name is not enclosed in |
| 188 |
\&\f(CW""\fR. |
| 189 |
.IP \(bu 4 |
| 190 |
Unknown directive: \fICMD\fR |
| 191 |
.Sp |
| 192 |
An invalid POD command has been found. Valid are \f(CW\*(C`=head1\*(C'\fR, \f(CW\*(C`=head2\*(C'\fR, |
| 193 |
\&\f(CW\*(C`=head3\*(C'\fR, \f(CW\*(C`=head4\*(C'\fR, \f(CW\*(C`=over\*(C'\fR, \f(CW\*(C`=item\*(C'\fR, \f(CW\*(C`=back\*(C'\fR, \f(CW\*(C`=begin\*(C'\fR, \f(CW\*(C`=end\*(C'\fR, |
| 194 |
\&\f(CW\*(C`=for\*(C'\fR, \f(CW\*(C`=pod\*(C'\fR, \f(CW\*(C`=cut\*(C'\fR |
| 195 |
.IP \(bu 4 |
| 196 |
Deleting unknown formatting code \fISEQ\fR |
| 197 |
.Sp |
| 198 |
An invalid markup command has been encountered. Valid are: |
| 199 |
\&\f(CW\*(C`B<>\*(C'\fR, \f(CW\*(C`C<>\*(C'\fR, \f(CW\*(C`E<>\*(C'\fR, \f(CW\*(C`F<>\*(C'\fR, |
| 200 |
\&\f(CW\*(C`I<>\*(C'\fR, \f(CW\*(C`L<>\*(C'\fR, \f(CW\*(C`S<>\*(C'\fR, \f(CW\*(C`X<>\*(C'\fR, |
| 201 |
\&\f(CW\*(C`Z<>\*(C'\fR |
| 202 |
.IP \(bu 4 |
| 203 |
Unterminated \fISEQ\fR<> sequence |
| 204 |
.Sp |
| 205 |
An unclosed formatting code |
| 206 |
.IP \(bu 4 |
| 207 |
An E<...> surrounding strange content |
| 208 |
.Sp |
| 209 |
The \fISTRING\fR found cannot be interpreted as a character entity. |
| 210 |
.IP \(bu 4 |
| 211 |
An empty E<> |
| 212 |
.IP \(bu 4 |
| 213 |
An empty \f(CW\*(C`L<>\*(C'\fR |
| 214 |
.IP \(bu 4 |
| 215 |
An empty X<> |
| 216 |
.Sp |
| 217 |
There needs to be content inside E, L, and X formatting codes. |
| 218 |
.IP \(bu 4 |
| 219 |
Spurious text after =pod / =cut |
| 220 |
.Sp |
| 221 |
The commands \f(CW\*(C`=pod\*(C'\fR and \f(CW\*(C`=cut\*(C'\fR do not take any arguments. |
| 222 |
.IP \(bu 4 |
| 223 |
=back doesn't take any parameters, but you said =back \fIARGUMENT\fR |
| 224 |
.Sp |
| 225 |
The \f(CW\*(C`=back\*(C'\fR command does not take any arguments. |
| 226 |
.IP \(bu 4 |
| 227 |
=pod directives shouldn't be over one line long! Ignoring all \fIN\fR lines of content |
| 228 |
.Sp |
| 229 |
Self explanatory |
| 230 |
.IP \(bu 4 |
| 231 |
=cut found outside a pod block. |
| 232 |
.Sp |
| 233 |
A '=cut' directive found in the middle of non-POD |
| 234 |
.IP \(bu 4 |
| 235 |
Invalid =encoding syntax: \fICONTENT\fR |
| 236 |
.Sp |
| 237 |
Syntax error in =encoding directive |
| 238 |
.SS Warnings |
| 239 |
.IX Subsection "Warnings" |
| 240 |
These may not necessarily cause trouble, but indicate mediocre style. |
| 241 |
.IP \(bu 4 |
| 242 |
nested commands \fICMD\fR<...\fICMD\fR<...>...> |
| 243 |
.Sp |
| 244 |
Two nested identical markup commands have been found. Generally this |
| 245 |
does not make sense. |
| 246 |
.IP \(bu 4 |
| 247 |
multiple occurrences (\fIN\fR) of link target \fIname\fR |
| 248 |
.Sp |
| 249 |
The POD file has some \f(CW\*(C`=item\*(C'\fR and/or \f(CW\*(C`=head\*(C'\fR commands that have |
| 250 |
the same text. Potential hyperlinks to such a text cannot be unique then. |
| 251 |
This warning is printed only with warning level greater than one. |
| 252 |
.IP \(bu 4 |
| 253 |
line containing nothing but whitespace in paragraph |
| 254 |
.Sp |
| 255 |
There is some whitespace on a seemingly empty line. POD is very sensitive |
| 256 |
to such things, so this is flagged. \fBvi\fR users switch on the \fBlist\fR |
| 257 |
option to avoid this problem. |
| 258 |
.IP \(bu 4 |
| 259 |
=item has no contents |
| 260 |
.Sp |
| 261 |
There is a list \f(CW\*(C`=item\*(C'\fR that has no text contents. You probably want to delete |
| 262 |
empty items. |
| 263 |
.IP \(bu 4 |
| 264 |
You can't have =items (as at line \fIN\fR) unless the first thing after the =over is an =item |
| 265 |
.Sp |
| 266 |
A list introduced by \f(CW\*(C`=over\*(C'\fR starts with a text or verbatim paragraph, |
| 267 |
but continues with \f(CW\*(C`=item\*(C'\fRs. Move the non-item paragraph out of the |
| 268 |
\&\f(CW\*(C`=over\*(C'\fR/\f(CW\*(C`=back\*(C'\fR block. |
| 269 |
.IP \(bu 4 |
| 270 |
Expected '=item \fIEXPECTED VALUE\fR' |
| 271 |
.IP \(bu 4 |
| 272 |
Expected '=item *' |
| 273 |
.IP \(bu 4 |
| 274 |
Possible =item type mismatch: '\fIx\fR' found leading a supposed definition =item |
| 275 |
.Sp |
| 276 |
A list started with e.g. a bullet-like \f(CW\*(C`=item\*(C'\fR and continued with a |
| 277 |
numbered one. This is obviously inconsistent. For most translators the |
| 278 |
type of the \fIfirst\fR \f(CW\*(C`=item\*(C'\fR determines the type of the list. |
| 279 |
.IP \(bu 4 |
| 280 |
You have '=item x' instead of the expected '=item \fIN\fR' |
| 281 |
.Sp |
| 282 |
Erroneous numbering of =item numbers; they need to ascend consecutively. |
| 283 |
.IP \(bu 4 |
| 284 |
Unknown E content in E<\fICONTENT\fR> |
| 285 |
.Sp |
| 286 |
A character entity was found that does not belong to the standard |
| 287 |
ISO set or the POD specials \f(CW\*(C`verbar\*(C'\fR and \f(CW\*(C`sol\*(C'\fR. \fICurrently, this warning |
| 288 |
only appears if a character entity was found that does not have a Unicode |
| 289 |
character. This should be fixed to adhere to the original warning.\fR |
| 290 |
.IP \(bu 4 |
| 291 |
empty =over/=back block |
| 292 |
.Sp |
| 293 |
The list opened with \f(CW\*(C`=over\*(C'\fR does not contain anything. |
| 294 |
.IP \(bu 4 |
| 295 |
empty section in previous paragraph |
| 296 |
.Sp |
| 297 |
The previous section (introduced by a \f(CW\*(C`=head\*(C'\fR command) does not contain |
| 298 |
any valid content. This usually indicates that something is missing. Note: A |
| 299 |
\&\f(CW\*(C`=head1\*(C'\fR followed immediately by \f(CW\*(C`=head2\*(C'\fR does not trigger this warning. |
| 300 |
.IP \(bu 4 |
| 301 |
Verbatim paragraph in NAME section |
| 302 |
.Sp |
| 303 |
The NAME section (\f(CW\*(C`=head1 NAME\*(C'\fR) should consist of a single paragraph |
| 304 |
with the script/module name, followed by a dash `\-' and a very short |
| 305 |
description of what the thing is good for. |
| 306 |
.IP \(bu 4 |
| 307 |
=head\fIn\fR without preceding higher level |
| 308 |
.Sp |
| 309 |
For example if there is a \f(CW\*(C`=head2\*(C'\fR in the POD file prior to a |
| 310 |
\&\f(CW\*(C`=head1\*(C'\fR. |
| 311 |
.IP \(bu 4 |
| 312 |
A non-empty Z<> |
| 313 |
.Sp |
| 314 |
The \f(CW\*(C`Z<>\*(C'\fR sequence is supposed to be empty. Caveat: this issue is |
| 315 |
detected in Pod::Simple and will be flagged as an \fIERROR\fR by any client |
| 316 |
code; any contents of \f(CW\*(C`Z<...>\*(C'\fR will be disregarded, anyway. |
| 317 |
.SS Hyperlinks |
| 318 |
.IX Subsection "Hyperlinks" |
| 319 |
There are some warnings with respect to malformed hyperlinks: |
| 320 |
.IP \(bu 4 |
| 321 |
ignoring leading/trailing whitespace in link |
| 322 |
.Sp |
| 323 |
There is whitespace at the beginning or the end of the contents of |
| 324 |
L<...>. |
| 325 |
.IP \(bu 4 |
| 326 |
alternative text/node '%s' contains non-escaped | or / |
| 327 |
.Sp |
| 328 |
The characters \f(CW\*(C`|\*(C'\fR and \f(CW\*(C`/\*(C'\fR are special in the L<...> context. |
| 329 |
Although the hyperlink parser does its best to determine which "/" is |
| 330 |
text and which is a delimiter in case of doubt, one ought to escape |
| 331 |
these literal characters like this: |
| 332 |
.Sp |
| 333 |
.Vb 2 |
| 334 |
\& / E<sol> |
| 335 |
\& | E<verbar> |
| 336 |
.Ve |
| 337 |
.PP |
| 338 |
Note that the line number of the error/warning may refer to the line number of |
| 339 |
the start of the paragraph in which the error/warning exists, not the line |
| 340 |
number that the error/warning is on. This bug is present in errors/warnings |
| 341 |
related to formatting codes. \fIThis should be fixed.\fR |
| 342 |
.SH "RETURN VALUE" |
| 343 |
.IX Header "RETURN VALUE" |
| 344 |
\&\fBpodchecker\fR returns the number of POD syntax errors found or \-1 if |
| 345 |
there were no POD commands at all found in the file. |
| 346 |
.SH EXAMPLES |
| 347 |
.IX Header "EXAMPLES" |
| 348 |
See "SYNOPSIS" |
| 349 |
.SH SCRIPTS |
| 350 |
.IX Header "SCRIPTS" |
| 351 |
The \fBpodchecker\fR script that comes with this distribution is a lean wrapper |
| 352 |
around this module. See the online manual with |
| 353 |
.PP |
| 354 |
.Vb 2 |
| 355 |
\& podchecker \-help |
| 356 |
\& podchecker \-man |
| 357 |
.Ve |
| 358 |
.SH INTERFACE |
| 359 |
.IX Header "INTERFACE" |
| 360 |
While checking, this module collects document properties, e.g. the nodes |
| 361 |
for hyperlinks (\f(CW\*(C`=headX\*(C'\fR, \f(CW\*(C`=item\*(C'\fR) and index entries (\f(CW\*(C`X<>\*(C'\fR). |
| 362 |
POD translators can use this feature to syntax-check and get the nodes in |
| 363 |
a first pass before actually starting to convert. This is expensive in terms |
| 364 |
of execution time, but allows for very robust conversions. |
| 365 |
.PP |
| 366 |
Since v1.24 the \fBPod::Checker\fR module uses only the \fBpoderror\fR |
| 367 |
method to print errors and warnings. The summary output (e.g. |
| 368 |
"Pod syntax OK") has been dropped from the module and has been included in |
| 369 |
\&\fBpodchecker\fR (the script). This allows users of \fBPod::Checker\fR to |
| 370 |
control completely the output behavior. Users of \fBpodchecker\fR (the script) |
| 371 |
get the well-known behavior. |
| 372 |
.PP |
| 373 |
v1.45 inherits from Pod::Simple as opposed to all previous versions |
| 374 |
inheriting from Pod::Parser. Do \fBnot\fR use Pod::Simple's interface when |
| 375 |
using Pod::Checker unless it is documented somewhere on this page. I |
| 376 |
repeat, DO \fBNOT\fR USE POD::SIMPLE'S INTERFACE. |
| 377 |
.PP |
| 378 |
The following list documents the overrides to Pod::Simple, primarily to |
| 379 |
make Pod::Coverage happy: |
| 380 |
.IP end_B 4 |
| 381 |
.IX Item "end_B" |
| 382 |
.PD 0 |
| 383 |
.IP end_C 4 |
| 384 |
.IX Item "end_C" |
| 385 |
.IP end_Document 4 |
| 386 |
.IX Item "end_Document" |
| 387 |
.IP end_F 4 |
| 388 |
.IX Item "end_F" |
| 389 |
.IP end_I 4 |
| 390 |
.IX Item "end_I" |
| 391 |
.IP end_L 4 |
| 392 |
.IX Item "end_L" |
| 393 |
.IP end_Para 4 |
| 394 |
.IX Item "end_Para" |
| 395 |
.IP end_S 4 |
| 396 |
.IX Item "end_S" |
| 397 |
.IP end_X 4 |
| 398 |
.IX Item "end_X" |
| 399 |
.IP end_fcode 4 |
| 400 |
.IX Item "end_fcode" |
| 401 |
.IP end_for 4 |
| 402 |
.IX Item "end_for" |
| 403 |
.IP end_head 4 |
| 404 |
.IX Item "end_head" |
| 405 |
.IP end_head1 4 |
| 406 |
.IX Item "end_head1" |
| 407 |
.IP end_head2 4 |
| 408 |
.IX Item "end_head2" |
| 409 |
.IP end_head3 4 |
| 410 |
.IX Item "end_head3" |
| 411 |
.IP end_head4 4 |
| 412 |
.IX Item "end_head4" |
| 413 |
.IP end_item 4 |
| 414 |
.IX Item "end_item" |
| 415 |
.IP end_item_bullet 4 |
| 416 |
.IX Item "end_item_bullet" |
| 417 |
.IP end_item_number 4 |
| 418 |
.IX Item "end_item_number" |
| 419 |
.IP end_item_text 4 |
| 420 |
.IX Item "end_item_text" |
| 421 |
.IP handle_pod_and_cut 4 |
| 422 |
.IX Item "handle_pod_and_cut" |
| 423 |
.IP handle_text 4 |
| 424 |
.IX Item "handle_text" |
| 425 |
.IP handle_whiteline 4 |
| 426 |
.IX Item "handle_whiteline" |
| 427 |
.IP hyperlink 4 |
| 428 |
.IX Item "hyperlink" |
| 429 |
.IP scream 4 |
| 430 |
.IX Item "scream" |
| 431 |
.IP start_B 4 |
| 432 |
.IX Item "start_B" |
| 433 |
.IP start_C 4 |
| 434 |
.IX Item "start_C" |
| 435 |
.IP start_Data 4 |
| 436 |
.IX Item "start_Data" |
| 437 |
.IP start_F 4 |
| 438 |
.IX Item "start_F" |
| 439 |
.IP start_I 4 |
| 440 |
.IX Item "start_I" |
| 441 |
.IP start_L 4 |
| 442 |
.IX Item "start_L" |
| 443 |
.IP start_Para 4 |
| 444 |
.IX Item "start_Para" |
| 445 |
.IP start_S 4 |
| 446 |
.IX Item "start_S" |
| 447 |
.IP start_Verbatim 4 |
| 448 |
.IX Item "start_Verbatim" |
| 449 |
.IP start_X 4 |
| 450 |
.IX Item "start_X" |
| 451 |
.IP start_fcode 4 |
| 452 |
.IX Item "start_fcode" |
| 453 |
.IP start_for 4 |
| 454 |
.IX Item "start_for" |
| 455 |
.IP start_head 4 |
| 456 |
.IX Item "start_head" |
| 457 |
.IP start_head1 4 |
| 458 |
.IX Item "start_head1" |
| 459 |
.IP start_head2 4 |
| 460 |
.IX Item "start_head2" |
| 461 |
.IP start_head3 4 |
| 462 |
.IX Item "start_head3" |
| 463 |
.IP start_head4 4 |
| 464 |
.IX Item "start_head4" |
| 465 |
.IP start_item_bullet 4 |
| 466 |
.IX Item "start_item_bullet" |
| 467 |
.IP start_item_number 4 |
| 468 |
.IX Item "start_item_number" |
| 469 |
.IP start_item_text 4 |
| 470 |
.IX Item "start_item_text" |
| 471 |
.IP start_over 4 |
| 472 |
.IX Item "start_over" |
| 473 |
.IP start_over_block 4 |
| 474 |
.IX Item "start_over_block" |
| 475 |
.IP start_over_bullet 4 |
| 476 |
.IX Item "start_over_bullet" |
| 477 |
.IP start_over_empty 4 |
| 478 |
.IX Item "start_over_empty" |
| 479 |
.IP start_over_number 4 |
| 480 |
.IX Item "start_over_number" |
| 481 |
.IP start_over_text 4 |
| 482 |
.IX Item "start_over_text" |
| 483 |
.IP whine 4 |
| 484 |
.IX Item "whine" |
| 485 |
.ie n .IP """Pod::Checker\->new( %options )""" 4 |
| 486 |
.el .IP "\f(CWPod::Checker\->new( %options )\fR" 4 |
| 487 |
.IX Item "Pod::Checker->new( %options )" |
| 488 |
.PD |
| 489 |
Return a reference to a new Pod::Checker object that inherits from |
| 490 |
Pod::Simple and is used for calling the required methods later. The |
| 491 |
following options are recognized: |
| 492 |
.Sp |
| 493 |
\&\f(CW\*(C`\-warnings => num\*(C'\fR |
| 494 |
Print warnings if \f(CW\*(C`num\*(C'\fR is true. The higher the value of \f(CW\*(C`num\*(C'\fR, |
| 495 |
the more warnings are printed. Currently there are only levels 1 and 2. |
| 496 |
.Sp |
| 497 |
\&\f(CW\*(C`\-quiet => num\*(C'\fR |
| 498 |
If \f(CW\*(C`num\*(C'\fR is true, do not print any errors/warnings. This is useful |
| 499 |
when Pod::Checker is used to munge POD code into plain text from within |
| 500 |
POD formatters. |
| 501 |
.ie n .IP """$checker\->poderror( @args )""" 4 |
| 502 |
.el .IP "\f(CW$checker\->poderror( @args )\fR" 4 |
| 503 |
.IX Item "$checker->poderror( @args )" |
| 504 |
.PD 0 |
| 505 |
.ie n .IP """$checker\->poderror( {%opts}, @args )""" 4 |
| 506 |
.el .IP "\f(CW$checker\->poderror( {%opts}, @args )\fR" 4 |
| 507 |
.IX Item "$checker->poderror( {%opts}, @args )" |
| 508 |
.PD |
| 509 |
Internal method for printing errors and warnings. If no options are given, |
| 510 |
simply prints "@_". The following options are recognized and used to form |
| 511 |
the output: |
| 512 |
.Sp |
| 513 |
.Vb 1 |
| 514 |
\& \-msg |
| 515 |
.Ve |
| 516 |
.Sp |
| 517 |
A message to print prior to \f(CW@args\fR. |
| 518 |
.Sp |
| 519 |
.Vb 1 |
| 520 |
\& \-line |
| 521 |
.Ve |
| 522 |
.Sp |
| 523 |
The line number the error occurred in. |
| 524 |
.Sp |
| 525 |
.Vb 1 |
| 526 |
\& \-file |
| 527 |
.Ve |
| 528 |
.Sp |
| 529 |
The file (name) the error occurred in. Defaults to the name of the current |
| 530 |
file being processed. |
| 531 |
.Sp |
| 532 |
.Vb 1 |
| 533 |
\& \-severity |
| 534 |
.Ve |
| 535 |
.Sp |
| 536 |
The error level, should be 'WARNING' or 'ERROR'. |
| 537 |
.ie n .IP """$checker\->num_errors()""" 4 |
| 538 |
.el .IP \f(CW$checker\->num_errors()\fR 4 |
| 539 |
.IX Item "$checker->num_errors()" |
| 540 |
Set (if argument specified) and retrieve the number of errors found. |
| 541 |
.ie n .IP """$checker\->num_warnings()""" 4 |
| 542 |
.el .IP \f(CW$checker\->num_warnings()\fR 4 |
| 543 |
.IX Item "$checker->num_warnings()" |
| 544 |
Set (if argument specified) and retrieve the number of warnings found. |
| 545 |
.ie n .IP """$checker\->name()""" 4 |
| 546 |
.el .IP \f(CW$checker\->name()\fR 4 |
| 547 |
.IX Item "$checker->name()" |
| 548 |
Set (if argument specified) and retrieve the canonical name of POD as |
| 549 |
found in the \f(CW\*(C`=head1 NAME\*(C'\fR section. |
| 550 |
.ie n .IP """$checker\->node()""" 4 |
| 551 |
.el .IP \f(CW$checker\->node()\fR 4 |
| 552 |
.IX Item "$checker->node()" |
| 553 |
Add (if argument specified) and retrieve the nodes (as defined by \f(CW\*(C`=headX\*(C'\fR |
| 554 |
and \f(CW\*(C`=item\*(C'\fR) of the current POD. The nodes are returned in the order of |
| 555 |
their occurrence. They consist of plain text, each piece of whitespace is |
| 556 |
collapsed to a single blank. |
| 557 |
.ie n .IP """$checker\->idx()""" 4 |
| 558 |
.el .IP \f(CW$checker\->idx()\fR 4 |
| 559 |
.IX Item "$checker->idx()" |
| 560 |
Add (if argument specified) and retrieve the index entries (as defined by |
| 561 |
\&\f(CW\*(C`X<>\*(C'\fR) of the current POD. They consist of plain text, each piece |
| 562 |
of whitespace is collapsed to a single blank. |
| 563 |
.ie n .IP """$checker\->hyperlinks()""" 4 |
| 564 |
.el .IP \f(CW$checker\->hyperlinks()\fR 4 |
| 565 |
.IX Item "$checker->hyperlinks()" |
| 566 |
Retrieve an array containing the hyperlinks to things outside |
| 567 |
the current POD (as defined by \f(CW\*(C`L<>\*(C'\fR). |
| 568 |
.Sp |
| 569 |
Each is an instance of a class with the following methods: |
| 570 |
.IP \fBline()\fR 4 |
| 571 |
.IX Item "line()" |
| 572 |
Returns the approximate line number in which the link was encountered |
| 573 |
.IP \fBtype()\fR 4 |
| 574 |
.IX Item "type()" |
| 575 |
Returns the type of the link; one of: |
| 576 |
\&\f(CW"url"\fR for things like |
| 577 |
\&\f(CW\*(C`http://www.foo\*(C'\fR, \f(CW"man"\fR for man pages, or \f(CW"pod"\fR. |
| 578 |
.IP \fBpage()\fR 4 |
| 579 |
.IX Item "page()" |
| 580 |
Returns the linked-to page or url. |
| 581 |
.IP \fBnode()\fR 4 |
| 582 |
.IX Item "node()" |
| 583 |
Returns the anchor or node within the linked-to page, or an empty string |
| 584 |
(\f(CW""\fR) if none appears in the link. |
| 585 |
.SH AUTHOR |
| 586 |
.IX Header "AUTHOR" |
| 587 |
Please report bugs using <http://rt.cpan.org>. |
| 588 |
.PP |
| 589 |
Brad Appleton <[email protected]> (initial version), |
| 590 |
Marek Rouchal <[email protected]>, |
| 591 |
Marc Green <[email protected]> (port to Pod::Simple) |
| 592 |
Ricardo Signes <[email protected]> (more porting to Pod::Simple) |
| 593 |
Karl Williamson <[email protected]> (more porting to Pod::Simple) |
| 594 |
.PP |
| 595 |
Based on code for \fBPod::Text::pod2text()\fR written by |
| 596 |
Tom Christiansen <[email protected]> |