podchecker - check pod documents for syntax errors |
Pod::Checker, podchecker()
- check pod documents for syntax errors
use Pod::Checker;
$syntax_okay = 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
.
podchecker()
This function can take a hash of options:
podchecker will perform syntax checking of Perl5 POD format 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:
=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 the perlpod manpage
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.
=head1
or =head2
) without any text? That ain't no
heading!
=over
command does not have a corresponding =back
before the
next heading (=head1
or =head2
) or the end of the file.
=item
or =back
command has been found outside a
=over
/=back
block.
=begin
command was found that is not followed by the formatter
specification.
=end
command was found.
=begin
commands without
the corresponding =end
. Only one =begin
may be active at
a time.
=for
command.
""
.
=head1
, =head2
,
=head3
, =head4
, =over
, =item
, =back
, =begin
, =end
,
=for
, =pod
, =cut
B<>
, C<>
, E<>
, F<>
,
I<>
, L<>
, S<>
, X<>
,
Z<>
Z<>
sequence is supposed to be empty.
=pod
and =cut
do not take any arguments.
character(s)
after =back=back
command does not take any arguments.
These may not necessarily cause trouble, but indicate mediocre style.
=item
and/or =head
commands that have
the same text. Potential hyperlinks to such a text cannot be unique then.
=item
right above the flagged line that has no
text contents. You probably want to delete empty items.
paragraph(s)
=over
starts with a text or verbatim paragraph,
but continues with =item
s. Move the non-item paragraph out of the
=over
/=back
block.
=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.
<>
in paragraph<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.
verbar
and sol
.
=over
does not contain any items.
=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.
=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.
=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.
There are some warnings wrt. malformed hyperlinks.
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 ().
|
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>
podchecker returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file.
[T.B.D.]
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.
Pod::Checker->new( %options )
-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 )
-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()
$checker->name()
=head1 NAME
section.
$checker->node()
=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()
X<>
) of the current POD. They consist of plain text, each piece
of whitespace is collapsed to a single blank.
$checker->hyperlink()
L<>
) of the current POD. They consist of a 2-item array: line
number and Pod::Hyperlink
object.
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>
podchecker - check pod documents for syntax errors |