LanX has asked for the wisdom of the Perl Monks concerning the following question:

Hi

Anyone here interested to track back this bug and report it?

(I can't tell if it's a parsing or document error.)

Pod::Perldoc v3.14_02

This is perl, v5.10.0 built for i486-linux-gnu-thread-multi

> perldoc -f y
       y///    The transliteration operator.  Same as "tr///".  See pe
+rlop.

POD ERRORS
       Hey! The above document had some coding errors, which are expla
+ined
       below:

       Around line 7:
           =back doesn’t take any parameters, but you said =back  =bac
+k

[download]

Cheers Rolf

UPDATE: I've send an email reporting this to perl5-porters@perl.org also pointing back to this thread.

Replies are listed 'Best First'.
Re: pod-error in perldocs
by ikegami (Patriarch) on Sep 23, 2009 at 15:55 UTC

    y/// is the last item in perlfunc, so the item is ended by =back.

    Whatever is splitting the entries in perlfunc is probably using /^=item\b/m to find where the item ends. This needs to be /^=(?:item|back)\b/m.

[reply]
[d/l]
[select]
      That is correct. This is the relevant section in Pod/Perldoc.pm search_perlfunc() 
       891     while (<PFUNC>) {  # "The Mothership Connection is here!"
 892         if ( m/^=item\s+$search_re\b/ )  {
 893             $found = 1;
 894         }
 895         elsif (/^=item/) {
 896             last if $found > 1 and not $inlist;
 897         }
 898         next unless $found;
 899         if (/^=over/) {
 900             ++$inlist;
 901         }
 902         elsif (/^=back/) {
 903             --$inlist;
 904         }
 905         push @$pod, $_;
 906         ++$found if /^\w/;        # found descriptive text
 907     }

      [download]
[reply]
[d/l]
      Thx!

      Whatever is splitting the entries

      IMHO parsing is done in POD::Simple, but I can't remember this bug in any older perl-versions...

      Anyway I've send an email to perl5porters reporting it and pointing back to this thread.

      If someone can spot the problem or can even supply a patch in thsi thread it should be seen!

      Anyhow I have work to do with POD::Simple next week so I'm gonna have a look...

      Cheers Rolf

      PS: @all Thanx for downvoting! 8)

[reply]
        I can confirm that this error exists in 5.10.0 and that it does not exist in 5.8.4 or 5.8.8. Also, in 5.10 at least, parsing for this option occurs entirely in Pod::Perldoc, not Pod::Simple.
[reply]
Re: pod-error in perldocs (fix)
by ikegami (Patriarch) on Sep 23, 2009 at 16:11 UTC

    For the same reason, perldoc -v %SIG also produces bad POD.

    The bugs are still present in blead.

    Untested fix for Pod/Perldoc.pm: 

    sub search_perlvar {
        .
        .
        .
        elsif (/^=back/) {
            --$inlist;
        }
        .
        .
        .
}

#.....................................................................
+.....

sub search_perlfunc {
        .
        .
        .
        elsif (/^=back/) {
            --$inlist;
        }
        .
        .
        .
}

    [download]
    should be 
    sub search_perlvar {
        .
        .
        .
        elsif (/^=back/) {
            last if $found && !$inheader && !$inlist;
            --$inlist;
        }
        .
        .
        .
}

#.....................................................................
+.....

sub search_perlfunc {
        .
        .
        .
        elsif (/^=back/) {
            last if $found > 1 and not $inlist;
            --$inlist;
        }
        .
        .
        .
}

    [download]

    Want the honours of reporting it?

[reply]
[d/l]
[select]
      Want the honours of reporting it?

      Do we get a cake or a beer for free :-)

      seriously, let's share the honours (however they are realized) me for reporting, and you two for fixing.

      Is there a bugtracker (especially for perldoc) errors?

      Cheers Rolf

[reply]
        It's a core module, so you can use perlbug
[reply]
[d/l]

Back to Seekers of Perl Wisdom