CPAN not so comprehensive

[Anonymous Monk]

Hello Monks. Sorry for posting as anonymous but i could not wait until my password will arrive.

So, here's my concern. I am rather a newbie to perl (i write simple scripts, but i still mix contexts and commit other newb's crimes like using out-of-scope variables and swear that my $precious_Data appears to be empty outside of sub ;)) and i heavily relay on Monastery as well as on CPAN.

But i've ran into same problem again: documentation on CPAN does not answer my questions. Consider following example

Author mentions an 'exec' method of ssh2->channel object in example, but does not write a word what it exactly does :(. Thanks to that after heavily scrolling of this site i still don't know how to use this powerfull (i think so) module.

Of course i am fully aware that Monks are not 1st line of support for newbs, but please answer me: is documentation bad or i am missing something there?
How should i "use/read" CPAN knowledge? Should cycle through @INC and finally open SSH2.pm and analyze it line-by-line to slurp authors' wisdom? Or CPAN is just brief summary of given module and after downloading/ installing i should run it through perldoc or expect some COMPLETE_READ.me text inside tgz?

Don't get me wrong: i did not wrote this post to complain (maybye a little bit:P) but rather to ask you, those who thinks in perl, for advice in how do you actually cope with new modules; ie. do you read it's source to get full view over functionality or there's more human-friedly way.

I strongly belive in perl's power and i want to master it, but everytime when before actual run i need to look for my shoes which were tied by shoelaces to chandelier by some hoaxer, it dispirits me.

I humbly asking for your wise advice and hope that character of my post does not discouraed you.

[BrowserUk]

If you look at the sample, the exec method is called on a $chan object. And if you look at the previous line:

      my $chan = $ssh2->channel();
      $chan->exec('program');

You'll see that is create using the channel() method. Look down for the documentation on the channel method and you find:

channel ( [type, [window size, [packet size]]] )

Creates and returns a new channel object. See Net::SSH2::Channel.

That reference to Net::SSH2::Channel is a live link, and if you click it, you'll find:

exec ( command ) Execute the command on the remote host (calls process("exec", command)). Note that the given command is parsed by the remote shell; it should be properly quoted, specially when passing data from untrusted sources.

Modules by this author are better (if sometimes more tersely) documented than most.

[Anonymous Monk]

Thank you kindly BrowserUk, when you showed it to me, everything seemed to be a bit clearer :). So, documentation can be nested, it's a valuable information.

May i assume that this rule applies to all modules? like when Foo::Bar calls baz method and i did not find (sub?)methods for baz, looking for Foo::Bar::baz is an option?

Question might sound naive, but i am rather skilled in shell scripting/ 8bit assemblers and this whole OO-way of thinking is much abstraction to me. I found it very complicated as you can see on above example...

[BrowserUk]

May i assume that this rule applies to all modules? like when Foo::Bar calls baz method and i did not find (sub?)methods for baz, looking for Foo::Bar::baz is an option?

No. Don't assume that. It is entirely down to how the author choses to document (or not!) his code.

But it certainly does no harm to look for it :)

[VinsWorldcom]

If you have a specific Net::SSH2 question - ask it! I too have had issues trying to understand its use but finally figured out some of my problems. Another challenge is that I'm exclusively on Windows / Strawberry Perl so that's (one of) the only SSH modules that will work - and it comes bundled / compiled with Strawberry in vendor/lib. I was able to understand enough to cobble together a simple SSH client and the CPAN Net::SSH2::Cisco module - a drop in replacement for Net::Telnet::Cisco. Happy to share that code if you think it will help.

That said, in a more general sense, I try to put probably more documentation in my releases than most. I started with inline comments but then moved to POD once I understood what that was, how it worked, and how superior it is to understanding usage for new users. I (most of the time) try to include a pretty complete SYNOPSIS and either an EXAMPLES section or provide bin/ scripts that provide basic functionality which a user can use right away, or customize to their heart's content.

True, some authors just don't document or don't document "well", but that's relative. Someone who writes a module is sometimes so familiar with the way it works and what it does, they may sometimes lose sight that other users may not be as familiar and need a jump-start / working example to build on.

Good luck!

[Anonymous Monk]

Thank you all for fistful of valuable informations. Now i see that being a perlist isn't so colorful and fluffy as being pythonist, but on the other hand, what comes in pain gives more gain ;)

Like on this meme https://pics.me.me/ill-protect-you-ill-keep-you-warm-until-youre-ready-21405659.png ,just s/Gentoo/perl/

[Your Mother]

…being a perlist isn't so colorful and fluffy as being pythonist…

I must add that Python is scaly and black and white, no softness or shades of color at all. :P

[soonix]

not colorful? For Brits we even have colours!