| Subject: | podchecker notice missing blank line before command |
| Date: | Fri, 10 Sep 2010 10:20:29 +1000 |
| To: | bug-Pod-Parser [...] rt.cpan.org |
| From: | Kevin Ryde <user42 [...] zip.com.au> |
It can be a bit easy to forget a blank line between multiple =item,
after a verbatim, etc. Without picking on anyone, for instance in perl
5.10.1 Compress::Zlib
=head2 B<($out, $status) = $d-E<gt>flush()>
=head2 B<($out, $status) = $d-E<gt>flush($flush_type)>
or ExtUtils::ParseXS
optimize => 1,
prototypes => 1,
);
=head1 DESCRIPTION
The diff below is an idea to notice =foo commands at the start of a line
but in the middle of a paragraph, verbatim, or other command.
I think such a line can be rated as an error. The circumstances for
actually wanting an =foo at the start of a line in the middle of a
paragraph will be rare, I think very much rarer than a mistake with
blank lines.
--- Checker.pm.orig 2010-09-10 09:50:44.000000000 +1000
+++ Checker.pm 2010-09-10 10:10:50.000000000 +1000
@@ -140,6 +140,14 @@
There is no specification of the formatter after the C<=for> command.
+=item * Apparent command =foo not preceded by blank line
+
+A command which has ended up in the middle of a paragraph or other command,
+such as
+
+ =item one
+ =item two <-- bad
+
=item * unresolved internal link I<NAME>
The given link to I<NAME> does not have a matching node in the current
@@ -813,6 +821,8 @@
else { # found a valid command
$self->{_commands}++; # delete this line if below is enabled again
+ _commands_in_paragraphs ($self, $paragraph, $pod_para);
+
##### following check disabled due to strong request
#if(!$self->{_commands}++ && $cmd !~ /^head/) {
# $self->poderror({ -line => $line, -file => $file,
@@ -1209,6 +1219,7 @@
my ($self, $paragraph, $line_num, $pod_para) = @_;
$self->_preproc_par($paragraph);
+ _commands_in_paragraphs ($self, $paragraph, $pod_para);
if($self->{_current_head1} eq 'NAME') {
my ($file, $line) = $pod_para->file_line;
@@ -1224,6 +1235,7 @@
my ($file, $line) = $pod_para->file_line;
$self->_preproc_par($paragraph);
+ _commands_in_paragraphs ($self, $paragraph, $pod_para);
# skip this paragraph if in a =begin block
unless($self->{_have_begin}) {
@@ -1250,6 +1262,35 @@
}
}
+# look for =foo commands at the start of a line within a paragraph, as for
+# instance the following which prints as "* one =item two".
+#
+# =item one
+# =item two
+#
+# Examples of =foo written in docs are expected to be indented in a verbatim
+# or marked up C<=foo> so won't be caught. A double-angle C<< =foo >> could
+# have the =foo at the start of a line, but that should be unlikely and is
+# easily enough dealt with by not putting a newline after the C<<.
+#
+sub _commands_in_paragraphs {
+ my ($self, $str, $pod_para) = @_;
+ while ($str =~ /[^\n]\n=([a-z][a-z0-9]+)/sg) {
+ my $cmd = $1;
+ my $pos = pos($str);
+ if ($VALID_COMMANDS{$cmd}) {
+ my ($file, $line) = $pod_para->file_line;
+ my $part = substr ($str, 0, $pos);
+ $line += ($part =~ tr/\n//); # count of newlines
+
+ $self->poderror
+ ({ -line => $line, -file => $file,
+ -severity => 'ERROR',
+ -msg => "Apparent command =$cmd not preceded by blank line"});
+ }
+ }
+}
+
1;
__END__