Perl documentation documentation

I had too much free time today, so I created a new perl man page. It's been surprisingly useful for other people already.

NAME

perldocs - Perl documentation documentation

DESCRIPTION

If you have perl, you should have the documentation.

Before perl existed, it had no documention. Then version 1 came along and that changed. As I write this, perl is up to version 5.8 (and up to 5.16 as I update this) and it has over a thousand pages of documentation that comes with perl itself.

I generally advise people to read the documentation first, but it's too late for that in most cases, and even if you did, it would take you a long time to finish. The trick is to know where to look to get what you need.

Reading the Frickin' Manual

The perl manual pages are on your system somewhere (unless you have Mac OS X, it seems: stay tuned for updates). You can use the perldoc command line program to read a particular page. If you want to find out how to use it, use the perldoc command to read its documentation.

        perldoc perldoc

Any time you want to read a perl manual page, just tell perldoc to display that page. If I want to read perltoc, I use perldoc.

        perldoc perltoc

Your system may also have the documentation in other formats, such as HTML or Windows Help files.

You can also read the perl docs on the web: http://perldoc.perl.org/.

Enough POD to be dangerous

POD is ``Plain old documentation''. It's a minimal plain text format that most perlers use to write things. Its format is explained in perlpod.

        perldoc perlpod

You can look at the POD source with perldoc's -m switch.

        perldoc -m perlpod

