perltutorial
brian_d_foy
<p>I had too much free time today, so I created a new perl man page.
It's been surprisingly useful for other people already.</p>
<h2><a name="name">NAME</a></h2>
<p>perldocs - Perl documentation documentation</p>
<hr />
<h2><a name="synopsis">SYNOPSIS</a></h2>
<p>This documents the perl documentation</p>
<hr />
<h2><a name="description">DESCRIPTION</a></h2>
<p>If you have perl, you should have the documentation.</p>
<p>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.</p>
<p>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.</p>
<readmore>
<h3><a name="reading_the_frickin__manual">Reading the Frickin' Manual</a></h3>
<p>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 <code>perldoc</code> 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.</p>
<pre>
perldoc perldoc</pre>
<p>Any time you want to read a perl manual page, just tell
perldoc to display that page. If I want to read <code>perltoc</code>, I
use <code>perldoc</code>.</p>
<pre>
perldoc perltoc</pre>
<p>Your system may also have the documentation in other
formats, such as HTML or Windows Help files.</p>
<p>You can also read the perl docs on the web: [http://perldoc.perl.org/].</p>
<h3><a name="enough_pod_to_be_dangerous">Enough POD to be dangerous</a></h3>
<p>POD is ``Plain old documentation''. It's a minimal plain text format
that most perlers use to write things. Its format is explained in
<code>perlpod</code>.</p>
<pre>
perldoc perlpod</pre>
<p>You can look at the POD source with <code>perldoc</code>'s -m switch.</p>
<pre>
perldoc -m perlpod</pre>
<p>You can check your (or somebody else's) POD with <code>podchecker</code>
or the Test::Pod module.</p>
<p>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 <code>perldoc</code>'s -l switch.</p>
<pre>
pod2html `perldoc -l perl` > perl.html</pre>
<h3><a name="perltoc">perltoc</a></h3>
<p>If you don't know which page you need to read, start with <code>perltoc</code>,
which is the table of contents for the rest of the core perl
documentation.</p>
<pre>
perldoc perltoc</pre>
<h3><a name="perlfaq">perlfaq</a></h3>
<p>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 <code>perlfaq</code> somewhere.</p>
<p>There are nine <code>perlfaq</code> pages, broken into broad
categories. <code>perlfaq</code> is a table of contents.</p>
<p>You can search the <code>perlfaq</code> pages with <code>perldoc</code>'s -q
switch.</p>
<pre>
perldoc -q perldoc</pre>
<p>You can read the perlfaq online at [http://perldoc.perl.org/perlfaq.html].</p>
<p>Parts of the <code>perlfaq</code> are regularly posted to the usenet group
comp.lang.perl.misc .</p>
<p>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/]</p>
<h3><a name="perlfunc">perlfunc</a></h3>
<p><code>perlfunc</code> 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 <code>perldoc</code>'s -f switch.</p>
<pre>
perldoc -f localtime</pre>
<h3><a name="modules">Modules</a></h3>
<p>Use the <code>perldoc</code> command to read the documentation for
installed modules.</p>
<pre>
perldoc Module::Starter</pre>
<h3><a name="cpan_search">CPAN search sites</a></h3>
<p>Look on CPAN Search, [http://search.cpan.org/], or MetaCPAN, [https://www.metacpan.org/], for
documentation on modules that you haven't installed.</p>
<h3><a name="randal_s_columns">Randal's columns</a></h3>
<p>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].</p>
<h3><a name="google">Google</a></h3>
<p>Learn to use Google to find things. Use <code>perl</code> 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.</p>
<p>For instance, you can limit your search to a particular site
with in a Google search. This query limits itself to perldoc.perl.org</p>
<pre>
site:perldoc.perl.org CGI</pre>
<p>You can search Randal's articles for ``deep copy'',</p>
<pre>
site:www.stonehenge.com "deep copy"</pre>
<p>or search Perlmonks for @ISA</p>
<pre>
site:perlmonks.thepen.com @ISA</pre>
<p>or search CPAN Search for ``pop3 ssl''</p>
<pre>
site:search.cpan.org POP3 ssl</pre>
<h3><a name="the_camel">The Camel</a></h3>
<p>[http://shop.oreilly.com/product/9780596004927.do]</p>
<p>You don't have to buy ``Programming Perl'', also known as the
Camel book, but you also don't have to have any free time
either. It's your choice. Every copy you buy supports starving
children in Mountain View.</p>
<h3><a name="the_llama">The Llama</a></h3>
<p>[http://shop.oreilly.com/product/0636920018452.do]</p>
<p>The Llama book is ``Learning Perl''. You don't have to learn
Perl, but it helps. You'd be surprised how many people try
to get by without learning Perl.</p>
<h3><a name="the_ram">The Ram</a></h3>
<p>[http://www.oreilly.com/catalog/perlckbk2/index.html]</p>
<p>A lot of people like ``The Perl Cookbook''. When you aren't reading
its hundreds of pages for Perl recipes, it makes a darned
good paperweight or a doorstop.</p>
<h3><a name="comprehensive_perl_archive_network__cpan_">Comprehensive Perl Archive Network (CPAN)</a></h3>
<p>Most of what you think of CPAN probably isn't: it's just the archive.
CPAN Search, module uploads, CPAN.pm, and other things are not CPAN.</p>
<p>CPAN has its own FAQ that explains it all. [http://www.cpan.org/misc/cpan-faq.html]</p>
<h3><a name="perl_authors_upload_server__pause_">Perl Authors Upload Server (PAUSE)</a></h3>
<p>PAUSE is the author interface to CPAN, and it has its own documentation.
[http://pause.perl.org/pause/query?ACTION=pause_04about|http://pause.perl.org/pause/query].</p>
</readmore>
<!-- Node text goes above. Div tags should contain sig only -->
<div class="pmsig"><div class="pmsig-366986">
-- <br />
brian d foy <bdfoy@cpan.org>
</div></div>