Re: non-empty blank-lines in PODs

Here is a patch that turns off the warning in Pod::Parser (and hence for
pod2xxx) but leaves it on for Pod::Checker. I made issuing of warnings
by Pod::Parser be contingent upon a parse-option that is unset by default
(this is for warnings in general, not pedantry as was suggested by an
earlier patch). Pod::Checker (and hence podchecker) sets the -warning
parse-option. It also ignores \r and \n when looking for "non-empty"
blank lines.

Patches follow for Pod::Parser, Pod::Checker, and t/pod/poderrs.xr
-- 
Brad Appleton <bradapp@enteract.com> http://www.enteract.com/~bradapp/
  "And miles to go before I sleep." -- Robert Frost



*** lib/Pod/Parser.pm.orig	Sat Mar  4 23:46:28 2000
--- lib/Pod/Parser.pm	Sun Mar  5 00:09:54 2000
***************
*** 172,178 ****
  
  Normally (by default) B<Pod::Parser> handles the C<=cut> POD directive
  by itself and does not pass it on to the caller for processing. Setting
! this option to non-empty, non-zero value will cause B<Pod::Parser> to
  pass the C<=cut> directive to the caller just like any other POD command
  (and hence it may be processed by the B<command()> method).
  
--- 172,178 ----
  
  Normally (by default) B<Pod::Parser> handles the C<=cut> POD directive
  by itself and does not pass it on to the caller for processing. Setting
! this option to a non-empty, non-zero value will cause B<Pod::Parser> to
  pass the C<=cut> directive to the caller just like any other POD command
  (and hence it may be processed by the B<command()> method).
  
***************
*** 181,186 ****
--- 181,195 ----
  to capture the actual C<=cut> paragraph itself for whatever purpose
  it desires.
  
+ =item B<-warnings> (default: unset)
+ 
+ Normally (by default) B<Pod::Parser> recognizes a bare minimum of
+ pod syntax errors and warnings and issues diagnostic messages
+ for errors, but not for warnings. (Use B<Pod::Checker> to do more
+ thorough checking of POD syntax.) Setting this option to a non-empty,
+ non-zero value will cause B<Pod::Parser> to issue diagnostics for
+ the few warnings it recognizes as well as the errors.
+ 
  =back
  
  Please see L<"parseopts()"> for a complete description of the interface
***************
*** 837,843 ****
         ($rdelim = $ldelim) =~ tr/</>/;
         $rdelim  =~ s/^(\S+)(\s*)$/$2$1/;
         pop @seq_stack;
!        my $errmsg = "*** WARNING: unterminated ${cmd}${ldelim}...${rdelim}".
                      " at line $line in file $file\n";
         (ref $errorsub) and &{$errorsub}($errmsg)
             or (defined $errorsub) and $self->$errorsub($errmsg)
--- 846,852 ----
         ($rdelim = $ldelim) =~ tr/</>/;
         $rdelim  =~ s/^(\S+)(\s*)$/$2$1/;
         pop @seq_stack;
!        my $errmsg = "*** ERROR: unterminated ${cmd}${ldelim}...${rdelim}".
                      " at line $line in file $file\n";
         (ref $errorsub) and &{$errorsub}($errmsg)
             or (defined $errorsub) and $self->$errorsub($errmsg)
***************
*** 1026,1031 ****
--- 1035,1042 ----
      my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
      my ($in_fh, $out_fh) = @_;
      $in_fh = \*STDIN  unless ($in_fh);
+     local *myData = $self;  ## alias to avoid deref-ing overhead
+     local *myOpts = ($myData{_PARSEOPTS} ||= {});  ## get parse-options
      local $_;
  
      ## Put this stream at the top of the stack and do beginning-of-input
***************
*** 1060,1069 ****
  
          ## See if this line is blank and ends the current paragraph.
          ## If it isn't, then keep iterating until it is.
!         next unless (($textline =~ /^(\s*)$/) && (length $paragraph));
  
          ## Issue a warning about any non-empty blank lines
