SPUG: perldoc failures on OS X

[Michael R. Wolf]

[I'm writing this from OS X.  Thanks to all who responded to my  
previous "Perl on OS X" posting.  I'm very happy with the new  
"unibody" design (machined from a single aluminum block) which should  
hold up to the physical demands of my "road warrior" schedule.   
And.... I have a *native* command line.  Bye, bye Cygwin.  Thanks for  
making my XP sane. but so long....]

Since my old #1 problem (no portable computing) is solved, a new #1  
problem has emerged: perldoc(1) is installed, but doesn't work.

     $ perldoc perl
     No documentation found for "perl".
     $ perldoc -f chomp
     No documentation found for "perlfunc".
     $ perldoc -q handle
     No documentation found for "perlfaq1".
     No documentation found for "perlfaq2".
     No documentation found for "perlfaq3".
     No documentation found for "perlfaq4".
     No documentation found for "perlfaq5".
     No documentation found for "perlfaq6".
     No documentation found for "perlfaq7".
     No documentation found for "perlfaq8".
     No documentation found for "perlfaq9".
     $

Look familiar?  Is this a Perl or OS X issue?

Is this partial install to be expected in OS X?  Am I expecting a full  
(developer) installation when a partial (GUI-user only) installation  
is the norm?  Or do I merely have a buggy installation of Mac OS 10.5?

On one hand, I want a complete Perl distribution, including  
documentation.  On the other hand there's lots of documentation that  
suggests not mucking with the native Perl installation in /usr/bin/ 
perl (see note #1 below).


If I need to install a more complete version of Perl, where should I go?
  - source install (from http://www.perl.org)
  - ActivePerl (from http://www.ActiveState.com/Products/activeperl)
  - fink (at http://www.finkproject.org)
  - macports (FKA darwinports? at http://www.macports.org)
  - darwinports (at http://www.darwinports.com)
  - Xcode (from ADC (Apple Developer Connection) at http://www.developer.apple.com 
)

I was hoping that the simple stuff would "just work".  Did running  
Perl on Mac OS X just get as complex as running a Unix environment  
(via cygwin.org) on my XP box, or am I missing something simple?

Thanks,
Michael (the newbie OS X guy with 20+ years' Unix experience) Wolf


Notes:
  1.  From perlmacosx(1) man page:

[snip, snip...]

        Updating Apple's Perl

        In a word - don't, at least without a *very* good reason. Your  
scripts can
        just as easily begin with "#!/usr/local/bin/perl" as with "#!/ 
usr/bin/perl".
        Scripts supplied by Apple and other third parties as part of  
installation
        packages and such have generally only been tested with the / 
usr/bin/perl
        that's installed by Apple.

[snip, snip...]

Starting From Scratch
        Unfortunately it is not that difficult somehow manage to break  
one's Mac OS X
        Perl rather severely.

[snip, snip...]


Michael R. Wolf
MichaelRWolf at att.net