package Pod::Checker;
use vars qw($VERSION);
-$VERSION = 1.3; ## Current version of this package
+$VERSION = 1.40; ## Current version of this package
require 5.005; ## requires this Perl version or later
use Pod::ParseUtils; ## for hyperlinks and lists
=over 4
-=item * multiple occurence of link target I<name>
+=item * multiple occurrence of link target I<name>
The POD file has some C<=item> and/or C<=head> commands that have
the same text. Potential hyperlinks to such a text cannot be unique then.
with the script/module name, followed by a dash `-' and a very short
description of what the thing is good for.
+=item * =headI<n> without preceding higher level
+
+For example if there is a C<=head2> in the POD file prior to a
+C<=head1>.
+
=back
=head2 Hyperlinks
=item * (section) in '$page' deprecated
There is a section detected in the page name of LE<lt>...E<gt>, e.g.
-C<LE<gt>passwd(2)E<gt>>. POD hyperlinks may point to POD documents only.
+C<LE<lt>passwd(2)E<gt>>. POD hyperlinks may point to POD documents only.
Please write C<CE<lt>passwd(2)E<gt>> instead. Some formatters are able
to expand this to appropriate code. For links to (builtin) functions,
please say C<LE<lt>perlfunc/mkdirE<gt>>, without ().
## Initialize number of errors, and setup an error function to
## increment this number and then print to the designated output.
$self->{_NUM_ERRORS} = 0;
+ $self->{_NUM_WARNINGS} = 0;
$self->{-quiet} ||= 0;
# set the error handling subroutine
$self->errorsub($self->{-quiet} ? sub { 1; } : 'poderror');
## Increment error count and print message "
++($self->{_NUM_ERRORS})
if(!%opts || ($opts{-severity} && $opts{-severity} eq 'ERROR'));
+ ++($self->{_NUM_WARNINGS})
+ if(!%opts || ($opts{-severity} && $opts{-severity} eq 'WARNING'));
my $out_fh = $self->output_handle() || \*STDERR;
print $out_fh ($severity, $msg, $line, $file, "\n")
if($self->{-warnings} || !%opts || $opts{-severity} ne 'WARNING');
##################################
+=item C<$checker-E<gt>num_warnings()>
+
+Set (if argument specified) and retrieve the number of warnings found.
+
+=cut
+
+sub num_warnings {
+ return (@_ > 1) ? ($_[0]->{_NUM_WARNINGS} = $_[1]) : $_[0]->{_NUM_WARNINGS};
+}
+
+##################################
+
=item C<$checker-E<gt>name()>
Set (if argument specified) and retrieve the canonical name of POD as
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 occurence. They consist of plain text, each piece of whitespace is
+their occurrence. They consist of plain text, each piece of whitespace is
collapsed to a single blank.
=cut
=item C<$checker-E<gt>hyperlink()>
Add (if argument specified) and retrieve the hyperlinks (as defined by
-C<LE<lt>E<gt>>) of the current POD. They consist of an 2-item array: line
+C<LE<lt>E<gt>>) of the current POD. They consist of a 2-item array: line
number and C<Pod::Hyperlink> object.
=back
keys %{$self->{_unique_nodes}})) {
$self->poderror({ -line => '-', -file => $infile,
-severity => 'WARNING',
- -msg => "multiple occurence of link target '$_'"});
+ -msg => "multiple occurrence of link target '$_'"});
}
## Print the number of errors found
}
}
elsif($cmd =~ /^head(\d+)/) {
+ my $hnum = $1;
+ $self->{"_have_head_$hnum"}++; # count head types
+ if($hnum > 1 && !$self->{"_have_head_".($hnum -1)}) {
+ $self->poderror({ -line => $line, -file => $file,
+ -severity => 'WARNING',
+ -msg => "=head$hnum without preceding higher level"});
+ }
# check whether the previous =head section had some contents
if(defined $self->{_commands_in_head} &&
$self->{_commands_in_head} == 0 &&
defined $self->{_last_head} &&
- $self->{_last_head} >= $1) {
+ $self->{_last_head} >= $hnum) {
$self->poderror({ -line => $line, -file => $file,
-severity => 'WARNING',
-msg => "empty section in previous paragraph"});
}
$self->{_commands_in_head} = -1;
- $self->{_last_head} = $1;
+ $self->{_last_head} = $hnum;
# check if there is an open list
if(@{$self->{_list_stack}}) {
my $list;