Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things

pod-error in perldocs

by LanX (Sage)
on Sep 23, 2009 at 15:30 UTC ( #797001=perlquestion: print w/replies, xml ) Need Help??

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


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

Cheers Rolf

UPDATE: I've send an email reporting this to also pointing back to this thread.

Replies are listed 'Best First'.
Re: pod-error in perldocs
by ikegami (Pope) 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.

      That is correct. This is the relevant section in Pod/ 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 }

      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)

        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.
Re: pod-error in perldocs (fix)
by ikegami (Pope) 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/

    sub search_perlvar { . . . elsif (/^=back/) { --$inlist; } . . . } #..................................................................... +..... sub search_perlfunc { . . . elsif (/^=back/) { --$inlist; } . . . }
    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; } . . . }

    Want the honours of reporting it?

      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

        It's a core module, so you can use perlbug

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://797001]
Approved by toolic
Front-paged by toolic
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (4)
As of 2021-10-23 21:46 GMT
Find Nodes?
    Voting Booth?
    My first memorable Perl project was:

    Results (88 votes). Check out past polls.