Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

How to RTFM

by Masem (Monsignor)
on May 08, 2001 at 06:49 UTC ( [id://78752]=perltutorial: print w/replies, xml ) 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

Distribution Docs

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.

Manual Pages

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:

  • perlfaq - a list of Frequently Asked Questions about perl
  • perldata - details on perl's data types
  • perlop - details on perl's builtin operators
  • perlsyn - details on perl's syntax
  • perlfunc - a list of built-in perl functions
  • perlref - details on perl's implementation of references
  • perlre - details on the regular expression engine in perl

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

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

all of which have either the documentation for many modules, the core/standard perl documentation, or both. They are all useful if you want to view the documentation in an easy-to-read, hypertext format.

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.

Summary

As 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.

updateThanks chromatic and lachoy for pointing out cmd line switches on perldoc, those have been added in directly into the above to keep that section together.

Replies are listed 'Best First'.
Re: How to RTFM
by Chmrr (Vicar) on May 08, 2001 at 07:53 UTC

    I'd add two points as appendices to Masem's highly useful post:

    • If you're using ActivePerl, you already have a goodly number of docs in pretty HTML format on your hard drive. From release notes to install notes, the FAQs to all installed modules, and much, much more! All for the low price of -- oh, nevermind. Anyways, look in the \html directory off of your Perl install directory. For me, that's c:\Perl\html, for example. If you're lazy, you can take a look at the official ActiveState's copy to get an idea of what sort of info is there.
    • There's one more reference site that I didn't see mentioned: PerlFAQ has some useful tidbits, and deserves mention.
    Anyways, hope these help in y'all's quest to Respect The Friendly Monks!

     
    perl -e 'print "I love $^X$\"$]!$/"#$&V"+@( NO CARRIER'

Re: How to RTFM
by lachoy (Parson) on May 08, 2001 at 15:36 UTC

    Quick note: perldoc -q regex will use a regular expression to perform a search of the perlfaq pages you mentioned. For instance:

    [cwinters@genesee cwinters]$ perldoc -q hash Found in /usr/local/lib/perl5/5.6.1/pod/perlfaq3.pod How can I free an array or hash so my program shrinks? ... Found in /usr/local/lib/perl5/5.6.1/pod/perlfaq4.pod How do I test whether two arrays or hashes are equal? ... Data: Hashes (Associative Arrays) How do I process an entire hash? ... What happens if I add or remove keys from a hash while iterating over it? ... How can I always keep my hash sorted? ... What's the difference between "delete" and "undef" with hashes? ... How do I sort a hash (optionally by value instead of key)? (etc.)

    Not only is this useful in and of itself, but since the FAQ entries frequently contain references to other perldoc pages folks might not know about (perlbot, perlref, ...), it's a great starting point, too.

    Chris
    M-x auto-bs-mode

Re: How to RTFM
by chromatic (Archbishop) on May 10, 2001 at 00:14 UTC
    perldoc -f functionname is irreplacable, especially if you're coding. I often keep a separate window open just for that purpose.

    This is much faster than browsing through perlfunc.

Re: How to RTFM
by davorg (Chancellor) on May 08, 2001 at 12:56 UTC

      Article now accessible via this link.

      Update: PerlMonth.com seems to be in la-la land. The server returns a 403 Forbidden error on every request. :-(

      www.perlmonth.com - is this domain still in operation?

        It seems to be dead at the moment. You can still read the articles on the Magnum Solutions web site.

        --
        <http://www.dave.org.uk>

        "The first rule of Perl club is you do not talk about Perl club."
        -- Chip Salzenberg

perldoc.com shortcuts
by cLive ;-) (Prior) on Jun 27, 2001 at 01:00 UTC

      Just a note to point out that perldoc.com has long since dried up and blown away.

      http://perldoc.perl.org is the place to go these days.


      TGI says moo

Re: How to RTFM
by toro (Beadle) on Jun 19, 2011 at 16:43 UTC

    My personal guideline is to RTFM for at least an hour, usually a couple hours, before posting a question.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perltutorial [id://78752]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others lurking in the Monastery: (8)
As of 2024-03-28 09:21 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found