From Novice to Adept: Perldoc


Some people say that Perl (at least versiosn 1 Perl 5) is a cleaned up dialect of the language called Unix. Certainly that's how I develop. Unix is my IDE, and I use Unix tools as much as possible.

You can see the schism between Unix developers and everyone else in the Perl world. Cygwin doesn't get as much attention and testing and bugfixing as it deserves. Dealing with shared libraries and installation on Windows and Mac OS X often requires special skills and knowledge and dedication that isn't always available or obvious or interesting to those of us for whom Unix and the free Unix-alikes just work.

For maximum fun and frustration, install Strawberry Perl on a friend's computer, then tell them they're going to learn how to program. Try to explain that your preferred approach mixes several terminal windows with GNU Screen and copious command-line utilities, then try to get them past the "Hello, world!" stage. (The real point of that exercise is to teach you how to write, save, compile, link, and run programs. Skip any step not necessary in your language.)

Certainly the bundling of Padre helps, but the mindset of the Unix hacker runs deeply through Perl culture. This is not a bad thing; it's the source of much goodness in the language and its ecosystem. Yet you can't be a productive Perl hacker unless you know that it's there.

Consider perldoc. A very naïve count of words in pod/ in bleadperl today suggests that the core Perl 5.13.0 distribution contains 740,000 words of documentation. Take out the deltas between releases and you still have 576,000 words of documentation. That's almost six novels worth of books, unless you're a prolific fantasy author, in which case that's the filler in your bookshelf-destroying series. That's only the core documentation. That doesn't count the documentation of the core libraries.

If you want to be a good Perl developer, you have to know that it exists and how to use it.

perldoc perltoc lists and describes all of the documents in the core documentation. Type the name of any of the files listed as the argument to perldoc to learn more.

perldoc perlfunc describes Perl's built-in functions, like push and chomp. If you don't remember the name of a function, you can skim through this file (especially its listings of functions by category) to find it. Most adept Perl programmers use perldoc -f funcname, however. I can't remember the order of return values from caller, so I type perldoc -f caller and skim the example code.

Get used to referring to the documentation. That's how good programmers work.

If you're not sure what you need to look up, but think you know how to describe it, perldoc -q keyword searches the Perl FAQ for the appropriate question. I use this less than perldoc -f, but I don't ask many of those questions about Perl.

Any module worth using has documentation. Type perldoc Module::Name to read its documentation.

There's plenty more documentation to read, such as perldoc perlsyn, which explains the language's syntax or perldoc perlop which describes operators. Even so, if you only know the -f and -q flags and the existence of perldoc perltoc, you're well on your way to understanding Perl.


Additionally, if your system doesn't have perldoc properly installed (which some don't), or you just prefer reading it in a browser tab, just type 'perldoc ' into your google search box on your favorite browser, and it'll almost always be the first or second link. You don't even need to remember the -f!

Perldoc in colors:

aptitude install most
export PAGER='/usr/bin/most'
perldoc Whatever::fu

Also manpages, get colorized headers and bolds, with this tip.

Nice post :-)

<giggles location="Fielding, Utah" description="where the Strawberry Perl code mines happen to exist..." />

Maximum fun and frustration, I will admit, is still there. But Strawberry IS trying to avoid adding to it as much as possible, and "Strawberry Professional" will try to help by including a graphical POD browser. (Alpha 1 included Tk::Pod for the purpose, if I recall correctly.)

And I do point people to in Strawberry's start menu options - hopefully people with at least minimal levels of clue notice.

Modern Perl: The Book

cover image for Modern Perl: the book

The best Perl Programmers read Modern Perl: The Book.

affiliated with Modern Perl Whitepapers



About this Entry

This page contains a single entry by chromatic published on April 26, 2010 4:11 PM.

State and the Syntax of Encapsulation was the previous entry in this blog.

Test-Driven Learning is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

Powered by the Perl programming language

what is programming?