perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.
Here’s a quick synopsis from “perldoc --help”:
=begin help output
perldoc [options] PageName|ModuleName|ProgramName…
perldoc [options] -f BuiltinFunction
perldoc [options] -q FAQRegex
Options:
-h Display this help message
-r Recursive search (slow)
-i Ignore case
-t Display pod using pod2text instead of pod2man and nroff
(-t is the default on win32 unless -n is specified)
-u Display unformatted pod text
-m Display module’s file in its entirety
-n Specify replacement for nroff
-l Display the module’s file name
-F Arguments are file names, not modules
-v Verbosely describe what’s going on
-X use index if present (looks for pod.idx at C:\Perl\lib)
-q Search the text of questions (not answers) in perlfaq[1-9]
-U Run in insecure mode (superuser only)
PageName>ModuleName…
is the name of a piece of documentation that you want to look
at. You
may either give a descriptive name of the page (as in the case
of
perlfunc') the name of a module, either like Term::Info’ or
like
Term/Info', or the name of a program, like perldoc’.
BuiltinFunction
is the name of a perl function. Will extract documentation
from
`perlfunc’.
FAQRegex
is a regex. Will search perlfaq[1-9] for and extract any
questions that match.
Any switches in the PERLDOC environment variable will be used before the
command line arguments. The optional pod index file contains a list of
filenames, one per line.
=end help output
So, for example, if I wanted everything from the FAQ that talks about
“unique”, I could do this:
perldoc -q unique
and get this:
Found in C:\Perl\lib\pod\perlfaq4.pod
How can I get the unique keys from two hashes?
First you extract the keys from the hashes into lists, then
solve the “removing duplicates” problem described above. For
example:
%seen = ();
for $element (keys(%foo), keys(%bar)) {
$seen{$element}++;
}
@uniq = keys %seen;
Or more succinctly:
@uniq = keys %{{%foo,%bar}};
Or if you really want to save space:
%seen = ();
while (defined ($key = each %foo)) {
$seen{$key}++;
}
while (defined ($key = each %bar)) {
$seen{$key}++;
}
@uniq = keys %seen;
Found in C:\Perl\lib\pod\perlfaq8.pod
How can I call my system’s unique C functions from Perl?
In most cases, you write an external module to do it–see
the
answer to “Where can I learn about linking C with Perl?
[h2xs,
xsubpp]”. However, if the function is a system call, and
your
system supports syscall(), you can use the syscall function
(documented in perlfunc).
Remember to check the modules that came with your
distribution,
and CPAN as well–someone may already have written a module
to
do it.
Perl also has a series of “pages” (not sure what the official name is)
such as perlsyn, perlfunc, etc. These pages discuss specific topics,
such as syntax, functions, lists-of-lists, etc, and can be searched via
perldoc as well.
Hope that helps.
Dan
···
-----Original Message-----
From: Hal Fulton [mailto:hal9000@hypermetrics.com]
Sent: Tuesday, December 16, 2003 11:44 AM
To: ruby-talk ML
Subject: Re: Newbie questionsJamis Buck wrote:
Daniel Carrera wrote:
I haven’t found any (and I’ve been around Ruby for over a year). I
think that Ruby could really benefit from the kind of
documentation
that I’ve seen from Perl.Any volunteers?
OK, I’ve heard this discussed before, but as I’m not a
Perler, I don’t know what the big deal is with perldoc.What is it, what can it do, how is it used, why is it better
than ri, etc.?Hal
