Pod::Checker, podchecker() - check pod documents for syntax errors

  use Pod::Checker;

  $syntax_okay = podchecker($filepath, $outputpath, %options);

  my $checker = new Pod::Checker %options;
  $checker->parse_from_file($filepath, \*STDERR);

CW$filepath is the input POD to read and CW$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 CW\*STDIN, and the output-file defaults to CW\*STDERR.

This function can take a hash of options:

-warnings => val

Turn warnings on/off. val is usually 1 for on, but higher values trigger additional warnings. See Warnings.

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 preformed:

•

Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and unterminated interior sequences.

•

Check for proper balancing of CW=begin and CW=end. The contents of such a block are generally ignored, i.e. no syntax checks are performed.

•

Check for proper nesting and balancing of CW=over, CW=item and CW=back.

•

Check for same nested interior-sequences (e.g. CWL<...L<...>...>).

•

Check for malformed or nonexisting entities CWE<...>.

•

Check for correct syntax of hyperlinks CWL<...>. See perlpod for details.

•

Check for unresolved document-internal links. This check may also reveal misspelled links that seem to be internal links but should be links to something else.

* empty =headn

A heading (CW=head1 or CW=head2) without any text? That ain't no heading!

* =over on line N without closing =back

The CW=over command does not have a corresponding CW=back before the next heading (CW=head1 or CW=head2) or the end of the file.

* =item without previous =over

* =back without previous =over

An CW=item or CW=back command has been found outside a CW=over/CW=back block.

* No argument for =begin

A CW=begin command was found that is not followed by the formatter specification.

* =end without =begin

A standalone CW=end command was found.

* Nested =begin's

There were at least two consecutive CW=begin commands without the corresponding CW=end. Only one CW=begin may be active at a time.

* =for without formatter specification

There is no specification of the formatter after the CW=for command.

* unresolved internal link NAME

The given link to NAME does not have a matching node in the current POD. This also happend when a single word node name is not enclosed in CW"". An invalid POD command has been found. Valid are CW=head1, CW=head2, CW=head3, CW=head4, CW=over, CW=item, CW=back, CW=begin, CW=end, CW=for, CW=pod, CW=cut An invalid markup command has been encountered. Valid are: CWB<>, CWC<>, CWE<>, CWF<>, CWI<>, CWL<>, CWS<>, CWX<>, CWZ<>

* nested commands CMD<...CMD<...>...>

Two nested identical markup commands have been found. Generally this does not make sense.

* garbled entity STRING

The STRING found cannot be interpreted as a character entity.

* Entity number out of range

An entity specified by number (dec, hex, oct) is out of range (1-255).

* malformed link L<>

The link found cannot be parsed because it does not conform to the syntax described in perlpod.

* nonempty Z<>

The CWZ<> sequence is supposed to be empty.

* empty X<>

The index entry specified contains nothing but whitespace.

* Spurious text after =pod / =cut

The commands CW=pod and CW=cut do not take any arguments.

* Spurious character(s) after =back

The CW=back command does not take any arguments.

These may not necessarily cause trouble, but indicate mediocre style.

* multiple occurrence of link target name

The POD file has some CW=item and/or CW=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.

* line containing nothing but whitespace in paragraph

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.

* previous =item has no contents

There is a list CW=item right above the flagged line that has no text contents. You probably want to delete empty items.

* preceding non-item paragraph(s)

A list introduced by CW=over starts with a text or verbatim paragraph, but continues with CW=items. Move the non-item paragraph out of the CW=over/CW=back block.

* =item type mismatch (one vs. two)

A list started with e.g. a bulletted CW=item and continued with a numbered one. This is obviously inconsistent. For most translators the type of the first CW=item determines the type of the list. Angle brackets not written as CW<lt> and CW<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.

* Unknown entity

A character entity was found that does not belong to the standard ISO set or the POD specials CWverbar and CWsol.

* No items in =over

The list opened with CW=over does not contain any items.

* No argument for =item

CW=item without any parameters is deprecated. It should either be followed by CW* 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.

* empty section in previous paragraph

The previous section (introduced by a CW=head command) does not contain any text. This usually indicates that something is missing. Note: A CW=head1 followed immediately by CW=head2 does not trigger this warning.

* Verbatim paragraph in NAME section

The NAME section (CW=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.

* =headn without preceding higher level

For example if there is a CW=head2 in the POD file prior to a CW=head1.

There are some warnings wrt. malformed hyperlinks.

* ignoring leading/trailing whitespace in link

There is whitespace at the beginning or the end of the contents of L<...>.

* (section) in '$page' deprecated

There is a section detected in the page name of L<...>, e.g. CWL<passwd(2)>. POD hyperlinks may point to POD documents only. Please write CWC<passwd(2)> instead. Some formatters are able to expand this to appropriate code. For links to (builtin) functions, please say CWL<perlfunc/mkdir>, without ().

* alternative text/node '%s' contains non-escaped | or /

The characters CW| and CW/ 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>

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

While checking, this module collects document properties, e.g. the nodes for hyperlinks (CW=headX, CW=item) and index entries (CWX<>). 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 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 behaviour. Users of podchecker (the script) get the well-known behaviour. Return a reference to a new Pod::Checker object that inherits from Pod::Parser and is used for calling the required methods later. The following options are recognized: CW-warnings => num Print warnings if CWnum is true. The higher the value of CWnum, the more warnings are printed. Currently there are only levels 1 and 2. CW-quiet => num If CWnum 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. Internal method for printing errors and warnings. If no options are given, simply prints @_. The following options are recognized and used to form the output:

  -msg

  -line

  -file

  -severity

Please report bugs using <http://rt.cpan.org>.

Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal <marekr@cpan.org>

Based on code for BIPod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com>