Many people are discovering that the scripting language Perl is the most useful language for getting many computing tasks done. In the last of his articles for Perlmonth Dave Cross takes a brief overview of Perl documentation.
This article first appeared in the January 2000 issue of the online Perl magazine PerlMonth (which no longer seems to be online).
Note: All of the articles in the RTFM series are really old. It’s likely that many of the links no longer work. I’m leaving these articles online for historical reasons, but these days you should visit perl.org for links to the best current Perl resources.
Introduction
A slightly different RTFM column this month. As I’ve covered just about every source of Perl help and advice over the last seven columns, this will be the last RTFM. In it I intend to revisit all of the previous columns and point out any updates and omissions.
Distribution Documentation
In the first two columns, I covered the documentation that is distributed free with every copy of Perl. The documentation can be accessed using the perldoc command or the Unix man command. It is also possible to convert the documents into HTML files (this is done automatically when you install the ActiveState version of Perl under Windows).
This documentation should always be your first port of call when you have a Perl question. This is for at least three good reasons:
- The version that you have will be specific to the version of Perl that you have installed. Any other sources of information won’t know exactly which version you have and therefore which features it supports.
- You’ll get an answer much quickly by looking locally that you would by posting a question off to a mailing list or a newsgroup. In these cases you might have to wait hours or even days before you get a response.
- The answers in the Perl documentation are definitive. They have been written by people who are closely involved with the development of the language. This can’t be said for most other sources of information.
The Perl documentation comes in three major sections. The first is the core Perl documentationwhich is a definitive reference to Perl and the second is the Perl Module documentation which describes all of the Perl modules which are distributed with Perl (for example CGI.pm and Data::Dumper.pm). The final section (and probably the most important) is the Perl Frequently Asked Questions list. This contains a huge number of the questions that often get asked on the Perl newsgroups together with their answers. These documents are invaluable and every Perl programmer should be familiar with them.
The link that I gave to the documentation on the web is still valid, but on the revamped www.perl.com website, a better link is:
for most of the documentation, and:
for the FAQs.
Plain Old Documentation
In my third column, I gave a quick tutorial on writing documentation for your own Perl code, using the simple markup language called POD (for Plain Old Documentation).
The definitive reference for writing POD is at:
Perl Books
In my next column I digressed slightly from free Perl documentation to look at Perl books. I listed a number of Perl books that I felt that every Perl programmer should own and also suggested a number of other books that you might consider.
In particular I mentioned a few ‘eagerly awaited’ books. Many of these are now available – so here’s a short addenda to my list.
CGI Programming with Perl (O’Reilly) ISBN: 1565924193
Shishir Gundavaram
When I wrote the original books article in July, this book was due out in December 1999. It’s now January 2000 and the O’Reilly web site is showing this book as available in about June. This is a much-needed update to CGI Programming on the World Wide Web which is now out of print and I wish there was some way it could be published sooner.
Mastering Algorithms with Perl (O’Reilly) ISBN: 1565923987
Jon Orwant, Jarkko Hietaniemi & John Macdonald
Perl is often seen as a lanuage for ‘quick and dirty’ scripts or a ‘glue language’ for sticking together pieces of code in other languages that do the ‘real work’. It is, of course, perfect for these uses, but in many cases it can be used to do the ‘real work’ as well as any other language. This book attempts to prove this by looking at some classic Computer Science algorithms and showing how to implement them using Perl.
Not a book for the ‘script kiddies’ who just want to put a counter on their home page, but this book is a very welcome addition to the Perl canon.
Object Oriented Perl (Manning) ISBN: 1884777791
Damian Conway
Manning Publications are new to the Perl publishing world and with their first two books (this one and Elements of Programming with Perl discussed below) they have made a very impressive entrance.
This was one of the most eagerly awaited Perl books for some time – and it more than lived up to everyone’s expectations. Other books have discussed the design and implementation of objects using Perl, but this is the first book dedicated to the subject. Not only is the subject matter useful and interesting, but the style is very readable. I think I’ll be adding this book to the ‘must have’ category.
Elements of Programming with Perl (Manning) ISBN: 1884777805
Andrew L. Johnson
This was Manning’s second Perl book and it’s another great book. This book is aimed at the non-programmer who wants to start learning Perl. Until this book arrived, the only good Perl tutorial books assumed a certain level of programming experience in other languages and the absolute beginner was left buying Learn Perl in 25 Minutes or Perl for Complete Numbskulls. Thankfully this is no longer the case as this book takes the beginner right from ‘what is a program?’ right through to writing some really quite complex programs.
N.B. – One final point about my book article. In it I made a couple of jokey remarks about shopping at Amazon. As regular Slashdot readers will know, over the last couple of months Amazon have been engaged in a couple of activities which are contrary to the spirit of free and open trade on the world wide web. I would therefore like to ask you to consider using other online book stores before Amazon.
Perl Newsgroups
In the October RTFM, I discussed Perl Newsgroups. This topic ties in very closely with the bundled Perl documentation that I discussed earlier. This is because by understanding the documentation that you have on your machine will save a huge number of flames when you become the one thousandth person to post a FAQ to the newsgroup.
As I write this the Perl newsgroups are full of people asking why their guest book script is showing the date as 04/01/100 or 01 Jan 19100. One thread has the subject 19100: don’t acuse me of not reading the documentation, I know I didn’t. Can you imagine the kind of responses this received from the regular posters? Even Matt Wright has finally put Y2K fixes to his scripts on his web site, so there really is no excuse for not finding out what localtime returns.
In the original article I posted a number of rules that would enable you to get the most out of the Perl newsgroups without annoying the people whose help you want. As this column is a sumamry, here is a summary of these rules in one rule:
- Remember that the people whose help you want are a) people (so be polite) and b) posting answers to questions in their own time, for no pay (so don’t waste their time!)
Perl Websites
In November I looked at Perl websites. I fully expected a number of emails pointing out sites that were missing from of emails pointing out sites that were missing from my list, but none arrived. This means that either I did an excellent job of surveying the most useful Perl websites or no-one was reading. Somehow, I prefer the first explaination.
One website that I did miss out (because I read the mailing list version) was the Perl news site at:
One this site you can find all the latest Perl news (and a good deal of the earlier Perl news). Of particular interest on this site is MyPortal at http://www.news.perl.org/my_portal/. On this page you can create a customised view on news from a number of sources including all the usual suspects (Slashdot, Freshmeat, Wired etc.) and other interesting sites like the Perl news site itself, perl.com and Perlmonth. The whole thing is put together using RSS and you can (of course) download the source code and hack away at it as much as you like.
Perl Mailing Lists
And so to last months article where I discussed Perl Mailing Lists. you can find a great deal of very detailed information on a mailing list as they are extremely focused. Whatever your specific Perl interest, there is probably a maili specific Perl interest, there is probably a mailing list about it (and if there isn’t you can easily start one at eGroups or OneList).
A reader pointed out this web site to me:
This site carries the archives of a number of mailing lists. They aren’t all Perl lists, but a good many of them are.
Conclusion
So there you have it. The end of the final RTFM. I hope you have found the series interesting and useful. As always I’m very interested to hear any comments that you have. Please email me at dave@mag-sol.com.
This isn’t the last you’ll here from me in Perlmonth. I plan to be back with a new column in a few months. Until then, if you’re ever in London on the first Thursday of the month, pop into the london.pm meeting and say hello.
One thought on “Perl Documentation Overview”