Conventions Used in This Book | Perl Cookbook, Second Edition

Programming Conventions

We give lots of examples, most of which are pieces of code that should go into a larger program. Some examples are complete programs, which you can recognize because they begin with a #! line. We start nearly all of our longer programs with:

#!/usr/bin/perl -w use strict;

or else the newer:

#!/usr/bin/perl  use strict; use warnings;

Still other examples are things to be typed on a command line. We've used % to show the shell prompt:

% perl -e 'print "Hello, world.\n"'  Hello, world.

This style represents a standard Unix command line, where single quotes represent the "most quoted" form. Quoting and wildcard conventions on other systems vary. For example, many command-line interpreters under MS-DOS and VMS require double quotes instead of single ones to group arguments with spaces or wildcards in them.

Typesetting Conventions

The following typographic conventions are used in this book:

Bold: is used exclusively for command-line switches. This allows one to distinguish for example, between the -w warnings switch and the -w filetest operator.
Italic: is used for URLs, manpages, pathnames, and programs. New terms are also italicized when they first appear in the text.
Constant Width: is used for function and method names and their arguments; in examples to show text that you enter verbatim; and in regular text to show literal code.
Constant Width Bold Italic: is used in examples to show output produced.

Indicates a warning or caution.

Documentation Conventions

The most up-to-date and complete documentation about Perl is included with Perl itself. If typeset and printed, this massive anthology would use more than a thousand pages of printed paper, greatly contributing to global deforestation. Fortunately, you don't have to print it out, because it's available in a convenient and searchable electronic form.

When we refer to a "manpage" in this book, we're talking about this set of online manuals. The name is purely a convention; you don't need a Unix-style man program to read them. The perldoc command distributed with Perl also works, and you may even have the manpages installed as HTML pages, especially on non-Unix systems. Plus, once you know where they're installed, you can grep them directly.^[1] The HTML version of the manpages is available on the Web at http://www.perl.com/CPAN/doc/manual/html/.

^[1] If your system doesn't have grep, use the tcgrep program supplied at the end of Chapter 6.

When we refer to non-Perl documentation, as in "See kill(2) in your system manual," this refers to the kill manpage from section 2 of the Unix Programmer's Manual (system calls). These won't be available on non-Unix systems, but that's probably okay, because you couldn't use them there anyway. If you really do need the documentation for a system call or library function, many organizations have put their manpages on the Web; a quick search of Google for crypt(3) manual will find many copies.