use Pod::Checker; $syntax_okay = podchecker($filepath, $outputpath, %options); my $checker = Pod::Checker->new(%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.
You need to indent a strictly positive number of spaces, not 0.
Either have an argumentless =over, or have its argument a strictly positive number.
A "=begin" command was found that has no matching =end command.
A "=begin" command was found that is not followed by the formatter specification.
A standalone "=end" command was found.
'=end' directives need to have a target, just like =begin directives.
TARGET needs to be one word
CONTENT needs to match =begin's TARGET.
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<>"
An unclosed formatting code
The STRING found cannot be interpreted as a character entity.
There needs to be content inside E, L, and X formatting codes.
The commands "=pod" and "=cut" do not take any arguments.
The "=back" command does not take any arguments.
A '=cut' directive found in the middle of non-POD
Syntax error in =encoding directive
Two nested identical markup commands have been found. Generally this does not make sense.
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" 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.
Erroneous numbering of =item numbers; they need to ascend consecutively.
A character entity was found that does not belong to the standard ISO set or the POD specials "verbar" and "sol". Currently, this warning only appears if a character entity was found that does not have a Unicode character. This should be fixed to adhere to the original warning.
The list opened with "=over" does not contain anything.
The previous section (introduced by a "=head" command) does not contain any valid content. 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".
The "Z<>" sequence is supposed to be empty. Caveat: this issue is detected in Pod::Simple and will be flagged as an ERROR by any client code; any contents of "Z<...>" will be disregarded, anyway.
There is whitespace at the beginning or the end of the contents of L<...>.
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>
Note that the line number of the error/warning may refer to the line number of the start of the paragraph in which the error/warning exists, not the line number that the error/warning is on. This bug is present in errors/warnings related to formatting codes. This should be fixed.
podchecker -help podchecker -man
Since v1.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.
v1.45 inherits from Pod::Simple as opposed to all previous versions inheriting from Pod::Parser. Do not use Pod::Simple's interface when using Pod::Checker unless it is documented somewhere on this page. I repeat, DO NOT USE POD::SIMPLE'S INTERFACE.
The following list documents the overrides to Pod::Simple, primarily to make Pod::Coverage happy:
"-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. Defaults to the name of the current file being processed.
The error level, should be 'WARNING' or 'ERROR'.
Each is an instance of a class with the following methods:
Brad Appleton <email@example.com> (initial version), Marek Rouchal <firstname.lastname@example.org>, Marc Green <email@example.com> (port to Pod::Simple) Ricardo Signes <firstname.lastname@example.org> (more porting to Pod::Simple) Karl Williamson <email@example.com> (more porting to Pod::Simple)
Based on code for Pod::Text::pod2text() written by Tom Christiansen <firstname.lastname@example.org>