Manual

Reference

Modules

  • A • B • C • D • E
  • F • G • H • I • L
  • M • N • O • P • S
  • T • U • X

Tools

Pod::Checker

Perl 5 version 8.8 documentation
Go to top • Download PDF
Show page index • Show recent pages
Recently read

Pod::Checker

NAME

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

SYNOPSIS

  1.   use Pod::Checker;
  3.   $syntax_okay = podchecker($filepath, $outputpath, %options);
  5.   my $checker = new Pod::Checker %options;
  6.   $checker->parse_from_file($filepath, \*STDERR);

OPTIONS/ARGUMENTS

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

podchecker()

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.

DESCRIPTION

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:

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

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

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

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

  • Check for malformed or nonexisting entities E<...> .

  • Check for correct syntax of hyperlinks L<...> . 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.

DIAGNOSTICS

Errors

  • empty =headn

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

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

  • =item without previous =over
  • =back without previous =over

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

  • No argument for =begin

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

  • =end without =begin

    A standalone =end command was found.

  • Nested =begin's

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

  • =for without formatter specification

    There is no specification of the formatter after the =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 "" .

  • Unknown command "CMD"

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

  • Unknown interior-sequence "SEQ"

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

  • 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 Z<> sequence is supposed to be empty.

  • empty X<>

    The index entry specified contains nothing but whitespace.

  • Spurious text after =pod / =cut

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

  • Spurious character(s) after =back

    The =back command does not take any arguments.

Warnings

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

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

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

  • file does not start with =head

    The file starts with a different POD directive than head. This is most probably something you do not want.

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

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

A list started with e.g. a bulletted C<=item> and continued with a numbered one. This is obviously inconsistent. For most translators the type of the I C<=item> determines the type of the list.

Angle brackets not written as CltE> and CgtE> 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 C and C.

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

C<=item> without any parameters is deprecated. It should either be followed by C<*> 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 C<=head> command) does not contain any text. This usually indicates that something is missing. Note: A C<=head1> followed immediately by C<=head2> does not trigger this warning.

The NAME section (C<=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 C<=head2> in the POD file prior to a C<=head1>.

Hyperlinks

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

  • (section) in '$page' deprecated

    There is a section detected in the page name of LE...E, e.g. Cpasswd(2)E>. POD hyperlinks may point to POD documents only. Please write Cpasswd(2)E> instead. Some formatters are able to expand this to appropriate code. For links to (builtin) functions, please say Cperlfunc/mkdirE>, without ().

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

    The characters C<|> and C are special in the LE...E 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:

    1.   /     E<sol>
    2.   |     E<verbar>

RETURN VALUE

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

EXAMPLES

See L

INTERFACE

While checking, this module collects document properties, e.g. the nodes for hyperlinks (C<=headX>, C<=item>) and index entries (CE>). 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 module uses only the B 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 (the script). This allows users of B to control completely the output behaviour. Users of B (the script) get the well-known behaviour.

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

    C<-warnings =E num> Print warnings if C is true. The higher the value of C, the more warnings are printed. Currently there are only levels 1 and 2.

    C<-quiet =E num> If C 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:

    1.   -msg

    A message to print prior to C<@args>.

    1.   -line

    The line number the error occurred in.

    1.   -file

    The file (name) the error occurred in.

    1.   -severity

    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 C<=head1 NAME> section.

  • $checker->node()

    Add (if argument specified) and retrieve the nodes (as defined by C<=headX> and C<=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 CE>) 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 CE>) of the current POD. They consist of a 2-item array: line number and C object.

AUTHOR

Please report bugs using L.

Brad Appleton Ebradapp@enteract.comE (initial version), Marek Rouchal Emarekr@cpan.orgE

Based on code for B written by Tom Christiansen Etchrist@mox.perl.comE

Page index