|go ahead... be a heretic|
How to RTFMby Masem (Monsignor)
|on May 08, 2001 at 06:49 UTC||Need Help??|
How to RTFM
If you're new the 'net (not just Perlmonks, but in general), you will eventually hear the phrase 'RTFM', which stands for "Read the Friendly Manual". (Well, actually, 'friendly' is something else, but you get the idea.) What this means is that the question asked is something that could have easily been learned by reading the documentation that comes with that program or language (for free!), and asking for help about it in public forums is considered a waste of time.
While it should not be taken as a rude comment by the person suggesting it, it's better to avoid getting an 'RTFM' in response to a question if you can, which means that you should do as much research in the manuals before posting. With Perl, that can be a daunting task, as there is a LOT of documentation that goes along with it. This tutorial is an attempt to try to sort out where you can find specific information about programming in perl that you can get for free (e.g., you don't need to buy any books, though this is always a good idea!), both with the install of perl and at various web sites, including Perlmonks.
It should be noted that some areas of perl documentation are quite complicated and overlapping, so it might take a couple of stabs to get to the right place, but after a few tries with the documentation, you'll get where you want to be.
Perl Documentation Included With Install
Regardless of your platform, you'll find that the perl install comes with several README files that discuss platform specific issues, and details on installing perl, as well as the obligatory license files. These typically will not be of interest to you as a new programmer, but you should be aware of their existence.
For UNIX-based systems, the bulk of the useful perl documentation will be installed as manual pages. For example, man perl will get you the 'index' for all other perl man pages. The "perl" man page itself will have little info, as most of it is split up among 20-30 smaller man pages. Some of the more useful ones that a new programmer will find useful include:
There are numerous others, but this is a good start for the beginning programmer. Of course, you can always pretty-print these out, but please note that the text might change with each new perl version, and the best way to make sure you are reading the current documentation is to read it on-line.
Of course, I'm sure that Windows and other OS users don't have similar options, but fortunately, default with every perl install is another nice feature:
Perldoc is similar to 'man' in some ways, but works with a special documentation format called POD, or "plain old documentation". This comes into play later with modules, but all the manual pages are also distributed as POD documents, meaning that you can do perldoc perlfaq to get the same text as man perlfaq. So the same sections highlighted above are ones that you will find useful regardless of what platform you are on.
In addition to this functionality, there are a few command line switches that you will find very useful. One is "-q" which will search the perl documentation for the text that follows the -q switch. (Actually, this is a regular expression, but for the beginner, words or phrases will work as well). This will list the various documents where that word or phrase appears, which you can follow up on with perldoc again. Another useful switch is "-f" which will return the relevent section in perlfunc for a given function name, which can be faster than scanning through perlfunc itself.
Documentation from Modules
Beyond the default install of perl are what are known as modules; these are extensions to the language devised by third parties that can be very useful, such as the classic CGI.pm for web CGI programming. Managing all the documentation for these modules may seem overwhelming, but perl's POD format saves the day again. As long as you know the module's name, excluding the trailing ".pm", you can use perldoc to view the POD documentation that each module contains; for example perldoc CGI will give you the documentation on the CGI module. This is the best way to get a summary of a module's functions, but many module authors also have web sites for additional information which are listed in the POD documentation, so keep your eyes open for that.
Documentation on Web Sites (beyond PM)
Besides the copies on your system, you can find the Perl documentation on the web, nicely formatted and easily navigable.
The primary location is the (quasi?)official http://perldoc.perl.org/, which has both core/standard documentation and the man pages for many modules.
Secondarily, you can try
Documentation at Perlmonks
If, for some reason, you have an aversion to venturing beyond the confines of the Monastery for your perl documents, you can browse our very own stacks; but be warned, the copies here are quite out of date. Another way to access information in the Library is to try locating a node whose title is the name of the document you want, such as perlfaq or perlre.
Frequently Asked Questions
You should always check through the FAQ if you can to see if your question has already been answered. The man/perldoc page, "perlfaq" is the official Perl FAQ, and should be consulted first; you can also look at this document online if you wish. Remember to check any relevant section, since some questions are more appropriate in one place rather than another.
Also, you should look through Perlmonk's Q&A section, which attempts to expend the FAQ by having more questions. The Q&A section is sectioned by task, so it should be easy to locate where your question may have already been answered.
Searching Previous Questions
At perlmonks, you can either use the search at the top of the page, or using Super Search to locate all nodes that match your search terms. In the former case, all nodes that match at least one term will be returned, so if you try to search for "string in list", the engine will return all nodes with "string" in them, and all nodes with "in" in them, and all nodes with "list" in them. Obviously not what you want. Super Search is a bit more picky about what it returns, and you can limit your search to certain areas of the site, making it easier to find your results.
Offsite, never doubt the power of search engines, particularly Google's. It's fast and full-featured, and many perl questions and their answers can be found here. However, to get results effectively, you should be well versed in the language of search engines.
Probably more useful than that is the recent installment of the USENET archives back from 1995 at Google. You can limit you search to the primary perl newsgroups (comp.lang.perl.*) and have better narrowing of your search compared to a web search. Of course, a good understanding of getting effective web searches will improve your chances with this.
SummaryAs you can see, there is really a LOT of RTFM's that you can read, a nearly impossible task. However, it's more important to first understand what documentation is available, and how to use it effectively, such that you can avoid asking questions that have been asked thousands of times in the past, than it is to fully read all the man pages. If you consult these sources first, but are still confused, by all means please ask; in general, those that are knowledgeable will be able to recognize a good question about the manual pages that were consulted prior to asking compared to a question where the posted was too lazy to look up anything. Once you know where to look, you should be able to find anything about perl that you want within a few minutes, and save the time and trouble on PM for the other monks to toss "RTFM" replies to those that are lazy.