I have perl installed as follows:

/usr/local/bin/perl -> perl-5.6.1
/usr/local/bin/perl-5.005
/usr/local/bin/perl-5.6.0
/usr/local/bin/perl-5.6.1
/usr/local/bin/perl-5.7.0
[download]

And likewise for perldoc, and all of the other binaries and scripts in the standard dist. (I also created cpan-5* shell script with obvious behaviour)

/usr/local/lib/perl5 looks like this:

5.005/ 5.6.0/ 5.6.1/ 5.7.0/ site_perl/
[download]

FYI, /usr/bin/perl is a link to /usr/local/bin/perl . In other words, I've got multiple installed versions, with 5.6.1 as the default. I was sure to make the cpan scripts call a specific version of perl, ie here's cpan-5.005 :

#!/usr/local/bin/perl-5.005 -MCPAN -e "shell;"
[download]

I've doen some sanity checks and testing, and yep, executing cpan-5.6.1 as root really does install to the 5.6.1 library without touching the others. And perl-VERSION -V is correctly configured. To manually install a module ("manual" as opposed to CPAN - relative laziness), it's just:

perl-VERSION<
make && make test && make install
[download]

And if we forget, we get the default perl lib, which is currently 5.6.1 . Which is very nice way to break.

Now, our own Perl modules use MakeMaker and so forth to build, test, and install, so the above works for our own modules as well. Now it's really easy to test against different versions of perl.

At this point I must pause to give thanks to the designers of the Perl distribution and installed layout. It wouldn't be possible to do this without the good planning and clear thought that went into so many details of the Perl building and distribution system. But I digress.

Now, I'd like to have perldoc-VERSION give documentation about the installed VERSION library, and perldoc give docs about the default (5.6.1) library. Unfortunately, that doesn't seem to work: I always get back the 5.6.1 docs (or at least that's what the header and footer says). Of course, perldoc-VERSION is itself written in perl: so I edited the shebang line to point to specific versions of perl, ie /usr/local/bin/perl-5.7.0 for the bleeding-edge perldoc-5.7.0 . I was hoping this would "just work" - but alas, the header still says 5.6.1 , for all perldoc-VERSION .

My next step is to read the perldoc source code in depth, and to see what I learn that way. If someone knows off the top of their head, I would much appreciate either further pointers to more info, or an in-depth, lavishly illustrated, annotated-bibliography-attached reply (sarcasm).

Before I do that though, I'll do a quick dump of why I'm at a loss. Show me where I stray from the path of wisdom, o masters! (Aside from anthropomorphizing a perl script)

If I were perldoc, I think my job would be to run accross the perl library, and extract the requested docs (presumably in the module itself, in POD format). Since I'm a perl script, all I do is ask my perl interpreter where it would find libraries. There's a number of obvious ways to ask this: @INC, Config.pm.... possibly others. Now, I know for a fact that perl-VERSION -V lists the correct, VERSION-specific @INC, and so it would presumably find the correct, VERSION-specific modules to snarf PODs out of.... && I know I'm calling the right, VERSION-specific perl binary in the shebang at the top of perldoc-VERSION.

Hence, stumped. I now set myself in meditation upon, if you will, a Holy Writing: the source code of perldoc, Perl by those who Make Perl. Oh, the drama!