You can check your (or somebody else's) POD with podchecker or the Test::Pod module.

You can convert POD to other formats, including LaTeX, HTML, and text. Look for the pod2latex, pod2html, and pod2text. You need to give it the file name to convert, which you can get with perldoc's -l switch.

        pod2html `perldoc -l perl` > perl.html

perltoc

If you don't know which page you need to read, start with perltoc, which is the table of contents for the rest of the core perl documentation.

        perldoc perltoc

perlfaq

Even if you are one in a million, that leaves 5,000 people just like you, and if only 1 in a thousand use perl, that's still 5 perl programmers just like you. Every one of those 5 people have already asked your question, twice. The answer might be in perlfaq somewhere.

There are nine perlfaq pages, broken into broad categories. perlfaq is a table of contents.

You can search the perlfaq pages with perldoc's -q switch.

        perldoc -q perldoc

You can read the perlfaq online at http://perldoc.perl.org/perlfaq.html.

Parts of the perlfaq are regularly posted to the usenet group comp.lang.perl.misc .

If you want to see the latest version of the perlfaq, you can check out the sources from CVS. http://cvs.perl.org/viewcvs/cvs-public/perlfaq/

perlfunc

perlfunc lists the documentation for each perl function, and although you should read it through at least once in your life, you can read the documentation for a single function with perldoc's -f switch.

        perldoc -f localtime

Modules

Use the perldoc command to read the documentation for installed modules.

        perldoc Module::Starter

CPAN search sites

Look on CPAN Search, http://search.cpan.org/, or MetaCPAN, https://www.metacpan.org/, for documentation on modules that you haven't installed.

Randal's columns

Randal has spent way too much time writing about Perl for it all to go to waste. Most of his columns are available online. http://www.stonehenge.com/merlyn/columns.html.

Google

Learn to use Google to find things. Use perl as a keyword. You only think this is obvious, but read the questions in usenet groups or on Perlmonks for a while to find out just how many people can't use a search engine.

For instance, you can limit your search to a particular site with in a Google search. This query limits itself to perldoc.perl.org

        site:perldoc.perl.org CGI

You can search Randal's articles for ``deep copy'',

        site:www.stonehenge.com "deep copy"

or search Perlmonks for @ISA

        site:perlmonks.thepen.com @ISA

or search CPAN Search for ``pop3 ssl''

        site:search.cpan.org POP3 ssl

Comment on Perl documentation documentation Select or Download Code

Replies are listed 'Best First'.
Re: Perl documentation documentation by demerphq (Chancellor) on Nov 17, 2004 at 13:59 UTC
You've missed out my favorite way to use the Perldocs: The ActiveState HTML documentation pack. It comes with an index which makes it a lot easier to browse the list of possible docs to find what you need (hmmm is it in perlop or is it perlfunc....) And if you use on of the many index updaters that are floating around the internet it will even list all of your installed modules too. Afaik its possible to get the same stuff for *nix too, although i have no experience with how to do it. --- demerphq	[reply]
Re^2: Perl documentation documentation by brian_d_foy (Abbot) on Nov 17, 2004 at 14:38 UTC
I'm not a Windows person and don't have access to Windows this week (the client site training machines are all Red Hat!). I knew something like that existed, but I don't know the details. Is it on the web anywhere? I see Perl Core Documentation on the ActiveState web site, but no index. Maybe we should one it available, even if we have to write our own. -- brian d foy <bdfoy@cpan.org>	[reply]
Re^3: Perl documentation documentation by tomhukins (Curate) on Nov 17, 2004 at 14:54 UTC
Jon Allen has put together a similar Web view of Perl's core documentation recently, as described in barbie's use.perl journal.	[reply]
Re^3: Perl documentation documentation by demerphq (Chancellor) on Nov 18, 2004 at 19:30 UTC
IIRC you can install ppm on a linux box and then download the ppm of the Activestate docs. There are also a set of activestate doctools for producing the index and etc. Maybe you aught ot look at one of their linux or solaris builds which will probably also contain it. And my opinion is that the tools involved should be coopted into the core. :-) BTW, i forgot to mention, class document if you submit it to p5p ill definately send a ++vote email in response. (Er, assuming i see it) --- demerphq	[reply]
Re^3: Perl documentation documentation by jplindstrom (Monsignor) on Nov 19, 2004 at 22:28 UTC
For the Windows users out there: If you installed Perl in the default location, open C:\Perl\html\index.html and bookmark it right away. /J	[reply]
Re^2: Perl documentation documentation by jobi (Scribe) on Nov 19, 2004 at 12:04 UTC
There is also Perlbook, which is in PDF format, with a nice index. Find it at: http://search.cpan.org/~bmidd/perlbook-5.005_02-a/ jobi	[reply]
Grammar police by runrig (Abbot) on Nov 16, 2004 at 22:12 UTC
When you reading it's... `s/$that/When you're not reading its.../`	[reply] [d/l]
Re: Perl documentation documentation by talexb (Chancellor) on Nov 17, 2004 at 01:58 UTC
A lot of people like ``The Perl Cookbook''. When you reading its hundreds of pages for Perl recipes, it makes a darned good paperweight or a doorstop. Maybe when you have finished* reading ..* instead? Alex / talexb / Toronto "Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds	[reply]
Re: Perl documentation documentation by Nkuvu (Priest) on Nov 17, 2004 at 14:35 UTC
The perl manual pages are on your system somewhere (unless you have Mac OS X, it seems: stay tuned for updates). I'm curious about this statement. My installation of OS X seems to have `perldoc` and the Perl manpages installed just fine. So I'm still waiting for updates...	[reply] [d/l]
Re^2: Perl documentation documentation by brian_d_foy (Abbot) on Nov 17, 2004 at 14:41 UTC
If you installed your own Perl, you have all of the documentation. If you are using the default Perl, some things are missing in some cases (see the macosx@perl.org mailing list discussions, for instance). -- brian d foy <bdfoy@cpan.org>	[reply]
Re^3: Perl documentation documentation by Nkuvu (Priest) on Nov 17, 2004 at 17:14 UTC
Jiminy Crickets. I think I'm looking in the right spot, but I'm not positive. I went to perl.org, then mailing list archives, and took a peek at the perl.macosx archive. Over 8000 messages, no search function. In my brief look through the messages, I noted a message which suggested that `perlfunc.pod` and `perldiag.pod` are missing from the default Perl installation. Is this perhaps what you were thinking of? I do have the Developer Tools installed, so I'm not sure if my copies of the above pod files were installed when I installed the Developer Tools or the System. But they're certainly both on my system.	[reply] [d/l] [select]
Re^4: Perl documentation documentation by brian_d_foy (Abbot) on Nov 17, 2004 at 17:25 UTC
Re^2: Perl documentation documentation by anadem (Scribe) on Nov 18, 2004 at 02:41 UTC
>... (unless you have Mac OS X, it seems: stay tuned for updates).< I'm curious about this statement. My installation of OS X seems to have perldoc and the Perl manpages installed just fine. So I'm still waiting for updates... Nvuku -- (fyi & fwiw) on my Mac, which has the default perl installation that came in OSX 10.3.5, "perldoc perlfunc" (or any other target) gets 'No documentation found for "perlfunc"'. The perldoc for perlfunc can be opened through "man perldoc" though. I'm kinda new to mac and to perl docs, so Brian's perldoc man page is very welcome to me -- and maybe my failure to have normal perldoc on the mac is me doing something wrong.	[reply]
Re^3: Perl documentation documentation by Nkuvu (Priest) on Nov 18, 2004 at 15:57 UTC
From what Brian has said (and the info I gleaned from the message in the newsgroup) it doesn't seem like you're doing anything wrong at all. I didn't run into this issue, it seems, because I installed the Developer Tools shortly after installing OS X. And apparently that also includes the missing perldoc files.	[reply]
Re: Perl documentation documentation by Anonymous Monk on Nov 17, 2004 at 20:02 UTC
How to RTFM	[reply]
Re: Perl documentation documentation by toolic (Bishop) on Jan 28, 2010 at 00:22 UTC
In light of the recent difficulties accessing the official Perl documentation website (http://perldoc.perl.org), the docs can also be accessed from the CPAN website at http://search.cpan.org/~dapm/perl-5.10.1/pod/perl.pod, for example. Consider this a backup plan.	[reply]
Re: Perl documentation documentation by simonflk (Pilgrim) on Nov 24, 2004 at 14:25 UTC
You can look at the POD source with perldoc's -m switch. I thought `-m` gave you the document source. Shouldn't that be `-u` ? (I realise that it's the same thing in the example you gave) -- simonflk	[reply]
A reply falls below the community's threshold of quality. You may see it by logging in.