How to navigate the docs?

[Mike]

What do you do when you want to find something in the Perl
documentation, and you have *no idea* in which of the many perlxxxx
it is? I've tried perltoc in the past with little success.

At this point someone would reply "But WHAT are you looking for???",
which would miss the point of my question, which is finding general
strategies for using the Perl docs.

The zsh documentation is also split into several man pages, but at
least one also has the option of doing "man zshall", which brings
up the mongo page for the whole zshebang that one can do a global
search on. Is there anything like this for Perl, or maybe a
search-engine-assisted doc page for Perl? (Google is not good enough
for this task; too many of the Perl keywords are too widely used
for a basic Google search to produce useful hits.)

Mike

 

[Sherm Pendley]

What do you do when you want to find something in the Perl
documentation, and you have *no idea* in which of the many perlxxxx
it is? I've tried perltoc in the past with little success.

'perldoc perl' gives a pretty good one-line description of the core
pods, and 'perldoc perlmodlib' gives the same for core modules.

<http://perldoc.com> provides full-text searching for the core pods &
modules, and <http://search.perl.org> for CPAN modules.

And of course, there's 'perldoc -q keyword' to search the FAQ.

sherm--

 

[Tad McClellan]

What do you do when you want to find something in the Perl
documentation, and you have *no idea* in which of the many perlxxxx
it is?

I grep(1) the *.pod files directly.

If that gives information overload, I grep only the "headlines"
in the *.pod files:

grep ^= *.pod | grep -i searchterm

Another way to reduce the number of hits is to search for "Searchterm"
rather than "searchterm" on the assumption that titles or beginning
of sentences are particularly relevant.

 

[Matt Garrish]

Is there anything like this for Perl, or maybe a
search-engine-assisted doc page for Perl? (Google is not good enough
for this task; too many of the Perl keywords are too widely used
for a basic Google search to produce useful hits.)

Have you tried the search engine at perldoc.com? Or if all else fails,
googling just that site.

Matt

 

[Bill Smith]

What do you do when you want to find something in the Perl
documentation, and you have *no idea* in which of the many perlxxxx
it is? I've tried perltoc in the past with little success.

At this point someone would reply "But WHAT are you looking for???",
which would miss the point of my question, which is finding general
strategies for using the Perl docs.

Many of us "senior citizens" are good at finding info in books, but have
not developed the analogous skills for using electronic documentation.
I start with my well worn copy of "Perl in a Nutshell". It usually
provides the key to find full documentation with perldoc. My copy of
the book improves with age as I add margin notes and cross-references.
When this fails, I also grep the .pod files. I wish that someone would
write a program that uses the algorithm in perldloc to find the .pod
files of interest, and then searches through each of them with a regular
expression the way that grep does.

 

[Anno Siegel]

Many of us "senior citizens" are good at finding info in books, but have
not developed the analogous skills for using electronic documentation.
I start with my well worn copy of "Perl in a Nutshell". It usually
provides the key to find full documentation with perldoc. My copy of
the book improves with age as I add margin notes and cross-references.

A senior citizen myself, I like to do that too. But I find that software,
including Perl, moves too fast, so books age too fast. I don't come
across the pearls of wisdom I once penciled into the 1991 Camel anymore.

There ought to be a method to attach notes to pods that re-appear
in the next version as long a the surrounding text is still there.
A diff/patch combo could do a decent job...

When this fails, I also grep the .pod files. I wish that someone would
write a program that uses the algorithm in perldloc to find the .pod
files of interest, and then searches through each of them with a regular
expression the way that grep does.

Yes, that is a request that comes up now and again. Years ago I took
a look at perldoc with an intent of adding that, but the code was a mess
and I gave up. Instead I have used a stand-alone script (shown below)that
searches the standard .../pod directory, like what Tad suggests to do
manually. It does a good job, but it doesn't give you the comfort of
searching everything that perldoc can find. Only integration into
perldoc would give that. These days, the perldoc code looks much more
inviting, it shouldn't be too hard.

Anno

#!/usr/local/bin/perl
use strict; use warnings; $| = 1;
use Config;
use Getopt::Std;

getopts( 'l', \ my %opt);
my $re = shift || '';
if ( $re =~ m{^(/?)(.*)\1$} ) {
$re = $2;
} else {
$re = quotemeta $re;
}
die "regex must be given\n" unless $re;
$re = qr/$re/;

my %pod_files = get_pod_files() or die "Can't find pod files";
while ( my ( $name, $file) = each %pod_files ) {
if ( $opt{ l} ) {
print "$name\n" if grep_pod( $re, $file);
} else {
print "$name: $_" for grep_pod( $re, $file);
}
}

########################################################################

sub get_pod_files {
my $privlib = $ENV{ PERL_PRIVLIB} || $Config{ privlib};
return unless $privlib;
my ( $pod_dir, $d);
for ( qw( pod pods) ) {
$pod_dir = "$privlib/$_";
last if opendir $d, $pod_dir;
}
return unless $d;

my %pod_files;
while ( my $pod = readdir $d ) {
( my $name = $pod ) =~ s/\.pod$// or next;
$pod_files{ $name} = "$pod_dir/$pod";
}
%pod_files;
}

sub grep_pod {
my ( $re, $file) = @_;
open my( $f), $file or return;
my @coll;
while ( <$f> ) {
next unless $_ =~ $re;
push @coll, $_;
last unless wantarray;
}
@coll;
}
__END__

 

[Kai Spitzley]

What do you do when you want to find something in the Perl
documentation, and you have *no idea* in which of the many perlxxxx
it is? I've tried perltoc in the past with little success.

A man -k equivalent for Perl would a godsend.

 

[Uri Guttman]

KS> A man -k equivalent for Perl would a godsend.

perl's docs are usually converted to man forms upon installation. if you
install them in their own directory (part of the configure process) you
can then build their own man -k index. then you can do man -Mperlmandir
-k (using your dir for the perl man pages).

you do have to rebuild the index when you install new modules.

so there is a man -k (not even an equivalent) but you have to set it up.

another idea is to install tkman/glimpse. it gives you full doc search
and it has commands to rebuild the glimpse indexes. you can use this for
your entire man set and when searching select a subset of man dirs. tkman
is a decent man gui (even if it is written in tk). it also handles
texinfo which is a nice plus.

uri

 

[Bill Smith]

--snip--

Yes, that is a request that comes up now and again. Years ago I took
a look at perldoc with an intent of adding that, but the code was a mess
and I gave up. Instead I have used a stand-alone script (shown below)that
searches the standard .../pod directory, like what Tad suggests to do
manually. It does a good job, but it doesn't give you the comfort of
searching everything that perldoc can find. Only integration into
perldoc would give that. These days, the perldoc code looks much more
inviting, it shouldn't be too hard.

Thanks, so far your code works great. I also like the fact that it
accepts perl RE's.

 

[Jazeker]

A man -k equivalent for Perl would a godsend.

If you have a windows machine, install ActivePerl... the html-ified
docs are quite handy.