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:
Turn warnings on/off. val is usually 1 for on, but higher values trigger additional warnings. See "Warnings".
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