!         if (length($1) > 1  and  ! $self->{_CUTTING}) {
              my $errorsub = $self->errorsub();
              my $file = $self->input_file();
              my $errmsg = "*** WARNING: line containing nothing but whitespace".
--- 1071,1081 ----
  
          ## See if this line is blank and ends the current paragraph.
          ## If it isn't, then keep iterating until it is.
!         next unless (($textline =~ /^([^\S\r\n]*)[\r\n]*$/)
!                                      && (length $paragraph));
  
          ## Issue a warning about any non-empty blank lines
!         if (length($1) > 1 and $myOpts{'-warnings'} and ! $myData{_CUTTING}) {
              my $errorsub = $self->errorsub();
              my $file = $self->input_file();
              my $errmsg = "*** WARNING: line containing nothing but whitespace".
***************
*** 1292,1298 ****
  given values. Any unspecified parse-options are unaffected.
  
              ## Set them back to the default
!             $parser->parseopts(-process_cut_cmd => 0);
  
  When passed a single hash-ref, B<parseopts> uses that hash to completely
  reset the existing parse-options, all previous parse-option values
--- 1304,1310 ----
  given values. Any unspecified parse-options are unaffected.
  
              ## Set them back to the default
!             $parser->parseopts(-warnings => 0);
  
  When passed a single hash-ref, B<parseopts> uses that hash to completely
  reset the existing parse-options, all previous parse-option values
***************
*** 1301,1307 ****
              ## Reset all options to default 
              $parser->parseopts( { } );
  
! See L<"PARSING OPTIONS"> for more for the name and meaning of each
  parse-option currently recognized.
  
  =cut
--- 1313,1319 ----
              ## Reset all options to default 
              $parser->parseopts( { } );
  
! See L<"PARSING OPTIONS"> for more information on the name and meaning of each
  parse-option currently recognized.
  
  =cut

*** lib/Pod/Checker.pm.orig	Sun Mar  5 00:01:59 2000
--- lib/Pod/Checker.pm	Sun Mar  5 00:02:33 2000
***************
*** 470,476 ****
  
      ## Now create a pod checker
      my $checker = new Pod::Checker(%options);
!     $checker->parseopts(-process_cut_cmd => 1);
  
      ## Now check the pod document for errors
      $checker->parse_from_file($infile, $outfile);
--- 470,476 ----
  
      ## Now create a pod checker
      my $checker = new Pod::Checker(%options);
!     $checker->parseopts(-process_cut_cmd => 1, -warnings => 1);
  
      ## Now check the pod document for errors
      $checker->parse_from_file($infile, $outfile);

*** t/pod/poderrs.xr.orig	Thu Feb 24 23:02:48 2000
--- t/pod/poderrs.xr	Sun Mar  5 00:05:17 2000
***************
*** 3,11 ****
  *** ERROR: Unknown interior-sequence 'A' at line 30 in file t/pod/poderrs.t
  *** ERROR: Unknown interior-sequence 'Y' at line 31 in file t/pod/poderrs.t
  *** ERROR: Unknown interior-sequence 'V' at line 31 in file t/pod/poderrs.t
! *** WARNING: unterminated B<...> at line 35 in file t/pod/poderrs.t
! *** WARNING: unterminated I<...> at line 34 in file t/pod/poderrs.t
! *** WARNING: unterminated C<...> at line 37 in file t/pod/poderrs.t
  *** WARNING: line containing nothing but whitespace in paragraph at line 45 in file t/pod/poderrs.t
  *** ERROR: =item without previous =over at line 52 in file t/pod/poderrs.t
  *** ERROR: =back without previous =over at line 56 in file t/pod/poderrs.t
--- 3,11 ----
  *** ERROR: Unknown interior-sequence 'A' at line 30 in file t/pod/poderrs.t
  *** ERROR: Unknown interior-sequence 'Y' at line 31 in file t/pod/poderrs.t
  *** ERROR: Unknown interior-sequence 'V' at line 31 in file t/pod/poderrs.t
! *** ERROR: unterminated B<...> at line 35 in file t/pod/poderrs.t
! *** ERROR: unterminated I<...> at line 34 in file t/pod/poderrs.t
! *** ERROR: unterminated C<...> at line 37 in file t/pod/poderrs.t
  *** WARNING: line containing nothing but whitespace in paragraph at line 45 in file t/pod/poderrs.t
  *** ERROR: =item without previous =over at line 52 in file t/pod/poderrs.t
  *** ERROR: =back without previous =over at line 56 in file t/pod/poderrs.t
***************
*** 30,33 ****
  *** ERROR: unresolved internal link 'abc def' at line 96 in file t/pod/poderrs.t
  *** ERROR: unresolved internal link 'passwd(5)' at line 103 in file t/pod/poderrs.t
  *** WARNING: multiple occurence of link target 'oops' at line - in file t/pod/poderrs.t
! t/pod/poderrs.t has 22 pod syntax errors.
--- 30,33 ----
  *** ERROR: unresolved internal link 'abc def' at line 96 in file t/pod/poderrs.t
  *** ERROR: unresolved internal link 'passwd(5)' at line 103 in file t/pod/poderrs.t
  *** WARNING: multiple occurence of link target 'oops' at line - in file t/pod/poderrs.t
! t/pod/poderrs.t has 25 pod syntax errors.

• Re: non-empty blank-lines in PODs by Brad Appleton