[perl #91720] "perldoc -l -q" does not usefully work

On Thu May 26 14:19:50 2011, eli@panix.com wrote:
> 
> "perldoc -l -q KEYWORD" lists all of the perldoc FAQ pod files
> instead of just the ones that match the KEYWORD.
> 
> 

While the poster's complaint is correct ...

#####
$ perldoc -l -q sort
/usr/local/lib/perl5/5.14.2/pods/perlfaq1.pod
/usr/local/lib/perl5/5.14.2/pods/perlfaq2.pod
/usr/local/lib/perl5/5.14.2/pods/perlfaq3.pod
...
/usr/local/lib/perl5/5.14.2/pods/perlfaq9.pod

# versus:

$ perldoc -u -q sort | grep '=head1 Found in' | cut -d ' ' -f4
/usr/local/lib/perl5/5.14.2/pods/perlfaq4.pod
#####

... the amount of code we would have to write in Pod::Perldoc would be
considerable and perhaps not worth the effort.

perldoc's usage statement explains the '-l' option thus:

#####
    -l   Display the module's file name
#####

That's accurate for most, but not all, uses of 'perldoc'.  The way it's
actually implemented inside Pod::Perldoc means that '-l' would be more
precisely defined as:

#####
    -l  Display a list of absolute paths to files which 'perldoc' would
subsequently use if the '-l' option were not present as the basis for
further actions such as sending a file to a POD-formatter.  (Those
further actions are not taken because 'perldoc' always exits after
displaying that list.)
#####

... which is quite a mouthful and usually less useful.  Usually you're
just looking for the location of a single file containing POD:

#####
$ perldoc -l perlrequick
/usr/local/lib/perl5/5.14.2/pods/perlrequick.pod

$ perldoc -l List::Compare
/usr/local/lib/perl5/site_perl/5.10.0/List/Compare.pm
#####

But you could actually ask for the paths to more than one file
containing POD:

#####
$ perldoc -l perlrequick List::Compare
/usr/local/lib/perl5/5.14.2/pods/perlrequick.pod
/usr/local/lib/perl5/site_perl/5.10.0/List/Compare.pm
#####

However, *other* 'perldoc' options, including '-u', '-m' and the default
case of no option at all, will only take action on the *first* item in
that list.

#####
$ perldoc -u perlrequick List::Compare
Perldoc is only really meant for reading one document at a time.
So these parameters are being ignored:
/usr/local/lib/perl5/site_perl/5.10.0/List/Compare.pm

=head1 NAME

perlrequick - Perl regular expressions quick start
...
#####
(The first three lines of output there are an argument to 'warn' and so
go to STDERR, not to the pager.)

In the case of the '-q' option, the list of absolute paths which
'perldoc' will subsequently use (blah, blah, blah) is hard-wired to the
paths to the nine perlfaq*.pod files mentioned above.  'perldoc' runs
regexes against those nine files, extracts the relevant Q&A pairs, then
concatenates them to a temporary file which is sent off to the
POD-formatter.  But if we pass the '-l' option as well as the '-q'
option, 'perldoc' always exits after displaying the list and never gets
as far as using the value provided to '-q' as a search pattern.

In principle it would be possible to modify this code in
Pod::Perldoc::process():

#####
    if ($self->opt_l) {
        DEBUG and print "We're in -l mode, so byebye after this:\n";
        print join("\n", @found), "\n";
        return;
    }
#####

... to have a different behavior for the case of '($self->opt_l and
$self->opt-q)', but the amount of code someone would have to write --
and the amount of code the Pod::Perldoc maintainer would have to test
and maintain -- hardly seems worth it.  Especially when, in a Unixish
environment, you could use the 'perldoc -u | grep | cut' pipeline I used
near the top of this post.

So my inclination is to reject this feature request -- but what do other
people think?

Thank you very much.
Jim Keenan

---
via perlbug:  queue: perl5 status: new
https://rt.perl.org:443/rt3/Ticket/Display.html?id=91720

• [perl #91720] "perldoc -l -q" does not usefully work by James E Keenan via RT