perldoc: The Documentation That Ships With Perl

Part I · Module 1 · Chapter 1.14 · perldoc: The Documentation That Ships With Perl

1. The Reference Is Already Installed

Perl ships its own documentation, and the tool that reads it is installed beside the interpreter:

command -v perldoc

/usr/bin/perldoc

Three properties make this worth using in preference to a search engine, and the third is the one engineers care about:

• It matches your interpreter. The pages describe the Perl you located in Chapter 1.2, not whichever version an answer online happened to be written for.
• It is complete. Every built-in function, every special variable, every pragma. Not a selection of the popular ones.
• It needs no network. On a locked-down compute server or a machine behind an air gap, this is the only reference available — and those are common conditions in semiconductor work.

2. Looking Up a Function

-f asks about one built-in function. This is the command you will use most:

perldoc -f print

    print FILEHANDLE LIST
    print FILEHANDLE
    print LIST
    print   Prints a string or a list of strings. Returns true if

Even that excerpt answers two questions this module raised. The forms listed confirm that a filehandle comes before the list with no comma between them — the rule from Chapter 1.7, and the explanation for the No comma allowed after filehandle message in Chapter 1.1. And Returns true if tells you print has a return value at all, which is not obvious and matters when you start checking whether output succeeded.

The pattern generalises: when you are unsure how a function behaves at an edge — what it returns, what it does with no arguments, which argument is optional — perldoc -f is faster and more reliable than experimenting.

3. Searching the FAQ

-q searches the question headings in Perl's FAQ, which is a genuine FAQ rather than a marketing page: it collects the questions people actually ask, with answers written by people who know why the question arises.

perldoc -q quoting

Found in /System/Library/Perl/5.34/pods/perlfaq4.pod
  What's wrong with always quoting "$vars"?
    The problem is that those double-quotes force stringification--coercing

Note that it tells you which document the answer lives in. The FAQ is split across several files by subject, and -q finds the right one for you.

-q is the right tool when your question is about practice rather than definition — "why does this not work the way I expect", "what is the usual way to do X". The function pages in §2 tell you what something does; the FAQ tells you what people get wrong about it.

4. The Guides Worth Knowing by Name

Beyond functions and the FAQ, Perl's documentation is a set of named guides. You do not need to memorise the list, but four will come up repeatedly in this course:

perldoc perlre      # regular expressions — Module 11
perldoc perlvar     # the special variables, including $_ $! $@ $? — Chapter 2.12
perldoc perlop      # operators and their precedence — Module 3
perldoc perlfunc    # every built-in function, the page -f searches

These are long documents meant for paging through and searching rather than reading end to end. perldoc opens them in your system's pager, so the usual keys apply: a slash to search, q to quit.

Two of those names answer questions this module deliberately deferred. perlvar is where $! and $@ — mentioned in Chapter 1.12's translations and due properly in Chapter 2.12 — are defined precisely. perlre is the reference you will keep open throughout Module 11.

5. Using It Well

Three habits that make the difference between having the documentation and using it.

Look up the edge, not the basics. You will not read perldoc -f print to learn that print prints. You will read it to find out what it returns, or whether the filehandle takes a comma. Go to the documentation with a specific question.

Read the signature line first. The forms listed at the top of a function entry tell you what arguments are allowed and in what order. Most "why does this not work" questions about a built-in are answered there, before any prose.

Trust it over your memory and over the internet. It describes your installed version. An answer written for a different version may be right in general and wrong for you — which is the same class of problem Chapter 1.2 raised about having more than one Perl on a machine.

6. Mistakes and How They Look

perldoc print instead of perldoc -f print. Without -f you are asking for a document named print, which does not exist. The error says so; add the flag.

Expecting -q to search answers. It searches question headings. If a word does not appear in any heading you get nothing, even though the text may discuss it. Try a different word, or read the relevant perlfaq document directly.

Assuming perldoc is missing because the page is. Some minimal installations and container images ship the interpreter without the documentation. command -v perldoc tells you which situation you are in — a missing tool is different from a missing page.

Reading a version's documentation that is not yours. If a machine has more than one Perl, as Chapter 1.2 described, it may have more than one set of pages. The perldoc first on your PATH belongs to the Perl first on your PATH, which is usually what you want and worth knowing when it is not.

7. Why This Matters in Engineering Work

Two concrete reasons, both about where the work happens.

Compute servers are often offline or restricted. A design network may have no general internet access at all. The documentation on the machine is then not a convenience but the entire reference, and an engineer who can navigate it works at full speed where one who cannot is stuck.

Version differences are real and consequential. A legacy flow may run an older Perl than your laptop. When a script behaves differently in the two places, the documentation on the machine that misbehaved is the authority — it describes that interpreter. Reaching for it is often the fastest way to settle whether a behaviour is a version difference or a bug.

8. What You Should Be Able to Say Now

1. Perl installs its own complete documentation, read with perldoc, matching your interpreter and needing no network.
2. perldoc -f NAME documents one built-in function; read its signature lines first.
3. perldoc -q WORD searches FAQ question headings and names the document the answer is in.
4. perlre, perlvar, perlop and perlfunc are the guides this course will send you to most.
5. perldoc is authoritative about Perl and says nothing about your tools, your data or your environment.
6. A missing perldoc tool and a missing page are different problems; command -v perldoc distinguishes them.

9. Exercise

Exercise 1 — answer a question from this module. Run perldoc -f print and find what print returns. Then explain in one sentence why that is useful to know, referring to the filehandle rule from Chapter 1.7.

Exercise 2 — use the FAQ. Run perldoc -q quoting and read the first entry it finds. Write down the document name it reported and one sentence of what the entry is warning about.

Exercise 3 — look up a deferred term. Open perldoc perlvar and find the entry for $!. Compare what it says with the one-line description in Chapter 1.12, and note one thing the documentation adds.

Exercise 4 — pick the right tool. For each question, say whether perldoc can answer it and which command you would use: (a) what does chomp return? (b) why does my script find a different Perl under cron? (c) what is the usual way to read a whole file at once? (d) which column of this tool's report holds the slack value?

10. Summary

• The reference is already installed, matches your interpreter, and works with no network — which is what makes it the right default on a restricted machine.
• perldoc -f NAME documents a built-in; the signature lines answer most questions before the prose does.
• perldoc -q WORD searches FAQ headings and tells you which document holds the answer.
• perlre, perlvar, perlop, perlfunc are worth remembering by name.
• Go with a specific question — the edges, the return values, the argument order — not for the basics.
• It is silent about your environment and your data, which is precisely the boundary between Part I and Part II.

11. Where This Leaves You

That completes Module 1. Concretely, you can now:

• Say what Perl is, and tell the language apart from the interpreter that runs it.
• Find the interpreter on a machine, identify which one you are getting, and check its version.
• Write a script in a file, run it, and turn it into a command with a shebang and the execute bit.
• Explain why a fault at the end of a file can stop the beginning from producing output.
• Choose where output goes, keeping results and diagnostics on separate streams.
• Read a Perl error message: classify its stage, locate it, and translate its wording.
• Check a file without running it, and know the two things that check cannot promise.
• Look up anything else in the documentation on the machine.

Module 2 begins the language proper: values, the three sigils, and the one idea that explains more Perl behaviour than any other — whether Perl wants a single value or a list.