Checking for missed empty lines in POD

Question

I use Dist::Zilla and a bunch of plugins to check my pod, including syntax, links, coverage etc. One really annoying POD mistake that I keep repeating is to forget to add an extra line after a =headX; for example, I just created a module with pod that looks like the following:

=head1 METHODS

=head2 C<wm_graph>
There are three required arguments: ...
If the first arg is ...

Of course, I go and look at the CPAN page and realize I screwed it up, as the entire paragraph is in head2 format:

Messed up pod

Are there any good, automated ways to check that I didn't forget to put space between a =headX (or anything else) and the next paragraph?

The problem is that this is not an error, but a _feature_. Pod assumes that lines with no white space are really a continuation of the line above, so forgetting the space means that you really just have a really long heading. `podchecker` doesn't catch it, and I haven't seen any tools that will. Yes, it's annoying because I do the same thing, but it's not really an error. — David W., Dec 02 '12 at 00:53
Yes, I understand. I just wondered if anyone had been annoyed enough to write a warning generator or something. — Nate Glenn, Dec 02 '12 at 03:15

Gilbert · Answer 1 · 2012-12-02T02:30:54.413

Roll some perl code. Crude, but it works. I leave writing the main() to you.

sub do_pod_check
{
    my (
        $path,
         ) = @_;

    my $troubles = 0;
    open( my $handle, $path ) or
        die "Can not open file: $path: $!\n";

    while ( my $line = <$handle> )
    {
        if ( $line =~ /^=\w+/ )
        {
            my $line2 = <$handle>;
            if ( $line2 && $line2 =~ /\S/ )
            {
                $line2 =~ s/^\s+//;
                $line  =~ s/\s+$//;     #superchomp lines
                $line2 =~ s/\s+$//;
                print "$path\[$.]: suspect POD: /",
                                substr($line,0,30), "/",
                                substr($line2,0,30), "/",
                                "\n";
                $troubles++;
            }
        }
    }
    return $troubles;
}

Checking for missed empty lines in POD

1 Answers1