


Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


NAME
       Pod::Checker, podchecker() - check pod documents for syn-
       tax errors

SYNOPSIS
         use Pod::Checker;

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

         my $checker = new Pod::Checker %options;
         $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 refer-
       ence 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 the
           section on "Warnings".

DESCRIPTION
       podchecker will perform syntax checking of Perl5 POD for-
       mat documentation.

       NOTE THAT THIS MODULE IS CURRENTLY IN THE BETA STAGE!

       It is hoped that curious/ambitious user will help flesh
       out and add the additional features they wish to see in
       Pod::Checker and podchecker and verify that the checks are
       consistent with the perlpod manpage.

       The following checks are currently preformed:

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





2001-05-24                 perl v5.6.1                          1





Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


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

       o   Check for malformed or nonexisting entities "E<...>".

       o   Check for correct syntax of hyperlinks "L<...>". See
           the perlpod manpage 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.

DIAGNOSTICS
       Errors


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

       o Unknown command ""CMD""
           An invalid POD command has been found. Valid are
           "=head1", "=head2", "=over", "=item", "=back",



2001-05-24                 perl v5.6.1                          2





Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


           "=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 the perlpod man-
           page.

       o nonempty Z<>
           The "Z<>" sequence is supposed to be empty.

       o empty X<>
           The index entry specified contains nothing but whites-
           pace.

       o Spurious text after =pod / =cut
           The commands "=pod" and "=cut" do not take any argu-
           ments.

       o Spurious character(s) after =back
           The "=back" command does not take any arguments.

       Warnings

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

       o multiple occurence 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.

       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. vi users switch on the list option to avoid
           this problem.




2001-05-24                 perl v5.6.1                          3





Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


       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 "=item"s. 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 bulletted "=item" and con-
           tinued with a numbered one. This is obviously incon-
           sistent. 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 misinter-
           preted 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 imme-
           diately 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.







2001-05-24                 perl v5.6.1                          4





Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


       Hyperlinks

       There are some warnings wrt. 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 delim-
           iter in case of doubt, one ought to escape these lit-
           eral characters like this:

             /     E<sol>
             |     E<verbar>


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

EXAMPLES
       [T.B.D.]

INTERFACE
       While checking, this module collects document properties,
       e.g. the nodes for hyperlinks ("=headX", "=item") and
       index entries ("X<>").  POD translators can use this fea-
       ture 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 con-
       versions.

       ""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 rec-
           ognized:

           "-warnings => num"
             Print warnings if "num" is true. The higher the
           value of "num", the more warnings are printed. Cur-
           rently there are only levels 1 and 2.



2001-05-24                 perl v5.6.1                          5





Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


           "-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 follow-
           ing options are recognized and used to form the out-
           put:

             -msg

           A message to print prior to "@args".

             -line

           The line number the error occurred in.

             -file

           The file (name) the error occurred in.

             -severity

           The error level, should be 'WARNING' or 'ERROR'.

       ""$checker->num_errors()""
           Set (if argument specified) and retrieve the number of
           errors 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
           occurence. 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 hyper-
           links (as defined by "L<>") of the current POD. They
           consist of an 2-item array: line number and
           "Pod::Hyperlink" object.



2001-05-24                 perl v5.6.1                          6





Pod::Checker(3p) Perl Programmers Reference GuidePod::Checker(3p)


AUTHOR
       Brad Appleton <bradapp@enteract.com> (initial version),
       Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>

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



















































2001-05-24                 perl v5.6.1                          7


