The search capabilities that Jerrad Pierce's message (which I just replied to CC'ing the Pod-People list) reminded me of this unresolved problem: in the current /Programming Perl/'s introduction, there is discussion of a bit of sort-of vaporware description of perlman, Tom C's ill and ill-fated rewrite of perldoc.
Now that perldoc actually /has/ been rewritten (with "perldoc" just a tiny wrapper around Pod::Perldoc), I'd be awfully happy if someone could try to do an at least partial emulation of the perlman features described in the /Programming Perl/ quote below. It could probably be done with just a bit of @ARGV tweaking before passing off to Pod::Perldoc. Oh, and I see that perlman's actual switches aren't promised below, so there should be no need to emulate those! I'm a bit ambivalent about the ability to run "perltoc" to get "perldoc perltoc"; I think Hugo and I decided that it wasn't something that should necessarily be in the core, but it would be nice if someone could make there be a wee program (as a CPAN dist maybe?) that makes all those files. The only problem I see is the question of how to make the .bats under MSWin. I doubt it's a hard question, but it's just one that I've not been able to look into lately, as I've been frustratingly short on time lately (or else I would just do it all myself). It's probably something automated by MakeMakeMakeMaker or whatever those utilities are that understand the bits of Makefile.PL's that say there's Perl programs to install as binaries; but I don't know. Ideas? Promises? [startquote] Online Documentation Perl's extensive online documentation comes as part of the standard Perl distribution. (See the next section for offline documentation.) Additional documentation shows up whenever you install a module from CPAN. When we refer to a "Perl manpage" in this book, we're talking about this set of online Perl manual pages, sitting on your computer. The term manpage is purely a convention meaning a file containing documentation--you don't need a Unix-style man program to read one. You may even have the Perl manpages installed as HTML pages, especially on non-Unix systems. The online manpages for Perl have been divided into separate sections, so you can easily find what you are looking for without wading through hundreds of pages of text. Since the top-level manpage is simply called perl, the Unix command man perl should take you to it.[Footnote: If you still get a truly humongous page when you do that, you're probably picking up the ancient release 4 manpage. Check your MANPATH for archeological sites. (Say perldoc perl to find out how to configure your MANPATH based on the output of perl -V:man.dir.)] That page in turn directs you to more specific pages. For example, man perlre will display the manpage for Perl's regular expressions. The perldoc command often works on systems when the man command won't. On Macs, you need to use the Shuck program. Your port may also provide the Perl manpages in HTML format or your system's native help format. Check with your local sysadmin--unless you're the local sysadmin. Navigating the Standard Manpages In the Beginning (of Perl, that is, back in 1987), the perl manpage was a terse document, filling about 24 pages when typeset and printed. For example, its section on regular expressions was only two paragraphs long. (That was enough, if you knew egrep.) In some ways, nearly everything has changed since then. Counting the standard documentation, the various utilities, the per-platform porting information, and the scads of standard modules, we're now up over 1,500 typeset pages of documentation spread across many separate manpages. (And that's not even counting any CPAN modules you install, which is likely to be quite a few.) But in other ways, nothing has changed: there's still a perl manpage kicking around. And it's still the right place to start when you don't know where to start. The difference is that once you arrive, you can't just stop there. Perl documentation is no longer a cottage industry; it's a supermall with hundreds of stores. When you walk in the door, you need to find the YOU ARE HERE to figure out which shop or department store sells what you're shopping for. Of course, once you get familiar with the mall, you'll usually know right where to go. Here are a few of the store signs you'll see: Manpage Covers ----------- ------------------------------------ perl What Perl manpages are available perldata Data types perlsyn Syntax perlop Operators and precedence perlre Regular expressions perlvar Predefined variables perlsub Subroutines perlfunc Built-in functions perlmod How to make Perl modules work perlref References perlobj Objects perlipc Interprocess communication perlrun How to run Perl commands, plus switches perldebug Debugging perldiag Diagnostic messages That's just a small excerpt, but it has the important parts. You can tell that if you want to learn about an operator, perlop is apt to have what you're looking for. And if you want to find something out about predefined variables, you'd check in perlvar. If you got a diagnostic message you didn't understand, you'd go to perldiag. And so on. Part of the standard Perl manual is the frequently asked questions (FAQ) list. It's split up into these nine different pages: Manpage Covers ----------- ------------------------------------ perlfaq1 General questions about Perl perlfaq2 Obtaining and learning about Perl perlfaq3 Programming tools perlfaq4 Data manipulation perlfaq5 Files and formats perlfaq6 Regular expressions perlfaq7 General Perl language issues perlfaq8 System interaction perlfaq9 Networking Some manpages contain platform-specific notes: Manpage Covers ----------- ------------------------------------ perlamiga The Amiga port perlcygwin The Cygwin port perldos The MS-DOS port perlhpux The HP-UX port perlmachten The Power MachTen port perlos2 The OS/2 port perlos390 The OS/390 port perlvms The DEC VMS port perlwin32 The MS-Windows port (See also Chapter 25, and the CPAN ports directory described earlier for porting information.) Searching the Manpages Nobody expects you to read through all 1,500 typeset pages just to find a needle in a haystack. There's an old saying that you can't grep [Footnote: Don't forget there's a Glossary if you need it.] dead trees. Besides the customary search capabilities inherent in most document-viewing programs, as of the 5.6.1 release of Perl, each main Perl manpage has its own search and display capability. You can search individual pages by using the name of the manpage as the command and passing a Perl regular expression (see Chapter 5) as the search pattern: % perlop comma % perlfunc split % perlvar ARGV % perldiag 'assigned to typeglob' When you don't quite know where something is in the documentation, you can expand your search. For example, to search all the FAQs, use the perlfaq command (which is also a manpage): % perlfaq round The perltoc command (which is also a manpage) searches all the manpages' collective tables of contents: % perltoc typeglob perl5005delta: Undefined value assigned to typeglob perldata: Typeglobs and Filehandles perldiag: Undefined value assigned to typeglob Or to search the complete online Perl manual, including all headers, descriptions, and examples, for any instances of the string, use the perlhelp command: % perlhelp CORE::GLOBAL See the perldoc manpage for details. Non-Perl Manpages When we refer to non-Perl documentation, as in getitimer (2), this refers to the getitimer manpage from section 2 of the Unix Programmer's Manual.[Footnote: Section 2 is only supposed to contain direct calls into the operating system. (These are often called "system calls", but we'll consistently call them syscalls in this book to avoid confusion with the system function, which has nothing to do with syscalls). However, systems vary somewhat in which calls are implemented as syscalls and which are implemented as C library calls, so you could conceivably find getitimer (2) in section 3 instead.] Manpages for syscalls such as getitimer may not be available on non-Unix systems, but that's probably okay, because you couldn't use the Unix syscall there anyway. If you really do need the documentation for a Unix command, syscall, or library function, many organizations have put their manpages on the web--a quick search of AltaVista for "+crypt(3) +manual" will find many copies. Although the top-level Perl manpages are typically installed in section 1 of the standard man directories, we will omit appending a (1) to those manpage names in this book. You can recognize them anyway because they are all of the form "perlmumble". [endquote] -- Sean M. Burke http://search.cpan.org/~sburke/
