A while back I mentioned a bug in Pod2Html involving blank lines in <PRE></PRE> blocks. Very quickly a patch was forthcoming. Trouble was, it wasn't quite enough. It seems that a command paragraph not preceeded by a single newline doesn't get parsed as the end of one paragraph and the beginning of the next. The documentation on perlpod is pretty clear when it says that:

All command paragraphs start with ``='' followed by an identifier, followed by arbitrary text that the command can use however it pleases…

Now to my perhaps twisted way of thinking you could construe this paragraph to mean that the regex /^=/ clearly indicates the end of the preceding paragraph of whatever type and the beginning of the command paragraph (inclusive of the equal sign). However, other folks mileage may vary.

So— it looks like there are two ways to deal with this problem:

1. Patch the documentation to mention this problem and the work around of preceeding command paragraphs with a sole newline. In particular, the paragraph that reads:

   And don't forget, when using any command, that the command lasts up until the end of the paragraph, not the line. Hence in the examples below, you can see the empty lines after each command to end its paragraph.

   Should be re-written to read:

   And don't forget, when using any command, that the command lasts up until the end of the paragraph, not the line. Hence in the examples below, you can see the empty lines after each command to end its paragraph, and before to end the preceding paragraph.

2. Patch html.pm Specifically the sub clean_data, which currently looks like:

   #
   # clean_data: global clean-up of pod data
   #
   sub clean_data($) {
       my ($dataref) = @_;
       my $i;
       for ( $i = 0 ; $i <= $#$dataref ; $i++ ) {
           ${$dataref}[$i] =~ s/\s+\Z//;
   
           # have a look for all-space lines
           if ( ${$dataref}[$i] =~ /^\s+$/m and ${$dataref}[$i] !~ /^\s/ 
   +) {
               my @chunks = split ( /^\s+$/m, ${$dataref}[$i] );
               splice( @$dataref, $i, 1, @chunks );
           }
       }
   }
   [download]

   to look like:

   #
   # clean_data: global clean-up of pod data
   #
   sub clean_data($) {
       my ($dataref) = @_;
       my $i;
       for ( $i = 0 ; $i <= $#$dataref ; $i++ ) {
   #-------------------------------------------------------------------
           if(${$dataref}[$i] =~ s/([^\x0a])\x0a=/$1\x00=/g) {
               my @otherchunks = split ( /\x00/m,${$dataref}[$i]);
               splice( @$dataref, $i, 1, @otherchunks );
               redo;
           }
   #-------------------------------------------------------------------
           ${$dataref}[$i] =~ s/\s+\Z//;
   
           # have a look for all-space lines
           if ( ${$dataref}[$i] =~ /^\s+$/m and ${$dataref}[$i] !~ /^\s/ 
   +) {
               my @chunks = split ( /^\s+$/m, ${$dataref}[$i] );
               splice( @$dataref, $i, 1, @chunks );
           }
       }
   }
   [download]

So the question is which solution? Is it a bug? Feature? What?

hsm