major pod update from Tom Christiansen
authorGurusamy Sarathy <gsar@cpan.org>
Mon, 24 May 1999 07:24:11 +0000 (07:24 +0000)
committerGurusamy Sarathy <gsar@cpan.org>
Mon, 24 May 1999 07:24:11 +0000 (07:24 +0000)
p4raw-id: //depot/perl@3460

35 files changed:
MANIFEST
lib/Pod/Functions.pm
pod/Makefile
pod/buildtoc
pod/perl.pod
pod/perl5004delta.pod
pod/perlcall.pod
pod/perldata.pod
pod/perldebug.pod
pod/perldelta.pod
pod/perldsc.pod
pod/perlfunc.pod
pod/perlipc.pod
pod/perllol.pod
pod/perlmod.pod
pod/perlmodinstall.pod
pod/perlmodlib.pod
pod/perlobj.pod
pod/perlop.pod
pod/perlopentut.pod
pod/perlpod.pod
pod/perlport.pod
pod/perlre.pod
pod/perlref.pod
pod/perlrun.pod
pod/perlsec.pod
pod/perlsub.pod
pod/perlsyn.pod
pod/perlthrtut.pod
pod/perltie.pod
pod/perltootc.pod [new file with mode: 0644]
pod/perltrap.pod
pod/perlvar.pod
pod/perlxs.pod
pod/pod2man.PL

index 10a1bcc..2678567 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1001,6 +1001,7 @@ pod/perltie.pod           Tieing an object class into a simple variable
 pod/perltoc.pod                Table of Contents info
 pod/perltodo.pod       Todo list explained
 pod/perltoot.pod       Tom's object-oriented tutorial
+pod/perltootc.pod      Tom's object-oriented tutorial (more on class data)
 pod/perltrap.pod       Trap info
 pod/perlvar.pod                Variable info
 pod/perlxs.pod         XS api info
index 033c579..5e6551f 100644 (file)
@@ -90,9 +90,9 @@ __DATA__
 abs    Math    absolute value function
 accept Socket  accept an incoming socket connect
 alarm  Process schedule a SIGALRM 
-atan2  Math    arctangent of Y/X 
+atan2  Math    arctangent of Y/X in the range -PI to PI
 bind   Socket  binds an address to a socket
-binmode        I/O     prepare binary files on old systems
+binmode        I/O     prepare binary files for I/O
 bless  Objects create an object 
 caller Flow,Namespace  get context of the current subroutine call
 chdir  File    change your current working directory
@@ -104,7 +104,7 @@ chr String  get character this number represents
 chroot File    make directory new root for path lookups
 close  I/O     close file (or pipe or socket) handle
 closedir       I/O     close directory handle
-connect        Socket  connect to a remove socket
+connect        Socket  connect to a remote socket
 continue       Flow    optional trailing block in a while or foreach 
 cos    Math    cosine function
 crypt  String  one-way passwd-style encryption
@@ -123,12 +123,12 @@ endprotoent       Network be done using protocols file
 endpwent       User    be done using passwd file
 endservent     Network be done using services file
 eof    I/O     test a filehandle for its end
-eval   Flow,Misc       catch exceptions or compile code
+eval   Flow,Misc       catch exceptions or compile and run code
 exec   Process abandon this program to run another
 exists HASH    test whether a hash key is present
 exit   Flow    terminate this program
 exp    Math    raise I<e> to a power
-fcntl  File    file control system all
+fcntl  File    file control system call
 fileno I/O     return file descriptor from filehandle
 flock  I/O     lock an entire file with an advisory lock
 fork   Process create a new process just like this one
@@ -145,7 +145,7 @@ getlogin    User    return who logged in at this tty
 getnetbyaddr   Network get network record given its address
 getnetbyname   Network get networks record given name
 getnetent      Network get next networks record 
-getpeername    Socket  find the other hend of a socket connection
+getpeername    Socket  find the other end of a socket connection
 getpgrp        Process get process group
 getppid        Process get parent process ID
 getpriority    Process get current nice value
@@ -180,6 +180,7 @@ link        File    create a hard link in the filesytem
 listen Socket  register your socket as a server 
 local  Misc,Namespace  create a temporary value for a global variable (dynamic scoping)
 localtime      Time    convert UNIX time into record or string using local time
+lock   Threads get a thread lock on a variable, subroutine, or method
 log    Math    retrieve the natural logarithm for a number
 lstat  File    stat a symbolic link
 m//    Regexp  match a string with a regular expression pattern
@@ -251,7 +252,7 @@ shmget      SysV    get SysV shared memory segment identifier
 shmread        SysV    read SysV shared memory 
 shmwrite       SysV    write SysV shared memory 
 shutdown       Socket  close down just half of a socket connection
-sin    Math    return the sin of a number
+sin    Math    return the sine of a number
 sleep  Process block for some number of seconds
 socket Socket  create a socket
 socketpair     Socket  create a pair of sockets
index 7db379c..f28b9d4 100644 (file)
@@ -38,6 +38,7 @@ POD = \
        perldsc.pod     \
        perllol.pod     \
        perltoot.pod    \
+       perltootc.pod   \
        perlobj.pod     \
        perltie.pod     \
        perlbot.pod     \
@@ -96,6 +97,7 @@ MAN = \
        perldsc.man     \
        perllol.man     \
        perltoot.man    \
+       perltootc.man   \
        perlobj.man     \
        perltie.man     \
        perlbot.man     \
@@ -154,6 +156,7 @@ HTML = \
        perldsc.html    \
        perllol.html    \
        perltoot.html   \
+       perltootc.html  \
        perlobj.html    \
        perltie.html    \
        perlbot.html    \
@@ -212,6 +215,7 @@ TEX = \
        perldsc.tex     \
        perllol.tex     \
        perltoot.tex    \
+       perltootc.tex   \
        perlobj.tex     \
        perltie.tex     \
        perlbot.tex     \
index 62df02b..2574b10 100644 (file)
@@ -10,7 +10,8 @@ sub output ($);
           perlsyn perlop perlre perlrun perlfunc perlvar perlsub
           perlmod perlmodlib perlmodinstall perlform perllocale 
           perlref perlreftut perldsc
-          perllol perltoot perlobj perltie perlbot perlipc perldbmfilter perldebug
+          perllol perltoot perltootc perlobj perltie perlbot perlipc
+          perldbmfilter perldebug
           perldiag perlsec perltrap perlport perlstyle perlpod perlbook
           perlembed perlapio perlxs perlxstut perlguts perlcall
           perlhist
index 8f688c7..3b4d785 100644 (file)
@@ -4,16 +4,13 @@ perl - Practical Extraction and Report Language
 
 =head1 SYNOPSIS
 
-B<perl>        S<[ B<-sTuU> ]>
-       S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
-       S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
-       S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
-       S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
-       S<[ B<-P> ]>
-       S<[ B<-S> ]>
-       S<[ B<-x>[I<dir>] ]>
-       S<[ B<-i>[I<extension>] ]>
-       S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+B<perl>        S<[ B<-sTuU> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+    S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+    S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+    S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
+    S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I<dir>] ]>
+    S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ] 
+    [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
 
 For ease of access, the Perl manual has been split up into a number
 of sections:
@@ -40,11 +37,12 @@ of sections:
     perlform           Perl formats
     perllocale         Perl locale support
 
-    perlref            Perl references
     perlreftut         Perl references short introduction
+    perlref            Perl references, the rest of the story
     perldsc            Perl data structures intro
-    perllol            Perl data structures: lists of lists
-    perltoot           Perl OO tutorial
+    perllol            Perl data structures: arrays of arrays
+    perltoot           Perl OO tutorial, part 1
+    perltootc          Perl OO tutorial, part 2
     perlobj            Perl objects
     perltie            Perl objects hidden behind simple variables
     perlbot            Perl OO tricks and examples
@@ -75,7 +73,7 @@ of sections:
 (If you're intending to read these straight through for the first time,
 the suggested order will tend to reduce the number of forward references.)
 
-By default, all of the above manpages are installed in the 
+By default, the manpages listed above are installed in the 
 F</usr/local/man/> directory.  
 
 Extensive additional documentation for Perl modules is available.  The
@@ -140,107 +138,63 @@ scripts into Perl scripts.
 
 But wait, there's more...
 
-Perl version 5 is nearly a complete rewrite, and provides
-the following additional benefits:
+Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
+rewrite that provides the following additional benefits:
 
-=over 5
+=over
 
-=item * Many usability enhancements
+=item * modularity and reusability using innumerable modules 
 
-It is now possible to write much more readable Perl code (even within
-regular expressions).  Formerly cryptic variable names can be replaced
-by mnemonic identifiers.  Error messages are more informative, and the
-optional warnings will catch many of the mistakes a novice might make.
-This cannot be stressed enough.  Whenever you get mysterious behavior,
-try the B<-w> switch!!!  Whenever you don't get mysterious behavior,
-try using B<-w> anyway.
+Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
 
-=item * Simplified grammar
+=item * embeddable and extensible 
 
-The new yacc grammar is one half the size of the old one.  Many of the
-arbitrary grammar rules have been regularized.  The number of reserved
-words has been cut by 2/3.  Despite this, nearly all old Perl scripts
-will continue to work unchanged.
+Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
+L<perlguts>, and L<xsubpp>.
 
-=item * Lexical scoping
+=item * roll-your-own magic variables (including multiple simultaneous DBM implementations)
 
-Perl variables may now be declared within a lexical scope, like "auto"
-variables in C.  Not only is this more efficient, but it contributes
-to better privacy for "programming in the large".  Anonymous
-subroutines exhibit deep binding of lexical variables (closures).
+Described in L<perltie> and L<AnyDBM_File>.
 
-=item * Arbitrarily nested data structures
+=item * subroutines can now be overridden, autoloaded, and prototyped
 
-Any scalar value, including any array element, may now contain a
-reference to any other variable or subroutine.  You can easily create
-anonymous variables and subroutines.  Perl manages your reference
-counts for you.
+Described in L<perlsub>.
 
-=item * Modularity and reusability
+=item * arbitrarily nested data structures and anonymous functions
 
-The Perl library is now defined in terms of modules which can be easily
-shared among various packages.  A package may choose to import all or a
-portion of a module's published interface.  Pragmas (that is, compiler
-directives) are defined and used by the same mechanism.
+Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
 
-=item * Object-oriented programming
+=item * object-oriented programming
 
-A package can function as a class.  Dynamic multiple inheritance and
-virtual methods are supported in a straightforward manner and with very
-little new syntax.  Filehandles may now be treated as objects.
+Described in L<perlobj>, L<perltoot>, and L<perlbot>.
 
-=item * Embeddable and Extensible
+=item * compilability into C code or Perl bytecode
 
-Perl may now be embedded easily in your C or C++ application, and can
-either call or be called by your routines through a documented
-interface.  The XS preprocessor is provided to make it easy to glue
-your C or C++ routines into Perl.  Dynamic loading of modules is
-supported, and Perl itself can be made into a dynamic library.
+Described in L<B> and L<B::Bytecode>.
 
-=item * POSIX compliant
+=item * support for light-weight processes (threads)
 
-A major new module is the POSIX module, which provides access to all
-available POSIX routines and definitions, via object classes where
-appropriate.
+Described in L<perlthrtut> and L<Thread>.
 
-=item * Package constructors and destructors
+=item * support for internationalization, localization, and Unicode 
 
-The new BEGIN and END blocks provide means to capture control as
-a package is being compiled, and after the program exits.  As a
-degenerate case they work just like awk's BEGIN and END when you
-use the B<-p> or B<-n> switches.
+Described in L<perllocale> and L<utf8>.
 
-=item * Multiple simultaneous DBM implementations
+=item * lexical scoping
 
-A Perl program may now access DBM, NDBM, SDBM, GDBM, and Berkeley DB
-files from the same script simultaneously.  In fact, the old dbmopen
-interface has been generalized to allow any variable to be tied
-to an object class which defines its access methods.
+Described in L<perlsub>.
 
-=item * Subroutine definitions may now be autoloaded
+=item * regular expression enhancements
 
-In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
-semantics for undefined subroutine calls.  It's not for just autoloading.
+Described in L<perlre>, with additional examples in L<perlop>.
 
-=item * Regular expression enhancements
+=item * enhanced debugger and interactive Perl environment, with intregrated editor support
 
-You can now specify nongreedy quantifiers.  You can now do grouping
-without creating a backreference.  You can now write regular expressions
-with embedded whitespace and comments for readability.  A consistent
-extensibility mechanism has been added that is upwardly compatible with
-all old regular expressions.
+Described in L<perldebug>.
 
-=item * Innumerable Unbundled Modules
+=item * POSIX 1003.1 compliant library
 
-The Comprehensive Perl Archive Network described in L<perlmodlib>
-contains hundreds of plug-and-play modules full of reusable code.
-See F<http://www.perl.com/CPAN> for a site near you.
-
-=item * Compilability
-
-While not yet in full production mode, a working perl-to-C compiler
-does exist.  It can generate portable byte code, simple C, or
-optimized C code.
+Described in L<POSIX>.
 
 =back
 
@@ -254,7 +208,7 @@ February 1999 and Perl 5.005_03.
 
 The following platforms are able to build Perl from the standard
 source code distribution available at
-F<http://www.perl.com/CPAN/src/index.html>
+http://www.perl.com/CPAN/src/index.html
 
         AIX             Linux           SCO ODT/OSR
         A/UX            MachTen         Solaris
@@ -278,7 +232,7 @@ F<http://www.perl.com/CPAN/src/index.html>
 The following platforms have been known to build Perl from the source
 but for the Perl release 5.005_03 we haven't been able to verify them,
 either because the hardware/software platforms are rather rare or
-because we don't have an active champion on these platformsor both.
+because we don't have an active champion on these platforms--or both.
                                        
         3b1             FPS             Plan 9
         AmigaOS         GENIX           PowerUX
@@ -301,7 +255,7 @@ supported in the Perl release 5.005_03:
         VM/ESA
 
 The following platforms have their own source code distributions and
-binaries available via F<http://www.perl.com/CPAN/ports/index.html>.
+binaries available via http://www.perl.com/CPAN/ports/index.html.
 
                                Perl release
 
@@ -311,7 +265,7 @@ binaries available via F<http://www.perl.com/CPAN/ports/index.html>.
        Tandem Guardian         5.004
 
 The following platforms have only binaries available via
-F<http://www.perl.com/CPAN/ports/index.html>.
+http://www.perl.com/CPAN/ports/index.html.
 
                                Perl release
 
@@ -325,12 +279,12 @@ See L<perlrun>.
 
 =head1 AUTHOR
 
-Larry Wall <F<larry@wall.org>>, with the help of oodles of other folks.
+Larry Wall <larry@wall.org>, with the help of oodles of other folks.
 
 If your Perl success stories and testimonials may be of help to others 
 who wish to advocate the use of Perl in their applications, 
 or if you wish to simply express your gratitude to Larry and the 
-Perl developers, please write to <F<perl-thanks@perl.org>>.
+Perl developers, please write to perl-thanks@perl.org .
 
 =head1 FILES
 
@@ -339,9 +293,11 @@ Perl developers, please write to <F<perl-thanks@perl.org>>.
 =head1 SEE ALSO
 
  a2p   awk to perl translator
-
  s2p   sed to perl translator
 
+ http://www.perl.com/      the Perl Home Page
+ http://www.perl.com/CPAN   the Comphrehensive Perl Archive
+
 =head1 DIAGNOSTICS
 
 The B<-w> switch produces some lovely diagnostics.
@@ -381,10 +337,10 @@ so they are limited to a maximum of 65535 (higher numbers usually being
 affected by wraparound).
 
 You may mail your bug reports (be sure to include full configuration
-information as output by the myconfig program in the perl source tree,
-or by C<perl -V>) to <F<perlbug@perl.com>>.
-If you've succeeded in compiling perl, the perlbug script in the utils/
-subdirectory can be used to help mail in a bug report.
+information as output by the myconfig program in the perl source
+tree, or by C<perl -V>) to perlbug@perl.com .  If you've succeeded
+in compiling perl, the perlbug script in the utils/ subdirectory
+can be used to help mail in a bug report.
 
 Perl actually stands for Pathologically Eclectic Rubbish Lister, but
 don't tell anyone I said that.
index 323830b..43bfb51 100644 (file)
@@ -268,7 +268,7 @@ referenced subroutine, with the given parameters (if any).
 
 This new syntax follows the pattern of S<C<$hashref-E<gt>{FOO}>> and
 S<C<$aryref-E<gt>[$foo]>>: You may now write S<C<&$subref($foo)>> as
-S<C<$subref-E<gt>($foo)>>.  All of these arrow terms may be chained;
+S<C<$subref-E<gt>($foo)>>.  All these arrow terms may be chained;
 thus, S<C<&{$table-E<gt>{FOO}}($bar)>> may now be written
 S<C<$table-E<gt>{FOO}-E<gt>($bar)>>.
 
@@ -758,7 +758,7 @@ details on how to get started with building this port.
 
 There is also support for building perl under the Cygwin32 environment.
 Cygwin32 is a set of GNU tools that make it possible to compile and run
-many UNIX programs under Windows NT by providing a mostly UNIX-like 
+many Unix programs under Windows NT by providing a mostly Unix-like 
 interface for compilation and execution.  See F<README.cygwin32> in the
 perl distribution for more details on this port and how to obtain the
 Cygwin32 toolkit.
@@ -936,7 +936,7 @@ requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>).
 
 =head2 IO
 
-The IO module provides a simple mechanism to load all of the IO modules at one
+The IO module provides a simple mechanism to load all the IO modules at one
 go.  Currently this includes:
 
      IO::Handle
index 2b83780..35c0f05 100644 (file)
@@ -116,7 +116,7 @@ subroutine are stored on the Perl stack.
 As a general rule you should I<always> check the return value from
 these functions.  Even if you are expecting only a particular number of
 values to be returned from the Perl subroutine, there is nothing to
-stop someone from doing something unexpected - don't say you haven't
+stop someone from doing something unexpected--don't say you haven't
 been warned.
 
 =head1 FLAG VALUES
@@ -505,9 +505,9 @@ returned from I<perl_call_pv>. It will always be 0.
 =head2 Passing Parameters
 
 Now let's make a slightly more complex example. This time we want to
-call a Perl subroutine, C<LeftString>, which will take 2 parameters - a
-string (C<$s>) and an integer (C<$n>).  The subroutine will simply
-print the first C<$n> characters of the string.
+call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
+string ($s) and an integer ($n).  The subroutine will simply
+print the first $n characters of the string.
 
 So the Perl subroutine would look like this
 
@@ -555,7 +555,7 @@ as C<SP>.
 =item 2.
 
 If you are going to put something onto the Perl stack, you need to know
-where to put it. This is the purpose of the macro C<dSP> - it declares
+where to put it. This is the purpose of the macro C<dSP>--it declares
 and initializes a I<local> copy of the Perl stack pointer.
 
 All the other macros which will be used in this example require you to
@@ -563,7 +563,7 @@ have used this macro.
 
 The exception to this rule is if you are calling a Perl subroutine
 directly from an XSUB function. In this case it is not necessary to
-use the C<dSP> macro explicitly - it will be declared for you
+use the C<dSP> macro explicitly--it will be declared for you
 automatically.
 
 =item 3.
@@ -578,12 +578,12 @@ The C<PUSHMARK> macro tells Perl to make a mental note of the current
 stack pointer. Even if you aren't passing any parameters (like the
 example shown in the section I<No Parameters, Nothing returned>) you
 must still call the C<PUSHMARK> macro before you can call any of the
-I<perl_call_*> functions - Perl still needs to know that there are no
+I<perl_call_*> functions--Perl still needs to know that there are no
 parameters.
 
 The C<PUTBACK> macro sets the global copy of the stack pointer to be
 the same as our local copy. If we didn't do this I<perl_call_pv>
-wouldn't know where the two parameters we pushed were - remember that
+wouldn't know where the two parameters we pushed were--remember that
 up to now all the stack pointer manipulation we have done is with our
 local copy, I<not> the global copy.
 
@@ -922,7 +922,7 @@ and here is a C function to call it.
 
 To be able to access the two parameters that were pushed onto the stack
 after they return from I<perl_call_pv> it is necessary to make a note
-of their addresses - thus the two variables C<sva> and C<svb>.
+of their addresses--thus the two variables C<sva> and C<svb>.
 
 The reason this is necessary is that the area of the Perl stack which
 held them will very likely have been overwritten by something else by
@@ -1175,11 +1175,11 @@ the version of Perl you are using)
     Not a CODE reference at ...
     Undefined subroutine &main::47 called ...
 
-The variable C<$ref> may have referred to the subroutine C<fred>
+The variable $ref may have referred to the subroutine C<fred>
 whenever the call to C<SaveSub1> was made but by the time
 C<CallSavedSub1> gets called it now holds the number C<47>. Because we
 saved only a pointer to the original SV in C<SaveSub1>, any changes to
-C<$ref> will be tracked by the pointer C<rememberSub>. This means that
+$ref will be tracked by the pointer C<rememberSub>. This means that
 whenever C<CallSavedSub1> gets called, it will attempt to execute the
 code which is referenced by the SV* C<rememberSub>.  In this case
 though, it now refers to the integer C<47>, so expect Perl to complain
@@ -1351,7 +1351,7 @@ So the methods C<PrintID> and C<Display> can be invoked like this
     call_PrintID('Mine', 'PrintID') ;
 
 The only thing to note is that in both the static and virtual methods,
-the method name is not passed via the stack - it is used as the first
+the method name is not passed via the stack--it is used as the first
 parameter to I<perl_call_method>.
 
 =head2 Using GIMME_V
@@ -1485,9 +1485,9 @@ enclosing scope at some stage.  In the event driven scenario that may
 never happen.  This means that as time goes on, your program will
 create more and more temporaries, none of which will ever be freed. As
 each of these temporaries consumes some memory your program will
-eventually consume all the available memory in your system - kapow!
+eventually consume all the available memory in your system--kapow!
 
-So here is the bottom line - if you are sure that control will revert
+So here is the bottom line--if you are sure that control will revert
 back to the enclosing Perl scope fairly quickly after the end of your
 callback, then it isn't absolutely necessary to dispose explicitly of
 any temporaries you may have created. Mind you, if you are at all
@@ -1579,7 +1579,7 @@ require is a means of storing the mapping between the opened file and
 the Perl subroutine we want to be called for that file.
 
 Say the i/o library has a function C<asynch_read> which associates a C
-function C<ProcessRead> with a file handle C<fh> - this assumes that it
+function C<ProcessRead> with a file handle C<fh>--this assumes that it
 has also provided some routine to open the file and so obtain the file
 handle.
 
index ad27db1..f4c660d 100644 (file)
@@ -8,9 +8,9 @@ perldata - Perl data types
 
 Perl has three built-in data types: scalars, arrays of scalars, and
 associative arrays of scalars, known as "hashes".  Normal arrays
-are ordered lists indexed by number, starting with 0 and with
+are ordered lists of scalars indexed by number, starting with 0 and with
 negative subscripts counting from the end.  Hashes are unordered
-collections of values indexed by their associated string key.
+collections of scalar values indexed by their associated string key.
 
 Values are usually referred to by name, or through a named reference.
 The first character of the name tells you to what sort of data
@@ -165,7 +165,7 @@ references are strongly-typed, uncastable pointers with builtin
 reference-counting and destructor invocation.
 
 A scalar value is interpreted as TRUE in the Boolean sense if it is not
-the empty string or the number 0 (or its string equivalent, "0").  The
+the null string or the number 0 (or its string equivalent, "0").  The
 Boolean context is just a special kind of scalar context where no 
 conversion to a string or a number is ever performed.
 
@@ -220,7 +220,7 @@ had to break this to make sure destructors were called when expected.)
 You can also gain some miniscule measure of efficiency by pre-extending
 an array that is going to get big.  You can also extend an array
 by assigning to an element that is off the end of the array.  You
-can truncate an array down to nothing by assigning the empty list
+can truncate an array down to nothing by assigning the null list
 () to it.  The following are equivalent:
 
     @whatever = ();
@@ -278,8 +278,8 @@ integer formats:
 String literals are usually delimited by either single or double
 quotes.  They work much like quotes in the standard Unix shells:
 double-quoted string literals are subject to backslash and variable
-substitution; single-quoted strings are not (except for "C<\'>" and
-"C<\\>").  The usual C-style backslash rules apply for making
+substitution; single-quoted strings are not (except for C<\'> and
+C<\\>).  The usual C-style backslash rules apply for making
 characters such as newline, tab, etc., as well as some more exotic
 forms.  See L<perlop/"Quote and Quotelike Operators"> for a list.
 
@@ -490,7 +490,7 @@ followed by all the elements returned by the subroutine named SomeSub
 called in list context, followed by the key/value pairs of %glarch.
 To make a list reference that does I<NOT> interpolate, see L<perlref>.
 
-The empty list is represented by ().  Interpolating it in a list
+The null list is represented by ().  Interpolating it in a list
 has no effect.  Thus ((),(),()) is equivalent to ().  Similarly,
 interpolating an array with no elements is the same as if no
 array had been interpolated at that point.
@@ -530,7 +530,7 @@ produced by the expression on the right side of the assignment:
     $x = (($foo,$bar) = f());          # set $x to f()'s return count
 
 This is handy when you want to do a list assignment in a Boolean
-context, because most list functions return a empty list when finished,
+context, because most list functions return a null list when finished,
 which when assigned produces a 0, which is interpreted as FALSE.
 
 The final element may be an array or a hash:
@@ -639,9 +639,10 @@ You couldn't just loop through C<values %hash> to do this because
 that function produces a new list which is a copy of the values,
 so changing them doesn't change the original.
 
-As a special rule, if a slice would produce a list consisting entirely
-of undefined values, the empty list is produced instead.  This makes
-it easy to write loops that terminate when an empty list is returned:
+As a special rule, if a list slice would produce a list consisting
+entirely of undefined values, the null list is produced instead.
+This makes it easy to write loops that terminate when a null list
+is returned:
 
     while ( ($home, $user) = (getpwent)[7,0]) {
        printf "%-8s %s\n", $user, $home;
@@ -649,7 +650,7 @@ it easy to write loops that terminate when an empty list is returned:
 
 As noted earlier in this document, the scalar sense of list assignment
 is the number of elements on the right-hand side of the assignment.
-The empty list contains no elements, so when the password file is
+The null list contains no elements, so when the password file is
 exhausted, the result is 0, not 2.
 
 If you're confused about why you use an '@' there on a hash slice
index ed77fd3..5699732 100644 (file)
@@ -557,7 +557,7 @@ Quit.  ("quit" doesn't work for this.)  This is the only supported way
 to exit the debugger, though typing C<exit> twice may do it too.
 
 Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step
-off> the end the script.  You may also need to set C<$finished> to 0 at
+off> the end the script.  You may also need to set $finished to 0 at
 some moment if you want to step through global destruction.
 
 =item R
@@ -968,7 +968,7 @@ application.
 
 The array C<@{"_E<lt>$filename"}> is the line-by-line contents of
 $filename for all the compiled files.  Same for C<eval>ed strings which
-contain subroutines, or which are currently executed.  The C<$filename>
+contain subroutines, or which are currently executed.  The $filename
 for C<eval>ed strings looks like C<(eval 34)>.
 
 =item *
index fe4f29f..7ffaf74 100644 (file)
@@ -117,7 +117,7 @@ extent of 64-bit support.  Depending on the platform (hints file) more
 or less 64-awareness becomes available.  As of 5.005_54 at least
 somewhat 64-bit aware platforms are HP-UX 11 or better, Solaris 2.6 or
 better, IRIX 6.2 or better.  Naturally 64-bit platforms like Digital
-UNIX and UNICOS also have 64-bit support.
+Unix and UNICOS also have 64-bit support.
 
 =head2 Better syntax checks on parenthesized unary operators
 
@@ -335,8 +335,8 @@ O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.
 =item File::Spec
 
 New methods have been added to the File::Spec module: devnull() returns
-the name of the null device (/dev/null on UNIX) and tmpdir() the name of
-the temp directory (normally /tmp on UNIX). There are now also methods
+the name of the null device (/dev/null on Unix) and tmpdir() the name of
+the temp directory (normally /tmp on Unix). There are now also methods
 to convert between absolute and relative filenames: abs2rel() and
 rel2abs(). For compatibility with operating systems that specify volume
 names in file paths, the splitpath(), splitdir() and catdir() methods
index ef3ae75..5ab97e1 100644 (file)
@@ -8,8 +8,8 @@ The single feature most sorely lacking in the Perl programming language
 prior to its 5.0 release was complex data structures.  Even without direct
 language support, some valiant programmers did manage to emulate them, but
 it was hard work and not for the faint of heart.  You could occasionally
-get away with the C<$m{$LoL,$b}> notation borrowed from I<awk> in which the
-keys are actually more like a single concatenated string C<"$LoL$b">, but
+get away with the C<$m{$AoA,$b}> notation borrowed from B<awk> in which the
+keys are actually more like a single concatenated string C<"$AoA$b">, but
 traversal and sorting were difficult.  More desperate programmers even
 hacked Perl's internal symbol table directly, a strategy that proved hard
 to develop and maintain--to put it mildly.
@@ -21,7 +21,7 @@ with three dimensions!
     for $x (1 .. 10) {
        for $y (1 .. 10) {
            for $z (1 .. 10) {
-               $LoL[$x][$y][$z] =
+               $AoA[$x][$y][$z] =
                    $x ** $y + $z;
            }
        }
@@ -30,7 +30,7 @@ with three dimensions!
 Alas, however simple this may appear, underneath it's a much more
 elaborate construct than meets the eye!
 
-How do you print it out?  Why can't you say just C<print @LoL>?  How do
+How do you print it out?  Why can't you say just C<print @AoA>?  How do
 you sort it?  How can you pass it to a function or get one of these back
 from a function?  Is is an object?  Can you save it to disk to read
 back later?  How do you access whole rows or columns of that matrix?  Do
@@ -93,8 +93,8 @@ level.  It's just that you can I<use> it as though it were a
 two-dimensional one.  This is actually the way almost all C
 multidimensional arrays work as well.
 
-    $list[7][12]                       # array of arrays
-    $list[7]{string}                   # array of hashes
+    $array[7][12]                      # array of arrays
+    $array[7]{string}                  # array of hashes
     $hash{string}[7]                   # hash of arrays
     $hash{string}{'another string'}    # hash of hashes
 
@@ -102,10 +102,10 @@ Now, because the top level contains only references, if you try to print
 out your array in with a simple print() function, you'll get something
 that doesn't look very nice, like this:
 
-    @LoL = ( [2, 3], [4, 5, 7], [0] );
-    print $LoL[1][2];
+    @AoA = ( [2, 3], [4, 5, 7], [0] );
+    print $AoA[1][2];
   7
-    print @LoL;
+    print @AoA;
   ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0)
 
 
@@ -124,25 +124,25 @@ repeatedly.  Here's the case where you just get the count instead
 of a nested array:
 
     for $i (1..10) {
-       @list = somefunc($i);
-       $LoL[$i] = @list;       # WRONG!
+       @array = somefunc($i);
+       $AoA[$i] = @array;      # WRONG!
     }
 
-That's just the simple case of assigning a list to a scalar and getting
+That's just the simple case of assigning an array to a scalar and getting
 its element count.  If that's what you really and truly want, then you
 might do well to consider being a tad more explicit about it, like this:
 
     for $i (1..10) {
-       @list = somefunc($i);
-       $counts[$i] = scalar @list;
+       @array = somefunc($i);
+       $counts[$i] = scalar @array;
     }
 
 Here's the case of taking a reference to the same memory location
 again and again:
 
     for $i (1..10) {
-       @list = somefunc($i);
-       $LoL[$i] = \@list;      # WRONG!
+       @array = somefunc($i);
+       $AoA[$i] = \@array;     # WRONG!
     }
 
 So, what's the big problem with that?  It looks right, doesn't it?
@@ -150,8 +150,8 @@ After all, I just told you that you need an array of references, so by
 golly, you've made me one!
 
 Unfortunately, while this is true, it's still broken.  All the references
-in @LoL refer to the I<very same place>, and they will therefore all hold
-whatever was last in @list!  It's similar to the problem demonstrated in
+in @AoA refer to the I<very same place>, and they will therefore all hold
+whatever was last in @array!  It's similar to the problem demonstrated in
 the following C program:
 
     #include <pwd.h>
@@ -176,40 +176,40 @@ hash constructor C<{}> instead.   Here's the right way to do the preceding
 broken code fragments:
 
     for $i (1..10) {
-       @list = somefunc($i);
-       $LoL[$i] = [ @list ];
+       @array = somefunc($i);
+       $AoA[$i] = [ @array ];
     }
 
 The square brackets make a reference to a new array with a I<copy>
-of what's in @list at the time of the assignment.  This is what
+of what's in @array at the time of the assignment.  This is what
 you want.
 
 Note that this will produce something similar, but it's
 much harder to read:
 
     for $i (1..10) {
-       @list = 0 .. $i;
-       @{$LoL[$i]} = @list;
+       @array = 0 .. $i;
+       @{$AoA[$i]} = @array;
     }
 
 Is it the same?  Well, maybe so--and maybe not.  The subtle difference
 is that when you assign something in square brackets, you know for sure
 it's always a brand new reference with a new I<copy> of the data.
-Something else could be going on in this new case with the C<@{$LoL[$i]}}>
+Something else could be going on in this new case with the C<@{$AoA[$i]}}>
 dereference on the left-hand-side of the assignment.  It all depends on
-whether C<$LoL[$i]> had been undefined to start with, or whether it
-already contained a reference.  If you had already populated @LoL with
+whether C<$AoA[$i]> had been undefined to start with, or whether it
+already contained a reference.  If you had already populated @AoA with
 references, as in
 
-    $LoL[3] = \@another_list;
+    $AoA[3] = \@another_array;
 
 Then the assignment with the indirection on the left-hand-side would
 use the existing reference that was already there:
 
-    @{$LoL[3]} = @list;
+    @{$AoA[3]} = @array;
 
 Of course, this I<would> have the "interesting" effect of clobbering
