Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  POD::CHECKER (3)

.ds Aq ’


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



  use Pod::Checker;

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

  my $checker = new Pod::Checker %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:
<B>-warningsB> => val Turn warnings on/off. val is usually 1 for on, but higher values trigger additional warnings. See Warnings.


<B>podcheckerB> will perform syntax checking of Perl5 POD format documentation.

Curious/ambitious users are welcome to propose additional features they wish to see in <B>Pod::CheckerB> and <B>podcheckerB> and verify that the checks are consistent with perlpod.

The following checks are currently performed:
o Unknown ’=xxxx’ commands, unknown ’X<...>’ interior-sequences, and unterminated interior sequences.
o Check for proper balancing of =begin and =end. The contents of such a block are generally ignored, i.e. no syntax checks are performed.
o Check for proper nesting and balancing of =over, =item and =back.
o Check for same nested interior-sequences (e.g. L<...L<...>...>).
o Check for malformed or non-existing entities E<...>.
o Check for correct syntax of hyperlinks L<...>. See perlpod for details.
o 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.



o empty =headn

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

o =over on line N without closing =back

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

o =item without previous =over
o =back without previous =over

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

o No argument for =begin

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

o =end without =begin

A standalone =end command was found.

o Nested =begin’s

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

o =for without formatter specification

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

o Apparent command =foo not preceded by blank line

A command which has ended up in the middle of a paragraph or other command, such as

  =item one
  =item two <-- bad

o unresolved internal link NAME

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 "".

o Unknown command "CMD"

An invalid POD command has been found. Valid are =head1, =head2, =head3, =head4, =over, =item, =back, =begin, =end, =for, =pod, =cut

o Unknown interior-sequence "SEQ"

An invalid markup command has been encountered. Valid are: B<>, C<>, E<>, F<>, I<>, L<>, S<>, X<>, Z<>

o nested commands CMD<...CMD<...>...>

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

o garbled entity STRING

The STRING found cannot be interpreted as a character entity.

o Entity number out of range

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

o malformed link L<>

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

o nonempty Z<>

The Z<> sequence is supposed to be empty.

o empty X<>

The index entry specified contains nothing but whitespace.

o Spurious text after =pod / =cut

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

o Spurious =cut command

A =cut command was found without a preceding POD paragraph.

o Spurious =pod command

A =pod command was found after a preceding POD paragraph.

o Spurious character(s) after =back

The =back command does not take any arguments.


These may not necessarily cause trouble, but indicate mediocre style.
o multiple occurrence of link target name

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.

o 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. <B>viB> users switch on the <B>listB> option to avoid this problem.

o previous =item has no contents

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

o preceding non-item paragraph(s)

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

o =item type mismatch (one vs. two)

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.

o N unescaped <> in paragraph

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.

o Unknown entity

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

o No items in =over

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

o No argument for =item

=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.

o empty section in previous paragraph

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.

o Verbatim paragraph in NAME section

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.

o =headn without preceding higher level

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


There are some warnings with respect to malformed hyperlinks:
o ignoring leading/trailing whitespace in link

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

o (section) in ’$page’ deprecated

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 ().

o alternative text/node ’%s’ contains non-escaped | or /

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>


<B>podcheckerB> returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file.




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 PodParser-1.24 the <B>Pod::CheckerB> module uses only the <B>poderrorB> 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 <B>podcheckerB> (the script). This allows users of <B>Pod::CheckerB> to control completely the output behavior. Users of <B>podcheckerB> (the script) get the well-known behavior.
Pod::Checker->new( %options ) 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:

-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.

$checker->poderror( @args )
$checker->poderror( {%opts}, @args ) 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:


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’.

$checker->num_errors() Set (if argument specified) and retrieve the number of errors found.
$checker->num_warnings() Set (if argument specified) and retrieve the number of warnings found.
$checker->name() Set (if argument specified) and retrieve the canonical name of POD as found in the =head1 NAME section.
$checker->node() Add (if argument specified) and retrieve the nodes (as defined by =headX and =item) of the current POD. The nodes are returned in the order of their occurrence. They consist of plain text, each piece of whitespace is collapsed to a single blank.
$checker->idx() Add (if argument specified) and retrieve the index entries (as defined by X<>) of the current POD. They consist of plain text, each piece of whitespace is collapsed to a single blank.
$checker->hyperlink() Add (if argument specified) and retrieve the hyperlinks (as defined by L<>) of the current POD. They consist of a 2-item array: line number and Pod::Hyperlink object.


Please report bugs using <>.

Brad Appleton <> (initial version), Marek Rouchal <>

Based on code for <B>B>Pod::Text::pod2text()<B>B> written by Tom Christiansen <>

<B>Pod::CheckerB> is part of the Pod-Checker distribution, and is based on Pod::Parser.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.22.1 POD::CHECKER (3) 2015-10-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.