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:
- -warnings => val
-
Turn warnings on/off. val is usually 1 for on, but higher values
trigger additional warnings. See Warnings.
- -quiet => val
-
If
val is true, do not print any errors/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 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 non-existing 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.
- empty =headn
A heading (=head1 or =head2 ) without any text? That ain't no
heading!
- =over on line N without closing =back
- You forgot a '=back' before '=headN'
- =over is the last thing in the document?!
The =over command does not have a corresponding =back before the
next heading (=head1 or =head2 ) or the end of the file.
- '=item' outside of any '=over'
- =back without =over
An =item or =back command has been found outside a
=over /=back block.
- Can't have a 0 in =over N
You need to indent a strictly positive number of spaces, not 0.
- =over should be: '=over' or '=over positive_number'
Either have an argumentless =over, or have its argument a strictly positive number.
- =begin TARGET without matching =end TARGET
A =begin command was found that has no matching =end command.
- =begin without a target?
A =begin command was found that is not followed by the formatter
specification.
- =end TARGET without matching =begin.
A standalone =end command was found.
- '=end' without a target?
'=end' directives need to have a target, just like =begin directives.
- '=end TARGET' is invalid.
TARGET needs to be one word
- =end CONTENT doesn't match =begin TARGET
CONTENT needs to match =begin's TARGET.
- =for without a target?
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 happened when a single word node name is not enclosed in
"" .
- Unknown directive: CMD
An invalid POD command has been found. Valid are =head1 , =head2 ,
=head3 , =head4 , =over , =item , =back , =begin , =end ,
=for , =pod , =cut
- Deleting unknown formatting code SEQ
An invalid markup command has been encountered. Valid are:
B<> , C<> , E<> , F<> ,
I<> , L<> , S<> , X<> ,
Z<>
- Unterminated SEQ<> sequence
An unclosed formatting code
- An E<...> surrounding strange content
The STRING found cannot be interpreted as a character entity.
- An empty E<>
- An empty L<>
- An empty X<>
There needs to be content inside E, L, and X formatting codes.
- A non-empty Z<>
The Z<> sequence is supposed to be empty.
- Spurious text after =pod / =cut
The commands =pod and =cut do not take any arguments.
- =back doesn't take any parameters, but you said =back ARGUMENT
The =back command does not take any arguments.
- =pod directives shouldn't be over one line long! Ignoring all N lines of content
Self explanatory
- =cut found outside a pod block.
A '=cut' directive found in the middle of non-POD
- Invalid =encoding syntax: CONTENT
Syntax error in =encoding directive
These may not necessarily cause trouble, but indicate mediocre style.
There are some warnings with respect to malformed hyperlinks:
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.
- Pod::Checker->new( %options )
-
Return a reference to a new Pod::Checker object that inherits from
Pod::Simple 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 ) $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:
-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'.
- $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->hyperlinks()
-
Retrieve an array containing the hyperlinks to things outside
the current POD (as defined by
L<> ).
Each is an instance of a class with the following methods:
- line()
-
Returns the approximate line number in which the link was encountered
- type()
-
Returns the type of the link; one of:
"url" for things like
http://www.foo , "man" for man pages, or "pod" .
- page()
-
Returns the linked-to page or url.
node() node()
-
Returns the anchor or node within the linked-to page, or an empty string
(
"" ) if none appears in the link.
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>
|