I found the following comment in perldoc

perldoc perldoc
       ...
       -X   Use an index if it is present -- the -X option 
            looks for an entry whose basename matches the
            name given on the command line in the file
            "$Config{archlib}/pod.idx". The pod.idx file
            should contain fully qualified filenames, one
            per line.
 
       ...
[download]

So it sounds like the pod.idx file contains fully qualified filenames, one per line.

Yes, I read that too. However this file does not exist on any system where Perl is. "Filenames" of which files? I have to believe that there is some PERL source code which will correctly create this file, but I can't find it.

sobeach writes: "Filenames" of which files?

The files you want to index.

---

s//----->\t/;$~="JAPH";s//\r<$~~/;{s|~$~-|-~$~|||s |-$~~|$~~-|||s,<$~~,<~$~,,s,~$~>,$~~>,, $|=1,select$,,$,,$,,1e-1;print;redo}

There is no standard way to "correctly" create this file. Without the -X option, perldoc searches for the usual locations. With the -X option, it searches an alternative list of documentation files. So the quesion is: what do you want in the list?
"What should it profit a man, if he should win a flame war, yet lose his cool?"

pod.idx files are not needed to use Perl or the perldoc system. A pod.idx file simply contains a list of .pod files. To generate a list of pod files on a *nix system you would use:

locate .pod >filelist

Although I don't know why you would want to do this. Perhaps if you tell us what you are trying to accomplish?

I've never noticed this option, but I can think of a reason to use it: I have loads of local installs and development trees of modules. This could be useful to review the documentation without needing to search for the module(s) first.

I'd probably index .pm files too, though :-)

"What should it profit a man, if he should win a flame war, yet lose his cool?"

Couldn't find the FM either. Here's the code...I guess this is RTFC ;) It's in Pod::Perldoc. Command line option -X translates to the attribute podidx in the Pod::Perldoc::options_processing method. Pod::Perldoc::grand_search_init is where packages are found matching the search package.

sub grand_search_init {
    my($self, $pages, @found) = @_;

    foreach (@$pages) {
        if ($self->{'podidx'} && open(PODIDX, $self->{'podidx'})) {
            my $searchfor = catfile split '::', $_;
            $self->aside( "Searching for '$searchfor' in $self->{'podi
+dx'}\n" );
            local $_;
            while (<PODIDX>) {
                chomp;
                push(@found, $_) if m,/$searchfor(?:\.(?:pod|pm))?\z,i
+;
            }
            close(PODIDX)            or die "Can't close $$self{'podid
+x'}: $!";
            next;
        }
        ...
[download]

It looks like the .idx file would speed up searches for package pod if the .idx file existed.

Hope that helps.

Ok Monks. There exists a one-liner but I am hoping to make him do some of the work himself.

You should have a look at the perlindex cpan distro and see if that will do what you want.