Pod::Checker(3perl) | Perl Programmers Reference Guide | Pod::Checker(3perl) |
Pod::Checker - check pod documents for syntax errors
use Pod::Checker; $syntax_okay = podchecker($filepath, $outputpath, %options); my $checker = Pod::Checker->new(%options); $checker->parse_from_file($filepath, \*STDERR);
$filepath is the input POD to read and $outputpath is where to write POD syntax error messages. Either argument may be a scalar indicating a file-path, or else a reference to an open filehandle. If unspecified, the input-file it defaults to "\*STDIN", and the output-file defaults to "\*STDERR".
This function can take a hash of options:
podchecker will perform syntax checking of Perl5 POD format documentation.
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.
Self explanatory
A '=cut' directive found in the middle of non-POD
Syntax error in =encoding directive
These may not necessarily cause trouble, but indicate mediocre style.
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 are some warnings with respect to malformed hyperlinks:
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 returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file.
See "SYNOPSIS"
The podchecker script that comes with this distribution is a lean wrapper around this module. See the online manual with
podchecker -help podchecker -man
While checking, this module collects document properties, e.g. the nodes for hyperlinks ("=headX", "=item") and index entries ("X<>"). POD translators can use this feature to syntax-check and get the nodes in a first pass before actually starting to convert. This is expensive in terms of execution time, but allows for very robust conversions.
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.
-msg
A message to print prior to @args.
-line
The line number the error occurred in.
-file
The file (name) the error occurred in. Defaults to the name of the current file being processed.
-severity
The error level, should be 'WARNING' or 'ERROR'.
Each is an instance of a class with the following methods:
Please report bugs using <http://rt.cpan.org>.
Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal <marekr@cpan.org>, Marc Green <marcgreen@cpan.org> (port to Pod::Simple) Ricardo Signes <rjbs@cpan.org> (more porting to Pod::Simple) Karl Williamson <khw@cpan.org> (more porting to Pod::Simple)
Based on code for Pod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com>
2023-11-25 | perl v5.36.0 |