-@another_list.  (Have you ever noticed how when a programmer says
+@another_array.  (Have you ever noticed how when a programmer says
 something is "interesting", that rather than meaning "intriguing",
 they're disturbingly more apt to mean that it's "annoying",
 "difficult", or both?  :-)
@@ -222,8 +222,8 @@ Surprisingly, the following dangerous-looking construct will
 actually work out fine:
 
     for $i (1..10) {
-        my @list = somefunc($i);
-        $LoL[$i] = \@list;
+        my @array = somefunc($i);
+        $AoA[$i] = \@array;
     }
 
 That's because my() is more of a run-time statement than it is a
@@ -242,18 +242,18 @@ do the right thing behind the scenes.
 
 In summary:
 
-    $LoL[$i] = [ @list ];      # usually best
-    $LoL[$i] = \@list;         # perilous; just how my() was that list?
-    @{ $LoL[$i] } = @list;     # way too tricky for most programmers
+    $AoA[$i] = [ @array ];     # usually best
+    $AoA[$i] = \@array;                # perilous; just how my() was that array?
+    @{ $AoA[$i] } = @array;    # way too tricky for most programmers
 
 
 =head1 CAVEAT ON PRECEDENCE
 
-Speaking of things like C<@{$LoL[$i]}>, the following are actually the
+Speaking of things like C<@{$AoA[$i]}>, the following are actually the
 same thing:
 
-    $listref->[2][2]   # clear
-    $$listref[2][2]    # confusing
+    $aref->[2][2]      # clear
+    $$aref[2][2]       # confusing
 
 That's because Perl's precedence rules on its five prefix dereferencers
 (which look like someone swearing: C<$ @ * % &>) make them bind more
@@ -263,11 +263,11 @@ accustomed to using C<*a[i]> to mean what's pointed to by the I<i'th>
 element of C<a>.  That is, they first take the subscript, and only then
 dereference the thing at that subscript.  That's fine in C, but this isn't C.
 
-The seemingly equivalent construct in Perl, C<$$listref[$i]> first does
-the deref of C<$listref>, making it take $listref as a reference to an
+The seemingly equivalent construct in Perl, C<$$aref[$i]> first does
+the deref of $aref, making it take $aref as a reference to an
 array, and then dereference that, and finally tell you the I<i'th> value
-of the array pointed to by $LoL. If you wanted the C notion, you'd have to
-write C<${$LoL[$i]}> to force the C<$LoL[$i]> to get evaluated first
+of the array pointed to by $AoA. If you wanted the C notion, you'd have to
+write C<${$AoA[$i]}> to force the C<$AoA[$i]> to get evaluated first
 before the leading C<$> dereferencer.
 
 =head1 WHY YOU SHOULD ALWAYS C<use strict>
@@ -283,19 +283,19 @@ This way, you'll be forced to declare all your variables with my() and
 also disallow accidental "symbolic dereferencing".  Therefore if you'd done
 this:
 
-    my $listref = [
+    my $aref = [
        [ "fred", "barney", "pebbles", "bambam", "dino", ],
        [ "homer", "bart", "marge", "maggie", ],
        [ "george", "jane", "elroy", "judy", ],
     ];
 
-    print $listref[2][2];
+    print $aref[2][2];
 
 The compiler would immediately flag that as an error I<at compile time>,
-because you were accidentally accessing C<@listref>, an undeclared
+because you were accidentally accessing C<@aref>, an undeclared
 variable, and it would thereby remind you to write instead:
 
-    print $listref->[2][2]
+    print $aref->[2][2]
 
 =head1 DEBUGGING
 
@@ -303,10 +303,10 @@ Before version 5.002, the standard Perl debugger didn't do a very nice job of
 printing out complex data structures.  With 5.002 or above, the
 debugger includes several new features, including command line editing as
 well as the C<x> command to dump out complex data structures.  For
-example, given the assignment to $LoL above, here's the debugger output:
+example, given the assignment to $AoA above, here's the debugger output:
 
-    DB<1> x $LoL
-    $LoL = ARRAY(0x13b5a0)
+    DB<1> x $AoA
+    $AoA = ARRAY(0x13b5a0)
        0  ARRAY(0x1f0a24)
          0  'fred'
          1  'barney'
@@ -330,79 +330,79 @@ Presented with little comment (these will get their own manpages someday)
 here are short code examples illustrating access of various
 types of data structures.
 
-=head1 LISTS OF LISTS
+=head1 ARRAYS OF ARRAYS
 
-=head2 Declaration of a LIST OF LISTS
+=head2 Declaration of a ARRAY OF ARRAYS
 
- @LoL = (
+ @AoA = (
         [ "fred", "barney" ],
         [ "george", "jane", "elroy" ],
         [ "homer", "marge", "bart" ],
       );
 
-=head2 Generation of a LIST OF LISTS
+=head2 Generation of a ARRAY OF ARRAYS
 
  # reading from file
  while ( <> ) {
-     push @LoL, [ split ];
+     push @AoA, [ split ];
  }
 
  # calling a function
  for $i ( 1 .. 10 ) {
-     $LoL[$i] = [ somefunc($i) ];
+     $AoA[$i] = [ somefunc($i) ];
  }
 
  # using temp vars
  for $i ( 1 .. 10 ) {
      @tmp = somefunc($i);
-     $LoL[$i] = [ @tmp ];
+     $AoA[$i] = [ @tmp ];
  }
 
  # add to an existing row
- push @{ $LoL[0] }, "wilma", "betty";
+ push @{ $AoA[0] }, "wilma", "betty";
 
-=head2 Access and Printing of a LIST OF LISTS
+=head2 Access and Printing of a ARRAY OF ARRAYS
 
  # one element
- $LoL[0][0] = "Fred";
+ $AoA[0][0] = "Fred";
 
  # another element
- $LoL[1][1] =~ s/(\w)/\u$1/;
+ $AoA[1][1] =~ s/(\w)/\u$1/;
 
  # print the whole thing with refs
- for $aref ( @LoL ) {
+ for $aref ( @AoA ) {
      print "\t [ @$aref ],\n";
  }
 
  # print the whole thing with indices
- for $i ( 0 .. $#LoL ) {
-     print "\t [ @{$LoL[$i]} ],\n";
+ for $i ( 0 .. $#AoA ) {
+     print "\t [ @{$AoA[$i]} ],\n";
  }
 
  # print the whole thing one at a time
- for $i ( 0 .. $#LoL ) {
-     for $j ( 0 .. $#{ $LoL[$i] } ) {
-         print "elt $i $j is $LoL[$i][$j]\n";
+ for $i ( 0 .. $#AoA ) {
+     for $j ( 0 .. $#{ $AoA[$i] } ) {
+         print "elt $i $j is $AoA[$i][$j]\n";
      }
  }
 
-=head1 HASHES OF LISTS
+=head1 HASHES OF ARRAYS
 
-=head2 Declaration of a HASH OF LISTS
+=head2 Declaration of a HASH OF ARRAYS
 
- %HoL = (
+ %HoA = (
         flintstones        => [ "fred", "barney" ],
         jetsons            => [ "george", "jane", "elroy" ],
         simpsons           => [ "homer", "marge", "bart" ],
       );
 
-=head2 Generation of a HASH OF LISTS
+=head2 Generation of a HASH OF ARRAYS
 
  # reading from file
  # flintstones: fred barney wilma dino
  while ( <> ) {
      next unless s/^(.*?):\s*//;
-     $HoL{$1} = [ split ];
+     $HoA{$1} = [ split ];
  }
 
  # reading from file; more temps
@@ -410,65 +410,65 @@ types of data structures.
  while ( $line = <> ) {
      ($who, $rest) = split /:\s*/, $line, 2;
      @fields = split ' ', $rest;
-     $HoL{$who} = [ @fields ];
+     $HoA{$who} = [ @fields ];
  }
 
  # calling a function that returns a list
  for $group ( "simpsons", "jetsons", "flintstones" ) {
-     $HoL{$group} = [ get_family($group) ];
+     $HoA{$group} = [ get_family($group) ];
  }
 
  # likewise, but using temps
  for $group ( "simpsons", "jetsons", "flintstones" ) {
      @members = get_family($group);
-     $HoL{$group} = [ @members ];
+     $HoA{$group} = [ @members ];
  }
 
  # append new members to an existing family
- push @{ $HoL{"flintstones"} }, "wilma", "betty";
+ push @{ $HoA{"flintstones"} }, "wilma", "betty";
 
-=head2 Access and Printing of a HASH OF LISTS
+=head2 Access and Printing of a HASH OF ARRAYS
 
  # one element
- $HoL{flintstones}[0] = "Fred";
+ $HoA{flintstones}[0] = "Fred";
 
  # another element
- $HoL{simpsons}[1] =~ s/(\w)/\u$1/;
+ $HoA{simpsons}[1] =~ s/(\w)/\u$1/;
 
  # print the whole thing
- foreach $family ( keys %HoL ) {
-     print "$family: @{ $HoL{$family} }\n"
+ foreach $family ( keys %HoA ) {
+     print "$family: @{ $HoA{$family} }\n"
  }
 
  # print the whole thing with indices
- foreach $family ( keys %HoL ) {
+ foreach $family ( keys %HoA ) {
      print "family: ";
-     foreach $i ( 0 .. $#{ $HoL{$family} } ) {
-         print " $i = $HoL{$family}[$i]";
+     foreach $i ( 0 .. $#{ $HoA{$family} } ) {
+         print " $i = $HoA{$family}[$i]";
      }
      print "\n";
  }
 
  # print the whole thing sorted by number of members
- foreach $family ( sort { @{$HoL{$b}} <=> @{$HoL{$a}} } keys %HoL ) {
-     print "$family: @{ $HoL{$family} }\n"
+ foreach $family ( sort { @{$HoA{$b}} <=> @{$HoA{$a}} } keys %HoA ) {
+     print "$family: @{ $HoA{$family} }\n"
  }
 
  # print the whole thing sorted by number of members and name
  foreach $family ( sort {
-                           @{$HoL{$b}} <=> @{$HoL{$a}}
+                           @{$HoA{$b}} <=> @{$HoA{$a}}
                                        ||
                                    $a cmp $b
-           } keys %HoL )
+           } keys %HoA )
  {
-     print "$family: ", join(", ", sort @{ $HoL{$family} }), "\n";
+     print "$family: ", join(", ", sort @{ $HoA{$family} }), "\n";
  }
 
-=head1 LISTS OF HASHES
+=head1 ARRAYS OF HASHES
 
-=head2 Declaration of a LIST OF HASHES
+=head2 Declaration of a ARRAY OF HASHES
 
- @LoH = (
+ @AoH = (
         {
             Lead     => "fred",
             Friend   => "barney",
@@ -485,7 +485,7 @@ types of data structures.
         }
   );
 
-=head2 Generation of a LIST OF HASHES
+=head2 Generation of a ARRAY OF HASHES
 
  # reading from file
  # format: LEAD=fred FRIEND=barney
@@ -495,7 +495,7 @@ types of data structures.
          ($key, $value) = split /=/, $field;
          $rec->{$key} = $value;
      }
-     push @LoH, $rec;
+     push @AoH, $rec;
  }
 
 
@@ -503,34 +503,34 @@ types of data structures.
  # format: LEAD=fred FRIEND=barney
  # no temp
  while ( <> ) {
-     push @LoH, { split /[\s+=]/ };
+     push @AoH, { split /[\s+=]/ };
  }
 
- # calling a function  that returns a key,value list, like
+ # calling a function  that returns a key/value pair list, like
  # "lead","fred","daughter","pebbles"
  while ( %fields = getnextpairset() ) {
-     push @LoH, { %fields };
+     push @AoH, { %fields };
  }
 
  # likewise, but using no temp vars
  while (<>) {
-     push @LoH, { parsepairs($_) };
+     push @AoH, { parsepairs($_) };
  }
 
  # add key/value to an element
- $LoH[0]{pet} = "dino";
- $LoH[2]{pet} = "santa's little helper";
+ $AoH[0]{pet} = "dino";
+ $AoH[2]{pet} = "santa's little helper";
 
-=head2 Access and Printing of a LIST OF HASHES
+=head2 Access and Printing of a ARRAY OF HASHES
 
  # one element
- $LoH[0]{lead} = "fred";
+ $AoH[0]{lead} = "fred";
 
  # another element
- $LoH[1]{lead} =~ s/(\w)/\u$1/;
+ $AoH[1]{lead} =~ s/(\w)/\u$1/;
 
  # print the whole thing with refs
- for $href ( @LoH ) {
+ for $href ( @AoH ) {
      print "{ ";
      for $role ( keys %$href ) {
          print "$role=$href->{$role} ";
@@ -539,18 +539,18 @@ types of data structures.
  }
 
  # print the whole thing with indices
- for $i ( 0 .. $#LoH ) {
+ for $i ( 0 .. $#AoH ) {
      print "$i is { ";
-     for $role ( keys %{ $LoH[$i] } ) {
-         print "$role=$LoH[$i]{$role} ";
+     for $role ( keys %{ $AoH[$i] } ) {
+         print "$role=$AoH[$i]{$role} ";
      }
      print "}\n";
  }
 
  # print the whole thing one at a time
- for $i ( 0 .. $#LoH ) {
-     for $role ( keys %{ $LoH[$i] } ) {
-         print "elt $i $role is $LoH[$i]{$role}\n";
+ for $i ( 0 .. $#AoH ) {
+     for $role ( keys %{ $AoH[$i] } ) {
+         print "elt $i $role is $AoH[$i]{$role}\n";
      }
  }
 
@@ -767,9 +767,9 @@ many different sorts:
      ###########################################################
      # now, you might want to make interesting extra fields that
      # include pointers back into the same data structure so if
-     # change one piece, it changes everywhere, like for examples
-     # if you wanted a {kids} field that was an array reference
-     # to a list of the kids' records without having duplicate
+     # change one piece, it changes everywhere, like for example
+     # if you wanted a {kids} field that was a reference
+     # to an array of the kids' records without having duplicate
      # records and thus update problems.
      ###########################################################
      foreach $family (keys %TV) {
@@ -784,7 +784,7 @@ many different sorts:
          $rec->{kids} = [ @kids ];
      }
 
-     # you copied the list, but the list itself contains pointers
+     # you copied the array, but the array itself contains pointers
      # to uncopied objects. this means that if you make bart get
      # older via
 
index d409319..650493a 100644 (file)
@@ -30,7 +30,7 @@ Elements of the LIST should be separated by commas.
 Any function in the list below may be used either with or without
 parentheses around its arguments.  (The syntax descriptions omit the
 parentheses.)  If you use the parentheses, the simple (but occasionally
-surprising) rule is this: It I<LOOKS> like a function, therefore it I<IS> a
+surprising) rule is this: It I<looks> like a function, therefore it I<is> a
 function, and precedence doesn't matter.  Otherwise it's a list
 operator or unary operator, and precedence does matter.  And whitespace
 between the function and left parenthesis doesn't count--so you need to
@@ -80,8 +80,8 @@ In general, functions in Perl that serve as wrappers for system calls
 of the same name (like chown(2), fork(2), closedir(2), etc.) all return
 true when they succeed and C<undef> otherwise, as is usually mentioned
 in the descriptions below.  This is different from the C interfaces,
-which return C<-1> on failure.  Exceptions to this rule are C<wait()>,
-C<waitpid()>, and C<syscall()>.  System calls also set the special C<$!>
+which return C<-1> on failure.  Exceptions to this rule are C<wait>,
+C<waitpid>, and C<syscall>.  System calls also set the special C<$!>
 variable on failure.  Other functions do not, except accidentally.
 
 =head2 Perl Functions by Category
@@ -255,7 +255,7 @@ A file test, where X is one of the letters listed below.  This unary
 operator takes one argument, either a filename or a filehandle, and
 tests the associated file to see if something is true about it.  If the
 argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
-Unless otherwise documented, it returns C<1> for TRUE and C<''> for FALSE, or
+Unless otherwise documented, it returns C<1> for true and C<''> for false, or
 the undefined value if the file doesn't exist.  Despite the funny
 names, precedence is the same as any other named unary operator, and
 the argument may be parenthesized like any other unary operator.  The
@@ -339,12 +339,12 @@ characters with the high bit set.  If too many strange characters (E<gt>30%)
 are found, it's a C<-B> file, otherwise it's a C<-T> file.  Also, any file
 containing null in the first block is considered a binary file.  If C<-T>
 or C<-B> is used on a filehandle, the current stdio buffer is examined
-rather than the first block.  Both C<-T> and C<-B> return TRUE on a null
+rather than the first block.  Both C<-T> and C<-B> return true on a null
 file, or a file at EOF when testing a filehandle.  Because you have to
 read a file to do the C<-T> test, on most occasions you want to use a C<-f>
 against the file first, as in C<next unless -f $file && -T $file>.
 
-If any of the file tests (or either the C<stat()> or C<lstat()> operators) are given
+If any of the file tests (or either the C<stat> or C<lstat> operators) are given
 the special filehandle consisting of a solitary underline, then the stat
 structure of the previous file test (or stat operator) is used, saving
 a system call.  (This doesn't work with C<-t>, and you need to remember
@@ -373,7 +373,7 @@ If VALUE is omitted, uses C<$_>.
 =item accept NEWSOCKET,GENERICSOCKET
 
 Accepts an incoming socket connect, just as the accept(2) system call
-does.  Returns the packed address if it succeeded, FALSE otherwise.
+does.  Returns the packed address if it succeeded, false otherwise.
 See the example in L<perlipc/"Sockets: Client/Server Communication">.
 
 =item alarm SECONDS
@@ -391,18 +391,18 @@ starting a new one.  The returned value is the amount of time remaining
 on the previous timer.
 
 For delays of finer granularity than one second, you may use Perl's
-four-arugment version of select() leaving the first three arguments
-undefined, or you might be able to use the C<syscall()> interface to
+four-argument version of select() leaving the first three arguments
+undefined, or you might be able to use the C<syscall> interface to
 access setitimer(2) if your system supports it.  The Time::HiRes module
 from CPAN may also prove useful.
 
-It is usually a mistake to intermix C<alarm()>
-and C<sleep()> calls.
+It is usually a mistake to intermix C<alarm>
+and C<sleep> calls.
 
-If you want to use C<alarm()> to time out a system call you need to use an
-C<eval()>/C<die()> pair.  You can't rely on the alarm causing the system call to
+If you want to use C<alarm> to time out a system call you need to use an
+C<eval>/C<die> pair.  You can't rely on the alarm causing the system call to
 fail with C<$!> set to C<EINTR> because Perl sets up signal handlers to
-restart system calls on some systems.  Using C<eval()>/C<die()> always works,
+restart system calls on some systems.  Using C<eval>/C<die> always works,
 modulo the caveats given in L<perlipc/"Signals">.
 
     eval {
@@ -431,29 +431,51 @@ function, or use the familiar relation:
 =item bind SOCKET,NAME
 
 Binds a network address to a socket, just as the bind system call
-does.  Returns TRUE if it succeeded, FALSE otherwise.  NAME should be a
+does.  Returns true if it succeeded, false otherwise.  NAME should be a
 packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item binmode FILEHANDLE
 
-Arranges for the file to be read or written in "binary" mode in operating
-systems that distinguish between binary and text files.  Files that
-are not in binary mode have CR LF sequences translated to LF on input
-and LF translated to CR LF on output.  Binmode has no effect under
-many sytems, but in MS-DOS and similarly archaic systems, it may be
-imperative--otherwise your MS-DOS-damaged C library may mangle your file.
-The key distinction between systems that need C<binmode()> and those
-that don't is their text file formats.  Systems like Unix, MacOS, and
-Plan9 that delimit lines with a single character, and that encode that
-character in C as C<"\n">, do not need C<binmode()>.  The rest may need it.
-If FILEHANDLE is an expression, the value is taken as the name of the
-filehandle.
-
-If the system does care about it, using it when you shouldn't is just as
-perilous as failing to use it when you should.  Fortunately for most of
-us, you can't go wrong using binmode() on systems that don't care about
-it, though.
+Arranges for FILEHANDLE to be read or written in "binary" mode on
+systems whose run-time libraries force the programmer to guess
+between binary and text files.  If FILEHANDLE is an expression, the
+value is taken as the name of the filehandle.  binmode() should be
+called after the C<open> but before any I/O is done on the filehandle.
+The only way to reset binary mode on a filehandle is to reopen the
+file.
+
+The operating system, device drivers, C libraries, and Perl run-time
+system all conspire to let the programmer conveniently treat a
+simple, one-byte C<\n> as the line terminator, irrespective of its
+external representation.  On Unix and its brethren, the native file
+representation exactly matches the internal representation, making
+everyone's lives unbelievably simpler.  Consequently, L<binmode>
+has no effect under Unix, Plan9, or Mac OS, all of which use C<\n>
+to end each line.  (Unix and Plan9 think C<\n> means C<\cJ> and
+C<\r> means C<\cM>, whereas the Mac goes the other way--it uses
+C<\cM> for c<\n> and C<\cJ> to mean C<\r>.  But that's ok, because
+it's only one byte, and the internal and external representations
+match.)
+
+In legacy systems like MS-DOS and its embellishments, your program
+sees a C<\n> as a simple C<\cJ> (just as in Unix), but oddly enough,
+that's not what's physically stored on disk.  What's worse, these
+systems refuse to help you with this; it's up to you to remember
+what to do.  And you mustn't go applying binmode() with wild abandon,
+either, because if your system does care about binmode(), then using
+it when you shouldn't is just as perilous as failing to use it when
+you should.
+
+That means that on any version of Microsoft WinXX that you might
+care to name (or not), binmode() causes C<\cM\cJ> sequences on disk
+to be converted to C<\n> when read into your program, and causes
+any C<\n> in your program to be converted back to C<\cM\cJ> on
+output to disk.  This sad discrepancy leads to no end of
+problems in not just the readline operator, but also when using
+seek(), tell(), and read() calls.  See L<perlport> for other painful
+details.  See the C<$/> and C<$\> variables in L<perlvar> for how
+to manually set your input and output line-termination sequences.
 
 =item bless REF,CLASSNAME
 
@@ -461,7 +483,7 @@ it, though.
 
 This function tells the thingy referenced by REF that it is now an object
 in the CLASSNAME package.  If CLASSNAME is omitted, the current package
-is used.  Because a C<bless()> is often the last thing in a constructor.
+is used.  Because a C<bless> is often the last thing in a constructor,
 it returns the reference for convenience.  Always use the two-argument
 version if the function doing the blessing might be inherited by a
 derived class.  See L<perltoot> and L<perlobj> for more about the blessing
@@ -481,7 +503,7 @@ See L<perlmod/"Perl Modules">.
 
 Returns the context of the current subroutine call.  In scalar context,
 returns the caller's package name if there is a caller, that is, if
-we're in a subroutine or C<eval()> or C<require()>, and the undefined value
+we're in a subroutine or C<eval> or C<require>, and the undefined value
 otherwise.  In list context, returns
 
     ($package, $filename, $line) = caller;
@@ -493,12 +515,12 @@ to go back before the current one.
     ($package, $filename, $line, $subroutine,
      $hasargs, $wantarray, $evaltext, $is_require) = caller($i);
 
-Here C<$subroutine> may be C<"(eval)"> if the frame is not a subroutine
-call, but an C<eval()>.  In such a case additional elements C<$evaltext> and
+Here $subroutine may be C<"(eval)"> if the frame is not a subroutine
+call, but an C<eval>.  In such a case additional elements $evaltext and
 C<$is_require> are set: C<$is_require> is true if the frame is created by a
-C<require> or C<use> statement, C<$evaltext> contains the text of the
+C<require> or C<use> statement, $evaltext contains the text of the
 C<eval EXPR> statement.  In particular, for a C<eval BLOCK> statement,
-C<$filename> is C<"(eval)">, but C<$evaltext> is undefined.  (Note also that
+$filename is C<"(eval)">, but $evaltext is undefined.  (Note also that
 each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
 frame.
 
@@ -507,16 +529,16 @@ detailed information: it sets the list variable C<@DB::args> to be the
 arguments with which the subroutine was invoked.
 
 Be aware that the optimizer might have optimized call frames away before
-C<caller()> had a chance to get the information. That means that C<caller(N)>
+C<caller> had a chance to get the information.  That means that C<caller(N)>
 might not return information about the call frame you expect it do, for
-C<N E<gt> 1>. In particular, C<@DB::args> might have information from the 
-previous time C<caller()> was called.
+C<N E<gt> 1>.  In particular, C<@DB::args> might have information from the 
+previous time C<caller> was called.
 
 =item chdir EXPR
 
 Changes the working directory to EXPR, if possible.  If EXPR is omitted,
-changes to the user's home directory.  Returns TRUE upon success,
-FALSE otherwise.  See the example under C<die()>.
+changes to the user's home directory.  Returns true upon success,
+false otherwise.  See the example under C<die>.
 
 =item chmod LIST
 
@@ -548,7 +570,8 @@ that the final record may be missing its newline.  When in paragraph
 mode (C<$/ = "">), it removes all trailing newlines from the string.
 When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
 a reference to an integer or the like, see L<perlvar>) chomp() won't
-remove anything.  If VARIABLE is omitted, it chomps C<$_>.  Example:
+remove anything.  
+If VARIABLE is omitted, it chomps C<$_>.  Example:
 
     while (<>) {
        chomp;  # avoid \n on last field
@@ -588,16 +611,18 @@ You can actually chop anything that's an lvalue, including an assignment:
     chop($answer = <STDIN>);
 
 If you chop a list, each element is chopped.  Only the value of the
-last C<chop()> is returned.
+last C<chop> is returned.
 
-Note that C<chop()> returns the last character.  To return all but the last
+Note that C<chop> returns the last character.  To return all but the last
 character, use C<substr($string, 0, -1)>.
 
 =item chown LIST
 
 Changes the owner (and group) of a list of files.  The first two
-elements of the list must be the I<NUMERICAL> uid and gid, in that order.
-Returns the number of files successfully changed.
+elements of the list must be the I<numeric> uid and gid, in that
+order.  A value of -1 in either position is interpreted by most
+systems to leave that value unchanged.  Returns the number of files
+successfully changed.
 
     $cnt = chown $uid, $gid, 'foo', 'bar';
     chown $uid, $gid, @filenames;
@@ -605,9 +630,9 @@ Returns the number of files successfully changed.
 Here's an example that looks up nonnumeric uids in the passwd file:
 
     print "User: ";
-    chop($user = <STDIN>);
+    chomp($user = <STDIN>);
     print "Files: ";
-    chop($pattern = <STDIN>);
+    chomp($pattern = <STDIN>);
 
     ($login,$pass,$uid,$gid) = getpwnam($user)
        or die "$user not in passwd file";
@@ -619,6 +644,10 @@ On most systems, you are not allowed to change the ownership of the
 file unless you're the superuser, although you should be able to change
 the group to any of your secondary groups.  On insecure systems, these
 restrictions may be relaxed, but this is not a portable assumption.
+On POSIX systems, you can detect this condition this way:
+
+    use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
+    $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
 
 =item chr NUMBER
 
@@ -641,24 +670,24 @@ named directory the new root directory for all further pathnames that
 begin with a C<"/"> by your process and all its children.  (It doesn't
 change your current working directory, which is unaffected.)  For security
 reasons, this call is restricted to the superuser.  If FILENAME is
-omitted, does a C<chroot()> to C<$_>.
+omitted, does a C<chroot> to C<$_>.
 
 =item close FILEHANDLE
 
 =item close
 
-Closes the file or pipe associated with the file handle, returning TRUE
+Closes the file or pipe associated with the file handle, returning true
 only if stdio successfully flushes buffers and closes the system file
-descriptor. Closes the currently selected filehandle if the argument
+descriptor.  Closes the currently selected filehandle if the argument
 is omitted.
 
 You don't have to close FILEHANDLE if you are immediately going to do
-another C<open()> on it, because C<open()> will close it for you.  (See
-C<open()>.)  However, an explicit C<close()> on an input file resets the line
-counter (C<$.>), while the implicit close done by C<open()> does not.
+another C<open> on it, because C<open> will close it for you.  (See
+C<open>.)  However, an explicit C<close> on an input file resets the line
+counter (C<$.>), while the implicit close done by C<open> does not.
 
-If the file handle came from a piped open C<close()> will additionally
-return FALSE if one of the other system calls involved fails or if the
+If the file handle came from a piped open C<close> will additionally
+return false if one of the other system calls involved fails or if the
 program exits with non-zero status.  (If the only problem was that the
 program exited non-zero C<$!> will be set to C<0>.)  Closing a pipe 
 also waits for the process executing on the pipe to complete, in case you
@@ -681,7 +710,7 @@ filehandle, usually the real filehandle name.
 
 =item closedir DIRHANDLE
 
-Closes a directory opened by C<opendir()> and returns the success of that
+Closes a directory opened by C<opendir> and returns the success of that
 system call.
 
 DIRHANDLE may be an expression whose value can be used as an indirect
@@ -690,7 +719,7 @@ dirhandle, usually the real dirhandle name.
 =item connect SOCKET,NAME
 
 Attempts to connect to a remote socket, just as the connect system call
-does.  Returns TRUE if it succeeded, FALSE otherwise.  NAME should be a
+does.  Returns true if it succeeded, false otherwise.  NAME should be a
 packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
@@ -705,8 +734,8 @@ continued via the C<next> statement (which is similar to the C C<continue>
 statement).
 
 C<last>, C<next>, or C<redo> may appear within a C<continue>
-block. C<last> and C<redo> will behave as if they had been executed within
-the main block. So will C<next>, but since it will execute a C<continue>
+block.  C<last> and C<redo> will behave as if they had been executed within
+the main block.  So will C<next>, but since it will execute a C<continue>
 block, it may be more entertaining.
 
     while (EXPR) {
@@ -720,7 +749,7 @@ block, it may be more entertaining.
     ### last always comes here
 
 Omitting the C<continue> section is semantically equivalent to using an
-empty one, logically enough. In that case, C<next> goes directly back
+empty one, logically enough.  In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
 =item cos EXPR
@@ -741,14 +770,14 @@ extirpated as a potential munition).  This can prove useful for checking
 the password file for lousy passwords, amongst other things.  Only the
 guys wearing white hats should do this.
 
-Note that C<crypt()> is intended to be a one-way function, much like breaking
+Note that C<crypt> is intended to be a one-way function, much like breaking
 eggs to make an omelette.  There is no (known) corresponding decrypt
 function.  As a result, this function isn't all that useful for
 cryptography.  (For that, see your nearby CPAN mirror.)
 
 When verifying an existing encrypted string you should use the encrypted
 text as the salt (like C<crypt($plain, $crypted) eq $crypted>).  This
-allows your code to work with the standard C<crypt()> and with more
+allows your code to work with the standard C<crypt> and with more
 exotic implementations.  When choosing a new salt create a random two
 character string whose characters come from the set C<[./0-9A-Za-z]>
 (like C<join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
@@ -773,34 +802,40 @@ their own password:
 Of course, typing in your own password to whoever asks you
 for it is unwise.
 
+The L<crypt> function is unsuitable for encrypting large quantities
+of data, not least of all because you can't get the information
+back.  Look at the F<by-module/Crypt> and F<by-module/PGP> directories
+on your favorite CPAN mirror for a slew of potentially useful
+modules.
+
 =item dbmclose HASH
 
-[This function has been largely superseded by the C<untie()> function.]
+[This function has been largely superseded by the C<untie> function.]
 
 Breaks the binding between a DBM file and a hash.
 
-=item dbmopen HASH,DBNAME,MODE
+=item dbmopen HASH,DBNAME,MASK
 
-[This function has been largely superseded by the C<tie()> function.]
+[This function has been largely superseded by the C<tie> function.]
 
 This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
-hash.  HASH is the name of the hash.  (Unlike normal C<open()>, the first
-argument is I<NOT> a filehandle, even though it looks like one).  DBNAME
+hash.  HASH is the name of the hash.  (Unlike normal C<open>, the first
+argument is I<not> a filehandle, even though it looks like one).  DBNAME
 is the name of the database (without the F<.dir> or F<.pag> extension if
 any).  If the database does not exist, it is created with protection
-specified by MODE (as modified by the C<umask()>).  If your system supports
-only the older DBM functions, you may perform only one C<dbmopen()> in your
+specified by MASK (as modified by the C<umask>).  If your system supports
+only the older DBM functions, you may perform only one C<dbmopen> in your
 program.  In older versions of Perl, if your system had neither DBM nor
-ndbm, calling C<dbmopen()> produced a fatal error; it now falls back to
+ndbm, calling C<dbmopen> produced a fatal error; it now falls back to
 sdbm(3).
 
 If you don't have write access to the DBM file, you can only read hash
 variables, not set them.  If you want to test whether you can write,
-either use file tests or try setting a dummy hash entry inside an C<eval()>,
+either use file tests or try setting a dummy hash entry inside an C<eval>,
 which will trap the error.
 
-Note that functions such as C<keys()> and C<values()> may return huge lists
-when used on large DBM files.  You may prefer to use the C<each()>
+Note that functions such as C<keys> and C<values> may return huge lists
+when used on large DBM files.  You may prefer to use the C<each>
 function to iterate over large DBM files.  Example:
 
     # print out history file offsets
@@ -835,13 +870,13 @@ conditions.  This function allows you to distinguish C<undef> from
 other values.  (A simple Boolean test will not distinguish among
 C<undef>, zero, the empty string, and C<"0">, which are all equally
 false.)  Note that since C<undef> is a valid scalar, its presence
-doesn't I<necessarily> indicate an exceptional condition: C<pop()>
+doesn't I<necessarily> indicate an exceptional condition: C<pop>
 returns C<undef> when its argument is an empty array, I<or> when the
 element to return happens to be C<undef>.
 
-You may also use C<defined()> to check whether a subroutine exists, by
+You may also use C<defined> to check whether a subroutine exists, by
 saying C<defined &func> without parentheses.  On the other hand, use
-of C<defined()> upon aggregates (hashes and arrays) is not guaranteed to
+of C<defined> upon aggregates (hashes and arrays) is not guaranteed to
 produce intuitive results, and should probably be avoided.
 
 When used on a hash element, it tells you whether the value is defined,
@@ -857,7 +892,7 @@ Examples:
     sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
     $debugging = 0 unless defined $debugging;
 
-Note:  Many folks tend to overuse C<defined()>, and then are surprised to
+Note:  Many folks tend to overuse C<defined>, and then are surprised to
 discover that the number C<0> and C<""> (the zero-length string) are, in fact,
 defined values.  For example, if you say
 
@@ -868,11 +903,11 @@ matched "nothing".  But it didn't really match nothing--rather, it
 matched something that happened to be zero characters long.  This is all
 very above-board and honest.  When a function returns an undefined value,
 it's an admission that it couldn't give you an honest answer.  So you
-should use C<defined()> only when you're questioning the integrity of what
+should use C<defined> only when you're questioning the integrity of what
 you're trying to do.  At other times, a simple comparison to C<0> or C<""> is
 what you want.
 
-Currently, using C<defined()> on an entire array or hash reports whether
+Currently, using C<defined> on an entire array or hash reports whether
 memory for that aggregate has ever been allocated.  So an array you set
 to the empty list appears undefined initially, and one that once was full
 and that you then set to the empty list still appears defined.  You
@@ -881,13 +916,13 @@ should instead use a simple test for size:
     if (@an_array) { print "has array elements\n" }
     if (%a_hash)   { print "has hash members\n"   }
 
-Using C<undef()> on these, however, does clear their memory and then report
+Using C<undef> on these, however, does clear their memory and then report
 them as not defined anymore, but you shouldn't do that unless you don't
 plan to use them again, because it saves time when you load them up
 again to have memory already ready to be filled.  The normal way to 
 free up space used by an aggregate is to assign the empty list.
 
-This counterintuitive behavior of C<defined()> on aggregates may be
+This counterintuitive behavior of C<defined> on aggregates may be
 changed, fixed, or broken in a future release of Perl.
 
 See also L</undef>, L</exists>, L</ref>.
@@ -898,7 +933,7 @@ Deletes the specified key(s) and their associated values from a hash.
 For each key, returns the deleted value associated with that key, or
 the undefined value if there was no such key.  Deleting from C<$ENV{}>
 modifies the environment.  Deleting from a hash tied to a DBM file
-deletes the entry from the DBM file.  (But deleting from a C<tie()>d hash
+deletes the entry from the DBM file.  (But deleting from a C<tie>d hash
 doesn't necessarily return anything.)
 
 The following deletes all the values of a hash:
@@ -925,12 +960,13 @@ operation is a hash element lookup or hash slice:
 
 =item die LIST
 
-Outside an C<eval()>, prints the value of LIST to C<STDERR> and exits with
-the current value of C<$!> (errno).  If C<$!> is C<0>, exits with the value of
-C<($? E<gt>E<gt> 8)> (backtick `command` status).  If C<($? E<gt>E<gt> 8)>
-is C<0>, exits with C<255>.  Inside an C<eval(),> the error message is stuffed into
-C<$@> and the C<eval()> is terminated with the undefined value.  This makes
-C<die()> the way to raise an exception.
+Outside an C<eval>, prints the value of LIST to C<STDERR> and
+exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
+exits with the value of C<($? E<gt>E<gt> 8)> (backtick `command`
+status).  If C<($? E<gt>E<gt> 8)> is C<0>, exits with C<255>.  Inside
+an C<eval(),> the error message is stuffed into C<$@> and the
+C<eval> is terminated with the undefined value.  This makes
+C<die> the way to raise an exception.
 
 Equivalent examples:
 
@@ -984,25 +1020,26 @@ regular expressions.  Here's an example:
         }
     }
 
-Since perl will stringify uncaught exception messages before displaying
+Because perl will stringify uncaught exception messages before displaying
 them, you may want to overload stringification operations on such custom
 exception objects.  See L<overload> for details about that.
 
-You can arrange for a callback to be run just before the C<die()> does
-its deed, by setting the C<$SIG{__DIE__}> hook.  The associated handler
-will be called with the error text and can change the error message, if
-it sees fit, by calling C<die()> again.  See L<perlvar/$SIG{expr}> for details on
-setting C<%SIG> entries, and L<"eval BLOCK"> for some examples.
-
-Note that the C<$SIG{__DIE__}> hook is currently called even inside
-eval()ed blocks/strings!  If one wants the hook to do nothing in such
-situations, put
+You can arrange for a callback to be run just before the C<die>
+does its deed, by setting the C<$SIG{__DIE__}> hook.  The associated
+handler will be called with the error text and can change the error
+message, if it sees fit, by calling C<die> again.  See
+L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and
+L<"eval BLOCK"> for some examples.  Although this feature was meant
+to be run only right before your program was to exit, this is not
+currently the case--the C<$SIG{__DIE__}> hook is currently called
+even inside eval()ed blocks/strings!  If one wants the hook to do
+nothing in such situations, put
 
        die @_ if $^S;
 
-as the first line of the handler (see L<perlvar/$^S>).  Because this
-promotes action at a distance, this counterintuitive behavior may be fixed
-in a future release.
+as the first line of the handler (see L<perlvar/$^S>).  Because
+this promotes strange action at a distance, this counterintuitive
+behavior may be fixed in a future release.  
 
 =item do BLOCK
 
@@ -1046,7 +1083,7 @@ successfully compiled, C<do> returns the value of the last expression
 evaluated.
 
 Note that inclusion of library modules is better done with the
-C<use()> and C<require()> operators, which also do automatic error checking
+C<use> and C<require> operators, which also do automatic error checking
 and raise an exception if there's a problem.
 
 You might like to use C<do> to read in a program configuration
@@ -1067,40 +1104,31 @@ file.  Manual error checking can be done this way:
 
 =item dump
 
-This causes an immediate core dump.  Primarily this is so that you can
-use the B<undump> program to turn your core dump into an executable binary
-after having initialized all your variables at the beginning of the
-program.  When the new binary is executed it will begin by executing a
-C<goto LABEL> (with all the restrictions that C<goto> suffers).  Think of
-it as a goto with an intervening core dump and reincarnation.  If C<LABEL>
-is omitted, restarts the program from the top.  WARNING: Any files
-opened at the time of the dump will NOT be open any more when the
-program is reincarnated, with possible resulting confusion on the part
-of Perl.  See also B<-u> option in L<perlrun>.
-
-Example:
-
-    #!/usr/bin/perl
-    require 'getopt.pl';
-    require 'stat.pl';
-    %days = (
-       'Sun' => 1,
-       'Mon' => 2,
-       'Tue' => 3,
-       'Wed' => 4,
-       'Thu' => 5,
-       'Fri' => 6,
-       'Sat' => 7,
-    );
-
-    dump QUICKSTART if $ARGV[0] eq '-d';
-
-    QUICKSTART:
-    Getopt('f');
-
-This operator is largely obsolete, partly because it's very hard to 
-convert a core file into an executable, and because the real perl-to-C
-compiler has superseded it.
+This function causes an immediate core dump.  See also the B<-u>
+command-line switch in L<perlrun>, which does the same thing.
+Primarily this is so that you can use the B<undump> program (not
+supplied) to turn your core dump into an executable binary after
+having initialized all your variables at the beginning of the
+program.  When the new binary is executed it will begin by executing
+a C<goto LABEL> (with all the restrictions that C<goto> suffers).
+Think of it as a goto with an intervening core dump and reincarnation.
+If C<LABEL> is omitted, restarts the program from the top.
+
+B<WARNING>: Any files opened at the time of the dump will I<not>
+be open any more when the program is reincarnated, with possible
+resulting confusion on the part of Perl.  
+
+This function is now largely obsolete, partly because it's very
+hard to convert a core file into an executable, and because the
+real compiler backends for generating portable bytecode and compilable
+C code have superseded it.
+
+If you're looking to use L<dump> to speed up your program, consider
+generating bytecode or native C code as described in L<perlcc>.  If
+you're just trying to accelerate a CGI script, consider using the
+C<mod_perl> extension to B<Apache>, or the CPAN module, Fast::CGI.
+You might also consider autoloading or selfloading, which at least
+make your program I<appear> to run faster.  
 
 =item each HASH
 
@@ -1113,14 +1141,14 @@ for this reason.)
 
 Entries are returned in an apparently random order.  The actual random
 order is subject to change in future versions of perl, but it is guaranteed
-to be in the same order as either the C<keys()> or C<values()> function
+to be in the same order as either the C<keys> or C<values> function
 would produce on the same (unmodified) hash.
 
 When the hash is entirely read, a null array is returned in list context
-(which when assigned produces a FALSE (C<0>) value), and C<undef> in
-scalar context.  The next call to C<each()> after that will start iterating
-again.  There is a single iterator for each hash, shared by all C<each()>,
-C<keys()>, and C<values()> function calls in the program; it can be reset by
+(which when assigned produces a false (C<0>) value), and C<undef> in
+scalar context.  The next call to C<each> after that will start iterating
+again.  There is a single iterator for each hash, shared by all C<each>,
+C<keys>, and C<values> function calls in the program; it can be reset by
 reading all the elements from the hash, or by evaluating C<keys HASH> or
 C<values HASH>.  If you add or delete elements of a hash while you're
 iterating over it, you may get entries skipped or duplicated, so don't.
@@ -1132,7 +1160,7 @@ only in a different order:
        print "$key=$value\n";
     }
 
-See also C<keys()>, C<values()> and C<sort()>.
+See also C<keys>, C<values> and C<sort>.
 
 =item eof FILEHANDLE
 
@@ -1143,17 +1171,18 @@ See also C<keys()>, C<values()> and C<sort()>.
 Returns 1 if the next read on FILEHANDLE will return end of file, or if
 FILEHANDLE is not open.  FILEHANDLE may be an expression whose value
 gives the real filehandle.  (Note that this function actually
-reads a character and then C<ungetc()>s it, so isn't very useful in an
+reads a character and then C<ungetc>s it, so isn't very useful in an
 interactive context.)  Do not read from a terminal file (or call
-C<eof(FILEHANDLE)> on it) after end-of-file is reached.  Filetypes such
+C<eof(FILEHANDLE)> on it) after end-of-file is reached.  File types such
 as terminals may lose the end-of-file condition if you do.
 
 An C<eof> without an argument uses the last file read as argument.
 Using C<eof()> with empty parentheses is very different.  It indicates
-the pseudo file formed of the files listed on the command line, i.e.,
-C<eof()> is reasonable to use inside a C<while (E<lt>E<gt>)> loop to
-detect the end of only the last file.  Use C<eof(ARGV)> or eof without the
-parentheses to test I<EACH> file in a while (E<lt>E<gt>) loop.  Examples:
+the pseudo file formed of the files listed on the command line,
+i.e., C<eof()> is reasonable to use inside a C<while (E<lt>E<gt>)>
+loop to detect the end of only the last file.  Use C<eof(ARGV)> or
+C<eof> without the parentheses to test I<each> file in a while
+(E<lt>E<gt>) loop.  Examples:
 
     # reset line numbering on each input file
     while (<>) {
@@ -1206,16 +1235,16 @@ as with subroutines.  The expression providing the return value is evaluated
 in void, scalar, or list context, depending on the context of the eval itself.
 See L</wantarray> for more on how the evaluation context can be determined.
 
-If there is a syntax error or runtime error, or a C<die()> statement is
-executed, an undefined value is returned by C<eval()>, and C<$@> is set to the
+If there is a syntax error or runtime error, or a C<die> statement is
+executed, an undefined value is returned by C<eval>, and C<$@> is set to the
 error message.  If there was no error, C<$@> is guaranteed to be a null
-string.  Beware that using C<eval()> neither silences perl from printing
+string.  Beware that using C<eval> neither silences perl from printing
 warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
 To do either of those, you have to use the C<$SIG{__WARN__}> facility.  See
 L</warn> and L<perlvar>.
 
-Note that, because C<eval()> traps otherwise-fatal errors, it is useful for
-determining whether a particular feature (such as C<socket()> or C<symlink()>)
+Note that, because C<eval> traps otherwise-fatal errors, it is useful for
+determining whether a particular feature (such as C<socket> or C<symlink>)
 is implemented.  It is also Perl's exception trapping mechanism, where
 the die operator is used to raise exceptions.
 
@@ -1247,7 +1276,7 @@ as shown in this example:
     warn $@ if $@;
 
 This is especially significant, given that C<__DIE__> hooks can call
-C<die()> again, which has the effect of changing their error messages:
+C<die> again, which has the effect of changing their error messages:
 
     # __DIE__ hooks may modify error messages
     {
@@ -1257,10 +1286,10 @@ C<die()> again, which has the effect of changing their error messages:
        print $@ if $@;                # prints "bar lives here"
     }
 
-Because this promotes action at a distance, this counterintuive behavior
+Because this promotes action at a distance, this counterintuitive behavior
 may be fixed in a future release.
 
-With an C<eval()>, you should be especially careful to remember what's
+With an C<eval>, you should be especially careful to remember what's
 being looked at when:
 
     eval $x;           # CASE 1
@@ -1273,13 +1302,13 @@ being looked at when:
     $$x++;             # CASE 6
 
 Cases 1 and 2 above behave identically: they run the code contained in
-the variable C<$x>.  (Although case 2 has misleading double quotes making
+the variable $x.  (Although case 2 has misleading double quotes making
 the reader wonder what else might be happening (nothing is).)  Cases 3
 and 4 likewise behave in the same way: they run the code C<'$x'>, which
-does nothing but return the value of C<$x>.  (Case 4 is preferred for
+does nothing but return the value of $x.  (Case 4 is preferred for
 purely visual reasons, but it also has the advantage of compiling at
 compile-time instead of at run-time.)  Case 5 is a place where
-normally you I<WOULD> like to use double quotes, except that in this
+normally you I<would> like to use double quotes, except that in this
 particular situation, you can just use symbolic references instead, as
 in case 6.
 
@@ -1290,15 +1319,15 @@ C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
 
 =item exec PROGRAM LIST
 
-The C<exec()> function executes a system command I<AND NEVER RETURNS> -
-use C<system()> instead of C<exec()> if you want it to return. It fails and
-returns FALSE only if the command does not exist I<and> it is executed
+The C<exec> function executes a system command I<and never returns>--
+use C<system> instead of C<exec> if you want it to return.  It fails and
+returns false only if the command does not exist I<and> it is executed
 directly instead of via your system's command shell (see below).
 
-Since it's a common mistake to use C<exec()> instead of C<system()>, Perl
-warns you if there is a following statement which isn't C<die()>, C<warn()>,
-or C<exit()> (if C<-w> is set  -  but you always do that).   If you
-I<really> want to follow an C<exec()> with some other statement, you
+Since it's a common mistake to use C<exec> instead of C<system>, Perl
+warns you if there is a following statement which isn't C<die>, C<warn>,
+or C<exit> (if C<-w> is set  -  but you always do that).   If you
+I<really> want to follow an C<exec> with some other statement, you
 can use one of these styles to avoid the warning:
 
     exec ('foo')   or print STDERR "couldn't exec foo: $!";
@@ -1311,9 +1340,11 @@ the argument is checked for shell metacharacters, and if there are any,
 the entire argument is passed to the system's command shell for parsing
 (this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
 If there are no shell metacharacters in the argument, it is split into
-words and passed directly to C<execvp()>, which is more efficient.
+words and passed directly to C<execvp>, which is more efficient.  
+Examples:
 
-All files opened for output are flushed before attempting the exec().
+    exec '/bin/echo', 'Your arguments are: ', @ARGV;
+    exec "sort $outfile | uniq";
 
 If you don't really want to execute the first argument, but want to lie
 to the program you are executing about its own name, you can specify
@@ -1333,10 +1364,11 @@ When the arguments get executed via the system shell, results will
 be subject to its quirks and capabilities.  See L<perlop/"`STRING`">
 for details.
 
-Using an indirect object with C<exec()> or C<system()> is also more secure.
-This usage forces interpretation of the arguments as a multivalued list,
-even if the list had just one argument.  That way you're safe from the
-shell expanding wildcards or splitting up words with whitespace in them.
+Using an indirect object with C<exec> or C<system> is also more
+secure.  This usage (which also works fine with system()) forces
+interpretation of the arguments as a multivalued list, even if the
+list had just one argument.  That way you're safe from the shell
+expanding wildcards or splitting up words with whitespace in them.
 
     @args = ( "echo surprise" );
 
@@ -1349,19 +1381,19 @@ program, passing it C<"surprise"> an argument.  The second version
 didn't--it tried to run a program literally called I<"echo surprise">,
 didn't find it, and set C<$?> to a non-zero value indicating failure.
 
-Note that C<exec()> will not call your C<END> blocks, nor will it call
+Note that C<exec> will not call your C<END> blocks, nor will it call
 any C<DESTROY> methods in your objects.
 
 =item exists EXPR
 
-Returns TRUE if the specified hash key exists in its hash array, even
+Returns true if the specified hash key exists in its hash, even
 if the corresponding value is undefined.
 
     print "Exists\n"   if exists $array{$key};
     print "Defined\n"  if defined $array{$key};
     print "True\n"      if $array{$key};
 
-A hash element can be TRUE only if it's defined, and defined if
+A hash element can be true only if it's defined, and defined if
 it exists, but the reverse doesn't necessarily hold true.
 
 Note that the EXPR can be arbitrarily complicated as long as the final
@@ -1391,20 +1423,20 @@ Evaluates EXPR and exits immediately with that value.    Example:
     $ans = <STDIN>;
     exit 0 if $ans =~ /^[Xx]/;
 
-See also C<die()>.  If EXPR is omitted, exits with C<0> status.  The only
+See also C<die>.  If EXPR is omitted, exits with C<0> status.  The only
 universally recognized values for EXPR are C<0> for success and C<1>
 for error; other values are subject to interpretation depending on the
 environment in which the Perl program is running.  For example, exiting
 69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
 the mailer to return the item undelivered, but that's not true everywhere.
 
-Don't use C<exit()> to abort a subroutine if there's any chance that
-someone might want to trap whatever error happened.  Use C<die()> instead,
-which can be trapped by an C<eval()>.
+Don't use C<exit> to abort a subroutine if there's any chance that
+someone might want to trap whatever error happened.  Use C<die> instead,
+which can be trapped by an C<eval>.
 
-The exit() function does not always exit immediately. It calls any
+The exit() function does not always exit immediately.  It calls any
 defined C<END> routines first, but these C<END> routines may not
-themselves abort the exit. Likewise any object destructors that need to
+themselves abort the exit.  Likewise any object destructors that need to
 be called are called before the real exit.  If this is a problem, you
 can call C<POSIX:_exit($status)> to avoid END and destructor processing.
 See L<perlsub> for details.
@@ -1423,20 +1455,20 @@ Implements the fcntl(2) function.  You'll probably have to say
     use Fcntl;
 
 first to get the correct constant definitions.  Argument processing and
-value return works just like C<ioctl()> below.  
+value return works just like C<ioctl> below.  
 For example:
 
     use Fcntl;
     fcntl($filehandle, F_GETFL, $packed_return_buffer)
        or die "can't fcntl F_GETFL: $!";
 
-You don't have to check for C<defined()> on the return from C<fnctl()>.
-Like C<ioctl()>, it maps a C<0> return from the system call into "C<0>
-but true" in Perl.  This string is true in boolean context and C<0>
+You don't have to check for C<defined> on the return from C<fnctl>.
+Like C<ioctl>, it maps a C<0> return from the system call into C<"0
+but true"> in Perl.  This string is true in boolean context and C<0>
 in numeric context.  It is also exempt from the normal B<-w> warnings
 on improper numeric conversions.
 
-Note that C<fcntl()> will produce a fatal error if used on a machine that
+Note that C<fcntl> will produce a fatal error if used on a machine that
 doesn't implement fcntl(2).  See the Fcntl module or your fcntl(2)
 manpage to learn what functions are available on your system.
 
@@ -1444,7 +1476,7 @@ manpage to learn what functions are available on your system.
 
 Returns the file descriptor for a filehandle, or undefined if the
 filehandle is not open.  This is mainly useful for constructing
-bitmaps for C<select()> and low-level POSIX tty-handling operations.
+bitmaps for C<select> and low-level POSIX tty-handling operations.
 If FILEHANDLE is an expression, the value is taken as an indirect
 filehandle, generally its name.
 
@@ -1457,17 +1489,17 @@ same underlying descriptor:
 
 =item flock FILEHANDLE,OPERATION
 
-Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns TRUE
-for success, FALSE on failure.  Produces a fatal error if used on a
+Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
+for success, false on failure.  Produces a fatal error if used on a
 machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
-C<flock()> is Perl's portable file locking interface, although it locks
+C<flock> is Perl's portable file locking interface, although it locks
 only entire files, not records.
 
 Two potentially non-obvious but traditional C<flock> semantics are
 that it waits indefinitely until the lock is granted, and that its locks
 B<merely advisory>.  Such discretionary locks are more flexible, but offer
-fewer guarantees.  This means that files locked with C<flock()> may be
-modified by programs that do not also use C<flock()>.  See L<perlport>,
+fewer guarantees.  This means that files locked with C<flock> may be
+modified by programs that do not also use C<flock>.  See L<perlport>,
 your port's specific documentation, or your system-specific local manpages
 for details.  It's best to assume traditional behavior if you're writing
 portable programs.  (But if you're not, you should as always feel perfectly
@@ -1481,7 +1513,7 @@ you can use the symbolic names if import them from the Fcntl module,
 either individually, or as a group using the ':flock' tag.  LOCK_SH
 requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
 releases a previously requested lock.  If LOCK_NB is added to LOCK_SH or
-LOCK_EX then C<flock()> will return immediately rather than blocking
+LOCK_EX then C<flock> will return immediately rather than blocking
 waiting for the lock (check the return status to see if you got it).
 
 To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
@@ -1493,8 +1525,8 @@ are the semantics that lockf(3) implements.  Most if not all systems
 implement lockf(3) in terms of fcntl(2) locking, though, so the
 differing semantics shouldn't bite too many people.
 
-Note also that some versions of C<flock()> cannot lock things over the
-network; you would need to use the more system-specific C<fcntl()> for
+Note also that some versions of C<flock> cannot lock things over the
+network; you would need to use the more system-specific C<fcntl> for
 that.  If you like you can force Perl to ignore your system's flock(2)
 function, and so provide its own fcntl(2)-based emulation, by passing
 the switch C<-Ud_flock> to the F<Configure> program when you configure
@@ -1541,7 +1573,7 @@ dominant paradigm for multitasking over the last few decades.
 
 All files opened for output are flushed before forking the child process.
 
-If you C<fork()> without ever waiting on your children, you will
+If you C<fork> without ever waiting on your children, you will
 accumulate zombies.  On some systems, you can avoid this by setting
 C<$SIG{CHLD}> to C<"IGNORE">.  See also L<perlipc> for more examples of
 forking and reaping moribund children.
@@ -1549,12 +1581,12 @@ forking and reaping moribund children.
 Note that if your forked child inherits system file descriptors like
 STDIN and STDOUT that are actually connected by a pipe or socket, even
 if you exit, then the remote server (such as, say, a CGI script or a
-backgrounded job launced from a remote shell) won't think you're done.
+backgrounded job launched from a remote shell) won't think you're done.
 You should reopen those to F</dev/null> if it's any issue.
 
 =item format
 
-Declare a picture format for use by the C<write()> function.  For
+Declare a picture format for use by the C<write> function.  For
 example:
 
     format Something =
@@ -1575,18 +1607,18 @@ This is an internal function used by C<format>s, though you may call it,
 too.  It formats (see L<perlform>) a list of values according to the
 contents of PICTURE, placing the output into the format output
 accumulator, C<$^A> (or C<$ACCUMULATOR> in English).
-Eventually, when a C<write()> is done, the contents of
+Eventually, when a C<write> is done, the contents of
 C<$^A> are written to some filehandle, but you could also read C<$^A>
 yourself and then set C<$^A> back to C<"">.  Note that a format typically
-does one C<formline()> per line of form, but the C<formline()> function itself
+does one C<formline> per line of form, but the C<formline> function itself
 doesn't care how many newlines are embedded in the PICTURE.  This means
 that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line.
 You may therefore need to use multiple formlines to implement a single
 record format, just like the format compiler.
 
-Be careful if you put double quotes around the picture, because an "C<@>"
+Be careful if you put double quotes around the picture, because an C<@>
 character may be taken to mean the beginning of an array name.
-C<formline()> always returns TRUE.  See L<perlform> for other examples.
+C<formline> always returns true.  See L<perlform> for other examples.
 
 =item getc FILEHANDLE
 
@@ -1619,7 +1651,7 @@ something more like:
 Determination of whether $BSD_STYLE should be set
 is left as an exercise to the reader.
 
-The C<POSIX::getattr()> function can do this more portably on
+The C<POSIX::getattr> function can do this more portably on
 systems purporting POSIX compliance.  See also the C<Term::ReadKey>
 module from your nearest CPAN site; details on CPAN can be found on
 L<perlmodlib/CPAN>.
@@ -1628,12 +1660,12 @@ L<perlmodlib/CPAN>.
 
 Implements the C library function of the same name, which on most
 systems returns the current login from F</etc/utmp>, if any.  If null,
-use C<getpwuid()>.
+use C<getpwuid>.
 
     $login = getlogin || getpwuid($<) || "Kilroy";
 
-Do not consider C<getlogin()> for authentication: it is not as
-secure as C<getpwuid()>.
+Do not consider C<getlogin> for authentication: it is not as
+secure as C<getpwuid>.
 
 =item getpeername SOCKET
 
@@ -1641,7 +1673,7 @@ Returns the packed sockaddr address of other end of the SOCKET connection.
 
     use Socket;
     $hersockaddr    = getpeername(SOCK);
-    ($port, $iaddr) = unpack_sockaddr_in($hersockaddr);
+    ($port, $iaddr) = sockaddr_in($hersockaddr);
     $herhostname    = gethostbyaddr($iaddr, AF_INET);
     $herstraddr     = inet_ntoa($iaddr);
 
@@ -1651,7 +1683,7 @@ Returns the current process group for the specified PID.  Use
 a PID of C<0> to get the current process group for the
 current process.  Will raise an exception if used on a machine that
 doesn't implement getpgrp(2).  If PID is omitted, returns process
-group of current process.  Note that the POSIX version of C<getpgrp()>
+group of current process.  Note that the POSIX version of C<getpgrp>
 does not accept a PID argument, so only C<PID==0> is truly portable.
 
 =item getppid
@@ -1750,20 +1782,20 @@ lookup by name, in which case you get the other thing, whatever it is.
     $name  = getgrent();
     #etc.
 
-In I<getpw*()> the fields C<$quota>, C<$comment>, and C<$expire> are
+In I<getpw*()> the fields $quota, $comment, and $expire are
 special cases in the sense that in many systems they are unsupported.
-If the C<$quota> is unsupported, it is an empty scalar.  If it is
-supported, it usually encodes the disk quota.  If the C<$comment>
+If the $quota is unsupported, it is an empty scalar.  If it is
+supported, it usually encodes the disk quota.  If the $comment
 field is unsupported, it is an empty scalar.  If it is supported it
 usually encodes some administrative comment about the user.  In some
-systems the $quota field may be C<$change> or C<$age>, fields that have
-to do with password aging.  In some systems the C<$comment> field may
-be C<$class>.  The C<$expire> field, if present, encodes the expiration
+systems the $quota field may be $change or $age, fields that have
+to do with password aging.  In some systems the $comment field may
+be $class.  The $expire field, if present, encodes the expiration
 period of the account or the password.  For the availability and the
 exact meaning of these fields in your system, please consult your
 getpwnam(3) documentation and your F<pwd.h> file.  You can also find
-out from within Perl what your C<$quota> and C<$comment> fields mean
-and whether you have the C<$expire> field by using the C<Config> module
+out from within Perl what your $quota and $comment fields mean
+and whether you have the $expire field by using the C<Config> module
 and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>,
 and C<d_pwexpire>.  Shadow password files are only supported if your
 vendor has implemented them in the intuitive fashion that calling the
@@ -1771,7 +1803,7 @@ regular C library routines gets the shadow versions if you're running
 under privilege.  Those that incorrectly implement a separate library
 call are not supported.
 
-The C<$members> value returned by I<getgr*()> is a space separated list of
+The $members value returned by I<getgr*()> is a space separated list of
 the login names of the members of the group.
 
 For the I<gethost*()> functions, if the C<h_errno> variable is supported in
@@ -1790,29 +1822,36 @@ The Socket library makes this slightly easier:
     $name  = gethostbyaddr($iaddr, AF_INET);
 
     # or going the other way
-    $straddr = inet_ntoa($iaddr");
+    $straddr = inet_ntoa($iaddr);
 
-If you get tired of remembering which element of the return list contains
-which return value, by-name interfaces are also provided in modules:
-C<File::stat>, C<Net::hostent>, C<Net::netent>, C<Net::protoent>, C<Net::servent>,
-C<Time::gmtime>, C<Time::localtime>, and C<User::grent>.  These override the
-normal built-in, replacing them with versions that return objects with
-the appropriate names for each field.  For example:
+If you get tired of remembering which element of the return list
+contains which return value, by-name interfaces are provided
+in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
+C<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>,
+and C<User::grent>.  These override the normal built-ins, supplying
+versions that return objects with the appropriate names
+for each field.  For example:
 
    use File::stat;
    use User::pwent;
    $is_his = (stat($filename)->uid == pwent($whoever)->uid);
 
 Even though it looks like they're the same method calls (uid), 
-they aren't, because a C<File::stat> object is different from a C<User::pwent> object.
+they aren't, because a C<File::stat> object is different from 
+a C<User::pwent> object.
 
 =item getsockname SOCKET
 
-Returns the packed sockaddr address of this end of the SOCKET connection.
+Returns the packed sockaddr address of this end of the SOCKET connection,
+in case you don't know the address because you have several different
+IPs that the connection might have come in on.
 
     use Socket;
     $mysockaddr = getsockname(SOCK);
-    ($port, $myaddr) = unpack_sockaddr_in($mysockaddr);
+    ($port, $myaddr) = sockaddr_in($mysockaddr);
+    printf "Connect to %s [%s]\n", 
+       scalar gethostbyaddr($myaddr, AF_INET),
+       inet_ntoa($myaddr);
 
 =item getsockopt SOCKET,LEVEL,OPTNAME
 
@@ -1830,7 +1869,7 @@ discussed in more detail in L<perlop/"I/O Operators">.
 
 =item gmtime EXPR
 
-Converts a time as returned by the time function to a 9-element array
+Converts a time as returned by the time function to a 9-element list
 with the time localized for the standard Greenwich time zone.
 Typically used as follows:
 
@@ -1838,10 +1877,10 @@ Typically used as follows:
     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                            gmtime(time);
 
-All array elements are numeric, and come straight out of a struct tm.
-In particular this means that C<$mon> has the range C<0..11> and C<$wday>
-has the range C<0..6> with sunday as day C<0>.  Also, C<$year> is the
-number of years since 1900, that is, C<$year> is C<123> in year 2023,
+All list elements are numeric, and come straight out of a struct tm.
+In particular this means that $mon has the range C<0..11> and $wday
+has the range C<0..6> with sunday as day C<0>.  Also, $year is the
+number of years since 1900, that is, $year is C<123> in year 2023,
 I<not> simply the last two digits of the year.  If you assume it is,
 then you create non-Y2K-compliant programs--and you wouldn't want to do
 that, would you?
@@ -1852,7 +1891,7 @@ In scalar context, returns the ctime(3) value:
 
     $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
-Also see the C<timegm()> function provided by the C<Time::Local> module,
+Also see the C<timegm> function provided by the C<Time::Local> module,
 and the strftime(3) function available via the POSIX module.
 
 This scalar value is B<not> locale dependent (see L<perllocale>), but
@@ -1879,10 +1918,10 @@ The C<goto-LABEL> form finds the statement labeled with LABEL and resumes
 execution there.  It may not be used to go into any construct that
 requires initialization, such as a subroutine or a C<foreach> loop.  It
 also can't be used to go into a construct that is optimized away,
-or to get out of a block or subroutine given to C<sort()>.
+or to get out of a block or subroutine given to C<sort>.
 It can be used to go almost anywhere else within the dynamic scope,
 including out of subroutines, but it's usually better to use some other
-construct such as C<last> or C<die()>.  The author of Perl has never felt the
+construct such as C<last> or C<die>.  The author of Perl has never felt the
 need to use this form of C<goto> (in Perl, that is--C is another matter).
 
 The C<goto-EXPR> form expects a label name, whose scope will be resolved
@@ -1896,7 +1935,7 @@ named subroutine for the currently running subroutine.  This is used by
 C<AUTOLOAD> subroutines that wish to load another subroutine and then
 pretend that the other subroutine had been called in the first place
 (except that any modifications to C<@_> in the current subroutine are
-propagated to the other subroutine.)  After the C<goto>, not even C<caller()>
+propagated to the other subroutine.)  After the C<goto>, not even C<caller>
 will be able to tell that this routine was called first.
 
 =item grep BLOCK LIST
@@ -1908,8 +1947,8 @@ relatives.  In particular, it is not limited to using regular expressions.
 
 Evaluates the BLOCK or EXPR for each element of LIST (locally setting
 C<$_> to each element) and returns the list value consisting of those
-elements for which the expression evaluated to TRUE.  In scalar
-context, returns the number of times the expression was TRUE.
+elements for which the expression evaluated to true.  In scalar
+context, returns the number of times the expression was true.
 
     @foo = grep(!/^#/, @bar);    # weed out comments
 
@@ -1922,11 +1961,11 @@ be used to modify the elements of the array.  While this is useful and
 supported, it can cause bizarre results if the LIST is not a named array.
 Similarly, grep returns aliases into the original list, much as a for
 loop's index variable aliases the list elements.  That is, modifying an
-element of a list returned by grep (for example, in a C<foreach>, C<map()>
-or another C<grep()>) actually modifies the element in the original list.
+element of a list returned by grep (for example, in a C<foreach>, C<map>
+or another C<grep>) actually modifies the element in the original list.
 This is usually something to be avoided when writing clear code.
 
-See also L</map> for an array composed of the results of the BLOCK or EXPR.
+See also L</map> for a list composed of the results of the BLOCK or EXPR.
 
 =item hex EXPR
 
@@ -1939,11 +1978,14 @@ L</oct>.)  If EXPR is omitted, uses C<$_>.
     print hex '0xAf'; # prints '175'
     print hex 'aF';   # same
 
+Hex strings may only represent integers.  Strings that would cause
+integer overflow trigger a mandatory error message.
+
 =item import
 
-There is no builtin C<import()> function.  It is just an ordinary
+There is no builtin C<import> function.  It is just an ordinary
 method (subroutine) defined (or inherited) by modules that wish to export
-names to another module.  The C<use()> function calls the C<import()> method
+names to another module.  The C<use> function calls the C<import> method
 for the package used.  See also L</use()>, L<perlmod>, and L<Exporter>.
 
 =item index STR,SUBSTR,POSITION
@@ -1968,7 +2010,7 @@ towards C<0>, and two because machine representations of floating point
 numbers can sometimes produce counterintuitive results.  For example,
 C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's
 because it's really more like -268.99999999999994315658 instead.  Usually,
-the C<sprintf()>, C<printf()>, or the C<POSIX::floor> and C<POSIX::ceil>
+the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
 functions will serve you better than will int().
 
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
@@ -1983,33 +2025,21 @@ own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>.
 (There is a Perl script called B<h2ph> that comes with the Perl kit that
 may help you in this, but it's nontrivial.)  SCALAR will be read and/or
 written depending on the FUNCTION--a pointer to the string value of SCALAR
-will be passed as the third argument of the actual C<ioctl()> call.  (If SCALAR
+will be passed as the third argument of the actual C<ioctl> call.  (If SCALAR
 has no string value but does have a numeric value, that value will be
 passed rather than a pointer to the string value.  To guarantee this to be
-TRUE, add a C<0> to the scalar before using it.)  The C<pack()> and C<unpack()>
-functions are useful for manipulating the values of structures used by
-C<ioctl()>.  The following example sets the erase character to DEL.
-
-    require 'ioctl.ph';
-    $getp = &TIOCGETP;
-    die "NO TIOCGETP" if $@ || !$getp;
-    $sgttyb_t = "ccccs";               # 4 chars and a short
-    if (ioctl(STDIN,$getp,$sgttyb)) {
-       @ary = unpack($sgttyb_t,$sgttyb);
-       $ary[2] = 127;
-       $sgttyb = pack($sgttyb_t,@ary);
-       ioctl(STDIN,&TIOCSETP,$sgttyb)
-           || die "Can't ioctl: $!";
-    }
+true, add a C<0> to the scalar before using it.)  The C<pack> and C<unpack>
+functions may be needed to manipulate the values of structures used by
+C<ioctl>.  
 
-The return value of C<ioctl()> (and C<fcntl()>) is as follows:
+The return value of C<ioctl> (and C<fcntl>) is as follows:
 
        if OS returns:          then Perl returns:
            -1                    undefined value
             0                  string "0 but true"
        anything else               that number
 
-Thus Perl returns TRUE on success and FALSE on failure, yet you can
+Thus Perl returns true on success and false on failure, yet you can
 still easily determine the actual value returned by the operating
 system:
 
@@ -2019,6 +2049,18 @@ system:
 The special string "C<0> but true" is exempt from B<-w> complaints
 about improper numeric conversions.
 
+Here's an example of setting a filehandle named C<REMOTE> to be
+non-blocking at the system level.  You'll have to negotiate C<$|>
+on your own, though.
+
+    use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
+
+    $flags = fcntl(REMOTE, F_GETFL, 0)
+                or die "Can't get flags for the socket: $!\n";
+
+    $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
+                or die "Can't set flags for the socket: $!\n";
+
 =item join EXPR,LIST
 
 Joins the separate strings of LIST into a single string with fields
@@ -2030,11 +2072,11 @@ See L</split>.
 
 =item keys HASH
 
-Returns a list consisting of all the keys of the named hash.  (In a
+Returns a list consisting of all the keys of the named hash.  (In
 scalar context, returns the number of keys.)  The keys are returned in
 an apparently random order.  The actual random order is subject to
 change in future versions of perl, but it is guaranteed to be the same
-order as either the C<values()> or C<each()> function produces (given
+order as either the C<values> or C<each> function produces (given
 that the hash has not been modified).  As a side effect, it resets
 HASH's iterator.
 
@@ -2042,7 +2084,7 @@ Here is yet another way to print your environment:
 
     @keys = keys %ENV;
     @values = values %ENV;
-    while ($#keys >= 0) {
+    while (@keys) { 
        print pop(@keys), '=', pop(@values), "\n";
     }
 
@@ -2052,14 +2094,14 @@ or how about sorted by key:
        print $key, '=', $ENV{$key}, "\n";
     }
 
-To sort a hash by value, you'll need to use a C<sort()> function.
+To sort a hash by value, you'll need to use a C<sort> function.
 Here's a descending numeric sort of a hash by its values:
 
     foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
        printf "%4d %s\n", $hash{$key}, $key;
     }
 
-As an lvalue C<keys()> allows you to increase the number of hash buckets
+As an lvalue C<keys> allows you to increase the number of hash buckets
 allocated for the given hash.  This can gain you a measure of efficiency if
 you know the hash is going to get big.  (This is similar to pre-extending
 an array by assigning a larger number to $#array.)  If you say
@@ -2071,10 +2113,10 @@ in fact, since it rounds up to the next power of two.  These
 buckets will be retained even if you do C<%hash = ()>, use C<undef
 %hash> if you want to free the storage while C<%hash> is still in scope.
 You can't shrink the number of buckets allocated for the hash using
-C<keys()> in this way (but you needn't worry about doing this by accident,
+C<keys> in this way (but you needn't worry about doing this by accident,
 as trying has no effect).
 
-See also C<each()>, C<values()> and C<sort()>.
+See also C<each>, C<values> and C<sort>.
 
 =item kill LIST
 
@@ -2118,7 +2160,8 @@ C<redo> work.
 
 Returns an lowercased version of EXPR.  This is the internal function
 implementing the C<\L> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
+Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>
+and L<utf8>.
 
 If EXPR is omitted, uses C<$_>.
 
@@ -2143,17 +2186,17 @@ For that, use C<scalar @array> and C<scalar keys %hash> respectively.
 
 =item link OLDFILE,NEWFILE
 
-Creates a new filename linked to the old filename.  Returns TRUE for
-success, FALSE otherwise. 
+Creates a new filename linked to the old filename.  Returns true for
+success, false otherwise. 
 
 =item listen SOCKET,QUEUESIZE
 
-Does the same thing that the listen system call does.  Returns TRUE if
-it succeeded, FALSE otherwise.  See the example in L<perlipc/"Sockets: Client/Server Communication">.
+Does the same thing that the listen system call does.  Returns true if
+it succeeded, false otherwise.  See the example in L<perlipc/"Sockets: Client/Server Communication">.
 
 =item local EXPR
 
-You really probably want to be using C<my()> instead, because C<local()> isn't
+You really probably want to be using C<my> instead, because C<local> isn't
 what most people think of as "local".  See L<perlsub/"Private Variables
 via my()"> for details.
 
@@ -2164,7 +2207,7 @@ for details, including issues with tied arrays and hashes.
 
 =item localtime EXPR
 
-Converts a time as returned by the time function to a 9-element array
+Converts a time as returned by the time function to a 9-element list
 with the time analyzed for the local time zone.  Typically used as
 follows:
 
@@ -2172,10 +2215,10 @@ follows:
     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                                localtime(time);
 
-All array elements are numeric, and come straight out of a struct tm.
-In particular this means that C<$mon> has the range C<0..11> and C<$wday>
-has the range C<0..6> with sunday as day C<0>.  Also, C<$year> is the
-number of years since 1900, that is, C<$year> is C<123> in year 2023,
+All list elements are numeric, and come straight out of a struct tm.
+In particular this means that $mon has the range C<0..11> and $wday
+has the range C<0..6> with sunday as day C<0>.  Also, $year is the
+number of years since 1900, that is, $year is C<123> in year 2023,
 and I<not> simply the last two digits of the year.  If you assume it is,
 then you create non-Y2K-compliant programs--and you wouldn't want to do
 that, would you?
@@ -2199,13 +2242,24 @@ and try for example:
 Note that the C<%a> and C<%b>, the short forms of the day of the week
 and the month of the year, may not necessarily be three characters wide.
 
+=item lock
+
+    lock I<THING>
+
+This function places an advisory lock on a variable, subroutine,
+or referenced object contained in I<THING> until the lock goes out
+of scope.  This is a built-in function only if your version of Perl
+was built with threading enabled, and if you've said C<use Threads>.
+Otherwise a user-defined function by this name will be called.  See
+L<Thread>.
+
 =item log EXPR
 
 =item log
 
 Returns the natural logarithm (base I<e>) of EXPR.  If EXPR is omitted,
 returns log of C<$_>.  To get the log of another base, use basic algebra:
-The base-N log of a number is is equal to the natural log of that number
+The base-N log of a number is equal to the natural log of that number
 divided by the natural log of N.  For example:
 
     sub log10 {
@@ -2221,10 +2275,10 @@ See also L</exp> for the inverse operation.
 
 =item lstat
 
-Does the same thing as the C<stat()> function (including setting the
+Does the same thing as the C<stat> function (including setting the
 special C<_> filehandle) but stats a symbolic link instead of the file
 the symbolic link points to.  If symbolic links are unimplemented on
-your system, a normal C<stat()> is done.
+your system, a normal C<stat> is done.
 
 If EXPR is omitted, stats C<$_>.
 
@@ -2236,12 +2290,12 @@ The match operator.  See L<perlop>.
 
 =item map EXPR,LIST
 
-Evaluates the BLOCK or EXPR for each element of LIST (locally setting C<$_> to each
-element) and returns the list value composed of the results of each such
-evaluation.  Evaluates BLOCK or EXPR in a list context, so each element of LIST
-may produce zero, one, or more elements in the returned value.
-
-In scalar context, returns the total number of elements so generated.
+Evaluates the BLOCK or EXPR for each element of LIST (locally setting
+C<$_> to each element) and returns the list value composed of the
+results of each such evaluation.  In scalar context, returns the
+total number of elements so generated.  Evaluates BLOCK or EXPR in
+list context, so each element of LIST may produce zero, one, or
+more elements in the returned value.
 
     @chars = map(chr, @nums);
 
@@ -2263,18 +2317,18 @@ Using a regular C<foreach> loop for this purpose would be clearer in
 most cases.  See also L</grep> for an array composed of those items of
 the original list for which the BLOCK or EXPR evaluates to true.
 
-=item mkdir FILENAME,MODE
+=item mkdir FILENAME,MASK
 
 Creates the directory specified by FILENAME, with permissions
-specified by MODE (as modified by C<umask>).  If it succeeds it
-returns TRUE, otherwise it returns FALSE and sets C<$!> (errno).
+specified by MASK (as modified by C<umask>).  If it succeeds it
+returns true, otherwise it returns false and sets C<$!> (errno).
 
-In general, it is better to create directories with permissive MODEs,
+In general, it is better to create directories with permissive MASK,
 and let the user modify that with their C<umask>, than it is to supply
-a restrictive MODE and give the user no way to be more permissive.
+a restrictive MASK and give the user no way to be more permissive.
 The exceptions to this rule are when the file or directory should be
 kept private (mail files, for instance).  The perlfunc(1) entry on
-C<umask> discusses the choice of MODE in more detail.
+C<umask> discusses the choice of MASK in more detail.
 
 =item msgctl ID,CMD,ARG
 
@@ -2284,22 +2338,22 @@ Calls the System V IPC function msgctl(2).  You'll probably have to say
 
 first to get the correct constant definitions.  If CMD is C<IPC_STAT>,
 then ARG must be a variable which will hold the returned C<msqid_ds>
-structure.  Returns like C<ioctl()>: the undefined value for error, "C<0> but
-true" for zero, or the actual return value otherwise.  See also
-C<IPC::SysV> and C<IPC::Semaphore::Msg> documentation.
+structure.  Returns like C<ioctl>: the undefined value for error, C<"0 but
+true"> for zero, or the actual return value otherwise.  See also
+C<IPC::SysV> and C<IPC::Semaphore> documentation.
 
 =item msgget KEY,FLAGS
 
 Calls the System V IPC function msgget(2).  Returns the message queue
 id, or the undefined value if there is an error.  See also C<IPC::SysV>
-and C<IPC::SysV::Msg> documentation.
+and C<IPC::Msg> documentation.
 
 =item msgsnd ID,MSG,FLAGS
 
 Calls the System V IPC function msgsnd to send the message MSG to the
 message queue ID.  MSG must begin with the long integer message type,
-which may be created with C<pack("l", $type)>.  Returns TRUE if
-successful, or FALSE if there is an error.  See also C<IPC::SysV>
+which may be created with C<pack("l", $type)>.  Returns true if
+successful, or false if there is an error.  See also C<IPC::SysV>
 and C<IPC::SysV::Msg> documentation.
 
 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
@@ -2308,13 +2362,13 @@ Calls the System V IPC function msgrcv to receive a message from
 message queue ID into variable VAR with a maximum message size of
 SIZE.  Note that if a message is received, the message type will be
 the first thing in VAR, and the maximum length of VAR is SIZE plus the
-size of the message type.  Returns TRUE if successful, or FALSE if
+size of the message type.  Returns true if successful, or false if
 there is an error.  See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
-A C<my()> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval()>.  If
+A C<my> declares the listed variables to be local (lexically) to the
+enclosing block, file, or C<eval>.  If
 more than one value is listed, the list must be placed in parentheses.  See
 L<perlsub/"Private Variables via my()"> for details.
 
@@ -2357,10 +2411,16 @@ hex in the standard Perl or C notation:
 
     $val = oct($val) if $val =~ /^0/;
 
-If EXPR is omitted, uses C<$_>.  This function is commonly used when
-a string such as C<644> needs to be converted into a file mode, for
-example. (Although perl will automatically convert strings into
-numbers as needed, this automatic conversion assumes base 10.)
+If EXPR is omitted, uses C<$_>.   To go the other way (produce a number
+in octal), use sprintf() or printf():
+
+    $perms = (stat("filename"))[2] & 07777;
+    $oct_perms = sprintf "%lo", $perms;
+
+The oct() function is commonly used when a string such as C<644> needs
+to be converted into a file mode, for example. (Although perl will
+automatically convert strings into numbers as needed, this automatic
+conversion assumes base 10.)
 
 =item open FILEHANDLE,EXPR
 
@@ -2370,14 +2430,14 @@ Opens the file whose filename is given by EXPR, and associates it with
 FILEHANDLE.  If FILEHANDLE is an expression, its value is used as the
 name of the real filehandle wanted.  If EXPR is omitted, the scalar
 variable of the same name as the FILEHANDLE contains the filename.
-(Note that lexical variables--those declared with C<my()>--will not work
-for this purpose; so if you're using C<my()>, specify EXPR in your call
+(Note that lexical variables--those declared with C<my>--will not work
+for this purpose; so if you're using C<my>, specify EXPR in your call
 to open.)  See L<perlopentut> for a kinder, gentler explanation of opening
 files.
 
 If the filename begins with C<'E<lt>'> or nothing, the file is opened for input.
 If the filename begins with C<'E<gt>'>, the file is truncated and opened for
-output, being created if necessary. If the filename begins with C<'E<gt>E<gt>'>,
+output, being created if necessary.  If the filename begins with C<'E<gt>E<gt>'>,
 the file is opened for appending, again being created if necessary. 
 You can put a C<'+'> in front of the C<'E<gt>'> or C<'E<lt>'> to indicate that
 you want both read and write access to the file; thus C<'+E<lt>'> is almost
@@ -2395,29 +2455,29 @@ If the filename begins with C<'|'>, the filename is interpreted as a
 command to which output is to be piped, and if the filename ends with a
 C<'|'>, the filename is interpreted as a command which pipes output to
 us.  See L<perlipc/"Using open() for IPC">
-for more examples of this.  (You are not allowed to C<open()> to a command
+for more examples of this.  (You are not allowed to C<open> to a command
 that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
 and L<perlipc/"Bidirectional Communication"> for alternatives.)
 
 Opening C<'-'> opens STDIN and opening C<'E<gt>-'> opens STDOUT.  Open returns
-nonzero upon success, the undefined value otherwise.  If the C<open()>
+nonzero upon success, the undefined value otherwise.  If the C<open>
 involved a pipe, the return value happens to be the pid of the
 subprocess.
 
 If you're unfortunate enough to be running Perl on a system that
 distinguishes between text files and binary files (modern operating
 systems don't care), then you should check out L</binmode> for tips for
-dealing with this.  The key distinction between systems that need C<binmode()>
+dealing with this.  The key distinction between systems that need C<binmode>
 and those that don't is their text file formats.  Systems like Unix, MacOS, and
 Plan9, which delimit lines with a single character, and which encode that
-character in C as C<"\n">, do not need C<binmode()>.  The rest need it.
+character in C as C<"\n">, do not need C<binmode>.  The rest need it.
 
 When opening a file, it's usually a bad idea to continue normal execution
-if the request failed, so C<open()> is frequently used in connection with
-C<die()>. Even if C<die()> won't do what you want (say, in a CGI script,
+if the request failed, so C<open> is frequently used in connection with
+C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
 where you want to make a nicely formatted error message (but there are
 modules that can help with that problem)) you should always check
-the return value from opening a file. The infrequent exception is when
+the return value from opening a file.  The infrequent exception is when
 working with an unopened filehandle is actually what you want to do.
 
 Examples:
@@ -2496,7 +2556,7 @@ STDERR:
     print STDERR "stderr 2\n";
 
 If you specify C<'E<lt>&=N'>, where C<N> is a number, then Perl will do an
-equivalent of C's C<fdopen()> of that file descriptor; this is more
+equivalent of C's C<fdopen> of that file descriptor; this is more
 parsimonious of file descriptors.  For example:
 
     open(FILEHANDLE, "<&=$fd")
@@ -2545,8 +2605,8 @@ necessary to protect any leading and trailing whitespace:
     $file =~ s#^(\s)#./$1#;
     open(FOO, "< $file\0");
 
-If you want a "real" C C<open()> (see L<open(2)> on your system), then you
-should use the C<sysopen()> function, which involves no such magic.  This is
+If you want a "real" C C<open> (see L<open(2)> on your system), then you
+should use the C<sysopen> function, which involves no such magic.  This is
 another way to protect your filenames from interpretation.  For example:
 
     use IO::Handle;
@@ -2579,8 +2639,8 @@ See L</seek> for some details about mixing reading and writing.
 
 =item opendir DIRHANDLE,EXPR
 
-Opens a directory named EXPR for processing by C<readdir()>, C<telldir()>,
-C<seekdir()>, C<rewinddir()>, and C<closedir()>.  Returns TRUE if successful.
+Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
+C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord EXPR
@@ -2593,7 +2653,7 @@ See L<utf8> for more about Unicode.
 
 =item pack TEMPLATE,LIST
 
-Takes an array or list of values and packs it into a binary structure,
+Takes a list of values and packs it into a binary structure,
 returning the string containing the structure.  The TEMPLATE is a
 sequence of characters that give the order and type of values, as
 follows:
@@ -2617,7 +2677,7 @@ follows:
 
     i  A signed integer value.
     I  An unsigned integer value.
-         (This 'integer' is _at least_ 32 bits wide.  Its exact
+         (This 'integer' is _at_least_ 32 bits wide.  Its exact
            size depends on what a local C compiler calls 'int',
            and may even be larger than the 'long' described in
            the next item.)
@@ -2692,7 +2752,7 @@ The C<"p"> type packs a pointer to a null-terminated string.  You are
 responsible for ensuring the string is not a temporary value (which can
 potentially get deallocated before you get around to using the packed result).
 The C<"P"> type packs a pointer to a structure of the size indicated by the
-length. A NULL pointer is created if the corresponding value for C<"p"> or
+length.  A NULL pointer is created if the corresponding value for C<"p"> or
 C<"P"> is C<undef>.
 
 =item *
@@ -2713,10 +2773,15 @@ they are identical to C<"i"> and C<"I">.
 The actual sizes (in bytes) of native shorts, ints, and longs on
 the platform where Perl was built are also available via L<Config>:
 
-       use Config;
-       print $Config{shortsize}, "\n";
-       print $Config{intsize}, "\n";
-       print $Config{longsize}, "\n";
+The actual sizes (in bytes) of native shorts, ints, longs, and long
+longs on the platform where Perl was built are also available via
+L<Config>:
+
+       use Config;
+       print $Config{shortsize},    "\n";
+       print $Config{intsize},      "\n";
+       print $Config{longsize},     "\n";
+       print $Config{longlongsize}, "\n";
 
 =item *
 
@@ -2732,12 +2797,12 @@ because they obey the native byteorder and endianness.  For example a
 Basically, the Intel, Alpha, and VAX CPUs and little-endian, while
 everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA,
 Power, and Cray are big-endian.  MIPS can be either: Digital used it
-in little-endian mode, SGI uses it in big-endian mode.
+in little-endian mode; SGI uses it in big-endian mode.
 
-The names `big-endian' and `little-endian' are joking references to
+The names `big-endian' and `little-endian' are comic references to
 the classic "Gulliver's Travels" (via the paper "On Holy Wars and a
 Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and
-the egg-eating habits of the lilliputs.
+the egg-eating habits of the Lilliputians.
  
 Some systems may even have weird byte orders such as
  
@@ -2774,7 +2839,7 @@ of the IEEE spec).
 Note that Perl uses doubles internally for all numeric calculation, and
 converting from double into float and thence back to double again will
 lose precision (i.e., C<unpack("f", pack("f", $foo)>) will not in general
-equal C<$foo>).
+equal $foo).
 
 =back
 
@@ -2825,11 +2890,11 @@ The same template may generally also be used in unpack().
 
 Declares the compilation unit as being in the given namespace.  The scope
 of the package declaration is from the declaration itself through the end
-of the enclosing block, file, or eval (the same as the C<my()> operator).
+of the enclosing block, file, or eval (the same as the C<my> operator).
 All further unqualified dynamic identifiers will be in this namespace.
 A package statement affects only dynamic variables--including those
-you've used C<local()> on--but I<not> lexical variables, which are created
-with C<my()>.  Typically it would be the first declaration in a file to
+you've used C<local> on--but I<not> lexical variables, which are created
+with C<my>.  Typically it would be the first declaration in a file to
 be included by the C<require> or C<use> operator.  You can switch into a
 package in more than one place; it merely influences which symbol table
 is used by the compiler for the rest of that block.  You can refer to
@@ -2866,13 +2931,14 @@ See L<perlvar/$^F>.
 =item pop
 
 Pops and returns the last value of the array, shortening the array by
-one element.  Has a similar effect to
+one element.  Has an effect similar to
 
-    $tmp = $ARRAY[$#ARRAY--];
+    $ARRAY[$#ARRAY--]
 
-If there are no elements in the array, returns the undefined value.
-If ARRAY is omitted, pops the C<@ARGV> array in the main program, and
-the C<@_> array in subroutines, just like C<shift()>.
+If there are no elements in the array, returns the undefined value
+(although this may happen at other times as well).  If ARRAY is
+omitted, pops the C<@ARGV> array in the main program, and the C<@_>
+array in subroutines, just like C<shift>.
 
 =item pos SCALAR
 
@@ -2890,22 +2956,26 @@ L<perlop>.
 
 =item print
 
-Prints a string or a comma-separated list of strings.  Returns TRUE
-if successful.  FILEHANDLE may be a scalar variable name, in which case
-the variable contains the name of or a reference to the filehandle, thus
-introducing one level of indirection.  (NOTE: If FILEHANDLE is a variable
-and the next token is a term, it may be misinterpreted as an operator
+Prints a string or a list of strings.  Returns true if successful.
+FILEHANDLE may be a scalar variable name, in which case the variable
+contains the name of or a reference to the filehandle, thus introducing
+one level of indirection.  (NOTE: If FILEHANDLE is a variable and
+the next token is a term, it may be misinterpreted as an operator
 unless you interpose a C<+> or put parentheses around the arguments.)
-If FILEHANDLE is omitted, prints by default to standard output (or to the
-last selected output channel--see L</select>).  If LIST is also omitted,
-prints C<$_> to the currently selected output channel.  To set the default
-output channel to something other than STDOUT use the select operation.
-Note that, because print takes a LIST, anything in the LIST is evaluated
-in list context, and any subroutine that you call will have one or
-more of its expressions evaluated in list context.  Also be careful
-not to follow the print keyword with a left parenthesis unless you want
-the corresponding right parenthesis to terminate the arguments to the
-print--interpose a C<+> or put parentheses around all the arguments.
+If FILEHANDLE is omitted, prints by default to standard output (or
+to the last selected output channel--see L</select>).  If LIST is
+also omitted, prints C<$_> to the currently selected output channel.
+To set the default output channel to something other than STDOUT
+use the select operation.  The current value of C<$,> (if any) is
+printed between each LIST item.  The current value of C<$\> (if
+any) is printed after the entire LIST has been printed.  Because
+print takes a LIST, anything in the LIST is evaluated in list
+context, and any subroutine that you call will have one or more of
+its expressions evaluated in list context.  Also be careful not to
+follow the print keyword with a left parenthesis unless you want
+the corresponding right parenthesis to terminate the arguments to
+the print--interpose a C<+> or put parentheses around all the
+arguments.
 
 Note that if you're storing FILEHANDLES in an array or other expression,
 you will have to use a block returning its value instead:
@@ -2919,12 +2989,12 @@ you will have to use a block returning its value instead:
 
 Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
 (the output record separator) is not appended.  The first argument
-of the list will be interpreted as the C<printf()> format.  If C<use locale> is
+of the list will be interpreted as the C<printf> format.  If C<use locale> is
 in effect, the character used for the decimal point in formatted real numbers
 is affected by the LC_NUMERIC locale.  See L<perllocale>.
 
-Don't fall into the trap of using a C<printf()> when a simple
-C<print()> would do.  The C<print()> is more efficient and less
+Don't fall into the trap of using a C<printf> when a simple
+C<print> would do.  The C<print> is more efficient and less
 error prone.
 
 =item prototype FUNCTION
@@ -2936,7 +3006,7 @@ the function whose prototype you want to retrieve.
 If FUNCTION is a string starting with C<CORE::>, the rest is taken as a
 name for Perl builtin.  If the builtin is not I<overridable> (such as
 C<qw//>) or its arguments cannot be expressed by a prototype (such as
-C<system()>) returns C<undef> because the builtin does not really behave
+C<system>) returns C<undef> because the builtin does not really behave
 like a Perl function.  Otherwise, the string describing the equivalent
 prototype is returned.
 
@@ -2983,8 +3053,8 @@ If EXPR is omitted, uses C<$_>.
 
 Returns a random fractional number greater than or equal to C<0> and less
 than the value of EXPR.  (EXPR should be positive.)  If EXPR is
-omitted, the value C<1> is used.  Automatically calls C<srand()> unless
-C<srand()> has already been called.  See also C<srand()>.
+omitted, the value C<1> is used.  Automatically calls C<srand> unless
+C<srand> has already been called.  See also C<srand>.
 
 (Note: If your rand function consistently returns numbers that are too
 large or too small, then your version of Perl was probably compiled
@@ -3000,18 +3070,18 @@ C<0> at end of file, or undef if there was an error.  SCALAR will be grown
 or shrunk to the length actually read.  An OFFSET may be specified to
 place the read data at some other place than the beginning of the
 string.  This call is actually implemented in terms of stdio's fread(3)
-call.  To get a true read(2) system call, see C<sysread()>.
+call.  To get a true read(2) system call, see C<sysread>.
 
 =item readdir DIRHANDLE
 
-Returns the next directory entry for a directory opened by C<opendir()>.
+Returns the next directory entry for a directory opened by C<opendir>.
 If used in list context, returns all the rest of the entries in the
 directory.  If there are no more entries, returns an undefined value in
 scalar context or a null list in list context.
 
-If you're planning to filetest the return values out of a C<readdir()>, you'd
+If you're planning to filetest the return values out of a C<readdir>, you'd
 better prepend the directory in question.  Otherwise, because we didn't
-C<chdir()> there, it would have been testing the wrong file.
+C<chdir> there, it would have been testing the wrong file.
 
     opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
@@ -3061,7 +3131,7 @@ operator is discussed in more detail in L<perlop/"I/O Operators">.
 
 Receives a message on a socket.  Attempts to receive LENGTH bytes of
 data into variable SCALAR from the specified SOCKET filehandle.
-Actually does a C C<recvfrom()>, so that it can return the address of the
+Actually does a C C<recvfrom>, so that it can return the address of the
 sender.  Returns the undefined value if there's an error.  SCALAR will
 be grown or shrunk to the length actually read.  Takes the same flags
 as the system call of the same name.
@@ -3105,20 +3175,21 @@ C<redo> work.
 
 =item ref
 
-Returns a TRUE value if EXPR is a reference, FALSE otherwise.  If EXPR
+Returns a true value if EXPR is a reference, false otherwise.  If EXPR
 is not specified, C<$_> will be used.  The value returned depends on the
 type of thing the reference is a reference to.
 Builtin types include:
 
-    REF
     SCALAR
     ARRAY
     HASH
     CODE
+    REF
     GLOB
+    LVALUE
 
 If the referenced object has been blessed into a package, then that package
-name is returned instead.  You can think of C<ref()> as a C<typeof()> operator.
+name is returned instead.  You can think of C<ref> as a C<typeof> operator.
 
     if (ref($r) eq "HASH") {
        print "r is a reference to a hash.\n";
@@ -3134,7 +3205,9 @@ See also L<perlref>.
 
 =item rename OLDNAME,NEWNAME
 
-Changes the name of a file.  Returns C<1> for success, C<0> otherwise.
+Changes the name of a file; an existing file NEWNAME will be
+clobbered.  Returns true for success, false otherwise.
+
 Behavior of this function varies wildly depending on your system
 implementation.  For example, it will usually not work across file system
 boundaries, even though the system I<mv> command sometimes compensates
@@ -3152,7 +3225,7 @@ supplied.  If EXPR is numeric, demands that the current version of Perl
 
 Otherwise, demands that a library file be included if it hasn't already
 been included.  The file is included via the do-FILE mechanism, which is
-essentially just a variety of C<eval()>.  Has semantics similar to the following
+essentially just a variety of C<eval>.  Has semantics similar to the following
 subroutine:
 
     sub require {
@@ -3176,10 +3249,10 @@ subroutine:
     }
 
 Note that the file will not be included twice under the same specified
-name.  The file must return TRUE as the last statement to indicate
+name.  The file must return true as the last statement to indicate
 successful execution of any initialization code, so it's customary to
-end such a file with "C<1;>" unless you're sure it'll return TRUE
-otherwise.  But it's better just to put the "C<1;>", in case you add more
+end such a file with C<1;> unless you're sure it'll return true
+otherwise.  But it's better just to put the C<1;>, in case you add more
 statements.
 
 If EXPR is a bareword, the require assumes a "F<.pm>" extension and
@@ -3202,7 +3275,7 @@ But if you try this:
         require "Foo::Bar";  # not a bareword because of the ""
 
 The require function will look for the "F<Foo::Bar>" file in the @INC array and 
-will complain about not finding "F<Foo::Bar>" there. In this case you can do:
+will complain about not finding "F<Foo::Bar>" there.  In this case you can do:
 
         eval "require $class";
 
@@ -3235,10 +3308,10 @@ See L</my>.
 
 =item return
 
-Returns from a subroutine, C<eval()>, or C<do FILE> with the value 
+Returns from a subroutine, C<eval>, or C<do FILE> with the value 
 given in EXPR.  Evaluation of EXPR may be in list, scalar, or void
 context, depending on how the return value will be used, and the context
-may vary from one execution to the next (see C<wantarray()>).  If no EXPR
+may vary from one execution to the next (see C<wantarray>).  If no EXPR
 is given, returns an empty list in list context, the undefined value in
 scalar context, and (of course) nothing at all in a void context.
 
@@ -3269,7 +3342,7 @@ on a large hash, such as from a DBM file.
 =item rewinddir DIRHANDLE
 
 Sets the current position to the beginning of the directory for the
-C<readdir()> routine on DIRHANDLE.
+C<readdir> routine on DIRHANDLE.
 
 =item rindex STR,SUBSTR,POSITION
 
@@ -3284,7 +3357,7 @@ last occurrence at or before that position.
 =item rmdir
 
 Deletes the directory specified by FILENAME if that directory is empty.  If it
-succeeds it returns TRUE, otherwise it returns FALSE and sets C<$!> (errno).  If
+succeeds it returns true, otherwise it returns false and sets C<$!> (errno).  If
 FILENAME is omitted, uses C<$_>.
 
 =item s///
@@ -3304,7 +3377,7 @@ needed.  If you really wanted to do so, however, you could use
 the construction C<@{[ (some expression) ]}>, but usually a simple
 C<(some expression)> suffices.
 
-Wince C<scalar> is unary operator, if you accidentally use for EXPR a
+Because C<scalar> is unary operator, if you accidentally use for EXPR a
 parenthesized list, this behaves as a scalar comma expression, evaluating
 all but the last element in void context and returning the final element
 evaluated in scalar context.  This is seldom what you want.
@@ -3322,7 +3395,7 @@ See L<perlop> for more details on unary operators and the comma operator.
 
 =item seek FILEHANDLE,POSITION,WHENCE
 
-Sets FILEHANDLE's position, just like the C<fseek()> call of C<stdio()>.
+Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
 FILEHANDLE may be an expression whose value gives the name of the
 filehandle.  The values for WHENCE are C<0> to set the new position to
 POSITION, C<1> to set it to the current position plus POSITION, and C<2> to
@@ -3330,9 +3403,9 @@ set it to EOF plus POSITION (typically negative).  For WHENCE you may
 use the constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END> from either the
 C<IO::Seekable> or the POSIX module.  Returns C<1> upon success, C<0> otherwise.
 
-If you want to position file for C<sysread()> or C<syswrite()>, don't use
-C<seek()> -- buffering makes its effect on the file's system position
-unpredictable and non-portable.  Use C<sysseek()> instead.
+If you want to position file for C<sysread> or C<syswrite>, don't use
+C<seek>--buffering makes its effect on the file's system position
+unpredictable and non-portable.  Use C<sysseek> instead.
 
 Due to the rules and rigors of ANSI C, on some systems you have to do a
 seek whenever you switch between reading and writing.  Amongst other
@@ -3343,7 +3416,7 @@ A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving the file position:
 
 This is also useful for applications emulating C<tail -f>.  Once you hit
 EOF on your read, and then sleep for a while, you might have to stick in a
-seek() to reset things.  The C<seek()> doesn't change the current position,
+seek() to reset things.  The C<seek> doesn't change the current position,
 but it I<does> clear the end-of-file condition on the handle, so that the
 next C<E<lt>FILEE<gt>> makes Perl try again to read something.  We hope.
 
@@ -3361,8 +3434,8 @@ you may need something more like this:
 
 =item seekdir DIRHANDLE,POS
 
-Sets the current position for the C<readdir()> routine on DIRHANDLE.  POS
-must be a value returned by C<telldir()>.  Has the same caveats about
+Sets the current position for the C<readdir> routine on DIRHANDLE.  POS
+must be a value returned by C<telldir>.  Has the same caveats about
 possible directory compaction as the corresponding system library
 routine.
 
@@ -3372,7 +3445,7 @@ routine.
 
 Returns the currently selected filehandle.  Sets the current default
 filehandle for output, if FILEHANDLE is supplied.  This has two
-effects: first, a C<write()> or a C<print()> without a filehandle will
+effects: first, a C<write> or a C<print> without a filehandle will
 default to this FILEHANDLE.  Second, references to variables related to
 output will refer to this output channel.  For example, if you have to
 set the top of form format for more than one output channel, you might
@@ -3397,7 +3470,7 @@ methods, preferring to write the last example as:
 =item select RBITS,WBITS,EBITS,TIMEOUT
 
 This calls the select(2) system call with the bit masks specified, which
-can be constructed using C<fileno()> and C<vec()>, along these lines:
+can be constructed using C<fileno> and C<vec>, along these lines:
 
     $rin = $win = $ein = '';
     vec($rin,fileno(STDIN),1) = 1;
@@ -3426,32 +3499,32 @@ or to block until something becomes ready just do this
 
     $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
 
-Most systems do not bother to return anything useful in C<$timeleft>, so
-calling select() in scalar context just returns C<$nfound>.
+Most systems do not bother to return anything useful in $timeleft, so
+calling select() in scalar context just returns $nfound.
 
 Any of the bit masks can also be undef.  The timeout, if specified, is
 in seconds, which may be fractional.  Note: not all implementations are
-capable of returning theC<$timeleft>.  If not, they always return
-C<$timeleft> equal to the supplied C<$timeout>.
+capable of returning the$timeleft.  If not, they always return
+$timeleft equal to the supplied $timeout.
 
 You can effect a sleep of 250 milliseconds this way:
 
     select(undef, undef, undef, 0.25);
 
-B<WARNING>: One should not attempt to mix buffered I/O (like C<read()>
-or E<lt>FHE<gt>) with C<select()>, except as permitted by POSIX, and even
-then only on POSIX systems.  You have to use C<sysread()> instead.
+B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
+or E<lt>FHE<gt>) with C<select>, except as permitted by POSIX, and even
+then only on POSIX systems.  You have to use C<sysread> instead.
 
 =item semctl ID,SEMNUM,CMD,ARG
 
-Calls the System V IPC function C<semctl()>.  You'll probably have to say
+Calls the System V IPC function C<semctl>.  You'll probably have to say
 
     use IPC::SysV;
 
 first to get the correct constant definitions.  If CMD is IPC_STAT or
 GETALL, then ARG must be a variable which will hold the returned
-semid_ds structure or semaphore value array.  Returns like C<ioctl()>: the
-undefined value for error, "C<0> but true" for zero, or the actual return
+semid_ds structure or semaphore value array.  Returns like C<ioctl>: the
+undefined value for error, "C<0 but true>" for zero, or the actual return
 value otherwise.  See also C<IPC::SysV> and C<IPC::Semaphore> documentation.
 
 =item semget KEY,NSEMS,FLAGS
@@ -3466,9 +3539,9 @@ Calls the System V IPC function semop to perform semaphore operations
 such as signaling and waiting.  OPSTRING must be a packed array of
 semop structures.  Each semop structure can be generated with
 C<pack("sss", $semnum, $semop, $semflag)>.  The number of semaphore
-operations is implied by the length of OPSTRING.  Returns TRUE if
-successful, or FALSE if there is an error.  As an example, the
-following code waits on semaphore C<$semnum> of semaphore id C<$semid>:
+operations is implied by the length of OPSTRING.  Returns true if
+successful, or false if there is an error.  As an example, the
+following code waits on semaphore $semnum of semaphore id $semid:
 
     $semop = pack("sss", $semnum, -1, 0);
     die "Semaphore trouble: $!\n" unless semop($semid, $semop);
@@ -3482,7 +3555,7 @@ and C<IPC::SysV::Semaphore> documentation.
 
 Sends a message on a socket.  Takes the same flags as the system call
 of the same name.  On unconnected sockets you must specify a
-destination to send TO, in which case it does a C C<sendto()>.  Returns
+destination to send TO, in which case it does a C C<sendto>.  Returns
 the number of characters sent, or the undefined value if there is an
 error.  The C system call sendmsg(2) is currently unimplemented.
 See L<perlipc/"UDP: Message Passing"> for examples.
@@ -3492,7 +3565,7 @@ See L<perlipc/"UDP: Message Passing"> for examples.
 Sets the current process group for the specified PID, C<0> for the current
 process.  Will produce a fatal error if used on a machine that doesn't
 implement setpgrp(2).  If the arguments are omitted, it defaults to
-C<0,0>.  Note that the POSIX version of C<setpgrp()> does not accept any
+C<0,0>.  Note that the POSIX version of C<setpgrp> does not accept any
 arguments, so only C<setpgrp(0,0)> is portable.  See also C<POSIX::setsid()>.
 
 =item setpriority WHICH,WHO,PRIORITY
@@ -3517,8 +3590,8 @@ array, returns the undefined value.  If ARRAY is omitted, shifts the
 C<@_> array within the lexical scope of subroutines and formats, and the
 C<@ARGV> array at file scopes or within the lexical scopes established by
 the C<eval ''>, C<BEGIN {}>, C<END {}>, and C<INIT {}> constructs.
-See also C<unshift()>, C<push()>, and C<pop()>.  C<Shift()> and C<unshift()> do the
-same thing to the left end of an array that C<pop()> and C<push()> do to the
+See also C<unshift>, C<push>, and C<pop>.  C<Shift()> and C<unshift> do the
+same thing to the left end of an array that C<pop> and C<push> do to the
 right end.
 
 =item shmctl ID,CMD,ARG
@@ -3548,7 +3621,7 @@ position POS for size SIZE by attaching to it, copying in/out, and
 detaching from it.  When reading, VAR must be a variable that will
 hold the data read.  When writing, if STRING is too long, only SIZE
 bytes are used; if STRING is too short, nulls are written to fill out
-SIZE bytes.  Return TRUE if successful, or FALSE if there is an error.
+SIZE bytes.  Return true if successful, or false if there is an error.
 See also C<IPC::SysV> documentation and the C<IPC::Shareable> module
 from CPAN.
 
@@ -3564,7 +3637,7 @@ has the same interpretation as in the system call of the same name.
 This is useful with sockets when you want to tell the other
 side you're done writing but not done reading, or vice versa.
 It's also a more insistent form of close because it also 
-disables the filedescriptor in any forked copies in other
+disables the file descriptor in any forked copies in other
 processes.
 
 =item sin EXPR
@@ -3574,7 +3647,7 @@ processes.
 Returns the sine of EXPR (expressed in radians).  If EXPR is omitted,
 returns sine of C<$_>.
 
-For the inverse sine operation, you may use the C<POSIX::asin()>
+For the inverse sine operation, you may use the C<POSIX::asin>
 function, or use this relation:
 
     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
@@ -3586,8 +3659,8 @@ function, or use this relation:
 Causes the script to sleep for EXPR seconds, or forever if no EXPR.
 May be interrupted if the process receives a signal such as C<SIGALRM>.
 Returns the number of seconds actually slept.  You probably cannot
-mix C<alarm()> and C<sleep()> calls, because C<sleep()> is often implemented
-using C<alarm()>.
+mix C<alarm> and C<sleep> calls, because C<sleep> is often implemented
+using C<alarm>.
 
 On some older systems, it may sleep up to a full second less than what
 you requested, depending on how it counts seconds.  Most modern systems
@@ -3596,26 +3669,27 @@ however, because your process might not be scheduled right away in a
 busy multitasking system.
 
 For delays of finer granularity than one second, you may use Perl's
-C<syscall()> interface to access setitimer(2) if your system supports it,
+C<syscall> interface to access setitimer(2) if your system supports it,
 or else see L</select> above.
 
-See also the POSIX module's C<sigpause()> function.
+See also the POSIX module's C<sigpause> function.
 
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 
 Opens a socket of the specified kind and attaches it to filehandle
-SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for the
-system call of the same name.  You should "C<use Socket;>" first to get
-the proper definitions imported.  See the examples in L<perlipc/"Sockets: Client/Server Communication">.
+SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
+the system call of the same name.  You should C<use Socket> first
+to get the proper definitions imported.  See the examples in
+L<perlipc/"Sockets: Client/Server Communication">.
 
 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
 
 Creates an unnamed pair of sockets in the specified domain, of the
 specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
 for the system call of the same name.  If unimplemented, yields a fatal
-error.  Returns TRUE if successful.
+error.  Returns true if successful.
 
-Some systems defined C<pipe()> in terms of C<socketpair()>, in which a call
+Some systems defined C<pipe> in terms of C<socketpair>, in which a call
 to C<pipe(Rdr, Wtr)> is essentially:
 
     use Socket;
@@ -3632,10 +3706,10 @@ See L<perlipc> for an example of socketpair use.
 =item sort LIST
 
 Sorts the LIST and returns the sorted list value.  If SUBNAME or BLOCK
-is omitted, C<sort()>s in standard string comparison order.  If SUBNAME is
+is omitted, C<sort>s in standard string comparison order.  If SUBNAME is
 specified, it gives the name of a subroutine that returns an integer
 less than, equal to, or greater than C<0>, depending on how the elements
-of the array are to be ordered.  (The C<E<lt>=E<gt>> and C<cmp>
+of the list are to be ordered.  (The C<E<lt>=E<gt>> and C<cmp>
 operators are extremely useful in such routines.)  SUBNAME may be a
 scalar variable name (unsubscripted), in which case the value provides
 the name of (or a reference to) the actual subroutine to use.  In place
@@ -3645,12 +3719,12 @@ subroutine.
 In the interests of efficiency the normal calling code for subroutines is
 bypassed, with the following effects: the subroutine may not be a
 recursive subroutine, and the two elements to be compared are passed into
-the subroutine not via C<@_> but as the package global variables C<$a> and
-C<$b> (see example below).  They are passed by reference, so don't
-modify C<$a> and C<$b>.  And don't try to declare them as lexicals either.
+the subroutine not via C<@_> but as the package global variables $a and
+$b (see example below).  They are passed by reference, so don't
+modify $a and $b.  And don't try to declare them as lexicals either.
 
 You also cannot exit out of the sort block or subroutine using any of the
-loop control operators described in L<perlsyn> or with C<goto()>.
+loop control operators described in L<perlsyn> or with C<goto>.
 
 When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
 current collation locale.  See L<perllocale>.
@@ -3675,19 +3749,19 @@ Examples:
     # sort numerically descending
     @articles = sort {$b <=> $a} @files;
 
+    # this sorts the %age hash by value instead of key
+    # using an in-line function
+    @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
+
     # sort using explicit subroutine name
     sub byage {
        $age{$a} <=> $age{$b};  # presuming numeric
     }
     @sortedclass = sort byage @class;
 
-    # this sorts the %age hash by value instead of key
-    # using an in-line function
-    @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
-
-    sub backwards { $b cmp $a; }
-    @harry = ('dog','cat','x','Cain','Abel');
-    @george = ('gone','chased','yz','Punished','Axed');
+    sub backwards { $b cmp $a }
+    @harry  = qw(dog cat x Cain Abel);
+    @george = qw(gone chased yz Punished Axed);
     print sort @harry;
            # prints AbelCaincatdogx
     print sort backwards @harry;
@@ -3721,15 +3795,15 @@ Examples:
                       } 0..$#old
               ];
 
-    # same thing using a Schwartzian Transform (no temps)
+    # same thing, but without any temps
     @new = map { $_->[0] }
-        sort { $b->[1] <=> $a->[1]
-                        ||
-               $a->[2] cmp $b->[2]
-        } map { [$_, /=(\d+)/, uc($_)] } @old;
+           sort { $b->[1] <=> $a->[1]
+                           ||
+                  $a->[2] cmp $b->[2]
+           } map { [$_, /=(\d+)/, uc($_)] } @old;
 
-If you're using strict, you I<MUST NOT> declare C<$a>
-and C<$b> as lexicals.  They are package globals.  That means
+If you're using strict, you I<must not> declare $a
+and $b as lexicals.  They are package globals.  That means
 if you're in the C<main> package, it's
 
     @articles = sort {$main::b <=> $main::a} @files;
@@ -3758,7 +3832,7 @@ replaces them with the elements of LIST, if any.  In list context,
 returns the elements removed from the array.  In scalar context,
 returns the last element removed, or C<undef> if no elements are
 removed.  The array grows or shrinks as necessary.
-If OFFSET is negative then it start that far from the end of the array.
+If OFFSET is negative then it starts that far from the end of the array.
 If LENGTH is omitted, removes everything from OFFSET onward.
 If LENGTH is negative, leave that many elements off the end of the array.
 The following equivalences hold (assuming C<$[ == 0>):
@@ -3790,7 +3864,7 @@ Example, assuming array lengths are passed before arrays:
 
 =item split
 
-Splits a string into an array of strings, and returns it.  By default,
+Splits a string into a list of strings and returns that list.  By default,
 empty leading fields are preserved, and empty trailing ones are deleted.
 
 If not in list context, returns the number of fields found and splits into
@@ -3807,7 +3881,7 @@ that the delimiter may be longer than one character.)
 If LIMIT is specified and positive, splits into no more than that
 many fields (though it may split into fewer).  If LIMIT is unspecified
 or zero, trailing null fields are stripped (which potential users
-of C<pop()> would do well to remember).  If LIMIT is negative, it is
+of C<pop> would do well to remember).  If LIMIT is negative, it is
 treated as if an arbitrarily large LIMIT had been specified.
 
 A pattern matching the null string (not to be confused with
@@ -3829,7 +3903,7 @@ unnecessary work.  For the list above LIMIT would have been 4 by
 default.  In time critical applications it behooves you not to split
 into more fields than you really need.
 
-If the PATTERN contains parentheses, additional array elements are
+If the PATTERN contains parentheses, additional list elements are
 created from each matching substring in the delimiter.
 
     split(/([,-])/, "1-10,20", 3);
@@ -3838,7 +3912,7 @@ produces the list value
 
     (1, '-', 10, ',', 20)
 
-If you had the entire header of a normal Unix email message in C<$header>,
+If you had the entire header of a normal Unix email message in $header,
 you could split it up into fields and their values this way:
 
     $header =~ s/\n\s+/ /g;  # fix continuation lines
@@ -3849,11 +3923,11 @@ patterns that vary at runtime.  (To do runtime compilation only once,
 use C</$variable/o>.)
 
 As a special case, specifying a PATTERN of space (C<' '>) will split on
-white space just as C<split()> with no arguments does.  Thus, C<split(' ')> can
+white space just as C<split> with no arguments does.  Thus, C<split(' ')> can
 be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
 will give you as many null initial fields as there are leading spaces.
-A C<split()> on C</\s+/> is like a C<split(' ')> except that any leading
-whitespace produces a null first field.  A C<split()> with no arguments
+A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
+whitespace produces a null first field.  A C<split> with no arguments
 really does a C<split(' ', $_)> internally.
 
 Example:
@@ -3865,22 +3939,22 @@ Example:
        #...
     }
 
-(Note that C<$shell> above will still have a newline on it.  See L</chop>,
+(Note that $shell above will still have a newline on it.  See L</chop>,
 L</chomp>, and L</join>.)
 
 =item sprintf FORMAT, LIST
 
-Returns a string formatted by the usual C<printf()> conventions of the
-C library function C<sprintf()>.  See L<sprintf(3)> or L<printf(3)>
+Returns a string formatted by the usual C<printf> conventions of the
+C library function C<sprintf>.  See L<sprintf(3)> or L<printf(3)>
 on your system for an explanation of the general principles.
 
-Perl does its own C<sprintf()> formatting -- it emulates the C
-function C<sprintf()>, but it doesn't use it (except for floating-point
+Perl does its own C<sprintf> formatting--it emulates the C
+function C<sprintf>, but it doesn't use it (except for floating-point
 numbers, and even then only the standard modifiers are allowed).  As a
-result, any non-standard extensions in your local C<sprintf()> are not
+result, any non-standard extensions in your local C<sprintf> are not
 available from Perl.
 
-Perl's C<sprintf()> permits the following universally-known conversions:
+Perl's C<sprintf> permits the following universally-known conversions:
 
    %%  a percent sign
    %c  a character with the given number
@@ -3931,11 +4005,11 @@ There is also one Perl-specific flag:
 
    V       interpret integer as Perl's standard integer type
 
-Where a number would appear in the flags, an asterisk ("C<*>") may be
+Where a number would appear in the flags, an asterisk (C<*>) may be
 used instead, in which case Perl uses the next item in the parameter
 list as the given number (that is, as the field width or precision).
-If a field width obtained through "C<*>" is negative, it has the same
-effect as the "C<->" flag: left-justification.
+If a field width obtained through C<*> is negative, it has the same
+effect as the C<-> flag: left-justification.
 
 If C<use locale> is in effect, the character used for the decimal
 point in formatted real numbers is affected by the LC_NUMERIC locale.
@@ -3956,19 +4030,19 @@ loaded the standard Math::Complex module.
 
 =item srand
 
-Sets the random number seed for the C<rand()> operator.  If EXPR is
+Sets the random number seed for the C<rand> operator.  If EXPR is
 omitted, uses a semi-random value supplied by the kernel (if it supports
 the F</dev/urandom> device) or based on the current time and process
 ID, among other things.  In versions of Perl prior to 5.004 the default
-seed was just the current C<time()>.  This isn't a particularly good seed,
+seed was just the current C<time>.  This isn't a particularly good seed,
 so many old programs supply their own seed value (often C<time ^ $$> or
 C<time ^ ($$ + ($$ E<lt>E<lt> 15))>), but that isn't necessary any more.
 
-In fact, it's usually not necessary to call C<srand()> at all, because if
+In fact, it's usually not necessary to call C<srand> at all, because if
 it is not called explicitly, it is called implicitly at the first use of
-the C<rand()> operator.  However, this was not the case in version of Perl
+the C<rand> operator.  However, this was not the case in version of Perl
 before 5.004, so if your script will run under older Perl versions, it
-should call C<srand()>.
+should call C<srand>.
 
 Note that you need something much more random than the default seed for
 cryptographic purposes.  Checksumming the compressed output of one or more
@@ -3980,11 +4054,11 @@ example:
 If you're particularly concerned with this, see the C<Math::TrulyRandom>
 module in CPAN.
 
-Do I<not> call C<srand()> multiple times in your program unless you know
+Do I<not> call C<srand> multiple times in your program unless you know
 exactly what you're doing and why you're doing it.  The point of the
-function is to "seed" the C<rand()> function so that C<rand()> can produce
+function is to "seed" the C<rand> function so that C<rand> can produce
 a different sequence each time you run your program.  Just do it once at the
-top of your program, or you I<won't> get random numbers out of C<rand()>!
+top of your program, or you I<won't> get random numbers out of C<rand>!
 
 Frequently called programs (like CGI scripts) that simply use
 
@@ -4047,8 +4121,7 @@ if you want to see the real permissions.
     $mode = (stat($filename))[2];
     printf "Permissions are %04o\n", $mode & 07777;
 
-
-In scalar context, C<stat()> returns a boolean value indicating success
+In scalar context, C<stat> returns a boolean value indicating success
 or failure, and, if successful, sets the information associated with
 the special filehandle C<_>.
 
@@ -4068,12 +4141,12 @@ Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
 doing many pattern matches on the string before it is next modified.
 This may or may not save time, depending on the nature and number of
 patterns you are searching on, and on the distribution of character
-frequencies in the string to be searched -- you probably want to compare
+frequencies in the string to be searched--you probably want to compare
 run times with and without it to see which runs faster.  Those loops
 which scan for many short constant strings (including the constant
 parts of more complex patterns) will benefit most.  You may have only
-one C<study()> active at a time -- if you study a different scalar the first
-is "unstudied".  (The way C<study()> works is this: a linked list of every
+one C<study> active at a time--if you study a different scalar the first
+is "unstudied".  (The way C<study> works is this: a linked list of every
 character in the string to be searched is made, so we know, for
 example, where all the C<'k'> characters are.  From each search string,
 the rarest character is selected, based on some static frequency tables
@@ -4099,7 +4172,7 @@ it saves you more time than it took to build the linked list in the
 first place.
 
 Note that if you have to look for strings that you don't know till
-runtime, you can build an entire loop as a string and C<eval()> that to
+runtime, you can build an entire loop as a string and C<eval> that to
 avoid recompiling all your patterns all the time.  Together with
 undefining C<$/> to input entire files as one record, this can be very
 fast, often faster than specialized programs like fgrep(1).  The following
@@ -4152,7 +4225,7 @@ You can use the substr() function as an lvalue, in which case EXPR
 must itself be an lvalue.  If you assign something shorter than LEN,
 the string will shrink, and if you assign something longer than LEN,
 the string will grow to accommodate it.  To keep the string the same
-length you may need to pad or chop your value using C<sprintf()>.
+length you may need to pad or chop your value using C<sprintf>.
 
 An alternative to using substr() as an lvalue is to specify the
 replacement string as the 4th argument.  This allows you to replace
@@ -4177,12 +4250,12 @@ as follows: if a given argument is numeric, the argument is passed as
 an int.  If not, the pointer to the string value is passed.  You are
 responsible to make sure a string is pre-extended long enough to
 receive any result that might be written into a string.  You can't use a
-string literal (or other read-only string) as an argument to C<syscall()>
+string literal (or other read-only string) as an argument to C<syscall>
 because Perl has to assume that any string pointer might be written
 through.  If your
 integer arguments are not literals and have never been interpreted in a
 numeric context, you may need to add C<0> to them to force them to look
-like numbers.  This emulates the C<syswrite()> function (or vice versa):
+like numbers.  This emulates the C<syswrite> function (or vice versa):
 
     require 'syscall.ph';              # may need to run h2ph
     $s = "hi there\n";
@@ -4192,7 +4265,7 @@ Note that Perl supports passing of up to only 14 arguments to your system call,
 which in practice should usually suffice.
 
 Syscall returns whatever value returned by the system call it calls.
-If the system call fails, C<syscall()> returns C<-1> and sets C<$!> (errno).
+If the system call fails, C<syscall> returns C<-1> and sets C<$!> (errno).
 Note that some system calls can legitimately return C<-1>.  The proper
 way to handle such calls is to assign C<$!=0;> before the call and
 check the value of C<$!> if syscall returns C<-1>.
@@ -4200,7 +4273,7 @@ check the value of C<$!> if syscall returns C<-1>.
 There's a problem with C<syscall(&SYS_pipe)>: it returns the file
 number of the read end of the pipe it creates.  There is no way
 to retrieve the file number of the other end.  You can avoid this 
-problem by using C<pipe()> instead.
+problem by using C<pipe> instead.
 
 =item sysopen FILEHANDLE,FILENAME,MODE
 
@@ -4209,7 +4282,7 @@ problem by using C<pipe()> instead.
 Opens the file whose filename is given by FILENAME, and associates it
 with FILEHANDLE.  If FILEHANDLE is an expression, its value is used as
 the name of the real filehandle wanted.  This function calls the
-underlying operating system's C<open()> function with the parameters
+underlying operating system's C<open> function with the parameters
 FILENAME, MODE, PERMS.
 
 The possible values and flag bits of the MODE parameter are
@@ -4220,14 +4293,14 @@ means read/write.  We know that these values do I<not> work under
 OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
 use them in new code.
 
-If the file named by FILENAME does not exist and the C<open()> call creates
+If the file named by FILENAME does not exist and the C<open> call creates
 it (typically because MODE includes the C<O_CREAT> flag), then the value of
 PERMS specifies the permissions of the newly created file.  If you omit
-the PERMS argument to C<sysopen()>, Perl uses the octal value C<0666>.
+the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
 These permission values need to be in octal, and are modified by your
 process's current C<umask>.
 
-You should seldom if ever use C<0644> as argument to C<sysopen()>, because
+You should seldom if ever use C<0644> as argument to C<sysopen>, because
 that takes away the user's option to have a more permissive umask.
 Better to omit it.  See the perlfunc(1) entry on C<umask> for more
 on this.
@@ -4240,8 +4313,8 @@ See L<perlopentut> for a kinder, gentler explanation of opening files.
 
 Attempts to read LENGTH bytes of data into variable SCALAR from the
 specified FILEHANDLE, using the system call read(2).  It bypasses stdio,
-so mixing this with other kinds of reads, C<print()>, C<write()>,
-C<seek()>, C<tell()>, or C<eof()> can cause confusion because stdio
+so mixing this with other kinds of reads, C<print>, C<write>,
+C<seek>, C<tell>, or C<eof> can cause confusion because stdio
 usually buffers data.  Returns the number of bytes actually read, C<0>
 at end of file, or undef if there was an error.  SCALAR will be grown or
 shrunk so that the last byte actually read is the last byte of the
@@ -4256,13 +4329,13 @@ the result of the read is appended.
 
 There is no syseof() function, which is ok, since eof() doesn't work
 very well on device files (like ttys) anyway.  Use sysread() and check
-ofr a return value for 0 to decide whether you're done.
+for a return value for 0 to decide whether you're done.
 
 =item sysseek FILEHANDLE,POSITION,WHENCE
 
 Sets FILEHANDLE's system position using the system call lseek(2).  It
-bypasses stdio, so mixing this with reads (other than C<sysread()>),
-C<print()>, C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause
+bypasses stdio, so mixing this with reads (other than C<sysread>),
+C<print>, C<write>, C<seek>, C<tell>, or C<eof> may cause
 confusion.  FILEHANDLE may be an expression whose value gives the name
 of the filehandle.  The values for WHENCE are C<0> to set the new
 position to POSITION, C<1> to set the it to the current position plus
@@ -4271,37 +4344,40 @@ For WHENCE, you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and
 C<SEEK_END> from either the C<IO::Seekable> or the POSIX module.
 
 Returns the new position, or the undefined value on failure.  A position
-of zero is returned as the string "C<0> but true"; thus C<sysseek()> returns
-TRUE on success and FALSE on failure, yet you can still easily determine
+of zero is returned as the string C<"0 but true">; thus C<sysseek> returns
+true on success and false on failure, yet you can still easily determine
 the new position.
 
 =item system LIST
 
 =item system PROGRAM LIST
 
-Does exactly the same thing as "C<exec LIST>", except that a fork is done
-first, and the parent process waits for the child process to complete.
-Note that argument processing varies depending on the number of
-arguments.  If there is more than one argument in LIST, or if LIST is
-an array with more than one value, starts the program given by the
-first element of the list with arguments given by the rest of the list.
-If there is only one scalar argument, the argument is
-checked for shell metacharacters, and if there are any, the entire
-argument is passed to the system's command shell for parsing (this is
-C</bin/sh -c> on Unix platforms, but varies on other platforms).  If
-there are no shell metacharacters in the argument, it is split into
-words and passed directly to C<execvp()>, which is more efficient.
+Does exactly the same thing as C<exec LIST>, except that a fork is
+done first, and the parent process waits for the child process to
+complete.  Note that argument processing varies depending on the
+number of arguments.  If there is more than one argument in LIST,
+or if LIST is an array with more than one value, starts the program
+given by the first element of the list with arguments given by the
+rest of the list.  If there is only one scalar argument, the argument
+is checked for shell metacharacters, and if there are any, the
+entire argument is passed to the system's command shell for parsing
+(this is C</bin/sh -c> on Unix platforms, but varies on other
+platforms).  If there are no shell metacharacters in the argument,
+it is split into words and passed directly to C<execvp>, which is
+more efficient.
+
+All files opened for output are flushed before attempting the exec().
 
 The return value is the exit status of the program as
-returned by the C<wait()> call.  To get the actual exit value divide by
-256.  See also L</exec>.  This is I<NOT> what you want to use to capture
+returned by the C<wait> call.  To get the actual exit value divide by
+256.  See also L</exec>.  This is I<not> what you want to use to capture
 the output from a command, for that you should use merely backticks or
 C<qx//>, as described in L<perlop/"`STRING`">.
 
-Like C<exec()>, C<system()> allows you to lie to a program about its name if
-you use the "C<system PROGRAM LIST>" syntax.  Again, see L</exec>.
+Like C<exec>, C<system> allows you to lie to a program about its name if
+you use the C<system PROGRAM LIST> syntax.  Again, see L</exec>.
 
-Because C<system()> and backticks block C<SIGINT> and C<SIGQUIT>, killing the
+Because C<system> and backticks block C<SIGINT> and C<SIGQUIT>, killing the
 program they're running doesn't actually interrupt your program.
 
     @args = ("command", "arg1", "arg2");
@@ -4326,14 +4402,14 @@ See L<perlop/"`STRING`"> and L</exec> for details.
 =item syswrite FILEHANDLE,SCALAR
 
 Attempts to write LENGTH bytes of data from variable SCALAR to the
-specified FILEHANDLE, using the system call write(2).  If LENGTH is
-not specified, writes whole SCALAR. It bypasses
-stdio, so mixing this with reads (other than C<sysread())>, C<print()>,
-C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause confusion
-because stdio usually buffers data.  Returns the number of bytes
-actually written, or C<undef> if there was an error.  If the LENGTH is
-greater than the available data in the SCALAR after the OFFSET, only as
-much data as is available will be written.
+specified FILEHANDLE, using the system call write(2).  If LENGTH
+is not specified, writes whole SCALAR.  It bypasses stdio, so mixing
+this with reads (other than C<sysread())>, C<print>, C<write>,
+C<seek>, C<tell>, or C<eof> may cause confusion because stdio
+usually buffers data.  Returns the number of bytes actually written,
+or C<undef> if there was an error.  If the LENGTH is greater than
+the available data in the SCALAR after the OFFSET, only as much
+data as is available will be written.
 
 An OFFSET may be specified to write the data from some part of the
 string other than the beginning.  A negative OFFSET specifies writing
@@ -4348,12 +4424,12 @@ Returns the current position for FILEHANDLE.  FILEHANDLE may be an
 expression whose value gives the name of the actual filehandle.  If
 FILEHANDLE is omitted, assumes the file last read.  
 
-There is no C<systell()> function.  Use C<sysseek(FH, 0, 1)> for that.
+There is no C<systell> function.  Use C<sysseek(FH, 0, 1)> for that.
 
 =item telldir DIRHANDLE
 
-Returns the current position of the C<readdir()> routines on DIRHANDLE.
-Value may be given to C<seekdir()> to access a particular location in a
+Returns the current position of the C<readdir> routines on DIRHANDLE.
+Value may be given to C<seekdir> to access a particular location in a
 directory.  Has the same caveats about possible directory compaction as
 the corresponding system library routine.
 
@@ -4362,16 +4438,16 @@ the corresponding system library routine.
 This function binds a variable to a package class that will provide the
 implementation for the variable.  VARIABLE is the name of the variable
 to be enchanted.  CLASSNAME is the name of a class implementing objects
-of correct type.  Any additional arguments are passed to the "C<new()>"
+of correct type.  Any additional arguments are passed to the C<new>
 method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
 or C<TIEHASH>).  Typically these are arguments such as might be passed
-to the C<dbm_open()> function of C.  The object returned by the "C<new()>"
-method is also returned by the C<tie()> function, which would be useful
+to the C<dbm_open()> function of C.  The object returned by the C<new>
+method is also returned by the C<tie> function, which would be useful
 if you want to access other methods in CLASSNAME.
 
-Note that functions such as C<keys()> and C<values()> may return huge lists
+Note that functions such as C<keys> and C<values> may return huge lists
 when used on large objects, like DBM files.  You may prefer to use the
-C<each()> function to iterate over such.  Example:
+C<each> function to iterate over such.  Example:
 
     # print out history file offsets
     use NDBM_File;
@@ -4431,16 +4507,16 @@ A class implementing a scalar should have the following methods:
 Not all methods indicated above need be implemented.  See L<perltie>,
 L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>.
 
-Unlike C<dbmopen()>, the C<tie()> function will not use or require a module
+Unlike C<dbmopen>, the C<tie> function will not use or require a module
 for you--you need to do that explicitly yourself.  See L<DB_File>
-or the F<Config> module for interesting C<tie()> implementations.
+or the F<Config> module for interesting C<tie> implementations.
 
 For further details see L<perltie>, L<"tied VARIABLE">.
 
 =item tied VARIABLE
 
 Returns a reference to the object underlying VARIABLE (the same value
-that was originally returned by the C<tie()> call that bound the variable
+that was originally returned by the C<tie> call that bound the variable
 to a package.)  Returns the undefined value if VARIABLE isn't tied to a
 package.
 
@@ -4449,7 +4525,7 @@ package.
 Returns the number of non-leap seconds since whatever time the system
 considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
 and 00:00:00 UTC, January 1, 1970 for most other systems).
-Suitable for feeding to C<gmtime()> and C<localtime()>.
+Suitable for feeding to C<gmtime> and C<localtime>.
 
 =item times
 
@@ -4460,7 +4536,7 @@ seconds, for this process and the children of this process.
 
 =item tr///
 
-The transliteration operator.  Same as C<y///>. See L<perlop>.
+The transliteration operator.  Same as C<y///>.  See L<perlop>.
 
 =item truncate FILEHANDLE,LENGTH
 
@@ -4468,7 +4544,7 @@ The transliteration operator.  Same as C<y///>. See L<perlop>.
 
 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
 specified length.  Produces a fatal error if truncate isn't implemented
-on your system.  Returns TRUE if successful, the undefined value
+on your system.  Returns true if successful, the undefined value
 otherwise.
 
 =item uc EXPR
@@ -4479,7 +4555,7 @@ Returns an uppercased version of EXPR.  This is the internal function
 implementing the C<\U> escape in double-quoted strings.
 Respects current LC_CTYPE locale if C<use locale> in force.  See L<perllocale>.
 Under Unicode (C<use utf8>) it uses the standard Unicode uppercase mappings.  (It
-does not attempt to do titlecase mapping on initial letters.  See C<ucfirst()> for that.)
+does not attempt to do titlecase mapping on initial letters.  See C<ucfirst> for that.)
 
 If EXPR is omitted, uses C<$_>.
 
@@ -4511,12 +4587,12 @@ even if you tell C<sysopen> to create a file with permissions C<0777>,
 if your umask is C<0022> then the file will actually be created with
 permissions C<0755>.  If your C<umask> were C<0027> (group can't
 write; others can't read, write, or execute), then passing
-C<sysopen()> C<0666> would create a file with mode C<0640> (C<0666 &~
+C<sysopen> C<0666> would create a file with mode C<0640> (C<0666 &~
 027> is C<0640>).
 
 Here's some advice: supply a creation mode of C<0666> for regular
-files (in C<sysopen()>) and one of C<0777> for directories (in
-C<mkdir()>) and executable files.  This gives users the freedom of
+files (in C<sysopen>) and one of C<0777> for directories (in
+C<mkdir>) and executable files.  This gives users the freedom of
 choice: if they want protected files, they might choose process umasks
 of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
 Programs should rarely if ever make policy decisions better left to
@@ -4537,8 +4613,8 @@ string of octal digits.  See also L</oct>, if all you have is a string.
 =item undef
 
 Undefines the value of EXPR, which must be an lvalue.  Use only on a
-scalar value, an array (using "C<@>"), a hash (using "C<%>"), a subroutine
-(using "C<&>"), or a typeglob (using "<*>").  (Saying C<undef $hash{$key}>
+scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
+(using C<&>), or a typeglob (using <*>).  (Saying C<undef $hash{$key}>
 will probably not do what you expect on most predefined variables or
 DBM list values, so don't do that; see L<delete>.)  Always returns the
 undefined value.  You can omit the EXPR, in which case nothing is
@@ -4569,19 +4645,19 @@ deleted.
     unlink @goners;
     unlink <*.bak>;
 
-Note: C<unlink()> will not delete directories unless you are superuser and
+Note: C<unlink> will not delete directories unless you are superuser and
 the B<-U> flag is supplied to Perl.  Even if these conditions are
 met, be warned that unlinking a directory can inflict damage on your
-filesystem.  Use C<rmdir()> instead.
+filesystem.  Use C<rmdir> instead.
 
 If LIST is omitted, uses C<$_>.
 
 =item unpack TEMPLATE,EXPR
 
-C<Unpack()> does the reverse of C<pack()>: it takes a string representing a
-structure and expands it out into a list value, returning the array
-value.  (In scalar context, it returns merely the first value
-produced.)  The TEMPLATE has the same format as in the C<pack()> function.
+C<unpack> does the reverse of C<pack>: it takes a string
+representing a structure and expands it out into a list of values.
+(In scalar context, it returns merely the first value produced.)
+The TEMPLATE has the same format as in the C<pack> function.
 Here's a subroutine that does substring:
 
     sub substr {
@@ -4598,10 +4674,10 @@ you want a E<lt>numberE<gt>-bit checksum of the items instead of the items
 themselves.  Default is a 16-bit checksum.  For example, the following
 computes the same number as the System V sum program:
 
-    while (<>) {
-       $checksum += unpack("%32C*", $_);
-    }
-    $checksum %= 65535;
+    $checksum = do {
+       local $/;  # slurp!
+       unpack("%32C*",<>) % 65535;
+    };
 
 The following efficiently counts the number of set bits in a bit vector:
 
@@ -4616,18 +4692,18 @@ See L</pack> for more examples.
 
 =item untie VARIABLE
 
-Breaks the binding between a variable and a package.  (See C<tie()>.)
+Breaks the binding between a variable and a package.  (See C<tie>.)
 
 =item unshift ARRAY,LIST
 
-Does the opposite of a C<shift()>.  Or the opposite of a C<push()>,
+Does the opposite of a C<shift>.  Or the opposite of a C<push>,
 depending on how you look at it.  Prepends list to the front of the
 array, and returns the new number of elements in the array.
 
     unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
 
 Note the LIST is prepended whole, not one element at a time, so the
-prepended elements stay in the same order.  Use C<reverse()> to do the
+prepended elements stay in the same order.  Use C<reverse> to do the
 reverse.
 
 =item use Module LIST
@@ -4654,14 +4730,14 @@ Perl version before C<use>ing library modules that have changed in
 incompatible ways from older versions of Perl.  (We try not to do
 this more than we have to.)
 
-The C<BEGIN> forces the C<require> and C<import()> to happen at compile time.  The
+The C<BEGIN> forces the C<require> and C<import> to happen at compile time.  The
 C<require> makes sure the module is loaded into memory if it hasn't been
-yet.  The C<import()> is not a builtin--it's just an ordinary static method
-call into the "C<Module>" package to tell the module to import the list of
+yet.  The C<import> is not a builtin--it's just an ordinary static method
+call into the C<Module> package to tell the module to import the list of
 features back into the current package.  The module can implement its
-C<import()> method any way it likes, though most modules just choose to
-derive their C<import()> method via inheritance from the C<Exporter> class that
-is defined in the C<Exporter> module.  See L<Exporter>.  If no C<import()>
+C<import> method any way it likes, though most modules just choose to
+derive their C<import> method via inheritance from the C<Exporter> class that
+is defined in the C<Exporter> module.  See L<Exporter>.  If no C<import>
 method can be found then the error is currently silently ignored.  This
 may change to a fatal error in a future version.
 
@@ -4689,18 +4765,18 @@ are also implemented this way.  Currently implemented pragmas are:
     use strict  qw(subs vars refs);
     use subs    qw(afunc blurfl);
 
-Some of these these pseudo-modules import semantics into the current
+Some of these pseudo-modules import semantics into the current
 block scope (like C<strict> or C<integer>, unlike ordinary modules,
 which import symbols into the current package (which are effective
 through the end of the file).
 
-There's a corresponding "C<no>" command that unimports meanings imported
-by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import()>.
+There's a corresponding C<no> command that unimports meanings imported
+by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
 
     no integer;
     no strict 'refs';
 
-If no C<unimport()> method can be found the call fails with a fatal error.
+If no C<unimport> method can be found the call fails with a fatal error.
 
 See L<perlmod> for a list of standard modules and pragmas.
 
@@ -4710,7 +4786,7 @@ Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
 and modification times, in that order.  Returns the number of files
 successfully changed.  The inode modification time of each file is set
-to the current time.  This code has the same effect as the "C<touch>"
+to the current time.  This code has the same effect as the C<touch>
 command if the files already exist:
 
     #!/usr/bin/perl
@@ -4723,7 +4799,7 @@ Returns a list consisting of all the values of the named hash.  (In a
 scalar context, returns the number of values.)  The values are
 returned in an apparently random order.  The actual random order is
 subject to change in future versions of perl, but it is guaranteed to
-be the same order as either the C<keys()> or C<each()> function would
+be the same order as either the C<keys> or C<each> function would
 produce on the same (unmodified) hash.
 
 Note that you cannot modify the values of a hash this way, because the
@@ -4734,25 +4810,25 @@ since it's lvaluable in a way that values() is not.
     for (@hash{keys %hash}) { s/foo/bar/g }   # ok
 
 As a side effect, calling values() resets the HASH's internal iterator.
-See also C<keys()>, C<each()>, and C<sort()>.
+See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS
 
 Treats the string in EXPR as a vector of unsigned integers, and
 returns the value of the bit field specified by OFFSET.  BITS specifies
 the number of bits that are reserved for each entry in the bit
-vector.  This must be a power of two from 1 to 32. C<vec()> may also be
+vector.  This must be a power of two from 1 to 32.  C<vec> may also be
 assigned to, in which case parentheses are needed to give the expression
 the correct precedence as in
 
     vec($image, $max_x * $x + $y, 8) = 3;
 
-Vectors created with C<vec()> can also be manipulated with the logical
+Vectors created with C<vec> can also be manipulated with the logical
 operators C<|>, C<&>, and C<^>, which will assume a bit vector operation is
 desired when both operands are strings.  See L<perlop/"Bitwise String Operators">.
 
 The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
-The comments show the string after each step. Note that this code works
+The comments show the string after each step.  Note that this code works
 in the same way on big-endian or little-endian machines.
 
     my $foo = '';
@@ -4769,7 +4845,7 @@ in the same way on big-endian or little-endian machines.
     vec($foo, 94,  1) = 1;             # 'PerlPerlPerl'
                                         # 'l' is "\x6c"
 
-To transform a bit vector into a string or array of 0's and 1's, use these:
+To transform a bit vector into a string or list of 0's and 1's, use these:
 
     $bits = unpack("b*", $vector);
     @bits = split(//, unpack("b*", $vector));
@@ -4780,7 +4856,7 @@ If you know the exact length in bits, it can be used in place of the C<*>.
 
 Behaves like the wait(2) system call on your system: it waits for a child
 process to terminate and returns the pid of the deceased process, or
-C<-1> if there are no child processes.  The status is rketurned in C<$?>.
+C<-1> if there are no child processes.  The status is returned in C<$?>.
 Note that a return value of C<-1> could mean that child processes are
 being automatically reaped, as described in L<perlipc>.
 
@@ -4810,8 +4886,8 @@ and for other examples.
 
 =item wantarray
 
-Returns TRUE if the context of the currently executing subroutine is
-looking for a list value.  Returns FALSE if the context is looking
+Returns true if the context of the currently executing subroutine is
+looking for a list value.  Returns false if the context is looking
 for a scalar.  Returns the undefined value if the context is looking
 for no value (void context).
 
@@ -4819,30 +4895,32 @@ for no value (void context).
     my @a = complex_calculation();
     return wantarray ? @a : "@a";
 
+This function should have been named wantlist() instead.
+
 =item warn LIST
 
-Produces a message on STDERR just like C<die()>, but doesn't exit or throw
+Produces a message on STDERR just like C<die>, but doesn't exit or throw
 an exception.
 
 If LIST is empty and C<$@> already contains a value (typically from a
 previous eval) that value is used after appending C<"\t...caught">
-to C<$@>. This is useful for staying almost, but not entirely similar to
-C<die()>.
+to C<$@>.  This is useful for staying almost, but not entirely similar to
+C<die>.
 
 If C<$@> is empty then the string C<"Warning: Something's wrong"> is used.
 
 No message is printed if there is a C<$SIG{__WARN__}> handler
 installed.  It is the handler's responsibility to deal with the message
-as it sees fit (like, for instance, converting it into a C<die()>).  Most
+as it sees fit (like, for instance, converting it into a C<die>).  Most
 handlers must therefore make arrangements to actually display the
-warnings that they are not prepared to deal with, by calling C<warn()>
+warnings that they are not prepared to deal with, by calling C<warn>
 again in the handler.  Note that this is quite safe and will not
 produce an endless loop, since C<__WARN__> hooks are not called from
 inside one.
 
 You will find this behavior is slightly different from that of
 C<$SIG{__DIE__}> handlers (which don't suppress the error text, but can
-instead call C<die()> again to change it).
+instead call C<die> again to change it).
 
 Using a C<__WARN__> handler provides a powerful way to silence all
 warnings (even the so-called mandatory ones).  An example:
@@ -4871,7 +4949,7 @@ carp() and cluck() functions.
 Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
 using the format associated with that file.  By default the format for
 a file is the one having the same name as the filehandle, but the
-format for the current output channel (see the C<select()> function) may be set
+format for the current output channel (see the C<select> function) may be set
 explicitly by assigning the name of the format to the C<$~> variable.
 
 Top of form processing is handled automatically:  if there is
@@ -4886,11 +4964,11 @@ variable C<$->, which can be set to C<0> to force a new page.
 
 If FILEHANDLE is unspecified, output goes to the current default output
 channel, which starts out as STDOUT but may be changed by the
-C<select()> operator.  If the FILEHANDLE is an EXPR, then the expression
+C<select> operator.  If the FILEHANDLE is an EXPR, then the expression
 is evaluated and the resulting string is used to look up the name of
 the FILEHANDLE at run time.  For more on formats, see L<perlform>.
 
-Note that write is I<NOT> the opposite of C<read()>.  Unfortunately.
+Note that write is I<not> the opposite of C<read>.  Unfortunately.
 
 =item y///
 
index 1492ccf..e687304 100644 (file)
@@ -58,7 +58,7 @@ You may also choose to assign the strings C<'IGNORE'> or C<'DEFAULT'> as
 the handler, in which case Perl will try to discard the signal or do the
 default thing.
 
-On most UNIX platforms, the C<CHLD> (sometimes also known as C<CLD>) signal
+On most Unix platforms, the C<CHLD> (sometimes also known as C<CLD>) signal
 has special behavior with respect to a value of C<'IGNORE'>.
 Setting C<$SIG{CHLD}> to C<'IGNORE'> on such a platform has the effect of
 not creating zombie processes when the parent process fails to C<wait()>
@@ -276,7 +276,7 @@ same effect as opening a pipe for reading:
 
 While this is true on the surface, it's much more efficient to process the
 file one line or record at a time because then you don't have to read the
-whole thing into memory at once. It also gives you finer control of the
+whole thing into memory at once.  It also gives you finer control of the
 whole process, letting you to kill off the child process early if you'd
 like.
 
@@ -1157,7 +1157,7 @@ server. (Under Unix, ports under 1024 are restricted to the
 superuser.)  In our sample, we'll use port 9000, but you can use
 any port that's not currently in use on your system.  If you try
 to use one already in used, you'll get an "Address already in use"
-message. Under Unix, the C<netstat -a> command will show
+message.  Under Unix, the C<netstat -a> command will show
 which services current have servers.
 
 =item Listen
index 56f08c2..f015a20 100644 (file)
@@ -1,62 +1,62 @@
 =head1 NAME
 
-perlLoL - Manipulating Lists of Lists in Perl
+perllol - Manipulating Arrays of Arrays in Perl
 
 =head1 DESCRIPTION
 
-=head1 Declaration and Access of Lists of Lists
+=head1 Declaration and Access of Arrays of Arrays
 
-The simplest thing to build is a list of lists (sometimes called an array
-of arrays).  It's reasonably easy to understand, and almost everything
-that applies here will also be applicable later on with the fancier data
-structures.
+The simplest thing to build an array of arrays (sometimes imprecisely
+called a list of lists).  It's reasonably easy to understand, and
+almost everything that applies here will also be applicable later
+on with the fancier data structures.
 
-A list of lists, or an array of an array if you would, is just a regular
-old array @LoL that you can get at with two subscripts, like C<$LoL[3][2]>.  Here's
-a declaration of the array:
+An array of an array is just a regular old array @AoA that you can
+get at with two subscripts, like C<$AoA[3][2]>.  Here's a declaration
+of the array:
 
-    # assign to our array a list of list references
-    @LoL = (
+    # assign to our array, an array of array references
+    @AoA = (
           [ "fred", "barney" ],
           [ "george", "jane", "elroy" ],
           [ "homer", "marge", "bart" ],
     );
 
-    print $LoL[2][2];
+    print $AoA[2][2];
   bart
 
 Now you should be very careful that the outer bracket type
 is a round one, that is, a parenthesis.  That's because you're assigning to
-an @list, so you need parentheses.  If you wanted there I<not> to be an @LoL,
+an @array, so you need parentheses.  If you wanted there I<not> to be an @AoA,
 but rather just a reference to it, you could do something more like this:
 
-    # assign a reference to list of list references
-    $ref_to_LoL = [
+    # assign a reference to array of array references
+    $ref_to_AoA = [
        [ "fred", "barney", "pebbles", "bambam", "dino", ],
        [ "homer", "bart", "marge", "maggie", ],
        [ "george", "jane", "elroy", "judy", ],
     ];
 
-    print $ref_to_LoL->[2][2];
+    print $ref_to_AoA->[2][2];
 
 Notice that the outer bracket type has changed, and so our access syntax
 has also changed.  That's because unlike C, in perl you can't freely
-interchange arrays and references thereto.  $ref_to_LoL is a reference to an
-array, whereas @LoL is an array proper.  Likewise, C<$LoL[2]> is not an
+interchange arrays and references thereto.  $ref_to_AoA is a reference to an
+array, whereas @AoA is an array proper.  Likewise, C<$AoA[2]> is not an
 array, but an array ref.  So how come you can write these:
 
-    $LoL[2][2]
-    $ref_to_LoL->[2][2]
+    $AoA[2][2]
+    $ref_to_AoA->[2][2]
 
 instead of having to write these:
 
-    $LoL[2]->[2]
-    $ref_to_LoL->[2]->[2]
+    $AoA[2]->[2]
+    $ref_to_AoA->[2]->[2]
 
 Well, that's because the rule is that on adjacent brackets only (whether
 square or curly), you are free to omit the pointer dereferencing arrow.
 But you cannot do so for the very first one if it's a scalar containing
-a reference, which means that $ref_to_LoL always needs it.
+a reference, which means that $ref_to_AoA always needs it.
 
 =head1 Growing Your Own
 
@@ -67,81 +67,81 @@ it up entirely from scratch?
 First, let's look at reading it in from a file.  This is something like
 adding a row at a time.  We'll assume that there's a flat file in which
 each line is a row and each word an element.  If you're trying to develop an
-@LoL list containing all these, here's the right way to do that:
+@AoA array containing all these, here's the right way to do that:
 
     while (<>) {
        @tmp = split;
-       push @LoL, [ @tmp ];
+       push @AoA, [ @tmp ];
     }
 
 You might also have loaded that from a function:
 
     for $i ( 1 .. 10 ) {
-       $LoL[$i] = [ somefunc($i) ];
+       $AoA[$i] = [ somefunc($i) ];
     }
 
 Or you might have had a temporary variable sitting around with the
-list in it.
+array in it.
 
     for $i ( 1 .. 10 ) {
        @tmp = somefunc($i);
-       $LoL[$i] = [ @tmp ];
+       $AoA[$i] = [ @tmp ];
     }
 
-It's very important that you make sure to use the C<[]> list reference
+It's very important that you make sure to use the C<[]> array reference
 constructor.  That's because this will be very wrong:
 
-    $LoL[$i] = @tmp;
+    $AoA[$i] = @tmp;
 
-You see, assigning a named list like that to a scalar just counts the
+You see, assigning a named array like that to a scalar just counts the
 number of elements in @tmp, which probably isn't what you want.
 
 If you are running under C<use strict>, you'll have to add some
 declarations to make it happy:
 
     use strict;
-    my(@LoL, @tmp);
+    my(@AoA, @tmp);
     while (<>) {
        @tmp = split;
-       push @LoL, [ @tmp ];
+       push @AoA, [ @tmp ];
     }
 
 Of course, you don't need the temporary array to have a name at all:
 
     while (<>) {
-       push @LoL, [ split ];
+       push @AoA, [ split ];
     }
 
 You also don't have to use push().  You could just make a direct assignment
 if you knew where you wanted to put it:
 
-    my (@LoL, $i, $line);
+    my (@AoA, $i, $line);
     for $i ( 0 .. 10 ) {
        $line = <>;
-       $LoL[$i] = [ split ' ', $line ];
+       $AoA[$i] = [ split ' ', $line ];
     }
 
 or even just
 
-    my (@LoL, $i);
+    my (@AoA, $i);
     for $i ( 0 .. 10 ) {
-       $LoL[$i] = [ split ' ', <> ];
+       $AoA[$i] = [ split ' ', <> ];
     }
 
-You should in general be leery of using potential list functions
-in a scalar context without explicitly stating such.
-This would be clearer to the casual reader:
+You should in general be leery of using functions that could
+potentially return lists in scalar context without explicitly stating
+such.  This would be clearer to the casual reader:
 
-    my (@LoL, $i);
+    my (@AoA, $i);
     for $i ( 0 .. 10 ) {
-       $LoL[$i] = [ split ' ', scalar(<>) ];
+       $AoA[$i] = [ split ' ', scalar(<>) ];
     }
 
-If you wanted to have a $ref_to_LoL variable as a reference to an array,
+If you wanted to have a $ref_to_AoA variable as a reference to an array,
 you'd have to do something like this:
 
     while (<>) {
-       push @$ref_to_LoL, [ split ];
+       push @$ref_to_AoA, [ split ];
     }
 
 Now you can add new rows.  What about adding new columns?  If you're
@@ -149,12 +149,12 @@ dealing with just matrices, it's often easiest to use simple assignment:
 
     for $x (1 .. 10) {
        for $y (1 .. 10) {
-           $LoL[$x][$y] = func($x, $y);
+           $AoA[$x][$y] = func($x, $y);
        }
     }
 
     for $x ( 3, 7, 9 ) {
-       $LoL[$x][20] += func2($x);
+       $AoA[$x][20] += func2($x);
     }
 
 It doesn't matter whether those elements are already
@@ -165,11 +165,11 @@ If you wanted just to append to a row, you'd have
 to do something a bit funnier looking:
 
     # add new columns to an existing row
-    push @{ $LoL[0] }, "wilma", "betty";
+    push @{ $AoA[0] }, "wilma", "betty";
 
 Notice that I I<couldn't> say just:
 
-    push $LoL[0], "wilma", "betty";  # WRONG!
+    push $AoA[0], "wilma", "betty";  # WRONG!
 
 In fact, that wouldn't even compile.  How come?  Because the argument
 to push() must be a real array, not just a reference to such.
@@ -180,12 +180,12 @@ Now it's time to print your data structure out.  How
 are you going to do that?  Well, if you want only one
 of the elements, it's trivial:
 
-    print $LoL[0][0];
+    print $AoA[0][0];
 
 If you want to print the whole thing, though, you can't
 say
 
-    print @LoL;                # WRONG
+    print @AoA;                # WRONG
 
 because you'll get just references listed, and perl will never
 automatically dereference things for you.  Instead, you have to
@@ -193,41 +193,41 @@ roll yourself a loop or two.  This prints the whole structure,
 using the shell-style for() construct to loop across the outer
 set of subscripts.
 
-    for $aref ( @LoL ) {
+    for $aref ( @AoA ) {
        print "\t [ @$aref ],\n";
     }
 
 If you wanted to keep track of subscripts, you might do this:
 
-    for $i ( 0 .. $#LoL ) {
-       print "\t elt $i is [ @{$LoL[$i]} ],\n";
+    for $i ( 0 .. $#AoA ) {
+       print "\t elt $i is [ @{$AoA[$i]} ],\n";
     }
 
 or maybe even this.  Notice the inner loop.
 
-    for $i ( 0 .. $#LoL ) {
-       for $j ( 0 .. $#{$LoL[$i]} ) {
-           print "elt $i $j is $LoL[$i][$j]\n";
+    for $i ( 0 .. $#AoA ) {
+       for $j ( 0 .. $#{$AoA[$i]} ) {
+           print "elt $i $j is $AoA[$i][$j]\n";
        }
     }
 
 As you can see, it's getting a bit complicated.  That's why
 sometimes is easier to take a temporary on your way through:
 
-    for $i ( 0 .. $#LoL ) {
-       $aref = $LoL[$i];
+    for $i ( 0 .. $#AoA ) {
+       $aref = $AoA[$i];
        for $j ( 0 .. $#{$aref} ) {
-           print "elt $i $j is $LoL[$i][$j]\n";
+           print "elt $i $j is $AoA[$i][$j]\n";
        }
     }
 
 Hmm... that's still a bit ugly.  How about this:
 
-    for $i ( 0 .. $#LoL ) {
-       $aref = $LoL[$i];
+    for $i ( 0 .. $#AoA ) {
+       $aref = $AoA[$i];
        $n = @$aref - 1;
        for $j ( 0 .. $n ) {
-           print "elt $i $j is $LoL[$i][$j]\n";
+           print "elt $i $j is $AoA[$i][$j]\n";
        }
     }
 
@@ -240,49 +240,49 @@ pointer arrow for dereferencing, no such convenience exists for slices.
 (Remember, of course, that you can always write a loop to do a slice
 operation.)
 
-Here's how to do one operation using a loop.  We'll assume an @LoL
+Here's how to do one operation using a loop.  We'll assume an @AoA
 variable as before.
 
     @part = ();
     $x = 4;
     for ($y = 7; $y < 13; $y++) {
-       push @part, $LoL[$x][$y];
+       push @part, $AoA[$x][$y];
     }
 
 That same loop could be replaced with a slice operation:
 
-    @part = @{ $LoL[4] } [ 7..12 ];
+    @part = @{ $AoA[4] } [ 7..12 ];
 
 but as you might well imagine, this is pretty rough on the reader.
 
 Ah, but what if you wanted a I<two-dimensional slice>, such as having
 $x run from 4..8 and $y run from 7 to 12?  Hmm... here's the simple way:
 
-    @newLoL = ();
+    @newAoA = ();
     for ($startx = $x = 4; $x <= 8; $x++) {
        for ($starty = $y = 7; $y <= 12; $y++) {
-           $newLoL[$x - $startx][$y - $starty] = $LoL[$x][$y];
+           $newAoA[$x - $startx][$y - $starty] = $AoA[$x][$y];
        }
     }
 
 We can reduce some of the looping through slices
 
     for ($x = 4; $x <= 8; $x++) {
-       push @newLoL, [ @{ $LoL[$x] } [ 7..12 ] ];
+       push @newAoA, [ @{ $AoA[$x] } [ 7..12 ] ];
     }
 
 If you were into Schwartzian Transforms, you would probably
 have selected map for that
 
-    @newLoL = map { [ @{ $LoL[$_] } [ 7..12 ] ] } 4 .. 8;
+    @newAoA = map { [ @{ $AoA[$_] } [ 7..12 ] ] } 4 .. 8;
 
 Although if your manager accused of seeking job security (or rapid
 insecurity) through inscrutable code, it would be hard to argue. :-)
 If I were you, I'd put that in a function:
 
-    @newLoL = splice_2D( \@LoL, 4 => 8, 7 => 12 );
+    @newAoA = splice_2D( \@AoA, 4 => 8, 7 => 12 );
     sub splice_2D {
-       my $lrr = shift;        # ref to list of list refs!
+       my $lrr = shift;        # ref to array of array refs!
        my ($x_lo, $x_hi,
            $y_lo, $y_hi) = @_;
 
index 48ebf23..de94e71 100644 (file)
@@ -6,25 +6,27 @@ perlmod - Perl modules (packages and symbol tables)
 
 =head2 Packages
 
-Perl provides a mechanism for alternative namespaces to protect packages
-from stomping on each other's variables.  In fact, there's really no such
-thing as a global variable in Perl (although some identifiers default
-to the main package instead of the current one).  The package statement
-declares the compilation unit as
-being in the given namespace.  The scope of the package declaration
-is from the declaration itself through the end of the enclosing block,
-C<eval>, C<sub>, or end of file, whichever comes first (the same scope
-as the my() and local() operators).  All further unqualified dynamic
-identifiers will be in this namespace.  A package statement only affects
-dynamic variables--including those you've used local() on--but
-I<not> lexical variables created with my().  Typically it would be
-the first declaration in a file to be included by the C<require> or
-C<use> operator.  You can switch into a package in more than one place;
-it merely influences which symbol table is used by the compiler for the
-rest of that block.  You can refer to variables and filehandles in other
-packages by prefixing the identifier with the package name and a double
-colon: C<$Package::Variable>.  If the package name is null, the C<main>
-package is assumed.  That is, C<$::sail> is equivalent to C<$main::sail>.
+Perl provides a mechanism for alternative namespaces to protect
+packages from stomping on each other's variables.  In fact, there's
+really no such thing as a global variable in Perl .  The package
+statement declares the compilation unit as being in the given
+namespace.  The scope of the package declaration is from the
+declaration itself through the end of the enclosing block, C<eval>,
+or file, whichever comes first (the same scope as the my() and
+local() operators).  Unqualified dynamic identifiers will be in
+this namespace, except for those few identifiers that if unqualified,
+default to the main package instead of the current one as described
+below.  A package statement affects only dynamic variables--including
+those you've used local() on--but I<not> lexical variables created
+with my().  Typically it would be the first declaration in a file
+included by the C<do>, C<require>, or C<use> operators.  You can
+switch into a package in more than one place; it merely influences
+which symbol table is used by the compiler for the rest of that
+block.  You can refer to variables and filehandles in other packages
+by prefixing the identifier with the package name and a double
+colon: C<$Package::Variable>.  If the package name is null, the
+C<main> package is assumed.  That is, C<$::sail> is equivalent to
+C<$main::sail>.
 
 The old package delimiter was a single quote, but double colon is now the
 preferred delimiter, in part because it's more readable to humans, and
@@ -37,35 +39,38 @@ C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
 the $s variable in package C<owner>, which is probably not what you meant.
 Use braces to disambiguate, as in C<"This is ${owner}'s house">.
 
-Packages may be nested inside other packages: C<$OUTER::INNER::var>.  This
-implies nothing about the order of name lookups, however.  All symbols
+Packages may themselves contain package separators, as in
+C<$OUTER::INNER::var>.  This implies nothing about the order of
+name lookups, however.  There are no relative packages: all symbols
 are either local to the current package, or must be fully qualified
 from the outer package name down.  For instance, there is nowhere
-within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
-It would treat package C<INNER> as a totally separate global package.
-
-Only identifiers starting with letters (or underscore) are stored in a
-package's symbol table.  All other symbols are kept in package C<main>,
-including all of the punctuation variables like $_.  In addition, when
-unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV,
-INC, and SIG are forced to be in package C<main>, even when used for other
-purposes than their builtin one.  Note also that, if you have a package
-called C<m>, C<s>, or C<y>, then you can't use the qualified form of an
-identifier because it will be interpreted instead as a pattern match,
-a substitution, or a transliteration.
-
-(Variables beginning with underscore used to be forced into package
+within package C<OUTER> that C<$INNER::var> refers to
+C<$OUTER::INNER::var>.  It would treat package C<INNER> as a totally
+separate global package.
+
+Only identifiers starting with letters (or underscore) are stored
+in a package's symbol table.  All other symbols are kept in package
+C<main>, including all punctuation variables, like $_.  In addition,
+when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
+ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
+even when used for other purposes than their built-in one.  If you
+have a package called C<m>, C<s>, or C<y>, then you can't use the
+qualified form of an identifier because it would be instead interpreted
+as a pattern match, a substitution, or a transliteration.
+
+Variables beginning with underscore used to be forced into package
 main, but we decided it was more useful for package writers to be able
 to use leading underscore to indicate private variables and method names.
-$_ is still global though.)
+$_ is still global though.  See also L<perlvar/"Technical Note on the
+Syntax of Variable Names">.
 
-Eval()ed strings are compiled in the package in which the eval() was
+C<eval>ed strings are compiled in the package in which the eval() was
 compiled.  (Assignments to C<$SIG{}>, however, assume the signal
 handler specified is in the C<main> package.  Qualify the signal handler
 name if you wish to have a signal handler in a package.)  For an
 example, examine F<perldb.pl> in the Perl library.  It initially switches
 to the C<DB> package so that the debugger doesn't interfere with variables
-in the script you are trying to debug.  At various points, however, it
+in the program you are trying to debug.  At various points, however, it
 temporarily switches back to the C<main> package to evaluate various
 expressions in the context of the C<main> package (or wherever you came
 from).  See L<perldebug>.
@@ -92,8 +97,8 @@ table lookups at compile time:
     local $main::{foo}  = $main::{bar};
 
 You can use this to print out all the variables in a package, for
-instance.  The standard F<dumpvar.pl> library and the CPAN module
-Devel::Symdump make use of this.
+instance.  The standard but antequated F<dumpvar.pl> library and
+the CPAN module Devel::Symdump make use of this.
 
 Assignment to a typeglob performs an aliasing operation, i.e.,
 
@@ -102,7 +107,7 @@ Assignment to a typeglob performs an aliasing operation, i.e.,
 causes variables, subroutines, formats, and file and directory handles
 accessible via the identifier C<richard> also to be accessible via the
 identifier C<dick>.  If you want to alias only a particular variable or
-subroutine, you can assign a reference instead:
+subroutine, assign a reference instead:
 
     *dick = \$richard;
 
@@ -130,7 +135,7 @@ is a somewhat tricky way of passing around references cheaply
 when you won't want to have to remember to dereference variables
 explicitly.
 
-Another use of symbol tables is for making "constant"  scalars.
+Another use of symbol tables is for making "constant" scalars.
 
     *PI = \3.14159265358979;
 
@@ -157,14 +162,14 @@ This prints
     You gave me main::foo
     You gave me bar::baz
 
-The *foo{THING} notation can also be used to obtain references to the
+The C<*foo{THING}> notation can also be used to obtain references to the
 individual elements of *foo, see L<perlref>.
 
 =head2 Package Constructors and Destructors
 
 There are two special subroutine definitions that function as package
-constructors and destructors.  These are the C<BEGIN> and C<END>
-routines.  The C<sub> is optional for these routines.
+constructors and destructors.  These are the C<BEGIN>, C<INIT>, and
+C<END> routines.  The C<sub> is optional for these routines.
 
 A C<BEGIN> subroutine is executed as soon as possible, that is, the moment
 it is completely defined, even before the rest of the containing file
@@ -183,39 +188,45 @@ trap that yourself (if you can).)  You may have multiple C<END> blocks
 within a file--they will execute in reverse order of definition; that is:
 last in, first out (LIFO).
 
-Inside an C<END> subroutine, C<$?> contains the value that the script is
+Inside an C<END> subroutine, C<$?> contains the value that the program is
 going to pass to C<exit()>.  You can modify C<$?> to change the exit
-value of the script.  Beware of changing C<$?> by accident (e.g. by
+value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
 
-Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
+When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
 C<END> work just as they do in B<awk>, as a degenerate case.  As currently
 implemented (and subject to change, since its inconvenient at best),
-both C<BEGIN> I<and> C<END> blocks are run when you use the B<-c> switch
+both C<BEGIN> and<END> blocks are run when you use the B<-c> switch
 for a compile-only syntax check, although your main code is not.
 
+Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
+Perl runtime begins execution.  For example, the code generators
+documented in L<perlcc> make use of C<INIT> blocks to initialize
+and resolve pointers to XSUBs.
+
 =head2 Perl Classes
 
-There is no special class syntax in Perl, but a package may function
+There is no special class syntax in Perl, but a package may act
 as a class if it provides subroutines to act as methods.  Such a
 package may also derive some of its methods from another class (package)
-by listing the other package name in its global @ISA array (which 
+by listing the other package name(s) in its global @ISA array (which 
 must be a package global, not a lexical).
 
 For more on this, see L<perltoot> and L<perlobj>.
 
 =head2 Perl Modules
 
-A module is just a package that is defined in a library file of
-the same name, and is designed to be reusable.  It may do this by
-providing a mechanism for exporting some of its symbols into the symbol
-table of any package using it.  Or it may function as a class
-definition and make its semantics available implicitly through method
-calls on the class and its objects, without explicit exportation of any
-symbols.  Or it can do a little of both.
+A module is just a set of related function in a library file a Perl
+package with the same name as the file.  It is specifically designed
+to be reusable by other modules or programs.  It may do this by
+providing a mechanism for exporting some of its symbols into the
+symbol table of any package using it.  Or it may function as a class
+definition and make its semantics available implicitly through
+method calls on the class and its objects, without explicitly
+exportating anything.  Or it can do a little of both.
 
-For example, to start a normal module called Some::Module, create
-a file called Some/Module.pm and start with this template:
+For example, to start a traditional, non-OO module called Some::Module,
+create a file called F<Some/Module.pm> and start with this template:
 
     package Some::Module;  # assumes Some/Module.pm
 
@@ -275,10 +286,13 @@ a file called Some/Module.pm and start with this template:
 
     END { }       # module clean-up code here (global destructor)
 
-Then go on to declare and use your variables in functions
-without any qualifications.
-See L<Exporter> and the L<perlmodlib> for details on
-mechanics and style issues in module creation.
+    ## YOUR CODE GOES HERE
+
+    1;  # don't forget to return a true value from the file
+
+Then go on to declare and use your variables in functions without
+any qualifications.  See L<Exporter> and the L<perlmodlib> for
+details on mechanics and style issues in module creation.
 
 Perl modules are included into your program by saying
 
@@ -304,12 +318,13 @@ is exactly equivalent to
 
     BEGIN { require Module; }
 
-All Perl module files have the extension F<.pm>.  C<use> assumes this so
-that you don't have to spell out "F<Module.pm>" in quotes.  This also
-helps to differentiate new modules from old F<.pl> and F<.ph> files.
-Module names are also capitalized unless they're functioning as pragmas,
-"Pragmas" are in effect compiler directives, and are sometimes called
-"pragmatic modules" (or even "pragmata" if you're a classicist).
+All Perl module files have the extension F<.pm>.  The C<use> operator
+assumes this so you don't have to spell out "F<Module.pm>" in quotes.
+This also helps to differentiate new modules from old F<.pl> and
+F<.ph> files.  Module names are also capitalized unless they're
+functioning as pragmas; pragmas are in effect compiler directives,
+and are sometimes called "pragmatic modules" (or even "pragmata"
+if you're a classicist).
 
 The two statements:
 
@@ -319,18 +334,19 @@ The two statements:
 differ from each other in two ways.  In the first case, any double
 colons in the module name, such as C<Some::Module>, are translated
 into your system's directory separator, usually "/".   The second
-case does not, and would have to be specified literally.  The other difference
-is that seeing the first C<require> clues in the compiler that uses of 
-indirect object notation involving "SomeModule", as in C<$ob = purge SomeModule>,
-are method calls, not function calls.  (Yes, this really can make a difference.)
-
-Because the C<use> statement implies a C<BEGIN> block, the importation
-of semantics happens at the moment the C<use> statement is compiled,
+case does not, and would have to be specified literally.  The other
+difference is that seeing the first C<require> clues in the compiler
+that uses of indirect object notation involving "SomeModule", as
+in C<$ob = purge SomeModule>, are method calls, not function calls.
+(Yes, this really can make a difference.)
+
+Because the C<use> statement implies a C<BEGIN> block, the importing
+of semantics happens as soon as the C<use> statement is compiled,
 before the rest of the file is compiled.  This is how it is able
 to function as a pragma mechanism, and also how modules are able to
-declare subroutines that are then visible as list operators for
+declare subroutines that are then visible as list or unary operators for
 the rest of the current file.  This will not work if you use C<require>
-instead of C<use>.  With require you can get into this problem:
+instead of C<use>.  With C<require> you can get into this problem:
 
     require Cwd;               # make Cwd:: accessible
     $here = Cwd::getcwd();
@@ -354,22 +370,22 @@ filenames on some systems.  Therefore, if a module's name is, say,
 C<Text::Soundex>, then its definition is actually found in the library
 file F<Text/Soundex.pm>.
 
-Perl modules always have a F<.pm> file, but there may also be dynamically
-linked executables or autoloaded subroutine definitions associated with
-the module.  If so, these will be entirely transparent to the user of
-the module.  It is the responsibility of the F<.pm> file to load (or
-arrange to autoload) any additional functionality.  The POSIX module
-happens to do both dynamic loading and autoloading, but the user can
-say just C<use POSIX> to get it all.
-
-For more information on writing extension modules, see L<perlxstut>
-and L<perlguts>.
+Perl modules always have a F<.pm> file, but there may also be
+dynamically linked executables (often ending in F<.so>) or autoloaded
+subroutine definitions (often ending in F<.al> associated with the
+module.  If so, these will be entirely transparent to the user of
+the module.  It is the responsibility of the F<.pm> file to load
+(or arrange to autoload) any additional functionality.  For example,
+although the POSIX module happens to do both dynamic loading and
+autoloading, but the user can say just C<use POSIX> to get it all.
 
 =head1 SEE ALSO
 
 See L<perlmodlib> for general style issues related to building Perl
-modules and classes as well as descriptions of the standard library and
-CPAN, L<Exporter> for how Perl's standard import/export mechanism works,
-L<perltoot> for an in-depth tutorial on creating classes, L<perlobj>
-for a hard-core reference document on objects, and L<perlsub> for an
-explanation of functions and scoping.
+modules and classes, as well as descriptions of the standard library
+and CPAN, L<Exporter> for how Perl's standard import/export mechanism
+works, L<perltoot> and L<perltootc> for an in-depth tutorial on
+creating classes, L<perlobj> for a hard-core reference document on
+objects, L<perlsub> for an explanation of functions and scoping,
+and L<perlxstut> and L<perlguts> for more information on writing
+extension modules.
index b6176f0..4076254 100644 (file)
@@ -5,21 +5,23 @@ perlmodinstall - Installing CPAN Modules
 =head1 DESCRIPTION
 
 You can think of a module as the fundamental unit of reusable Perl
-code; see L<perlmod> for details.  Whenever anyone creates a chunk of
-Perl code that they think will be useful to the world, they register
-as a Perl developer at http://www.perl.com/CPAN/modules/04pause.html
-so that they can then upload their code to the CPAN.  The CPAN is the
-Comprehensive Perl Archive Network and can be accessed at
-http://www.perl.com/CPAN/.
+code; See L<perlmod> for details.  Whenever anyone creates a chunk
+of Perl code that they think will be useful to the world, they
+register as a Perl developer at
+http://www.perl.com/CPAN/modules/04pause.html so that they can then
+upload their code to CPAN.  CPAN is the Comprehensive Perl Archive
+Network and can be accessed at http://www.perl.com/CPAN/, or searched
+via http://cpan.perl.com/ and
+http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
 
 This documentation is for people who want to download CPAN modules
 and install them on their own computer.
 
 =head2 PREAMBLE
 
-You have a file ending in .tar.gz (or, less often, .zip).  You know
-there's a tasty module inside.  There are four steps you must now
-take:
+You have a file ending in F<.tar.gz> (or, less often, F<.zip>).
+You know there's a tasty module inside.  You must now take four
+steps:
 
 =over 5
 
@@ -44,8 +46,8 @@ say C<perl Makefile.PL>, you can substitute C<perl
 Makefile.PL PREFIX=/my/perl_directory> to install the modules
 into C</my/perl_directory>.  Then you can use the modules
 from your Perl programs with C<use lib
-"/my/perl_directory/lib/site_perl";> or sometimes just C<use
-"/my/perl_directory";>.  
+"/my/perl_directory/lib/site_perl"> or sometimes just C<use
+"/my/perl_directory">.  
 
 =over 4
 
@@ -54,7 +56,8 @@ from your Perl programs with C<use lib
 B<If you're on Unix,>
 
 You can use Andreas Koenig's CPAN module 
-( http://www.perl.com/CPAN/modules/by-module/CPAN ) 
+(which comes standard with Perl, or can itself be downloaded
+from http://www.perl.com/CPAN/modules/by-module/CPAN) 
 to automate the following steps, from DECOMPRESS through INSTALL.
 
 A. DECOMPRESS 
@@ -85,12 +88,12 @@ While still in that directory, type:
 
       make install
 
-Make sure you have the appropriate permissions to install the module
+Make sure you have appropriate permissions to install the module
 in your Perl 5 library directory.  Often, you'll need to be root.
 
 That's all you need to do on Unix systems with dynamic linking.
-Most Unix systems have dynamic linking -- if yours doesn't, or if for
-another reason you have a statically-linked perl, B<and> the
+Most Unix systems have dynamic linking--if yours doesn't, or if for
+another reason you have a statically-linked perl, I<and> the
 module requires compilation, you'll need to build a new Perl binary
 that includes the module.  Again, you'll probably need to be root.
 
@@ -100,7 +103,7 @@ B<If you're running Windows 95 or NT with the ActiveState port of Perl>
 
    A. DECOMPRESS
 
-You can use the shareware Winzip ( http://www.winzip.com ) to
+You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
 decompress and unpack modules.
 
    B. UNPACK
@@ -112,7 +115,7 @@ If you used WinZip, this was already done for you.
 Does the module require compilation (i.e. does it have files
 that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, you're on
 your own.  You can try compiling it yourself if you have a C compiler.
-If you're successful, consider uploading the resulting binary to the
+If you're successful, consider uploading the resulting binary to
 CPAN for others to use.  If it doesn't, go to INSTALL.
 
    D. INSTALL
@@ -129,11 +132,11 @@ B<If you're running Windows 95 or NT with the core Windows distribution of Perl,
    A. DECOMPRESS
 
 When you download the module, make sure it ends in either
-C<.tar.gz> or C<.zip>.  Windows browsers sometimes
+F<.tar.gz> or F<.zip>.  Windows browsers sometimes
 download C<.tar.gz> files as C<_tar.tar>, because
 early versions of Windows prohibited more than one dot in a filename.
 
-You can use the shareware WinZip ( http://www.winzip.com ) to
+You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
 decompress and unpack modules.
 
 Or, you can use InfoZip's C<unzip> utility (
@@ -151,7 +154,7 @@ UNPACK your module as well.
 
    B. UNPACK
 
-All of the methods in DECOMPRESS will have done this for you.
+The methods in DECOMPRESS will have done this for you.
 
    C. BUILD
 
@@ -185,18 +188,18 @@ Specificly the "Commpress & Translate" listing
 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ).
 
 
-You can either use the shareware StuffIt Expander 
+You can either use the shareware B<StuffIt Expander> program
 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/stuffit-expander-401.hqx ) 
 in combination with I<DropStuff with Expander Enhancer>
 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/drop-stuff-with-ee-40.hqx ) 
-or the freeware MacGzip (
+or the freeware B<MacGzip> program (
 http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
 
 
 B. UNPACK
 
 If you're using DropStuff or Stuffit, you can just extract the tar
-archive.  Otherwise, you can use the freeware I<suntar> 
+archive.  Otherwise, you can use the freeware B<suntar> 
 ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/suntar-221.hqx )
 or I<Tar> ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/tar-40b.hqx ).
 
@@ -208,9 +211,9 @@ Does the module require compilation?
 
 Overview: You need MPW and a combination of new and old CodeWarrior
 compilers for MPW and libraries.  Makefiles created for building under
-MPW use the Metrowerks compilers.  It's most likely possible to build
+MPW use Metrowerks compilers.  It's most likely possible to build
 without other compilers, but it has not been done successfully, to our
-knowledge.  Read the documentation in MacPerl: Power and Ease (
+knowledge.  Read the documentation in I<MacPerl: Power and Ease> (
 http://www.ptf.com/macperl/ ) on porting/building extensions, or find
 an existing precompiled binary, or hire someone to build it for you.
 
@@ -226,9 +229,10 @@ Make sure the newlines for the modules are in Mac format, not Unix format.
 If they are not then you might have decompressed them incorrectly.  Check
 your decompression and unpacking utilities settings to make sure they are
 translating text files properly.
-As a last resort, you can use the perl one-liner:
 
-       perl -i.bak -pe 's/(?:\015)?\012/\015/g' filenames
+As a last resort, you can use the perl one-liner:  
+
+    perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames> 
 
 on the source files.
 
@@ -275,7 +279,7 @@ Go into the newly-created directory and type:
       make
       make test
 
-You will need the packages mentioned in C<Readme.dos>
+You will need the packages mentioned in F<README.dos>
 in the Perl distribution.
 
    D. INSTALL
@@ -284,7 +288,7 @@ While still in that directory, type:
 
      make install      
      
-You will need the packages mentioned in Readme.dos in the Perl distribution.
+You will need the packages mentioned in F<README.dos> in the Perl distribution.
 
 =item *
 
@@ -298,8 +302,8 @@ the instructions for Unix.
 
 B<If you're on VMS,>
 
-When downloading from CPAN, save your file with a C<.tgz>
-extension instead of C<.tar.gz>.  All other periods in the
+When downloading from CPAN, save your file with a F<.tgz>
+extension instead of F<.tar.gz>.  All other periods in the
 filename should be replaced with underscores.  For example,
 C<Your-Module-1.33.tar.gz> should be downloaded as
 C<Your-Module-1_33.tgz>.
@@ -361,7 +365,7 @@ Substitute C<mmk> for C<mms> above if you're using MMK.
 
 B<If you're on MVS>,
 
-Introduce the .tar.gz file into an HFS as binary; don't translate from
+Introduce the F<.tar.gz> file into an HFS as binary; don't translate from
 ASCII to EBCDIC.
 
 A. DECOMPRESS 
index 2dc38df..4cee455 100644 (file)
@@ -6,54 +6,76 @@ perlmodlib - constructing new Perl modules and finding existing ones
 
 =head1 THE PERL MODULE LIBRARY
 
-A number of modules are included the Perl distribution.  These are
-described below, and all end in F<.pm>.  You may also discover files in
-the library directory that end in either F<.pl> or F<.ph>.  These are old
-libraries supplied so that old programs that use them still run.  The
-F<.pl> files will all eventually be converted into standard modules, and
-the F<.ph> files made by B<h2ph> will probably end up as extension modules
-made by B<h2xs>.  (Some F<.ph> values may already be available through the
-POSIX module.)  The B<pl2pm> file in the distribution may help in your
-conversion, but it's just a mechanical process and therefore far from
-bulletproof.
+Many modules are included the Perl distribution.  These are described
+below, and all end in F<.pm>.  You may discover compiled library
+file (usually ending in F<.so>) or small pieces of modules to be
+autoloaded (ending in F<.al>); these were automatically generated
+by the installation process.  You may also discover files in the
+library directory that end in either F<.pl> or F<.ph>.  These are
+old libraries supplied so that old programs that use them still
+run.  The F<.pl> files will all eventually be converted into standard
+modules, and the F<.ph> files made by B<h2ph> will probably end up
+as extension modules made by B<h2xs>.  (Some F<.ph> values may
+already be available through the POSIX, Errno, or Fcntl modules.)
+The B<pl2pm> file in the distribution may help in your conversion,
+but it's just a mechanical process and therefore far from bulletproof.
 
 =head2 Pragmatic Modules
 
-They work somewhat like pragmas in that they tend to affect the compilation of
-your program, and thus will usually work well only when used within a
-C<use>, or C<no>.  Most of these are lexically scoped, so an inner BLOCK
-may countermand any of these by saying:
+They work somewhat like compiler directives (pragmata) in that they
+tend to affect the compilation of your program, and thus will usually
+work well only when used within a C<use>, or C<no>.  Most of these
+are lexically scoped, so an inner BLOCK may countermand them
+by saying:
 
     no integer;
     no strict 'refs';
 
 which lasts until the end of that BLOCK.
 
-Unlike the pragmas that effect the C<$^H> hints variable, the C<use
-vars> and C<use subs> declarations are not BLOCK-scoped.  They allow
-you to predeclare a variables or subroutines within a particular
-I<file> rather than just a block.  Such declarations are effective
-for the entire file for which they were declared.  You cannot rescind
-them with C<no vars> or C<no subs>.
+Some pragmas are lexically scoped--typically those that affect the
+C<$^H> hints variable.  Others affect the current package instead,
+like C<use vars> and C<use subs>, whic allow you to predeclare a
+variables or subroutines within a particular I<file> rather than
+just a block.  Such declarations are effective for the entire file
+for which they were declared.  You cannot rescind them with C<no
+vars> or C<no subs>.
 
 The following pragmas are defined (and have their own documentation).
 
 =over 12
 
-=item use autouse MODULE => qw(sub1 sub2 sub3)
+=item attrs
 
-Defers C<require MODULE> until someone calls one of the specified
-subroutines (which must be exported by MODULE).  This pragma should be
-used with caution, and only when necessary.
+set/get attributes of a subroutine
+
+=item autouse
+
+postpone load of modules until a function is used
+
+=item base
+
+Establish IS-A relationship with base class at compile time
 
 =item blib
 
-manipulate @INC at compile time to use MakeMaker's uninstalled version
-of a package
+Use MakeMaker's uninstalled version of a package
+
+=item constant
+
+declare constants
 
 =item diagnostics
 
-force verbose warning diagnostics
+Perl compiler pragma to force verbose warning diagnostics
+
+=item fields
+
+compile-time class fields
+
+=item filetest
+
+control the filetest permission operators
 
 =item integer
 
@@ -61,7 +83,7 @@ compute arithmetic in integer instead of double
 
 =item less
 
-request less of something from the compiler
+perl pragma to request less of something from the compiler
 
 =item lib
 
@@ -69,19 +91,19 @@ manipulate @INC at compile time
 
 =item locale
 
-use or ignore current locale for builtin operations (see L<perllocale>)
+use and avoid POSIX locales for built-in operations
 
 =item ops
 
-restrict named opcodes when compiling or running Perl code
+restrict unsafe operations when compiling
 
 =item overload
 
-overload basic Perl operations
+Package for overloading perl operations
 
 =item re
 
-alter behaviour of regular expressions
+alter regular expression behavior
 
 =item sigtrap
 
@@ -95,14 +117,22 @@ restrict unsafe constructs
 
 predeclare sub names
 
-=item vmsish
+=item utf8
 
-adopt certain VMS-specific behaviors
+turn on UTF-8 and Unicode support
 
 =item vars
 
 predeclare global variable names
 
+=item vmsish
+
+control VMS-specific language features
+
+=item warning
+
+control optional warnings
+
 =back
 
 =head2 Standard Modules
@@ -119,27 +149,115 @@ provide framework for multiple DBMs
 
 =item AutoLoader
 
-load functions only on demand
+load subroutines only on demand
 
 =item AutoSplit
 
 split a package for autoloading
 
+=item B
+
+The Perl Compiler; See also L<perlcc>.
+
+=item B::Asmdata
+
+Autogenerated data about Perl ops, used to generate bytecode
+
+=item B::Assembler
+
+Assemble Perl bytecode
+
+=item B::Bblock
+
+Walk basic blocks
+
+=item B::Bytecode
+
+Perl compiler's bytecode backend
+
+=item B::C
+
+Perl compiler's C backend
+
+=item B::CC
+
+Perl compiler's optimized C translation backend
+
+=item B::Debug
+
+Walk Perl syntax tree, printing debug info about ops
+
+=item B::Deparse
+
+Perl compiler backend to produce perl code
+
+=item B::Disassembler
+
+Disassemble Perl bytecode
+
+=item B::Lint
+
+Perl lint
+
+=item B::Showlex
+
+Show lexical variables used in functions or files
+
+=item B::Stackobj
+
+Helper module for CC backend
+
+=item B::Terse
+
+Walk Perl syntax tree, printing terse info about ops
+
+=item B::Xref
+
+Generates cross reference reports for Perl programs
+
 =item Benchmark
 
 benchmark running times of code
 
+=item CGI
+
+Simple Common Gateway Interface Class
+
+=item CGI::Apache
+
+Make things work with CGI.pm against Perl-Apache API
+
+=item CGI::Carp
+
+CGI routines for writing to the HTTPD (or other) error log
+
+=item CGI::Cookie
+
+Interface to Netscape Cookies
+
+=item CGI::Fast
+
+CGI Interface for Fast CGI
+
+=item CGI::Push
+
+Simple Interface to Server Push
+
+=item CGI::Switch
+
+Try more than one constructors and return the first object available
+
 =item CPAN
 
-interface to Comprehensive Perl Archive Network
+query, download and build perl modules from CPAN sites
 
 =item CPAN::FirstTime
 
-create a CPAN configuration file
+Utility for CPAN::Config file Initialization
 
 =item CPAN::Nox
 
-run CPAN while avoiding compiled extensions
+Wrapper around CPAN.pm without using any XS module
 
 =item Carp
 
@@ -147,7 +265,7 @@ warn of errors (from perspective of caller)
 
 =item Class::Struct
 
-declare struct-like datatypes
+declare struct-like datatypes as Perl classes
 
 =item Config
 
@@ -157,13 +275,21 @@ access Perl configuration information
 
 get pathname of current working directory
 
+=item DB
+
+programmatic interface to the Perl debugging API 
+
 =item DB_File
 
-access to Berkeley DB
+Perl5 access to Berkeley DB version 1.x
+
+=item Data::Dumper
+
+stringified perl data structures, suitable for both printing and C<eval>
 
 =item Devel::Peek
 
-data debugging tool for the XS programmer
+data debugging tool for the XS programmer
 
 =item Devel::SelfStubber
 
@@ -173,9 +299,13 @@ generate stubs for a SelfLoading module
 
 supply object methods for directory handles
 
+=item Dumpvalue
+
+provides screen dump of Perl data.
+
 =item DynaLoader
 
-dynamically load C libraries into Perl code
+Dynamically load C libraries into Perl code
 
 =item English
 
@@ -183,27 +313,39 @@ use nice English (or awk) names for ugly punctuation variables
 
 =item Env
 
-import environment variables
+perl module that imports environment variables
+
+=item Errno
+
+System errno constants
 
 =item Exporter
 
-implements default import method for modules
+Implements default import method for modules
+
+=item ExtUtils::Command
+
+utilities to replace common UNIX commands in Makefiles etc.
 
 =item ExtUtils::Embed
 
-utilities for embedding Perl in C/C++ applications
+Utilities for embedding Perl in C/C++ applications
 
 =item ExtUtils::Install
 
 install files from here to there
 
+=item ExtUtils::Installed
+
+Inventory management of installed modules
+
 =item ExtUtils::Liblist
 
 determine libraries to use and how to use them
 
 =item ExtUtils::MM_OS2
 
-methods to override Unix behaviour in ExtUtils::MakeMaker
+methods to override UN*X behavior in ExtUtils::MakeMaker
 
 =item ExtUtils::MM_Unix
 
@@ -211,7 +353,11 @@ methods used by ExtUtils::MakeMaker
 
 =item ExtUtils::MM_VMS
 
-methods to override Unix behaviour in ExtUtils::MakeMaker
+methods to override UN*X behavior in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_Win32
+
+methods to override UN*X behavior in ExtUtils::MakeMaker
 
 =item ExtUtils::MakeMaker
 
@@ -221,6 +367,10 @@ create an extension Makefile
 
 utilities to write and check a MANIFEST file
 
+=item ExtUtils::Miniperl
+
+write the C code for perlmain.c
+
 =item ExtUtils::Mkbootstrap
 
 make a bootstrap file for use by DynaLoader
@@ -229,13 +379,17 @@ make a bootstrap file for use by DynaLoader
 
 write linker options files for dynamic extension
 
+=item ExtUtils::Packlist
+
+manage .packlist files
+
 =item ExtUtils::testlib
 
 add blib/* directories to @INC
 
 =item Fatal
 
-make errors in builtins or Perl functions fatal
+replace functions with equivalents which succeed or die
 
 =item Fcntl
 
@@ -245,17 +399,17 @@ load the C Fcntl.h defines
 
 split a pathname into pieces
 
-=item File::CheckTree
-
-run many filetest checks on a tree
-
 =item File::Compare
 
-compare files or filehandles
+Compare files or filehandles
 
 =item File::Copy
 
-copy files or filehandles
+Copy files or filehandles
+
+=item File::DosGlob
+
+DOS like globbing and then some
 
 =item File::Find
 
@@ -271,11 +425,31 @@ portably perform operations on file names
 
 =item File::Spec::Functions
 
-function call interface to File::Spec module
+portably perform operations on file names
+
+=item File::Spec::Mac
+
+File::Spec for MacOS
+
+=item File::Spec::OS2
+
+methods for OS/2 file specs
+
+=item File::Spec::Unix
+
+methods used by File::Spec
+
+=item File::Spec::VMS
+
+methods for VMS file specs
+
+=item File::Spec::Win32
+
+methods for Win32 file specs
 
 =item File::stat
 
-by-name interface to Perl's builtin stat() functions
+by-name interface to Perl's built-in stat() functions
 
 =item FileCache
 
@@ -287,11 +461,11 @@ supply object methods for filehandles
 
 =item FindBin
 
-locate directory of original Perl script
+Locate directory of original perl script
 
 =item GDBM_File
 
-access to the gdbm library
+Perl5 access to the gdbm library.
 
 =item Getopt::Long
 
@@ -299,7 +473,7 @@ extended processing of command line options
 
 =item Getopt::Std
 
-process single-character switches with switch clustering
+Process single-character switches with switch clustering
 
 =item I18N::Collate
 
@@ -309,6 +483,10 @@ compare 8-bit scalar data according to the current locale
 
 load various IO modules
 
+=item IO::Dir
+
+supply object methods for directory handles
+
 =item IO::File
 
 supply object methods for filehandles
@@ -321,6 +499,10 @@ supply object methods for I/O handles
 
 supply object methods for pipes
 
+=item IO::Poll
+
+Object interface to system poll call
+
 =item IO::Seekable
 
 supply seek based methods for I/O objects
@@ -331,7 +513,19 @@ OO interface to the select system call
 
 =item IO::Socket
 
-object interface to socket communications
+Object interface to socket communications
+
+=item IO::Socket::INET
+
+Object interface for AF_INET domain sockets
+
+=item IO::Socket::UNIX
+
+Object interface for AF_UNIX domain sockets
+
+=item IPC::Msg
+
+SysV Msg IPC object class
 
 =item IPC::Open2
 
@@ -341,13 +535,21 @@ open a process for both reading and writing
 
 open a process for reading, writing, and error handling
 
+=item IPC::Semaphore
+
+SysV Semaphore IPC object class
+
+=item IPC::SysV
+
+SysV IPC constants
+
 =item Math::BigFloat
 
-arbitrary length float math package
+Arbitrary length float math package
 
 =item Math::BigInt
 
-arbitrary size integer math package
+Arbitrary size integer math package
 
 =item Math::Complex
 
@@ -355,52 +557,59 @@ complex numbers and associated mathematical functions
 
 =item Math::Trig
 
-simple interface to parts of Math::Complex for those who
-need trigonometric functions only for real numbers
+trigonometric functions
 
 =item NDBM_File
 
-tied access to ndbm files
+Tied access to ndbm files
 
 =item Net::Ping
 
-Hello, anybody home?
+check a remote host for reachability
 
 =item Net::hostent
 
-by-name interface to Perl's builtin gethost*() functions
+by-name interface to Perl's built-in gethost*() functions
 
 =item Net::netent
 
-by-name interface to Perl's builtin getnet*() functions
+by-name interface to Perl's built-in getnet*() functions
 
 =item Net::protoent
 
-by-name interface to Perl's builtin getproto*() functions
+by-name interface to Perl's built-in getproto*() functions
 
 =item Net::servent
 
-by-name interface to Perl's builtin getserv*() functions
+by-name interface to Perl's built-in getserv*() functions
 
-=item Opcode
+=item O
 
-disable named opcodes when compiling or running Perl code
+Generic interface to Perl Compiler backends
 
-=item Pod::Text
+=item Opcode
 
-convert POD data to formatted ASCII text
+Disable named opcodes when compiling perl code
 
 =item POSIX
 
-interface to IEEE Standard 1003.1
+Perl interface to IEEE Std 1003.1
+
+=item Pod::Html
+
+module to convert pod files to HTML
+
+=item Pod::Text
+
+convert POD data to formatted ASCII text
 
 =item SDBM_File
 
-tied access to sdbm files
+Tied access to sdbm files
 
 =item Safe
 
-compile and execute code in restricted compartments
+Compile and execute code in restricted compartments
 
 =item Search::Dict
 
@@ -416,7 +625,7 @@ load functions only on demand
 
 =item Shell
 
-run shell commands transparently within Perl
+run shell commands transparently within perl
 
 =item Socket
 
@@ -428,27 +637,31 @@ manipulate Perl symbols and their names
 
 =item Sys::Hostname
 
-try every conceivable way to get hostname
+Try every conceivable way to get hostname
 
 =item Sys::Syslog
 
-interface to the Unix syslog(3) calls
+Perl interface to the UNIX syslog(3) calls
 
 =item Term::Cap
 
-termcap interface
+Perl termcap interface
 
 =item Term::Complete
 
-word completion module
+Perl word completion module
 
 =item Term::ReadLine
 
-interface to various C<readline> packages
+Perl interface to various C<readline> packages. 
+
+=item Test
+
+provides a simple framework for writing test scripts
 
 =item Test::Harness
 
-run Perl standard test scripts with statistics
+run perl standard test scripts with statistics
 
 =item Text::Abbrev
 
@@ -456,35 +669,61 @@ create an abbreviation table from a list
 
 =item Text::ParseWords
 
-parse text into an array of tokens
+parse text into an array of tokens or array of arrays
 
 =item Text::Soundex
 
-implementation of the Soundex Algorithm as described by Knuth
-
-=item Text::Tabs
+Implementation of the Soundex Algorithm as Described by Knuth
 
-expand and unexpand tabs per the Unix expand(1) and unexpand(1)
+=item Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)
 
 =item Text::Wrap
 
 line wrapping to form simple paragraphs
 
-=item Tie::Hash
+=item Thread 
+
+multithreading
+
+=item Thread::Queue 
+
+thread-safe queues
+
+=item Thread::Semaphore 
+
+thread-safe semaphores
+
+=item Thread::Signal 
+
+Start a thread which runs signal handlers reliably
+
+=item Thread::Specific 
+
+thread-specific keys
+
+=item Tie::Array
+
+base class for tied arrays
+
+=item Tie::Handle
+
+base class definitions for tied handles
+
+=item Tie::Hash, Tie::StdHash
 
 base class definitions for tied hashes
 
 =item Tie::RefHash
 
-base class definitions for tied hashes with references as keys
+use references as hash keys
 
-=item Tie::Scalar
+=item Tie::Scalar, Tie::StdScalar
 
 base class definitions for tied scalars
 
 =item Tie::SubstrHash
 
-fixed-table-size, fixed-key-length hashing
+Fixed-table-size, fixed-key-length hashing
 
 =item Time::Local
 
@@ -492,11 +731,11 @@ efficiently compute time from local and GMT time
 
 =item Time::gmtime
 
-by-name interface to Perl's builtin gmtime() function
+by-name interface to Perl's built-in gmtime() function
 
 =item Time::localtime
 
-by-name interface to Perl's builtin localtime() function
+by-name interface to Perl's built-in localtime() function
 
 =item Time::tm
 
@@ -508,42 +747,54 @@ base class for ALL classes (blessed references)
 
 =item User::grent
 
-by-name interface to Perl's builtin getgr*() functions
+by-name interface to Perl's built-in getgr*() functions
 
 =item User::pwent
 
-by-name interface to Perl's builtin getpw*() functions
+by-name interface to Perl's built-in getpw*() functions
 
 =back
 
-To find out I<all> the modules installed on your system, including
-those without documentation or outside the standard release, do this:
+To find out I<all> modules installed on your system, including
+those without documentation or outside the standard release, 
+jus tdo this:
 
     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 
-They should all have their own documentation installed and accessible via
-your system man(1) command.  If that fails, try the I<perldoc> program.
+They should all have their own documentation installed and accessible
+via your system man(1) command.  If you do not have a B<find>
+program, you can use the Perl B<find2perl> program instead, which
+generates Perl code as output you can run through perl.  If you
+have a B<man> program but it doesn't find your modules, you'll have
+to fix your manpath.  See L<perl> for details.  If you have no
+system B<man> command, you might try the B<perldoc> program.
 
 =head2 Extension Modules
 
-Extension modules are written in C (or a mix of Perl and C) and may be
-statically linked or in general are
-dynamically loaded into Perl if and when you need them.  Supported
-extension modules include the Socket, Fcntl, and POSIX modules.
+Extension modules are written in C (or a mix of Perl and C).  They
+are usually dynamically loaded into Perl if and when you need them,
+but may also be be linked in statically.  Supported extension modules
+include Socket, Fcntl, and POSIX.
 
 Many popular C extension modules do not come bundled (at least, not
-completely) due to their sizes, volatility, or simply lack of time for
-adequate testing and configuration across the multitude of platforms on
-which Perl was beta-tested.  You are encouraged to look for them in
-archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
-authors before randomly posting asking for their present condition and
-disposition.
+completely) due to their sizes, volatility, or simply lack of time
+for adequate testing and configuration across the multitude of
+platforms on which Perl was beta-tested.  You are encouraged to
+look for them on CPAN (described below), or using web search engines
+like Alta Vista or Deja News.
 
 =head1 CPAN
 
-CPAN stands for the Comprehensive Perl Archive Network.  This is a globally
-replicated collection of all known Perl materials, including hundreds
-of unbundled modules.  Here are the major categories of modules:
+CPAN stands for Comprehensive Perl Archive Network; it's a globally
+replicated trove of Perl materials, including documentation, style
+guides, tricks and trap, alternate ports to non-Unix systems and
+occasional binary distributions for these.   Search engines for
+CPAN can be found at http://cpan.perl.com/ and at
+http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
+
+Most importantly, CPAN includes around a thousand unbundled modules,
+some of which require a C compiler to build.  Major categories of
+modules are:
 
 =over
 
@@ -612,21 +863,18 @@ Miscellaneous Modules
 
 =back
 
-The registered CPAN sites as of this writing include the following.
+Registered CPAN sites as of this writing include the following.
 You should try to choose one close to you:
 
 =over
 
-=item *
-Africa
+=item Africa
 
    South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/
                    ftp://ftpza.co.za/pub/mirrors/cpan/
 
-=item *
-Asia
+=item Asia
 
-   Armenia         ftp://sunsite.aua.am/pub/CPAN/
    China           ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
    Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
    Israel          ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
@@ -634,6 +882,7 @@ Asia
                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
+                   ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
                    ftp://mirror.nucba.ac.jp/mirror/Perl/
    Singapore       ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
    South Korea     ftp://ftp.bora.net/pub/CPAN/
@@ -643,8 +892,7 @@ Asia
    Thailand        ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
                    ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
 
-=item *
-Australasia
+=item Australasia
 
    Australia       ftp://cpan.topend.com.au/pub/CPAN/
                    ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
@@ -653,13 +901,11 @@ Australasia
    New Zealand     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
 
-=item *
 Central America
 
    Costa Rica      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
 
-=item *
-Europe
+=item Europe
 
    Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
    Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
@@ -686,8 +932,10 @@ Europe
    Ireland         ftp://sunsite.compapp.dcu.ie/pub/perl/
    Italy           ftp://cis.uniRoma2.it/CPAN/
                    ftp://ftp.flashnet.it/pub/CPAN/
+                   ftp://ftp.unina.it/pub/Other/CPAN/
                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
    Netherlands     ftp://ftp.cs.uu.nl/mirror/CPAN/
+                   ftp://ftp.EU.net/packages/cpan/
                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
    Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
@@ -696,10 +944,11 @@ Europe
                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
                    ftp://sunsite.icm.edu.pl/pub/CPAN/
    Portugal        ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
+                   ftp://ftp.ist.utl.pt/pub/CPAN/
                    ftp://ftp.ua.pt/pub/CPAN/
    Romania         ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
                    ftp://ftp.dnttm.ro/pub/CPAN/
-   Russia          ftp://cpan.npi.msu.su/CPAN/
+    Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
    Slovakia        ftp://ftp.entry.sk/pub/languages/perl/CPAN/
    Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
@@ -714,11 +963,11 @@ Europe
                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
                    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
 
-=item *
-North America
+=item North America
 
    Alberta         ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
-   California      ftp://ftp.cdrom.com/pub/perl/CPAN/
+    California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
+                   ftp://ftp.cdrom.com/pub/perl/CPAN/
                    ftp://ftp.digital.com/pub/plan/perl/CPAN/
    Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
    Florida         ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
@@ -728,30 +977,30 @@ North America
    Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
    Massachusetts   ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
-   Mexico D.F.     ftp://ftp.msg.com.mx/pub/CPAN/
+    Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
+    Minnesota      ftp://ftp.midearthbbs.com/CPAN/
    New York        ftp://ftp.rge.com/pub/languages/perl/
    North Carolina  ftp://ftp.duke.edu/pub/perl/
    Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
-   Ontario         ftp://ftp.crc.ca/pub/packages/perl/CPAN/
+    Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
    Oregon          ftp://ftp.orst.edu/pub/packages/CPAN/
    Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
    Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
    Utah            ftp://mirror.xmission.com/CPAN/
    Virginia        ftp://ftp.perl.org/pub/perl/CPAN/
                    ftp://ruff.cs.jmu.edu/pub/CPAN/
-   Washington      ftp://ftp.spu.edu/pub/CPAN/
+    Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
+                   ftp://ftp.spu.edu/pub/CPAN/
 
-=item *
-South America
+=item South America
 
    Brazil          ftp://cpan.if.usp.br/pub/mirror/CPAN/
-   Chile           ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/
-                   ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
+    Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
 
 =back
 
 For an up-to-date listing of CPAN sites,
-see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
+see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
 
 =head1 Modules: Creation, Use, and Abuse
 
@@ -795,6 +1044,8 @@ scheme as the original author.
 
 =item Try to design the new module to be easy to extend and reuse.
 
+Always use B<-w>.  
+
 Use blessed references.  Use the two argument form of bless to bless
 into the class name given as the first parameter of the constructor,
 e.g.,:
@@ -819,7 +1070,7 @@ appropriate.  Split large methods into smaller more flexible ones.
 Inherit methods from other modules if appropriate.
 
 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
-Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
+Generally you can delete the C<eq 'FOO'> part with no harm at all.
 Let the objects look after themselves! Generally, avoid hard-wired
 class names as far as possible.
 
@@ -833,7 +1084,7 @@ the module after __END__ either using AutoSplit or by saying:
  eval join('',<main::DATA>) || die $@ unless caller();
 
 Does your module pass the 'empty subclass' test? If you say
-"C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able
+C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
 does your application still work if you change:  C<$obj = new YOURCLASS;>
 into: C<$obj = new SUBCLASS;> ?
@@ -842,11 +1093,18 @@ Avoid keeping any state information in your packages. It makes it
 difficult for multiple other packages to use yours. Keep state
 information in objects.
 
-Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
+Always use B<-w>.  
+
+Try to C<use strict;> (or C<use strict qw(...);>).
 Remember that you can add C<no strict qw(...);> to individual blocks
-of code that need less strictness. Always use B<-w>. Always use B<-w>!
+of code that need less strictness.  
+
+Always use B<-w>.  
+
 Follow the guidelines in the perlstyle(1) manual.
 
+Always use B<-w>.
+
 =item Some simple style guidelines
 
 The perlstyle manual supplied with Perl has many helpful points.
@@ -1016,7 +1274,7 @@ should store your module's version number in a non-my package
 variable called $VERSION.  This should be a floating point
 number with at least two digits after the decimal (i.e., hundredths,
 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
-See Exporter.pm in Perl5.001m or later for details.
+See L<Exporter> for details.
 
 It may be handy to add a function or method to retrieve the number.
 Use the number in announcements and archive file names when
@@ -1030,7 +1288,7 @@ module (or the module itself if small) to the comp.lang.perl.announce
 Usenet newsgroup.  This will at least ensure very wide once-off
 distribution.
 
-If possible you should place the module into a major ftp archive and
+If possible, register the module with CPAN.  You should 
 include details of its location in your announcement.
 
 Some notes about ftp archives: Please use a long descriptive file
@@ -1065,7 +1323,7 @@ Please remember to send me an updated entry for the Module list!
 
 Always strive to remain compatible with previous released versions.
 Otherwise try to add a mechanism to revert to the
-old behaviour if people rely on it. Document incompatible changes.
+old behavior if people rely on it.  Document incompatible changes.
 
 =back
 
@@ -1091,8 +1349,8 @@ it worth it unless you plan to make other changes at the same time?
 =item Make the most of the opportunity.
 
 If you are going to convert the script to a module you can use the
-opportunity to redesign the interface. The 'Guidelines for Module
-Creation' above include many of the issues you should consider.
+opportunity to redesign the interface.  The guidelines for module
+creation above include many of the issues you should consider.
 
 =item The pl2pm utility will get you started.
 
index a997ae0..137896f 100644 (file)
@@ -7,7 +7,7 @@ perlobj - Perl objects
 First of all, you need to understand what references are in Perl.
 See L<perlref> for that.  Second, if you still find the following
 reference work too complicated, a tutorial on object-oriented programming
-in Perl can be found in L<perltoot>.
+in Perl can be found in L<perltoot> and L<perltootc>.
 
 If you're still with us, then
 here are three very simple definitions that you should find reassuring.
@@ -115,12 +115,13 @@ reference as an ordinary reference.  Outside the class package,
 the reference is generally treated as an opaque value that may
 be accessed only through the class's methods.
 
-A constructor may re-bless a referenced object currently belonging to
-another class, but then the new class is responsible for all cleanup
-later.  The previous blessing is forgotten, as an object may belong
-to only one class at a time.  (Although of course it's free to
-inherit methods from many classes.)  If you find yourself having to 
-do this, the parent class is probably misbehaving, though.
+Although a a constructor can in theory re-bless a referenced object
+currently belonging to another class, this is almost certainly going
+to get you into trouble.  The new class is responsible for all
+cleanup later.  The previous blessing is forgotten, as an object
+may belong to only one class at a time.  (Although of course it's
+free to inherit methods from many classes.)  If you find yourself
+having to do this, the parent class is probably misbehaving, though.
 
 A clarification:  Perl objects are blessed.  References are not.  Objects
 know which package they belong to.  References do not.  The bless()
@@ -186,16 +187,16 @@ is to prepend your fieldname in the hash with the package name.
 Unlike say C++, Perl doesn't provide any special syntax for method
 definition.  (It does provide a little syntax for method invocation
 though.  More on that later.)  A method expects its first argument
-to be the object (reference) or package (string) it is being invoked on.  There are just two
-types of methods, which we'll call class and instance.
-(Sometimes you'll hear these called static and virtual, in honor of
-the two C++ method types they most closely resemble.)
+to be the object (reference) or package (string) it is being invoked
+on.  There are two ways of calling methods, which we'll call class
+methods and instance methods.  
 
 A class method expects a class name as the first argument.  It
-provides functionality for the class as a whole, not for any individual
-object belonging to the class.  Constructors are typically class
-methods.  Many class methods simply ignore their first argument, because
-they already know what package they're in, and don't care what package
+provides functionality for the class as a whole, not for any
+individual object belonging to the class.  Constructors are often
+class methods, but see L<perltoot> and L<perltootc> for alternatives.
+Many class methods simply ignore their first argument, because they
+already know what package they're in and don't care what package
 they were invoked via.  (These aren't necessarily the same, because
 class methods follow the inheritance tree just like ordinary instance
 methods.)  Another typical use for class methods is to look up an
@@ -310,10 +311,59 @@ class.
 
 Sometimes you want to call a method when you don't know the method name
 ahead of time.  You can use the arrow form, replacing the method name
-with a simple scalar variable containing the method name:
+with a simple scalar variable containing the method name or a
+reference to the function.
 
     $method = $fast ? "findfirst" : "findbest";
-    $fred->$method(@args);
+    $fred->$method(@args);         # call by name
+
+    if ($coderef = $fred->can($parent . "::findbest")) {
+       $self->$coderef(@args);     # call by coderef
+    }
+
+=head2 WARNING
+
+While indirect object syntax may well be appealing to English speakers and
+to C++ programmers, be not seduced!  It suffers from two grave problems.
+
+The first problem is that an indirect object is limited to a name,
+a scalar variable, or a block, because it would have to do too much
+lookahead otherwise, just like any other postfix dereference in the
+language.  (These are the same quirky rules as are used for the filehandle
+slot in functions like C<print> and C<printf>.)  This can lead to horribly
+confusing precedence problems, as in these next two lines:
+
+    move $obj->{FIELD};                 # probably wrong!
+    move $ary[$i];                      # probably wrong!
+
+Those actually parse as the very surprising:
+
+    $obj->move->{FIELD};                # Well, lookee here
+    $ary->move->[$i];                   # Didn't expect this one, eh?
+
+Rather than what you might have expected:
+
+    $obj->{FIELD}->move();              # You should be so lucky.
+    $ary[$i]->move;                     # Yeah, sure.
+
+The left side of ``-E<gt>'' is not so limited, because it's an infix operator,
+not a postfix operator.  
+
+As if that weren't bad enough, think about this: Perl must guess I<at
+compile time> whether C<name> and C<move> above are functions or methods.
+Usually Perl gets it right, but when it doesn't it, you get a function
+call compiled as a method, or vice versa.  This can introduce subtle
+bugs that are hard to unravel.  For example, calling a method C<new>
+in indirect notation--as C++ programmers are so wont to do--can
+be miscompiled into a subroutine call if there's already a C<new>
+function in scope.  You'd end up calling the current package's C<new>
+as a subroutine, rather than the desired class's method.  The compiler
+tries to cheat by remembering bareword C<require>s, but the grief if it
+messes up just isn't worth the years of debugging it would likely take
+you to to track such subtle bugs down.
+
+The infix arrow notation using ``C<-E<gt>>'' doesn't suffer from either
+of these disturbing ambiguities, so we recommend you use it exclusively.
 
 =head2 Default UNIVERSAL methods
 
@@ -391,50 +441,6 @@ one are destroyed.  Such objects will be freed and destroyed automatically
 when the current object is freed, provided no other references to them exist
 elsewhere.
 
-=head2 WARNING
-
-While indirect object syntax may well be appealing to English speakers and
-to C++ programmers, be not seduced!  It suffers from two grave problems.
-
-The first problem is that an indirect object is limited to a name,
-a scalar variable, or a block, because it would have to do too much
-lookahead otherwise, just like any other postfix dereference in the
-language.  (These are the same quirky rules as are used for the filehandle
-slot in functions like C<print> and C<printf>.)  This can lead to horribly
-confusing precedence problems, as in these next two lines:
-
-    move $obj->{FIELD};                 # probably wrong!
-    move $ary[$i];                      # probably wrong!
-
-Those actually parse as the very surprising:
-
-    $obj->move->{FIELD};                # Well, lookee here
-    $ary->move->[$i];                   # Didn't expect this one, eh?
-
-Rather than what you might have expected:
-
-    $obj->{FIELD}->move();              # You should be so lucky.
-    $ary[$i]->move;                     # Yeah, sure.
-
-The left side of ``-E<gt>'' is not so limited, because it's an infix operator,
-not a postfix operator.  
-
-As if that weren't bad enough, think about this: Perl must guess I<at
-compile time> whether C<name> and C<move> above are functions or methods.
-Usually Perl gets it right, but when it doesn't it, you get a function
-call compiled as a method, or vice versa.  This can introduce subtle
-bugs that are hard to unravel.  For example, calling a method C<new>
-in indirect notation--as C++ programmers are so wont to do--can
-be miscompiled into a subroutine call if there's already a C<new>
-function in scope.  You'd end up calling the current package's C<new>
-as a subroutine, rather than the desired class's method.  The compiler
-tries to cheat by remembering bareword C<require>s, but the grief if it
-messes up just isn't worth the years of debugging it would likely take
-you to to track such subtle bugs down.
-
-The infix arrow notation using ``C<-E<gt>>'' doesn't suffer from either
-of these disturbing ambiguities, so we recommend you use it exclusively.
-
 =head2 Summary
 
 That's about all there is to it.  Now you need just to go off and buy a
@@ -547,8 +553,8 @@ breaks the circularities in the self-referential structure.
 
 =head1 SEE ALSO
 
-A kinder, gentler tutorial on object-oriented programming in Perl can
-be found in L<perltoot>.
-You should also check out L<perlbot> for other object tricks, traps, and tips,
-as well as L<perlmodlib> for some style guides on constructing both modules
+A kinder, gentler tutorial on object-oriented programming in Perl
+can be found in L<perltoot> and L<perltootc>.  You should also check
+out L<perlbot> for other object tricks, traps, and tips, as well
+as L<perlmodlib> for some style guides on constructing both modules
 and classes.
index 106b9a9..0f8117c 100644 (file)
@@ -5,11 +5,11 @@ perlop - Perl operators and precedence
 =head1 SYNOPSIS
 
 Perl operators have the following associativity and precedence,
-listed from highest precedence to lowest.  Note that all operators
-borrowed from C keep the same precedence relationship with each other,
-even where C's precedence is slightly screwy.  (This makes learning
-Perl easier for C folks.)  With very few exceptions, these all
-operate on scalar values only, not array values.
+listed from highest precedence to lowest.  Operators borrowed from
+C keep the same precedence relationship with each other, even where
+C's precedence is slightly screwy.  (This makes learning Perl easier
+for C folks.)  With very few exceptions, these all operate on scalar
+values only, not array values.
 
     left       terms and list operators (leftward)
     left       ->
@@ -64,11 +64,11 @@ For example, in
     @ary = (1, 3, sort 4, 2);
     print @ary;                # prints 1324
 
-the commas on the right of the sort are evaluated before the sort, but
-the commas on the left are evaluated after.  In other words, list
-operators tend to gobble up all the arguments that follow them, and
+the commas on the right of the sort are evaluated before the sort,
+but the commas on the left are evaluated after.  In other words,
+list operators tend to gobble up all arguments that follow, and
 then act like a simple TERM with regard to the preceding expression.
-Note that you have to be careful with parentheses:
+Be careful with parentheses:
 
     # These evaluate exit before doing the print:
     print($foo, exit); # Obviously not what you want.
@@ -95,16 +95,18 @@ as well as L<"I/O Operators">.
 
 =head2 The Arrow Operator
 
-Just as in C and C++, "C<-E<gt>>" is an infix dereference operator.  If the
-right side is either a C<[...]> or C<{...}> subscript, then the left side
-must be either a hard or symbolic reference to an array or hash (or
-a location capable of holding a hard reference, if it's an lvalue (assignable)).
-See L<perlref>.
+"C<-E<gt>>" is an infix dereference operator, just as it is in C
+and C++.  If the right side is either a C<[...]>, C<{...}>, or a
+C<(...)> subscript, then the left side must be either a hard or
+symbolic reference to an array, a hash, or a subroutine respectively.
+(Or technically speaking, a location capable of holding a hard
+reference, if it's an array or hash reference being used for
+assignment.)  See L<perlreftut> and L<perlref>.
 
-Otherwise, the right side is a method name or a simple scalar variable
-containing the method name, and the left side must either be an object
-(a blessed reference) or a class name (that is, a package name).
-See L<perlobj>.
+Otherwise, the right side is a method name or a simple scalar
+variable containing either the method name or a subroutine reference,
+and the left side must be either an object (a blessed reference)
+or a class name (that is, a package name).  See L<perlobj>.
 
 =head2 Auto-increment and Auto-decrement
 
@@ -129,7 +131,7 @@ The auto-decrement operator is not magical.
 
 =head2 Exponentiation
 
-Binary "**" is the exponentiation operator.  Note that it binds even more
+Binary "**" is the exponentiation operator.  It binds even more
 tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
 implemented using C's pow(3) function, which actually works on doubles
 internally.)
@@ -155,10 +157,10 @@ syntactically for separating a function name from a parenthesized expression
 that would otherwise be interpreted as the complete list of function
 arguments.  (See examples above under L<Terms and List Operators (Leftward)>.)
 
-Unary "\" creates a reference to whatever follows it.  See L<perlref>.
-Do not confuse this behavior with the behavior of backslash within a
-string, although both forms do convey the notion of protecting the next
-thing from interpretation.
+Unary "\" creates a reference to whatever follows it.  See L<perlreftut>
+and L<perlref>.  Do not confuse this behavior with the behavior of
+backslash within a string, although both forms do convey the notion
+of protecting the next thing from interpolation.
 
 =head2 Binding Operators
 
@@ -384,23 +386,26 @@ of B<sed>, B<awk>, and various editors.  Each ".." operator maintains its
 own boolean state.  It is false as long as its left operand is false.
 Once the left operand is true, the range operator stays true until the
 right operand is true, I<AFTER> which the range operator becomes false
-again.  (It doesn't become false till the next time the range operator is
+again.  It doesn't become false till the next time the range operator is
 evaluated.  It can test the right operand and become false on the same
 evaluation it became true (as in B<awk>), but it still returns true once.
-If you don't want it to test the right operand till the next evaluation
-(as in B<sed>), use three dots ("...") instead of two.)  The right
-operand is not evaluated while the operator is in the "false" state, and
-the left operand is not evaluated while the operator is in the "true"
-state.  The precedence is a little lower than || and &&.  The value
-returned is either the empty string for false, or a sequence number
-(beginning with 1) for true.  The sequence number is reset for each range
-encountered.  The final sequence number in a range has the string "E0"
-appended to it, which doesn't affect its numeric value, but gives you
-something to search for if you want to exclude the endpoint.  You can
-exclude the beginning point by waiting for the sequence number to be
-greater than 1.  If either operand of scalar ".." is a constant expression,
-that operand is implicitly compared to the C<$.> variable, the current
-line number.  Examples:
+If you don't want it to test the right operand till the next
+evaluation, as in B<sed>, just use three dots ("...") instead of
+two.  In all other regards, "..." behaves just like ".." does.
+
+The right operand is not evaluated while the operator is in the
+"false" state, and the left operand is not evaluated while the
+operator is in the "true" state.  The precedence is a little lower
+than || and &&.  The value returned is either the empty string for
+false, or a sequence number (beginning with 1) for true.  The
+sequence number is reset for each range encountered.  The final
+sequence number in a range has the string "E0" appended to it, which
+doesn't affect its numeric value, but gives you something to search
+for if you want to exclude the endpoint.  You can exclude the
+beginning point by waiting for the sequence number to be greater
+than 1.  If either operand of scalar ".." is a constant expression,
+that operand is implicitly compared to the C<$.> variable, the
+current line number.  Examples:
 
 As a scalar operator:
 
@@ -429,7 +434,7 @@ can say
 
     @alphabet = ('A' .. 'Z');
 
-to get all the letters of the alphabet, or
+to get all normal letters of the alphabet, or
 
     $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
 
@@ -464,8 +469,6 @@ legal lvalues (meaning that you can assign to them):
 
     ($a_or_b ? $a : $b) = $c;
 
-This is not necessarily guaranteed to contribute to the readability of your program.
-
 Because this operator produces an assignable result, using assignments
 without parentheses will get you in trouble.  For example, this:
 
@@ -479,6 +482,10 @@ Rather than this:
 
     ($a % 2) ? ($a += 10) : ($a += 2)
 
+That should probably be written more simply as:
+
+    $a += ($a % 2) ? 10 : 2;
+
 =head2 Assignment Operators
 
 "=" is the ordinary assignment operator.
@@ -500,7 +507,7 @@ The following are recognized:
            .=    %=    ^=
                 x=
 
-Note that while these are grouped by family, they all have the precedence
+Although these are grouped by family, they all have the precedence
 of assignment.
 
 Unlike in C, the assignment operator produces a valid lvalue.  Modifying
@@ -573,14 +580,14 @@ probably avoid using this for assignment, only for control flow.
     ($a = $b) or $c;           # really means this
     $a = $b || $c;             # better written this way
 
-However, when it's a list context assignment and you're trying to use
+However, when it's a list-context assignment and you're trying to use
 "||" for control flow, you probably need "or" so that the assignment
 takes higher precedence.
 
     @info = stat($file) || die;     # oops, scalar sense of stat!
     @info = stat($file) or die;     # better, now @info gets its due
 
-Then again, you could always use parentheses.
+Then again, you could always use parentheses. 
 
 Binary "xor" returns the exclusive-OR of the two surrounding expressions.
 It cannot short circuit, of course.
@@ -602,7 +609,7 @@ operators are typed: $, @, %, and &.)
 
 =item (TYPE)
 
-Type casting operator.
+Type-casting operator.
 
 =back
 
@@ -627,17 +634,17 @@ the same character fore and aft, but the 4 sorts of brackets
                 s{}{}      Substitution          yes (unless '' is delimiter)
                tr{}{}    Transliteration         no (but see below)
 
-Note that there can be whitespace between the operator and the quoting
+There can be whitespace between the operator and the quoting
 characters, except when C<#> is being used as the quoting character.
-C<q#foo#> is parsed as being the string C<foo>, while C<q #foo#> is the
-operator C<q> followed by a comment. Its argument will be taken from the
-next line. This allows you to write:
+C<q#foo#> is parsed as the string C<foo>, while C<q #foo#> is the
+operator C<q> followed by a comment.  Its argument will be taken
+from the next line.  This allows you to write:
 
     s {foo}  # Replace foo
       {bar}  # with bar.
 
-For constructs that do interpolation, variables beginning with "C<$>"
-or "C<@>" are interpolated, as are the following sequences. Within
+For constructs that do interpolate, variables beginning with "C<$>"
+or "C<@>" are interpolated, as are the following escape sequences.  Within
 a transliteration, the first eleven of these sequences may be used.
 
     \t         tab             (HT, TAB)
@@ -650,7 +657,7 @@ a transliteration, the first eleven of these sequences may be used.
     \033       octal char      (ESC)
     \x1b       hex char        (ESC)
     \x{263a}   wide hex char   (SMILEY)
-    \c[                control char
+    \c[                control char    (ESC)
 
     \l         lowercase next char
     \u         uppercase next char
@@ -664,7 +671,7 @@ and C<\U> is taken from the current locale.  See L<perllocale>.
 
 All systems use the virtual C<"\n"> to represent a line terminator,
 called a "newline".  There is no such thing as an unvarying, physical
-newline character.  It is an illusion that the operating system,
+newline character.  It is only an illusion that the operating system,
 device drivers, C libraries, and Perl all conspire to preserve.  Not all
 systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF.  For example,
 on a Mac, these are reversed, and on systems without line terminator,
@@ -687,28 +694,17 @@ interpolated, so that regular expressions may be incorporated into the
 pattern from the variables.  If this is not what you want, use C<\Q> to
 interpolate a variable literally.
 
-Apart from the above, there are no multiple levels of interpolation.  In
-particular, contrary to the expectations of shell programmers, back-quotes
-do I<NOT> interpolate within double quotes, nor do single quotes impede
-evaluation of variables when used within double quotes.
+Apart from the behavior described above, Perl does not expand
+multiple levels of interpolation.  In particular, contrary to the
+expectations of shell programmers, back-quotes do I<NOT> interpolate
+within double quotes, nor do single quotes impede evaluation of
+variables when used within double quotes.
 
 =head2 Regexp Quote-Like Operators
 
 Here are the quote-like operators that apply to pattern
 matching and related activities.
 
-Most of this section is related to use of regular expressions from Perl.
-Such a use may be considered from two points of view: Perl handles a
-a string and a "pattern" to RE (regular expression) engine to match, 
-RE engine finds (or does not find) the match, and Perl uses the findings 
-of RE engine for its operation, possibly asking the engine for other matches.
-
-RE engine has no idea what Perl is going to do with what it finds, 
-similarly, the rest of Perl has no idea what a particular regular expression 
-means to RE engine.  This creates a clean separation, and in this section
-we discuss matching from Perl point of view only.  The other point of
-view may be found in L<perlre>.
-
 =over 8
 
 =item ?PATTERN?
@@ -727,21 +723,22 @@ patterns local to the current package are reset.
        reset if eof;       # clear ?? status for next file
     }
 
-This usage is vaguely deprecated, and may be removed in some future
-version of Perl.
+This usage is vaguely depreciated, which means it just might possibly
+be removed in some distant future version of Perl, perhaps somewhere
+around the year 2168.
 
 =item m/PATTERN/cgimosx
 
 =item /PATTERN/cgimosx
 
 Searches a string for a pattern match, and in scalar context returns
-true (1) or false ('').  If no string is specified via the C<=~> or
-C<!~> operator, the $_ string is searched.  (The string specified with
-C<=~> need not be an lvalue--it may be the result of an expression
-evaluation, but remember the C<=~> binds rather tightly.)  See also
-L<perlre>.
-See L<perllocale> for discussion of additional considerations that apply
-when C<use locale> is in effect.
+true if it succeeds, false if it fails.  If no string is specified
+via the C<=~> or C<!~> operator, the $_ string is searched.  (The
+string specified with C<=~> need not be an lvalue--it may be the
+result of an expression evaluation, but remember the C<=~> binds
+rather tightly.)  See also L<perlre>.  See L<perllocale> for
+discussion of additional considerations that apply when C<use locale>
+is in effect.
 
 Options are:
 
@@ -755,11 +752,10 @@ Options are:
 
 If "/" is the delimiter then the initial C<m> is optional.  With the C<m>
 you can use any pair of non-alphanumeric, non-whitespace characters 
-as delimiters. This is particularly useful for matching Unix path names
-that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is
+as delimiters.  This is particularly useful for matching path names
+that contain "/", to avoid LTS (leaning toothpick syndrome).  If "?" is
 the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
-If "'" is the delimiter, no variable interpolation is performed on the
-PATTERN.
+If "'" is the delimiter, no interpolation is performed on the PATTERN.
 
 PATTERN may contain variables, which will be interpolated (and the
 pattern recompiled) every time the pattern search is evaluated, except
@@ -770,12 +766,12 @@ the trailing delimiter.  This avoids expensive run-time recompilations,
 and is useful when the value you are interpolating won't change over
 the life of the script.  However, mentioning C</o> constitutes a promise
 that you won't change the variables in the pattern.  If you change them,
-Perl won't even notice.
+Perl won't even notice.  See also L<qr//>.
 
 If the PATTERN evaluates to the empty string, the last
 I<successfully> matched regular expression is used instead.
 
-If the C</g> option is not used, C<m//> in list context returns a
+If the C</g> option is not used, C<m//> in list context returns a
 list consisting of the subexpressions matched by the parentheses in the
 pattern, i.e., (C<$1>, C<$2>, C<$3>...).  (Note that here C<$1> etc. are
 also set, and that this differs from Perl 4's behavior.)  When there are
@@ -805,15 +801,16 @@ remainder of the line, and assigns those three fields to $F1, $F2, and
 $Etc.  The conditional is true if any variables were assigned, i.e., if
 the pattern matched.
 
-The C</g> modifier specifies global pattern matching--that is, matching
-as many times as possible within the string.  How it behaves depends on
-the context.  In list context, it returns a list of all the
-substrings matched by all the parentheses in the regular expression.
-If there are no parentheses, it returns a list of all the matched
-strings, as if there were parentheses around the whole pattern.
+The C</g> modifier specifies global pattern matching--that is,
+matching as many times as possible within the string.  How it behaves
+depends on the context.  In list context, it returns a list of the
+substrings matched by any capturing parentheses in the regular
+expression.  If there are no parentheses, it returns a list of all
+the matched strings, as if there were parentheses around the whole
+pattern.
 
 In scalar context, each execution of C<m//g> finds the next match,
-returning TRUE if it matches, and FALSE if there is no further match.
+returning true if it matches, and false if there is no further match.
 The position after the last match can be read or set using the pos()
 function; see L<perlfunc/pos>.   A failed match normally resets the
 search position to the beginning of the string, but you can avoid that
@@ -823,8 +820,8 @@ string also resets the search position.
 You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
 zero-width assertion that matches the exact position where the previous
 C<m//g>, if any, left off.  The C<\G> assertion is not supported without
-the C</g> modifier; currently, without C</g>, C<\G> behaves just like
-C<\A>, but that's accidental and may change in the future.
+the C</g> modifier.  (Currently, without C</g>, C<\G> behaves just like
+C<\A>, but that's accidental and may change in the future.)
 
 Examples:
 
@@ -832,12 +829,10 @@ Examples:
     ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
 
     # scalar context
-    {
-       local $/ = "";
-       while (defined($paragraph = <>)) {
-           while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
-               $sentences++;
-           }
+    $/ = ""; $* = 1;  # $* deprecated in modern perls
+    while (defined($paragraph = <>)) {
+       while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
+           $sentences++;
        }
     }
     print "$sentences\n";
@@ -893,7 +888,7 @@ Here is the output (split into several lines):
 
 =item C<'STRING'>
 
-A single-quoted, literal string. A backslash represents a backslash
+A single-quoted, literal string.  A backslash represents a backslash
 unless followed by the delimiter or another backslash, in which case
 the delimiter or backslash is interpolated.
 
@@ -909,15 +904,16 @@ A double-quoted, interpolated string.
 
     $_ .= qq
      (*** The previous line contains the naughty word "$1".\n)
-               if /(tcl|rexx|python)/;      # :-)
+               if /\b(tcl|java|python)\b/i;      # :-)
     $baz = "\n";               # a one-character string
 
 =item qr/STRING/imosx
 
-Quote-as-a-regular-expression operator.  I<STRING> is interpolated the
-same way as I<PATTERN> in C<m/PATTERN/>.  If "'" is used as the
-delimiter, no variable interpolation is done.  Returns a Perl value
-which may be used instead of the corresponding C</STRING/imosx> expression.
+This operators quotes--and compiles--its I<STRING> as a regular
+expression.  I<STRING> is interpolated the same way as I<PATTERN>
+in C<m/PATTERN/>.  If "'" is used as the delimiter, no interpolation
+is done.  Returns a Perl value which may be used instead of the
+corresponding C</STRING/imosx> expression.
 
 For example,
 
@@ -936,7 +932,7 @@ The result may be used as a subpattern in a match:
     $string =~ /$re/;          # or this way
 
 Since Perl may compile the pattern at the moment of execution of qr()
-operator, using qr() may have speed advantages in I<some> situations,
+operator, using qr() may have speed advantages in some situations,
 notably if the result of qr() is used standalone:
 
     sub match {
@@ -951,11 +947,11 @@ notably if the result of qr() is used standalone:
        } @_;
     }
 
-Precompilation of the pattern into an internal representation at the
-moment of qr() avoids a need to recompile the pattern every time a
-match C</$pat/> is attempted.  (Note that Perl has many other
-internal optimizations, but none would be triggered in the above
-example if we did not use qr() operator.)
+Precompilation of the pattern into an internal representation at
+the moment of qr() avoids a need to recompile the pattern every
+time a match C</$pat/> is attempted.  (Perl has many other internal
+optimizations, but none would be triggered in the above example if
+we did not use qr() operator.)
 
 Options are:
 
@@ -1012,7 +1008,7 @@ double-quote interpolation, passing it on to the shell instead:
     $perl_info  = qx(ps $$);            # that's Perl's $$
     $shell_info = qx'ps $$';            # that's the new shell's $$
 
-Note that how the string gets evaluated is entirely subject to the command
+How that string gets evaluated is entirely subject to the command
 interpreter on your system.  On most platforms, you will have to protect
 shell metacharacters if you want them treated literally.  This is in
 practice difficult to do, as it's unclear how to escape which characters.
@@ -1064,10 +1060,10 @@ Some frequently seen examples:
     use POSIX qw( setlocale localeconv )
     @EXPORT = qw( foo bar baz );
 
-A common mistake is to try to separate the words with comma or to put
-comments into a multi-line C<qw>-string.  For this reason the C<-w>
-switch produce warnings if the STRING contains the "," or the "#"
-character.
+A common mistake is to try to separate the words with comma or to
+put comments into a multi-line C<qw>-string.  For this reason, the
+B<-w> switch (that is, the C<$^W> variable) produces warnings if
+the STRING contains the "," or the "#" character.
 
 =item s/PATTERN/REPLACEMENT/egimosx
 
@@ -1080,7 +1076,7 @@ variable is searched and modified.  (The string specified with C<=~> must
 be scalar variable, an array element, a hash element, or an assignment
 to one of those, i.e., an lvalue.)
 
-If the delimiter chosen is a single quote, no variable interpolation is
+If the delimiter chosen is a single quote, no interpolation is
 done on either the PATTERN or the REPLACEMENT.  Otherwise, if the
 PATTERN contains a $ that looks like a variable rather than an
 end-of-string test, the variable will be interpolated into the pattern
@@ -1163,16 +1159,14 @@ B<sed>, we use the \E<lt>I<digit>E<gt> form in only the left hand side.
 Anywhere else it's $E<lt>I<digit>E<gt>.
 
 Occasionally, you can't use just a C</g> to get all the changes
-to occur.  Here are two common cases:
+to occur that you might want.  Here are two common cases:
 
     # put commas in the right places in an integer
-    1 while s/(.*\d)(\d\d\d)/$1,$2/g;      # perl4
-    1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;  # perl5
+    1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;  
 
     # expand tabs to 8-column spacing
     1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
 
-
 =item tr/SEARCHLIST/REPLACEMENTLIST/cdsUC
 
 =item y/SEARCHLIST/REPLACEMENTLIST/cdsUC
@@ -1206,14 +1200,14 @@ Options:
     U  Translate to/from UTF-8.
     C  Translate to/from 8-bit char (octet).
 
-If the C</c> modifier is specified, the SEARCHLIST character set is
-complemented.  If the C</d> modifier is specified, any characters specified
-by SEARCHLIST not found in REPLACEMENTLIST are deleted.  (Note
-that this is slightly more flexible than the behavior of some B<tr>
-programs, which delete anything they find in the SEARCHLIST, period.)
-If the C</s> modifier is specified, sequences of characters that were
-transliterated to the same character are squashed down to a single instance of the
-character.
+If the C</c> modifier is specified, the SEARCHLIST character set
+is complemented.  If the C</d> modifier is specified, any characters
+specified by SEARCHLIST not found in REPLACEMENTLIST are deleted.
+(Note that this is slightly more flexible than the behavior of some
+B<tr> programs, which delete anything they find in the SEARCHLIST,
+period.) If the C</s> modifier is specified, sequences of characters
+that were transliterated to the same character are squashed down
+to a single instance of the character.
 
 If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
 exactly as specified.  Otherwise, if the REPLACEMENTLIST is shorter
@@ -1245,19 +1239,20 @@ Examples:
     tr [\200-\377]
        [\000-\177];            # delete 8th bit
 
-    tr/\0-\xFF//CU;            # translate Latin-1 to Unicode
-    tr/\0-\x{FF}//UC;          # translate Unicode to Latin-1
+    tr/\0-\xFF//CU;            # change Latin-1 to Unicode
+    tr/\0-\x{FF}//UC;          # change Unicode to Latin-1
 
-If multiple transliterations are given for a character, only the first one is used:
+If multiple transliterations are given for a character, only the
+first one is used:
 
     tr/AAA/XYZ/
 
 will transliterate any A to X.
 
-Note that because the transliteration table is built at compile time, neither
+Because the transliteration table is built at compile time, neither
 the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
-interpolation.  That means that if you want to use variables, you must use
-an eval():
+interpolation.  That means that if you want to use variables, you
+must use an eval():
 
     eval "tr/$oldlist/$newlist/";
     die $@ if $@;
@@ -1268,52 +1263,52 @@ an eval():
 
 =head2 Gory details of parsing quoted constructs
 
-When presented with something which may have several different 
-interpretations, Perl uses the principle B<DWIM> (expanded to Do What I Mean 
-- not what I wrote) to pick up the most probable interpretation of the 
-source.  This strategy is so successful that Perl users usually do not
-suspect ambivalence of what they write.  However, time to time Perl's ideas
-differ from what the author meant.  
-
-The target of this section is to clarify the Perl's way of interpreting
-quoted constructs.  The most frequent reason one may have to want to know the 
-details discussed in this section is hairy regular expressions.  However, the 
-first steps of parsing are the same for all Perl quoting operators, so here
-they are discussed together.
-
-The most important detail of Perl parsing rules is the first one
-discussed below; when processing a quoted construct, Perl I<first>
-finds the end of the construct, then it interprets the contents of the
-construct.  If you understand this rule, you may skip the rest of this
-section on the first reading.  The other rules would
-contradict user's expectations much less frequently than the first one.
-
-Some of the passes discussed below are performed concurrently, but as 
-far as results are the same, we consider them one-by-one.  For different
-quoting constructs Perl performs different number of passes, from
-one to five, but they are always performed in the same order.
+When presented with something that might have several different
+interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
+principle to pick the most probable interpretation.  This strategy
+is so successful that Perl programmers often do not suspect the
+ambivalence of what they write.  But from time to time, Perl's
+notions differ substantially from what the author honestly meant.
+
+This section hopes to clarify how Perl handles quoted constructs.
+Although the most common reason to learn this is to unravel labyrinthine
+regular expressions, because the initial steps of parsing are the
+same for all quoting operators, they are all discussed together.
+
+The most important Perl parsing rule is the first one discussed
+below: when processing a quoted construct, Perl first finds the end
+of that construct, then interprets its contents.  If you understand
+this rule, you may skip the rest of this section on the first
+reading.  The other rules are likely to contradict the user's
+expectations much less frequently than this first one.
+
+Some passes discussed below are performed concurrently, but because
+their results are the same, we consider them individually.  For different
+quoting constructs, Perl performs different numbers of passes, from
+one to five, but these passes are always performed in the same order.
 
 =over
 
 =item Finding the end
 
-First pass is finding the end of the quoted construct, be it 
-a multichar delimiter
-C<"\nEOF\n"> of C<<<EOF> construct, C</> which terminates C<qq/> construct,
-C<]> which terminates C<qq[> construct, or C<E<gt>> which terminates a
-fileglob started with C<<>.
+The first pass is finding the end of the quoted construct, whether
+it be a multicharacter delimiter C<"\nEOF\n"> in the C<<<EOF>
+construct, a C</> that terminates a C<qq//> construct, a C<]> which
+terminates C<qq[]> construct, or a C<E<gt>> which terminates a
+fileglob started with C<E<lt>>.
 
-When searching for one-char non-matching delimiter, such as C</>, combinations
-C<\\> and C<\/> are skipped.  When searching for one-char matching delimiter,
-such as C<]>, combinations C<\\>, C<\]> and C<\[> are skipped, and 
-nested C<[>, C<]> are skipped as well.  When searching for multichar delimiter
-no skipping is performed.  
+When searching for single-character non-pairing delimiters, such
+as C</>, combinations of C<\\> and C<\/> are skipped.  However,
+when searching for single-character pairing delimiter like C<[>,
+combinations of C<\\>, C<\]>, and C<\[> are all skipped, and nested
+C<[>, C<]> are skipped as well.  When searching for multicharacter
+delimiters, nothing is skipped.
 
-For constructs with 3-part delimiters (C<s///> etc.) the search is
-repeated once more.
+For constructs with three-part delimiters (C<s///>, C<y///>, and
+C<tr///>), the search is repeated once more.
 
-During this search no attention is paid to the semantic of the construct,
-thus:
+During this search no attention is paid to the semantics of the construct.
+Thus:
 
     "$hash{"$foo/$bar"}"
 
@@ -1323,30 +1318,28 @@ or:
       bar      # NOT a comment, this slash / terminated m//!
      /x
 
-do not form legal quoted expressions, the quoted part ends on the first C<">
-and C</>, and the rest happens to be a syntax error.  Note that since the slash
-which terminated C<m//> was followed by a C<SPACE>, the above is not C<m//x>, 
-but rather C<m//> with no 'x' switch.  So the embedded C<#> is interpreted
-as a literal C<#>.
+do not form legal quoted expressions.   The quoted part ends on the
+first C<"> and C</>, and the rest happens to be a syntax error.
+Because the slash that terminated C<m//> was followed by a C<SPACE>,
+the example above is not C<m//x>, but rather C<m//> with no C</x>
+modifier.  So the embedded C<#> is interpreted as a literal C<#>.
 
 =item Removal of backslashes before delimiters
 
-During the second pass the text between the starting delimiter and 
-the ending delimiter is copied to a safe location, and the C<\> is 
-removed from combinations consisting of C<\> and delimiter(s) (both starting
-and ending delimiter if they differ).
-
-The removal does not happen for multi-char delimiters.
-
-Note that the combination C<\\> is left as it was!
+During the second pass, text between the starting and ending
+delimiters is copied to a safe location, and the C<\> is removed
+from combinations consisting of C<\> and delimiter--or delimiters,
+meaning both starting and ending delimiters will should these differ.
+This removal does not happen for multi-character delimiters.
+Note that the combination C<\\> is left intact, just as it was.
 
-Starting from this step no information about the delimiter(s) is used in the
-parsing.
+Starting from this step no information about the delimiters is
+used in parsing.
 
 =item Interpolation
 
-Next step is interpolation in the obtained delimiter-independent text.
-There are four different cases.
+The next step is interpolation in the text obtained, which is now
+delimiter-independent.  There are four different cases.
 
 =over
 
@@ -1360,44 +1353,40 @@ The only interpolation is removal of C<\> from pairs C<\\>.
 
 =item C<"">, C<``>, C<qq//>, C<qx//>, C<<file*globE<gt>>
 
-C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> (possibly paired with C<\E>) are converted
-to corresponding Perl constructs, thus C<"$foo\Qbaz$bar"> is converted to :
-
-   $foo . (quotemeta("baz" . $bar));
-
-Other combinations of C<\> with following chars are substituted with
-appropriate expansions.
+C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> (possibly paired with C<\E>) are
+converted to corresponding Perl constructs.  Thus, C<"$foo\Qbaz$bar">
+is converted to C<$foo . (quotemeta("baz" . $bar))> internally.
+The other combinations are replaced with appropriate expansions.
 
-Let it be stressed that I<whatever is between C<\Q> and C<\E>> is interpolated
-in the usual way.  Say, C<"\Q\\E"> has no C<\E> inside: it has C<\Q>, C<\\>,
-and C<E>, thus the result is the same as for C<"\\\\E">.  Generally speaking,
-having backslashes between C<\Q> and C<\E> may lead to counterintuitive
-results.  So, C<"\Q\t\E"> is converted to:
-
-  quotemeta("\t")
-
-which is the same as C<"\\\t"> (since TAB is not alphanumerical).  Note also
-that:
+Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
+is interpolated in the usual way.  Something like C<"\Q\\E"> has
+no C<\E> inside.  instead, it has C<\Q>, C<\\>, and C<E>, so the
+result is the same as for C<"\\\\E">.  As a general rule, backslashes
+between C<\Q> and C<\E> may lead to counterintuitive results.  So,
+C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
+as C<"\\\t"> (since TAB is not alphanumeric).  Note also that:
 
   $str = '\t';
   return "\Q$str";
 
 may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
 
-Interpolated scalars and arrays are internally converted to the C<join> and
-C<.> Perl operations, thus C<"$foo >>> '@arr'"> becomes:
+Interpolated scalars and arrays are converted internally to the C<join> and
+C<.> catentation operations.  Thus, C<"$foo XXX '@arr'"> becomes:
 
-  $foo . " >>> '" . (join $", @arr) . "'";
+  $foo . " XXX '" . (join $", @arr) . "'";
 
-All the operations in the above are performed simultaneously left-to-right.
+All operations above are performed simultaneously, left to right.
 
-Since the result of "\Q STRING \E" has all the metacharacters quoted
-there is no way to insert a literal C<$> or C<@> inside a C<\Q\E> pair: if
-protected by C<\> C<$> will be quoted to became "\\\$", if not, it is 
-interpreted as starting an interpolated scalar.
+Because the result of C<"\Q STRING \E"> has all metacharacters
+quoted, there is no way to insert a literal C<$> or C<@> inside a
+C<\Q\E> pair.  If protected by C<\>, C<$> will be quoted to became
+C<"\\\$">; if not, it is interpreted as the start of an interpolated
+scalar.
 
-Note also that the interpolating code needs to make a decision on where the 
-interpolated scalar ends. For instance, whether C<"a $b -E<gt> {c}"> means:
+Note also that the interpolation code needs to make a decision on
+where the interpolated scalar ends.  For instance, whether 
+C<"a $b -E<gt> {c}"> really means:
 
   "a " . $b . " -> {c}";
 
@@ -1405,99 +1394,108 @@ or:
 
   "a " . $b -> {c};
 
-I<Most of the time> the decision is to take the longest possible text which
-does not include spaces between components and contains matching
-braces/brackets.  Since the outcome may be determined by I<voting> based
-on heuristic estimators, the result I<is not strictly predictable>, but
-is usually correct for the ambiguous cases.
+Most of the time, the longest possible text that does not include
+spaces between components and which contains matching braces or
+brackets.  because the outcome may be determined by voting based
+on heuristic estimators, the result is not strictly predictable.
+Fortunately, it's usually correct for ambiguous cases.
 
 =item C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>, 
 
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> and interpolation happens 
-(almost) as with C<qq//> constructs, but I<the substitution of C<\> followed by
-RE-special chars (including C<\>) is not performed>!  Moreover, 
-inside C<(?{BLOCK})>, C<(?# comment )>, and C<#>-comment of
-C<//x>-regular expressions no processing is performed at all.
-This is the first step where presence of the C<//x> switch is relevant.
-
-Interpolation has several quirks: C<$|>, C<$(> and C<$)> are not interpolated, and
-constructs C<$var[SOMETHING]> are I<voted> (by several different estimators) 
-to be an array element or C<$var> followed by a RE alternative.  This is
-the place where the notation C<${arr[$bar]}> comes handy: C</${arr[0-9]}/>
-is interpreted as an array element C<-9>, not as a regular expression from
-variable C<$arr> followed by a digit, which is the interpretation of 
-C</$arr[0-9]/>.  Since voting among different estimators may be performed,
-the result I<is not predictable>.
-
-It is on this step that C<\1> is converted to C<$1> in the replacement
-text of C<s///>.
-
-Note that absence of processing of C<\\> creates specific restrictions on the
-post-processed text: if the delimiter is C</>, one cannot get the combination
-C<\/> into the result of this step: C</> will finish the regular expression,
-C<\/> will be stripped to C</> on the previous step, and C<\\/> will be left
-as is.  Since C</> is equivalent to C<\/> inside a regular expression, this
-does not matter unless the delimiter is a special character for the RE engine,
-as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>, or an alphanumeric char, as in:
+Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, and interpolation
+happens (almost) as with C<qq//> constructs, but the substitution
+of C<\> followed by RE-special chars (including C<\>) is not
+performed.  Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
+a C<#>-comment in a C<//x>-regular expression, no processing is
+performed whatsoever.  This is the first step at which the presence
+of the C<//x> modifier is relevant.
+
+Interpolation has several quirks: C<$|>, C<$(>, and C<$)> are not
+interpolated, and constructs C<$var[SOMETHING]> are voted (by several
+different estimators) to be either an array element or C<$var>
+followed by an RE alternative.  This is where the notation
+C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
+array element C<-9>, not as a regular expression from the variable
+C<$arr> followed by a digit, which would be the interpretation of
+C</$arr[0-9]/>.  Since voting among different estimators may occur,
+the result is not predictable.
+
+It is at this step that C<\1> is begrudgingly converted to C<$1> in
+the replacement text of C<s///> to correct the incorrigible
+I<sed> hackers who haven't picked up the saner idiom yet.  A warning
+is emitted if the B<-w> command-line flag (that is, the C<$^W> variable)
+was set.
+
+The lack of processing of C<\\> creates specific restrictions on
+the post-processed text.  If the delimiter is C</>, one cannot get
+the combination C<\/> into the result of this step.  C</> will
+finish the regular expression, C<\/> will be stripped to C</> on
+the previous step, and C<\\/> will be left as is.  Because C</> is
+equivalent to C<\/> inside a regular expression, this does not
+matter unless the delimiter happens to be character special to the
+RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>; or an
+alphanumeric char, as in:
 
   m m ^ a \s* b mmx;
 
-In the above RE, which is intentionally obfuscated for illustration, the
+In the RE above, which is intentionally obfuscated for illustration, the
 delimiter is C<m>, the modifier is C<mx>, and after backslash-removal the
-RE is the same as for C<m/ ^ a s* b /mx>).
+RE is the same as for C<m/ ^ a s* b /mx>).  There's more than one 
+reason you're encouraged to restrict your delimiters to non-alphanumeric,
+non-whitespace choices.
 
 =back
 
-This step is the last one for all the constructs except regular expressions,
+This step is the last one for all constructs except regular expressions,
 which are processed further.
 
 =item Interpolation of regular expressions
 
-All the previous steps were performed during the compilation of Perl code,
-this one happens in run time (though it may be optimized to be calculated
-at compile time if appropriate).  After all the preprocessing performed 
-above (and possibly after evaluation if catenation, joining, up/down-casing 
-and C<quotemeta()>ing are involved) the resulting I<string> is passed to RE
-engine for compilation.
-
-Whatever happens in the RE engine is better be discussed in L<perlre>,
-but for the sake of continuity let us do it here.
-
-This is another step where presence of the C<//x> switch is relevant.
-The RE engine scans the string left-to-right, and converts it to a finite 
-automaton.  
-
-Backslashed chars are either substituted by corresponding literal 
-strings (as with C<\{>), or generate special nodes of the finite automaton
-(as with C<\b>).  Characters which are special to the RE engine (such as
-C<|>) generate corresponding nodes or groups of nodes.  C<(?#...)>
-comments are ignored.  All the rest is either converted to literal strings
-to match, or is ignored (as is whitespace and C<#>-style comments if
-C<//x> is present).
-
-Note that the parsing of the construct C<[...]> is performed using 
-rather different rules than for the rest of the regular expression.  
-The terminator of this construct is found using the same rules as for
-finding a terminator of a C<{}>-delimited construct, the only exception
-being that C<]> immediately following C<[> is considered as if preceded
-by a backslash.  Similarly, the terminator of C<(?{...})> is found using
-the same rules as for finding a terminator of a C<{}>-delimited construct.
-
-It is possible to inspect both the string given to RE engine, and the
-resulting finite automaton.  See arguments C<debug>/C<debugcolor>
-of C<use L<re>> directive, and/or B<-Dr> option of Perl in
-L<perlrun/Switches>.
+Previous steps were performed during the compilation of Perl code,
+but this one happens at run time--although it may be optimized to
+be calculated at compile time if appropriate.  After preprocessing
+described above, and possibly after evaluation if catenation,
+joining, casing translation, or metaquoting are involved, the
+resulting I<string> is passed to the RE engine for compilation.
+
+Whatever happens in the RE engine might be better discussed in L<perlre>,
+but for the sake of continuity, we shall do so here.
+
+This is another step where the presence of the C<//x> modifier is
+relevant.  The RE engine scans the string from left to right and
+converts it to a finite automaton.
+
+Backslashed characters are either replaced with corresponding
+literal strings (as with C<\{>), or else they generate special nodes
+in the finite automaton (as with C<\b>).  Characters special to the
+RE engine (such as C<|>) generate corresponding nodes or groups of
+nodes.  C<(?#...)> comments are ignored.  All the rest is either
+converted to literal strings to match, or else is ignored (as is
+whitespace and C<#>-style comments if C<//x> is present).
+
+Parsing of the bracketed character class construct, C<[...]>, is
+rather different than the rule used for the rest of the pattern.
+The terminator of this construct is found using the same rules as
+for finding the terminator of a C<{}>-delimited construct, the only
+exception being that C<]> immediately following C<[> is treated as
+though preceded by a backslash.  Similarly, the terminator of
+C<(?{...})> is found using the same rules as for finding the
+terminator of a C<{}>-delimited construct.
+
+It is possible to inspect both the string given to RE engine and the
+resulting finite automaton.  See the arguments C<debug>/C<debugcolor>
+in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
+switch documented in L<perlrun/Switches>.
 
 =item Optimization of regular expressions
 
 This step is listed for completeness only.  Since it does not change
 semantics, details of this step are not documented and are subject
-to change.  This step is performed over the finite automaton generated
-during the previous pass.
+to change without notice.  This step is performed over the finite
+automaton that was generated during the previous pass.
 
-However, in older versions of Perl C<L<split>> used to silently
-optimize C</^/> to mean C</^/m>.  This behaviour, though present
-in current versions of Perl, may be deprecated in future.
+It is at this stage that C<split()> silently optimizes C</^/> to
+mean C</^/m>.
 
 =back
 
@@ -1506,39 +1504,40 @@ in current versions of Perl, may be deprecated in future.
 There are several I/O operators you should know about.
 
 A string enclosed by backticks (grave accents) first undergoes
-variable substitution just like a double quoted string.  It is then
-interpreted as a command, and the output of that command is the value
-of the pseudo-literal, like in a shell.  In scalar context, a single
-string consisting of all the output is returned.  In list context,
-a list of values is returned, one for each line of output.  (You can
-set C<$/> to use a different line terminator.)  The command is executed
+double-quote interpolation.  It is then interpreted as an external
+command, and the output of that command is the value of the
+pseudo-literal, j
+string consisting of all output is returned.  In list context, a
+list of values is returned, one per line of output.  (You can set
+C<$/> to use a different line terminator.)  The command is executed
 each time the pseudo-literal is evaluated.  The status value of the
 command is returned in C<$?> (see L<perlvar> for the interpretation
 of C<$?>).  Unlike in B<csh>, no translation is done on the return
 data--newlines remain newlines.  Unlike in any of the shells, single
 quotes do not hide variable names in the command from interpretation.
-To pass a $ through to the shell you need to hide it with a backslash.
-The generalized form of backticks is C<qx//>.  (Because backticks
-always undergo shell expansion as well, see L<perlsec> for
-security concerns.)
-
-In a scalar context, evaluating a filehandle in angle brackets yields the
-next line from that file (newline, if any, included), or C<undef> at
-end-of-file.  When C<$/> is set to C<undef> (i.e. file slurp mode),
-and the file is empty, it returns C<''> the first time, followed by
-C<undef> subsequently.
-
-Ordinarily you must assign the returned value to a variable, but there is one
-situation where an automatic assignment happens.  I<If and ONLY if> the
-input symbol is the only thing inside the conditional of a C<while> or
-C<for(;;)> loop, the value is automatically assigned to the variable
-C<$_>.  In these loop constructs, the assigned value (whether assignment
-is automatic or explicit) is then tested to see if it is defined.
-The defined test avoids problems where line has a string value
-that would be treated as false by perl e.g. "" or "0" with no trailing
-newline. (This may seem like an odd thing to you, but you'll use the 
-construct in almost every Perl script you write.) Anyway, the following 
-lines are equivalent to each other:
+To pass a literal dollar-sign through to the shell you need to hide
+it with a backslash.  The generalized form of backticks is C<qx//>.
+(Because backticks always undergo shell expansion as well, see
+L<perlsec> for security concerns.)
+
+In scalar context, evaluating a filehandle in angle brackets yields
+the next line from that file (the newline, if any, included), or
+C<undef> at end-of-file or on error.  When C<$/> is set to C<undef>
+(sometimes known as file-slurp mode) and the file is empty, it
+returns C<''> the first time, followed by C<undef> subsequently.
+
+Ordinarily you must assign the returned value to a variable, but
+there is one situation where an automatic assignment happens.  If
+and only if the input symbol is the only thing inside the conditional
+of a C<while> statement (even if disguised as a C<for(;;)> loop),
+the value is automatically assigned to the global variable $_,
+destroying whatever was there previously.  (This may seem like an
+odd thing to you, but you'll use the construct in almost every Perl
+script you write.)  The $_ variables is not implicitly localized.
+You'll have to put a C<local $_;> before the loop if you want that
+to happen.
+
+The following lines are equivalent:
 
     while (defined($_ = <STDIN>)) { print; }
     while ($_ = <STDIN>) { print; }
@@ -1548,34 +1547,40 @@ lines are equivalent to each other:
     print while ($_ = <STDIN>);
     print while <STDIN>;
 
-and this also behaves similarly, but avoids the use of $_ :
+This also behaves similarly, but avoids $_ :
 
     while (my $line = <STDIN>) { print $line }    
 
-If you really mean such values to terminate the loop they should be 
-tested for explicitly:
+In these loop constructs, the assigned value (whether assignment
+is automatic or explicit) is then tested to see whether it is
+defined.  The defined test avoids problems where line has a string
+value that would be treated as false by Perl, for example a "" or
+a "0" with no trailing newline.  If you really mean for such values
+to terminate the loop, they should be tested for explicitly:
 
     while (($_ = <STDIN>) ne '0') { ... }
     while (<STDIN>) { last unless $_; ... }
 
-In other boolean contexts, C<E<lt>I<filehandle>E<gt>> without explicit C<defined>
-test or comparison will solicit a warning if C<-w> is in effect.
+In other boolean contexts, C<E<lt>I<filehandle>E<gt>> without an
+explicit C<defined> test or comparison elicit a warning if the B<-w>
+command-line switch (the C<$^W> variable) is in effect.
 
 The filehandles STDIN, STDOUT, and STDERR are predefined.  (The
-filehandles C<stdin>, C<stdout>, and C<stderr> will also work except in
-packages, where they would be interpreted as local identifiers rather
-than global.)  Additional filehandles may be created with the open()
-function.  See L<perlfunc/open> for details on this.
+filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
+in packages, where they would be interpreted as local identifiers
+rather than global.)  Additional filehandles may be created with
+the open() function, amongst others.  See L<perlopentut> and
+L<perlfunc/open> for details on this.
 
-If a E<lt>FILEHANDLEE<gt> is used in a context that is looking for a list, a
-list consisting of all the input lines is returned, one line per list
-element.  It's easy to make a I<LARGE> data space this way, so use with
-care.
+If a E<lt>FILEHANDLEE<gt> is used in a context that is looking for
+a list, a list comprising all input lines is returned, one line per
+list element.  It's easy to grow to a rather large data space this
+way, so use with care.
 
-E<lt>FILEHANDLEE<gt> may also be spelt readline(FILEHANDLE).  See
-L<perlfunc/readline>.
+E<lt>FILEHANDLEE<gt> may also be spelled C<readline(*FILEHANDLE)>.
+See L<perlfunc/readline>.
 
-The null filehandle E<lt>E<gt> is special and can be used to emulate the
+The null filehandle E<lt>E<gt> is special: it can be used to emulate the
 behavior of B<sed> and B<awk>.  Input from E<lt>E<gt> comes either from
 standard input, or from each file listed on the command line.  Here's
 how it works: the first time E<lt>E<gt> is evaluated, the @ARGV array is
@@ -1597,16 +1602,17 @@ is equivalent to the following Perl-like pseudo code:
        }
     }
 
-except that it isn't so cumbersome to say, and will actually work.  It
-really does shift array @ARGV and put the current filename into variable
-$ARGV.  It also uses filehandle I<ARGV> internally--E<lt>E<gt> is just a
-synonym for E<lt>ARGVE<gt>, which is magical.  (The pseudo code above
-doesn't work because it treats E<lt>ARGVE<gt> as non-magical.)
+except that it isn't so cumbersome to say, and will actually work.
+It really does shift the @ARGV array and put the current filename
+into the $ARGV variable.  It also uses filehandle I<ARGV>
+internally--E<lt>E<gt> is just a synonym for E<lt>ARGVE<gt>, which
+is magical.  (The pseudo code above doesn't work because it treats
+E<lt>ARGVE<gt> as non-magical.)
 
 You can modify @ARGV before the first E<lt>E<gt> as long as the array ends up
 containing the list of filenames you really want.  Line numbers (C<$.>)
-continue as if the input were one big happy file.  (But see example
-under C<eof> for how to reset line numbers on each file.)
+continue as though the input were one big happy file.  See the example
+in L<perlfunc/eof> for how to reset line numbers on each file.
 
 If you want to set @ARGV to your own list of files, go right ahead.  
 This sets @ARGV to all plain text files if no @ARGV was given:
@@ -1634,12 +1640,13 @@ Getopts modules or put a loop on the front like this:
     }
 
 The E<lt>E<gt> symbol will return C<undef> for end-of-file only once.  
-If you call it again after this it will assume you are processing another 
-@ARGV list, and if you haven't set @ARGV, will input from STDIN.
+If you call it again after this, it will assume you are processing another 
+@ARGV list, and if you haven't set @ARGV, will read input from STDIN.
 
-If the string inside the angle brackets is a reference to a scalar
-variable (e.g., E<lt>$fooE<gt>), then that variable contains the name of the
-filehandle to input from, or its typeglob, or a reference to the same.  For example:
+If angle brackets contain is a simple scalar variable (e.g.,
+E<lt>$fooE<gt>), then that variable contains the name of the
+filehandle to input from, or its typeglob, or a reference to the
+same.  For example:
 
     $fh = \*STDIN;
     $line = <$fh>;
@@ -1648,9 +1655,9 @@ If what's within the angle brackets is neither a filehandle nor a simple
 scalar variable containing a filehandle name, typeglob, or typeglob
 reference, it is interpreted as a filename pattern to be globbed, and
 either a list of filenames or the next filename in the list is returned,
-depending on context.   This distinction is determined on syntactic
-grounds alone.  That means C<E<lt>$xE<gt>> is always a readline from
-an indirect handle, but C<E<lt>$hash{key}E<gt>> is always a glob.
+depending on context.  This distinction is determined on syntactic
+grounds alone.  That means C<E<lt>$xE<gt>> is always a readline() from
+an indirect handle, but C<E<lt>$hash{key}E<gt>> is always a glob().
 That's because $x is a simple scalar variable, but C<$hash{key}> is
 not--it's a hash element.
 
@@ -1660,7 +1667,7 @@ in the previous paragraph.  (In older versions of Perl, programmers
 would insert curly brackets to force interpretation as a filename glob:
 C<E<lt>${foo}E<gt>>.  These days, it's considered cleaner to call the
 internal function directly as C<glob($foo)>, which is probably the right
-way to have done it in the first place.)  Example:
+way to have done it in the first place.)  For example:
 
     while (<*.c>) {
        chmod 0644, $_;
@@ -1674,27 +1681,31 @@ is equivalent to
        chmod 0644, $_;
     }
 
-In fact, it's currently implemented that way.  (Which means it will not
-work on filenames with spaces in them unless you have csh(1) on your
-machine.)  Of course, the shortest way to do the above is:
+In fact, it's currently implemented that way, but this is expected
+to be made completely internal in the near future.  (Which means
+it will not work on filenames with spaces in them unless you have
+csh(1) on your machine.)  Of course, the shortest way to do the
+above is:
 
     chmod 0644, <*.c>;
 
-Because globbing invokes a shell, it's often faster to call readdir() yourself
-and do your own grep() on the filenames.  Furthermore, due to its current
-implementation of using a shell, the glob() routine may get "Arg list too
-long" errors (unless you've installed tcsh(1L) as F</bin/csh>).
-
-A glob evaluates its (embedded) argument only when it is starting a new
-list.  All values must be read before it will start over.  In a list
-context this isn't important, because you automatically get them all
-anyway.  In scalar context, however, the operator returns the next value
-each time it is called, or a C<undef> value if you've just run out. As
-for filehandles an automatic C<defined> is generated when the glob
-occurs in the test part of a C<while> or C<for> - because legal glob returns
-(e.g. a file called F<0>) would otherwise terminate the loop.
-Again, C<undef> is returned only once.  So if you're expecting a single value 
-from a glob, it is much better to say
+Because globbing currently invokes a shell, it's often faster to
+call readdir() yourself and do your own grep() on the filenames.
+Furthermore, due to its current implementation of using a shell,
+the glob() routine may get "Arg list too long" errors (unless you've
+installed tcsh(1L) as F</bin/csh> or hacked your F<config.sh>).
+
+A (file)glob evaluates its (embedded) argument only when it is
+starting a new list.  All values must be read before it will start
+over.  In list context, this isn't important because you automatically
+get them all anyway.  However, in scalar context the operator returns
+the next value each time it's called, or C
+run out.  As with filehandle reads, an automatic C<defined> is
+generated when the glob occurs in the test part of a C<while>,
+because legal glob returns (e.g. a file called F<0>) would otherwise
+terminate the loop.  Again, C<undef> is returned only once.  So if
+you're expecting a single value from a glob, it is much better to
+say
 
     ($file) = <blurch*>;
 
@@ -1703,7 +1714,7 @@ than
     $file = <blurch*>;
 
 because the latter will alternate between returning a filename and
-returning FALSE.
+returning false.
 
 It you're trying to do variable interpolation, it's definitely better
 to use the glob() function, because the older notation can cause people
@@ -1715,10 +1726,10 @@ to become confused with the indirect filehandle notation.
 =head2 Constant Folding
 
 Like C, Perl does a certain amount of expression evaluation at
-compile time, whenever it determines that all arguments to an
+compile time whenever it determines that all arguments to an
 operator are static and have no side effects.  In particular, string
 concatenation happens at compile time between literals that don't do
-variable substitution.  Backslash interpretation also happens at
+variable substitution.  Backslash interpolation also happens at
 compile time.  You can say
 
     'Now is the time for all' . "\n" .
@@ -1731,20 +1742,20 @@ you say
        if (-s $file > 5 + 100 * 2**16) {  }
     }
 
-the compiler will precompute the number that
-expression represents so that the interpreter
-won't have to.
+the compiler will precompute the number which that expression
+represents so that the interpreter won't have to.
 
 =head2 Bitwise String Operators
 
 Bitstrings of any size may be manipulated by the bitwise operators
 (C<~ | & ^>).
 
-If the operands to a binary bitwise op are strings of different sizes,
-B<|> and B<^> ops will act as if the shorter operand had additional
-zero bits on the right, while the B<&> op will act as if the longer
-operand were truncated to the length of the shorter.  Note that the
-granularity for such extension or truncation is one or more I<bytes>.
+If the operands to a binary bitwise op are strings of different
+sizes, B<|> and B<^> ops act as though the shorter operand had
+additional zero bits on the right, while the B<&> op acts as though
+the longer operand were truncated to the length of the shorter.
+The granularity for such extension or truncation is one or more
+bytes.
 
     # ASCII-based examples 
     print "j p \n" ^ " a h";           # prints "JAPH\n"
@@ -1752,9 +1763,9 @@ granularity for such extension or truncation is one or more I<bytes>.
     print "japh\nJunk" & '_____';      # prints "JAPH\n";
     print 'p N$' ^ " E<H\n";           # prints "Perl\n";
 
-If you are intending to manipulate bitstrings, you should be certain that
+If you are intending to manipulate bitstrings, be certain that
 you're supplying bitstrings: If an operand is a number, that will imply
-a B<numeric> bitwise operation. You may explicitly show which type of
+a B<numeric> bitwise operation.  You may explicitly show which type of
 operation you intend by using C<""> or C<0+>, as in the examples below.
 
     $foo =  150  |  105 ;      # yields 255  (0x96 | 0x69 is 0xFF)
@@ -1770,33 +1781,39 @@ in a bit vector.
 
 =head2 Integer Arithmetic
 
-By default Perl assumes that it must do most of its arithmetic in
+By default, Perl assumes that it must do most of its arithmetic in
 floating point.  But by saying
 
     use integer;
 
 you may tell the compiler that it's okay to use integer operations
-from here to the end of the enclosing BLOCK.  An inner BLOCK may
-countermand this by saying
+(if it feels like it) from here to the end of the enclosing BLOCK.
+An inner BLOCK may countermand this by saying
 
     no integer;
 
-which lasts until the end of that BLOCK.
-
-The bitwise operators ("&", "|", "^", "~", "<<", and ">>") always
-produce integral results.  (But see also L<Bitwise String Operators>.)
-However, C<use integer> still has meaning
-for them.  By default, their results are interpreted as unsigned
-integers.  However, if C<use integer> is in effect, their results are
-interpreted as signed integers.  For example, C<~0> usually evaluates
-to a large integral value.  However, C<use integer; ~0> is -1 on twos-complement machines.
+which lasts until the end of that BLOCK.  Note that this doesn't
+mean everything is only an integer, merely that Perl may use integer
+operations if it is so inclined.  For example, even under C<use
+integer>, if you take the C<sqrt(2)>, you'll still get C<1.4142135623731>
+or so.
+
+Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<",
+and ">>") always produce integral results.  (But see also L<Bitwise
+String Operators>.)  However, C<use integer> still has meaning for
+them.  By default, their results are interpreted as unsigned integers, but
+if C<use integer> is in effect, their results are interpreted
+as signed integers.  For example, C<~0> usually evaluates to a large
+integral value.  However, C<use integer; ~0> is C<-1> on twos-complement
+machines.
 
 =head2 Floating-point Arithmetic
 
 While C<use integer> provides integer-only arithmetic, there is no
-similar ways to provide rounding or truncation at a certain number of
-decimal places.  For rounding to a certain number of digits, sprintf()
-or printf() is usually the easiest route.
+analogous mechanism to provide automatic rounding or truncation to a
+certain number of decimal places.  For rounding to a certain number
+of digits, sprintf() or printf() is usually the easiest route.
+See L<perlfaq4>.
 
 Floating-point numbers are only approximations to what a mathematician
 would call real numbers.  There are infinitely more reals than floats,
@@ -1820,10 +1837,10 @@ this topic.
     }
 
 The POSIX module (part of the standard perl distribution) implements
-ceil(), floor(), and a number of other mathematical and trigonometric
-functions.  The Math::Complex module (part of the standard perl
-distribution) defines a number of mathematical functions that can also
-work on real numbers.  Math::Complex not as efficient as POSIX, but
+ceil(), floor(), and other mathematical and trigonometric functions.
+The Math::Complex module (part of the standard perl distribution)
+defines mathematical functions that work on both the reals and the
+imaginary numbers.  Math::Complex not as efficient as POSIX, but
 POSIX can't work with complex numbers.
 
 Rounding in financial applications can have serious implications, and