use Pod::Checker; $syntax_okay = podchecker($filepath, $outputpath, %options); my $checker = new Pod::Checker %options; $checker->parse_from_file($filepath, \*STDERR);
Curious/ambitious users are welcome to propose additional features they wish to see in Pod::Checker and podchecker and verify that the checks are consistent with perlpod.
The following checks are currently performed:
A heading ("=head1" or "=head2") without any text? That ain't no heading!
The "=over" command does not have a corresponding "=back" before the next heading ("=head1" or "=head2") or the end of the file.
An "=item" or "=back" command has been found outside a "=over"/"=back" block.
A "=begin" command was found that is not followed by the formatter specification.
A standalone "=end" command was found.
There were at least two consecutive "=begin" commands without the corresponding "=end". Only one "=begin" may be active at a time.
There is no specification of the formatter after the "=for" command.
The given link to NAME does not have a matching node in the current POD. This also happened when a single word node name is not enclosed in "".
An invalid POD command has been found. Valid are "=head1", "=head2", "=head3", "=head4", "=over", "=item", "=back", "=begin", "=end", "=for", "=pod", "=cut"
An invalid markup command has been encountered. Valid are: "B<>", "C<>", "E<>", "F<>", "I<>", "L<>", "S<>", "X<>", "Z<>"
Two nested identical markup commands have been found. Generally this does not make sense.
The STRING found cannot be interpreted as a character entity.
An entity specified by number (dec, hex, oct) is out of range (1-255).
The link found cannot be parsed because it does not conform to the syntax described in perlpod.
The "Z<>" sequence is supposed to be empty.
The index entry specified contains nothing but whitespace.
The commands "=pod" and "=cut" do not take any arguments.
The "=back" command does not take any arguments.
The POD file has some "=item" and/or "=head" commands that have the same text. Potential hyperlinks to such a text cannot be unique then. This warning is printed only with warning level greater than one.
There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. vi users switch on the list option to avoid this problem.
There is a list "=item" right above the flagged line that has no text contents. You probably want to delete empty items.
A list introduced by "=over" starts with a text or verbatim paragraph, but continues with "=item"s. Move the non-item paragraph out of the "=over"/"=back" block.
A list started with e.g. a bullet-like "=item" and continued with a numbered one. This is obviously inconsistent. For most translators the type of the first "=item" determines the type of the list.
Angle brackets not written as "<lt>" and "<gt>" can potentially cause errors as they could be misinterpreted as markup commands. This is only printed when the -warnings level is greater than 1.
A character entity was found that does not belong to the standard ISO set or the POD specials "verbar" and "sol".
The list opened with "=over" does not contain any items.
"=item" without any parameters is deprecated. It should either be followed by "*" to indicate an unordered list, by a number (optionally followed by a dot) to indicate an ordered (numbered) list or simple text for a definition list.
The previous section (introduced by a "=head" command) does not contain any text. This usually indicates that something is missing. Note: A "=head1" followed immediately by "=head2" does not trigger this warning.
The NAME section ("=head1 NAME") should consist of a single paragraph with the script/module name, followed by a dash `-' and a very short description of what the thing is good for.
For example if there is a "=head2" in the POD file prior to a "=head1".
There is whitespace at the beginning or the end of the contents of L<...>.
There is a section detected in the page name of L<...>, e.g. "L<passwd(2)>". POD hyperlinks may point to POD documents only. Please write "C<passwd(2)>" instead. Some formatters are able to expand this to appropriate code. For links to (builtin) functions, please say "L<perlfunc/mkdir>", without ().
The characters "|" and "/" are special in the L<...> context. Although the hyperlink parser does its best to determine which ``/'' is text and which is a delimiter in case of doubt, one ought to escape these literal characters like this:
/ E<sol> | E<verbar>
Since PodParser-1.24 the Pod::Checker module uses only the poderror method to print errors and warnings. The summary output (e.g. ``Pod syntax OK'') has been dropped from the module and has been included in podchecker (the script). This allows users of Pod::Checker to control completely the output behavior. Users of podchecker (the script) get the well-known behavior.
"-warnings => num"
Print warnings if "num" is true. The higher the value of "num", the more warnings are printed. Currently there are only levels 1 and 2.
"-quiet => num"
If "num" is true, do not print any errors/warnings. This is useful when Pod::Checker is used to munge POD code into plain text from within POD formatters.
A message to print prior to @args.
The line number the error occurred in.
The file (name) the error occurred in.
The error level, should be 'WARNING' or 'ERROR'.
Brad Appleton <[email protected]> (initial version), Marek Rouchal <[email protected]>
Based on code for Pod::Text::pod2text() written by Tom Christiansen <[email protected]>