package Pod::Checker;
use vars qw($VERSION);
-$VERSION = 1.40; ## Current version of this package
+$VERSION = 1.42; ## Current version of this package
require 5.005; ## requires this Perl version or later
use Pod::ParseUtils; ## for hyperlinks and lists
B<podchecker> will perform syntax checking of Perl5 POD format documentation.
-I<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 B<Pod::Checker> and B<podchecker>
-and verify that the checks are consistent with L<perlpod>.
+Curious/ambitious users are welcome to propose additional features they wish
+to see in B<Pod::Checker> and B<podchecker> and verify that the checks are
+consistent with L<perlpod>.
The following checks are currently preformed:
=item * unresolved internal link I<NAME>
The given link to I<NAME> does not have a matching node in the current
-POD. This also happend when a single word node name is not enclosed in
+POD. This also happens when a single word node name is not enclosed in
C<"">.
=item * Unknown command "I<CMD>"
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.
+This warning is printed only with warning level greater than one.
=item * line containing nothing but whitespace in paragraph
=item * =item type mismatch (I<one> vs. I<two>)
-A list started with e.g. a bulletted C<=item> and continued with a
+A list started with e.g. a bulleted C<=item> and continued with a
numbered one. This is obviously inconsistent. For most translators the
type of the I<first> C<=item> determines the type of the list.
=head1 EXAMPLES
-I<[T.B.D.]>
+See L</SYNOPSIS>
=head1 INTERFACE
a first pass before actually starting to convert. This is expensive in terms
of execution time, but allows for very robust conversions.
+Since PodParser-1.24 the B<Pod::Checker> module uses only the B<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
+B<podchecker> (the script). This allows users of B<Pod::Checker> to
+control completely the output behaviour. Users of B<podchecker> (the script)
+get the well-known behaviour.
+
=cut
#############################################################################
## print the number of errors found
my $self = shift;
my $infile = $self->input_file();
- my $out_fh = $self->output_handle();
if(@{$self->{_list_stack}}) {
- # _TODO_ display, but don't count them for now
my $list;
while(($list = $self->_close_list('EOF',$infile)) &&
$list->indent() ne 'auto') {
# check the internal nodes for uniqueness. This pertains to
# =headX, =item and X<...>
- foreach(grep($self->{_unique_nodes}->{$_} > 1,
- keys %{$self->{_unique_nodes}})) {
- $self->poderror({ -line => '-', -file => $infile,
+ if($self->{-warnings} && $self->{-warnings}>1) {
+ foreach(grep($self->{_unique_nodes}->{$_} > 1,
+ keys %{$self->{_unique_nodes}})) {
+ $self->poderror({ -line => '-', -file => $infile,
-severity => 'WARNING',
-msg => "multiple occurrence of link target '$_'"});
+ }
}
- ## Print the number of errors found
- my $num_errors = $self->num_errors();
- if ($num_errors > 0) {
- printf $out_fh ("$infile has $num_errors pod syntax %s.\n",
- ($num_errors == 1) ? "error" : "errors");
- }
- elsif($self->{_commands} == 0) {
- print $out_fh "$infile does not contain any pod commands.\n";
- $self->num_errors(-1);
- }
- else {
- print $out_fh "$infile pod syntax OK.\n";
- }
+ # no POD found here
+ $self->num_errors(-1) if($self->{_commands} == 0);
}
# check a POD command directive
foreach(@$ptree) {
# regular text chunk
unless(ref) {
- my $count;
# count the unescaped angle brackets
# complain only when warning level is greater than 1
- my $i = $_;
- if($count = $i =~ tr/<>/<>/) {
+ if($self->{-warnings} && $self->{-warnings}>1) {
+ my $count;
+ if($count = tr/<>/<>/) {
$self->poderror({ -line => $line, -file => $file,
-severity => 'WARNING',
- -msg => "$count unescaped <> in paragraph" })
- if($self->{-warnings} && $self->{-warnings}>1);
+ -msg => "$count unescaped <> in paragraph" });
+ }
}
- $text .= $i;
+ $text .= $_;
next;
}
# have an interior sequence
=head1 AUTHOR
+Please report bugs using L<http://rt.cpan.org>.
+
Brad Appleton E<lt>bradapp@enteract.comE<gt> (initial version),
-Marek Rouchal E<lt>marek@saftsack.fs.uni-bayreuth.deE<gt>
+Marek Rouchal E<lt>marekr@cpan.orgE<gt>
Based on code for B<Pod::Text::pod2text()> written by
Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>