Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris
 
PerlMonks  

What do you do with typos in the documentation?

by Anonymous Monk
on Jan 29, 2021 at 06:48 UTC ( #11127618=perlquestion: print w/replies, xml ) Need Help??

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

I ran "perldoc -f state" and it says in the last paragraph
" "state" is available only if the "state" feature is enabl +ed or if it is prefixed with "CORE::". The "state" feature is en +abled automatically with a "use v5.10" (or higher) declaration i +n the current scope. "
So I tried putting "use 5.10;" in my program and it said:
"Perl v5.100.0 required (did you mean v5.10.0?)--this is only v5.30.0, + stopped at bin/zclient line 5."
so it looks liek the "state" documentation is telling me to use version 5 by 100!

The manpage for IO::Socket::INET has this in it. I didn't even try running it because it has the bareword of udp there which I'm pretty sure is illegal?

$sock = IO::Socket::INET->new( PeerPort => 9999, PeerAddr => inet_ntoa(INADDR_BR +OADCAST), Proto => udp, LocalAddr => 'localhost', Broadcast => 1 ) or die "Can't bind : $@\n";

Replies are listed 'Best First'.
Re: What do you do with typos in the documentation?
by Corion (Pope) on Jan 29, 2021 at 06:52 UTC

    There is a difference between use v5.10; and use 5.10 (without the vee).

    But in general, documentation bugs are the same as other bugs and should be reported through the bugtracker of the module, or for Perl, in the Perl bugtracker.

Re: What do you do with typos in the documentation?
by GrandFather (Saint) on Jan 29, 2021 at 07:26 UTC

    So in the documentation you saw "use v5.10" and chose to write "use 5.10". How precisely is that the documentation's fault? You then got an error message that asks: "did you mean v5.10.0?". How do you get from that to the "documentation is telling me to use version 5 by 100!"?

    Optimising for fewest key strokes only makes sense transmitting to Pluto or beyond
      I presume he reached that conclusion because the error message begins "Perl v5.100.0 required".
Re: What do you do with typos in the documentation?
by hippo (Chancellor) on Jan 29, 2021 at 09:55 UTC
    The manpage for IO::Socket::INET has this in it.

    The IO::Socket::INET documentation also has this in it:

    Currently maintained by the Perl Porters. Please report all bugs to <perlbug@perl.org>.

    HTH.


    🦛

Re: What do you do with typos in the documentation?
by tobyink (Canon) on Jan 29, 2021 at 17:46 UTC

    For my distributions, I'd hope people would report doc bugs via the normal route for reporting issues, with a patch if possible.

    Generally speaking, I won't prioritize releasing a new version if the only change is a documentation fix; it'll just get rolled into whatever the next release is. Though if the mistake was serious enough, I might release a new version.

Re: What do you do with typos in the documentation?
by stevieb (Canon) on Jan 29, 2021 at 13:31 UTC
    "I didn't even try running it because it has the bareword of udp there which I'm pretty sure is illegal?"

    So you found two documentation "typos". One was a reading comprehension and instruction following issue on your part, the other was a lack of testing or investigation.

    The examples in the IO::Socket::INET documentation are not run under strict, so a bareword is completely legal and legitimate. Not only that, it appears as though you changed the excerpt, so it's not even an authentic example from their documentation.

    blah(bareword); sub blah { my $word = shift; print "$word\n"; }

    Output:

    bareword

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://11127618]
Approved by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (2)
As of 2021-05-07 15:34 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Perl 7 will be out ...





    Results (92 votes). Check out past polls.

    Notices?