Whether learn­ing a pro­gram­ming lan­guage, work­ing through a prob­lem, or try­ing to under­stand a new library, it may be tempt­ing to flail around craft­ing just the right search engine query or cry for help on a forum like Stack Overflow. But look at any guide to ask­ing good ques­tions and you’ll find this com­mand­ment at the top: do your research. And one of the pri­ma­ry sources of that research is the offi­cial doc­u­men­ta­tion for the lan­guage or library in question.

The perldoc command

Fortunately, Perl and its mod­ules come installed with exten­sive doc­u­men­ta­tion, also avail­able on the Web. Locally, you can use the perldoc command-​line pro­gram, or if you have the doc­u­men­ta­tion installed as Linux/​Unix man pages (short for man­u­al pages) you can use the stan­dard man com­mand. Because that isn’t always the case and because it has more Perl-​specific options, I rec­om­mend perldoc.

Note that if you’re using the Perl pro­vid­ed by your oper­at­ing sys­tem dis­tri­b­u­tion you may not have any doc­u­men­ta­tion installed at all with­out a sep­a­rate pack­age. For exam­ple, Ubuntu Linux calls this pack­age perl-doc; you can install it with this command:

sudo apt-get install perl-doc

(Splitting Perl across sev­er­al pack­ages is a com­mon oper­at­ing sys­tem dis­tri­b­u­tion tac­tic; it’s one of the rea­sons I rec­om­mend installing your own Perl.)

Once you’re sure you have the com­mand avail­able, run the fol­low­ing com­mand to get an intro­duc­tion to the Perl pro­gram­ming language:

perldoc perlintro

All of the built-​in doc­u­men­ta­tion begins with ​“perl” as above, so you can say perldoc perlrun to find out how to exe­cute Perl, perldoc perlfaq to get a direc­to­ry of fre­quent­ly asked ques­tions, or perldoc perltoc for a table of con­tents list­ing every­thing available.

As I men­tioned above, the perldoc com­mand has sev­er­al use­ful options. You can run perldoc perldoc for a full descrip­tion, but here are some highlights:

• perldoc -h: a brief help message
• perldoc -f function: describe a spe­cif­ic func­tion from perlfunc
• perldoc -q regular-expression: search the ques­tions in the var­i­ous perlfaq documents
• perldoc -v variable-name: describe a spe­cif­ic pre­de­fined vari­able from perlvar

The last argu­ment to perldoc can be a doc­u­men­ta­tion page as described ear­li­er, an installed mod­ule, a Perl pro­gram name in your path, or the URL to a Perl mod­ule or Plain Old Documentation (POD) file.

The Perldoc Browser website

You may have noticed a num­ber of links above to the perldoc.perl.org web­site. This is a great friend­ly resource if you pre­fer read­ing in a web brows­er, and you can use fea­tures like bookmarks/​favorites and send­ing hyper­links to oth­ers. It has a search engine and you can even switch between dif­fer­ent Perl ver­sions (includ­ing development).

MetaCPAN

Perl is more than the lan­guage and its stan­dard mod­ules. The Comprehensive Perl Archive Network (CPAN) has over 200,000 open-​source Perl mod­ules con­tributed by authors all over the world, solv­ing com­mon and not-​so-​common soft­ware devel­op­ment prob­lems from asyn­chro­nous pro­gram­ming to XML devel­op­ment.

In addi­tion to using the perldoc com­mand described ear­li­er to under­stand locally-​installed mod­ules, you can use the MetaCPAN web site​’s search engine (in both reg­u­lar and reg­u­lar expres­sion fla­vors) to dis­cov­er and learn how to save time piec­ing togeth­er pro­grams instead of rein­vent­ing the wheel. I always check MetaCPAN first when I need to write some Perl.

Writing your own

Perl has its own markup lan­guage called Plain Old Documentation (POD), and you can either inter­leave it with your own pro­gram source code or save it in sep­a­rate files. The perlpod doc­u­men­ta­tion page has all the details and the perlpodstyle page will guide you in writ­ing in a style con­sis­tent with oth­er doc­u­men­ta­tion. And if you need to pub­lish else­where, there are trans­la­tors for HTML, LaTeX, PDF, and oth­er for­mats on CPAN. You can also pro­vide your doc­u­men­ta­tion to oth­ers via a ded­i­cat­ed web appli­ca­tion; this is an excel­lent tool for teams with internal-​only (“DarkPAN”) code.

Documentation is like a present you give to both your lat­er self and any­body else that needs to use your work. I high­ly rec­om­mend you spend time writ­ing it in addi­tion to the usu­al developer-​level source code com­ments. This is espe­cial­ly impor­tant if you plan to release open source on CPAN; oth­er­wise, no one will under­stand what it does or why they should care. I’m incred­i­bly grate­ful to every devel­op­er who has put in the effort.