Not at all. I learned Perl from the manpages, and I'm mystified how noobs are to discover and convince themselves that "man perlobj" is now bad advice yet remains official.
As for bless/Moose interop, I read somewhere there were big problems mixing the two but don't remember the specifics (I mostly dropped Perl a long time ago over its dogged attempts to guess what I probably wanted when I made a mistake). Others in this thread now say that's not true if it ever was, which is good news for users of pre-Moose CPAN modules.
The Perl 5 world seems to change quite a lot every few years. If people have an old install, perldoc might be out of date. Wouldn't it be better to just add an URL at the top of the page to a page at perl.org and put the best practices for CPAN there?
The question is should the documentation shipped with perl document the features available with that distribution, or should it document the features available in the wider Perl culture?
For example, Moose has always made an effort to cooperate with the native Perl object system. The documentation in the perldoc's for object oriented programming isn't wrong. The skills you learn from perltoot and companions will transfer to Moose, you'll know how the underlying implementation works. Is this the right way to learn Perl's Object Oriented programming? That is an argument the Perl community itself is having[1]. As that argument is resolved the documentation is updated.
If you think about this in startup terms. Moose as a project is 4 years old. Would you invest in a startup that had an exit strategy that was targeted for than than 5 years? Moose has just recently (in the last year or two) reached a dominant market position when compared to the existing competition (Class::MethodMaker, Class::STD, etc) but still is adopted by only 5% of the total market (that is we have ~1K direct downstream dependencies out of about 20K distribution on CPAN). It would be premature to expect the industry to recognize let alone promote Moose as the de-facto standard. However it would be an excellent bet that sometime in the next few years that will happen.
Of the "Modern Perl" distributions out there Moose is one of the most consolidated in it's scope. Things like Catalyst have been gaining new competition (Dancer, Mojolicious) in their respective markets. It's interesting to watch things that appear to my untrained eye like market forces play out across the adoption of various CPAN modules.
To circle back around, perl documentation needs to strike a careful balance between what they can guarantee exists (bless $ref, __PACKAGE__) and what the community accepts as best practice (use Moose;). The documentation needs to intentionally be less dynamic than the fashions of the community. It must be conservative enough to provide continuity so that someone who happens to be on a perl-5.8.8 box (released 3 months before Moose, and still the standard on RHEL if I recall) doesn't learn a whole different set of "best practice" modules than someone on a 5.10.1 box. It does however need to be updated as things like Moose take over the mind share and prove themselves out. When only 1 in 20 modules you run into will likely involve Moose, you'll still need to understand the native solutions. When that ratio changes, the balance will need to change too.
A really well argued way of agreeing with my point that perldoc pages should start with a reference to e.g. a page on perl.org with the present best practices for that perldoc page? :-)
Or maybe as close as possible to get of a formal proof? :-)
>>[Moose] still is adopted by only 5% [of CPAN] [..] It would be premature to expect the industry to recognize let alone promote Moose as the de-facto standard.
The counter argument is that new work generally seems to use Moose. But, of course, new work use the CPAN modules.
Meh, I don't care for being spoonfed. I also read RFCs. I'm actually embarrassed to have paid for Real World Haskell, because if I were as smart as I want to be I wouldn't need it.
In this case, neither perlobj, perlboot, nor perlbot mention any CPAN modules at all, and perltoot cites a couple but Moose isn't among them.
As for bless/Moose interop, I read somewhere there were big problems mixing the two but don't remember the specifics (I mostly dropped Perl a long time ago over its dogged attempts to guess what I probably wanted when I made a mistake). Others in this thread now say that's not true if it ever was, which is good news for users of pre-Moose CPAN modules.