Reorder perl.pod once more.
Jarkko Hietaniemi [Mon, 10 Jul 2000 14:02:12 +0000 (14:02 +0000)]
p4raw-id: //depot/cfgperl@6329

pod/buildtoc.PL
pod/perl.pod
pod/perltoc.pod

index 94b2ed1..e4a040a 100644 (file)
@@ -60,57 +60,58 @@ if (-d "pod") {
 }
 
 @pods = qw(
-    perl                
-    perlfaq             
-    perltoc             
-
-    perlsyn            
-    perldata            
-    perlop              
-    perlsub             
-    perlfunc            
-    perlreftut          
-    perldsc             
-    perllol             
-    perlrequick         
-    perlretut           
-
-    perlrun             
-    perllexwarn         
-    perldebug           
-
-    perlopentut         
-    perlvar             
-    perlmod             
-    perlpod             
-
-    perlstyle           
-    perlmodlib          
-    perlmodinstall      
-    perlnewmod          
-    perltrap            
-    perlport            
-    perlsec             
-
-    perlref             
-    perlre              
-    perlform            
-    perllocale          
-    perlunicode         
-
-    perlboot            
-    perltoot            
-    perltootc           
-    perlobj             
-    perlbot             
-    perltie             
-
-    perlipc             
-    perlnumber          
-    perlfork            
-    perlthrtut          
-
-    perldiag            
+    perl
+    perlfaq
+    perltoc
+
+    perlsyn
+    perldata
+    perlop
+    perlsub
+    perlfunc
+    perlreftut
+    perldsc
+    perlrequick
+    perlpod
+    perlstyle
+    perltrap
+
+    perlrun
+    perldiag
+    perllexwarn
+    perldebug
+
+    perlvar
+    perllol
+    perlopentut
+    perlretut
+
+    perlref
+    perlre
+    perlform
+    perllocale
+    perlunicode
+
+    perlipc
+    perlfork
+    perlnumber
+    perlthrtut
+
+    perlport
+    perlsec
+
+    perlboot
+    perltoot
+    perltootc
+    perlobj
+    perlbot
+    perltie
+
+    perlmod
+    perlmodlib
+    perlmodinstall
+    perlnewmod
+
     perlfaq1            
     perlfaq2            
     perlfaq3            
index 46b7f2b..2b3f5e4 100644 (file)
@@ -25,26 +25,20 @@ For ease of access, the Perl manual has been split up into several sections:
     perlfunc           Perl builtin functions
     perlreftut         Perl references short introduction
     perldsc            Perl data structures intro
-    perllol            Perl data structures: arrays of arrays
     perlrequick                Perl regular expressions quick start
-    perlretut          Perl regular expressions tutorial
+    perlpod            Perl plain old documentation
+    perlstyle          Perl style guide
+    perltrap           Perl traps for the unwary
 
     perlrun            Perl execution and options
+    perldiag           Perl diagnostic messages
     perllexwarn                Perl warnings and their control
     perldebug          Perl debugging
 
-    perlopentut                Perl open() tutorial
     perlvar            Perl predefined variables
-    perlmod            Perl modules: how they work
-    perlpod            Perl plain old documentation
-
-    perlstyle          Perl style guide
-    perlmodlib         Perl modules: how to write and use
-    perlmodinstall     Perl modules: how to install from CPAN
-    perlnewmod         Perl modules: preparing a new module for distribution
-    perltrap           Perl traps for the unwary
-    perlport           Perl portability guide
-    perlsec            Perl security
+    perllol            Perl data structures: arrays of arrays
+    perlopentut                Perl open() tutorial
+    perlretut          Perl regular expressions tutorial
 
     perlref            Perl references, the rest of the story
     perlre             Perl regular expressions, the rest of the story
@@ -52,6 +46,14 @@ For ease of access, the Perl manual has been split up into several sections:
     perllocale         Perl locale support
     perlunicode                Perl unicode support
 
+    perlipc            Perl interprocess communication
+    perlfork           Perl fork() information
+    perlnumber         Perl number semantics
+    perlthrtut         Perl threads tutorial
+
+    perlport           Perl portability guide
+    perlsec            Perl security
+
     perlboot           Perl OO tutorial for beginners
     perltoot           Perl OO tutorial, part 1
     perltootc          Perl OO tutorial, part 2
@@ -59,12 +61,11 @@ For ease of access, the Perl manual has been split up into several sections:
     perlbot            Perl OO tricks and examples
     perltie            Perl objects hidden behind simple variables
 
-    perlipc            Perl interprocess communication
-    perlnumber         Perl number semantics
-    perlfork           Perl fork() information
-    perlthrtut         Perl threads tutorial
+    perlmod            Perl modules: how they work
+    perlmodlib         Perl modules: how to write and use
+    perlmodinstall     Perl modules: how to install from CPAN
+    perlnewmod         Perl modules: preparing a new module for distribution
 
-    perldiag           Perl diagnostic messages
     perlfaq1           General Questions About Perl
     perlfaq2           Obtaining and Learning about Perl
     perlfaq3           Programming Tools
index e0031ce..9808e5f 100644 (file)
@@ -756,26 +756,6 @@ more elaborate constructs
 
 =back
 
-=head2 perllol - Manipulating Arrays of Arrays in Perl
-
-=over
-
-=item DESCRIPTION
-
-=item Declaration and Access of Arrays of Arrays
-
-=item Growing Your Own
-
-=item Access and Printing
-
-=item Slices
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
 =head2 perlrequick - Perl regular expressions quick start
 
 =over
@@ -833,141 +813,122 @@ times
 
 =back
 
-=head2 perlretut - Perl regular expressions tutorial
+=head2 perlpod - plain old documentation
 
 =over
 
 =item DESCRIPTION
 
-=item Part 1: The basics
-
 =over
 
-=item Simple word matching
+=item Verbatim Paragraph
 
-=item Using character classes
+=item Command Paragraph
 
-\d is a digit and represents [0-9], \s is a whitespace character and
-represents [\ \t\r\n\f], \w is a word character (alphanumeric or _) and
-represents [0-9a-zA-Z_], \D is a negated \d; it represents any character
-but a digit [^0-9], \S is a negated \s; it represents any non-whitespace
-character [^\s], \W is a negated \w; it represents any non-word character
-[^\w], The period '.' matches any character but "\n", no modifiers (//):
-Default behavior.  C<'.'> matches any character except C<"\n">.  C<^>
-matches only at the beginning of the string and C<$> matches only at the
-end or before a newline at the end, s modifier (//s): Treat string as a
-single long line.  C<'.'> matches any character, even C<"\n">. C<^>
-matches only at the beginning of the string and C<$> matches only at the
-end or before a newline at the end, m modifier (//m): Treat string as a set
-of multiple lines.  C<'.'> matches any character except C<"\n">.  C<^> and
-C<$> are able to match at the start or end of I<any> line within the
-string, both s and m modifiers (//sm): Treat string as a single long line,
-but detect multiple lines.  C<'.'> matches any character, even C<"\n">. 
-C<^> and C<$>, however, are able to match at the start or end of I<any>
-line within the string
+=item Ordinary Block of Text
 
-=item Matching this or that
+=item The Intent
 
-=item Grouping things and hierarchical matching
+=item Embedding Pods in Perl Modules
 
-0 Start with the first letter in the string 'a', 1 Try the first
-alternative in the first group 'abd', 2 Match 'a' followed by 'b'. So far
-so good, 3 'd' in the regexp doesn't match 'c' in the string - a dead end. 
-So backtrack two characters and pick the second alternative in the first
-group 'abc', 4 Match 'a' followed by 'b' followed by 'c'.  We are on a roll
-and have satisfied the first group. Set $1 to 'abc', 5 Move on to the
-second group and pick the first alternative 'df', 6 Match the 'd', 7 'f' in
-the regexp doesn't match 'e' in the string, so a dead end.  Backtrack one
-character and pick the second alternative in the second group 'd', 8 'd'
-matches. The second grouping is satisfied, so set $2 to 'd', 9 We are at
-the end of the regexp, so we are done! We have matched 'abcd' out of the
-string "abcde"
+=item Common Pod Pitfalls
 
-=item Extracting matches
+=back
 
-=item Matching repetitions
+=item SEE ALSO
 
-C<a?> = match 'a' 1 or 0 times, C<a*> = match 'a' 0 or more times, i.e.,
-any number of times, C<a+> = match 'a' 1 or more times, i.e., at least
-once, C<a{n,m}> = match at least C<n> times, but not more than C<m> times,
-C<a{n,}> = match at least C<n> or more times, C<a{n}> = match exactly C<n>
-times, Principle 0: Taken as a whole, any regexp will be matched at the
-earliest possible position in the string, Principle 1: In an alternation
-C<a|b|c...>, the leftmost alternative that allows a match for the whole
-regexp will be the one used, Principle 2: The maximal matching quantifiers
-C<?>, C<*>, C<+> and C<{n,m}> will in general match as much of the string
-as possible while still allowing the whole regexp to match, Principle 3: If
-there are two or more elements in a regexp, the leftmost greedy quantifier,
-if any, will match as much of the string as possible while still allowing
-the whole regexp to match.  The next leftmost greedy quantifier, if any,
-will try to match as much of the string remaining available to it as
-possible, while still allowing the whole regexp to match.  And so on, until
-all the regexp elements are satisfied, C<a??> = match 'a' 0 or 1 times. Try
-0 first, then 1, C<a*?> = match 'a' 0 or more times, i.e., any number of
-times, but as few times as possible, C<a+?> = match 'a' 1 or more times,
-i.e., at least once, but as few times as possible, C<a{n,m}?> = match at
-least C<n> times, not more than C<m> times, as few times as possible,
-C<a{n,}?> = match at least C<n> times, but as few times as possible,
-C<a{n}?> = match exactly C<n> times.  Because we match exactly C<n> times,
-C<a{n}?> is equivalent to C<a{n}> and is just there for notational
-consistency, Principle 3: If there are two or more elements in a regexp,
-the leftmost greedy (non-greedy) quantifier, if any, will match as much
-(little) of the string as possible while still allowing the whole regexp to
-match. The next leftmost greedy (non-greedy) quantifier, if any, will try
-to match as much (little) of the string remaining available to it as
-possible, while still allowing the whole regexp to match.  And so on, until
-all the regexp elements are satisfied, 0 Start with the first letter in the
-string 't', 1 The first quantifier '.*' starts out by matching the whole
-string 'the cat in the hat', 2 'a' in the regexp element 'at' doesn't match
-the end of the string. Backtrack one character, 3 'a' in the regexp
-element 'at' still doesn't match the last letter of the string 't', so
-backtrack one more character, 4 Now we can match the 'a' and the 't', 5
-Move on to the third element '.*'.  Since we are at the end of the string
-and '.*' can match 0 times, assign it the empty string, 6 We are done!
+=item AUTHOR
 
-=item Building a regexp
+=back
 
-specifying the task in detail,, breaking down the problem into smaller
-parts,, translating the small parts into regexps,, combining the regexps,,
-and optimizing the final combined regexp
+=head2 perlstyle - Perl style guide
 
-=item Using regular expressions in Perl
+=over
+
+=item DESCRIPTION
 
 =back
 
-=item Part 2: Power tools
+=head2 perltrap - Perl traps for the unwary
 
 =over
 
-=item More on characters, strings, and character classes
+=item DESCRIPTION
 
-=item Compiling and saving regular expressions
+=over
 
-=item Embedding comments and modifiers in a regular expression
+=item Awk Traps
 
-=item Non-capturing groupings
+=item C Traps
 
-=item Looking ahead and looking behind
+=item Sed Traps
 
-=item Using independent subexpressions to prevent backtracking
+=item Shell Traps
 
-=item Conditional expressions
+=item Perl Traps
 
-=item A bit of magic: executing Perl code in a regular expression
+=item Perl4 to Perl5 Traps
 
-=item Pragmas and debugging
+Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical
+Traps, General data type traps, Context Traps - scalar, list contexts,
+Precedence Traps, General Regular Expression Traps using s///, etc,
+Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps
 
-=back
+=item Discontinuance, Deprecation, and BugFix traps
 
-=item BUGS
+Discontinuance, Deprecation, BugFix, Discontinuance, Discontinuance,
+Discontinuance, BugFix, Discontinuance, Discontinuance, BugFix,
+Discontinuance, Deprecation, Discontinuance, Discontinuance
 
-=item SEE ALSO
+=item Parsing Traps
 
-=item AUTHOR AND COPYRIGHT
+Parsing, Parsing, Parsing, Parsing
 
-=over
+=item Numerical Traps
 
-=item Acknowledgments
+Numerical, Numerical, Numerical, Bitwise string ops
+
+=item General data type traps
+
+(Arrays), (Arrays), (Hashes), (Globs), (Globs), (Scalar String),
+(Constants), (Scalars), (Variable Suicide)
+
+=item Context Traps - scalar, list contexts
+
+(list context), (scalar context), (scalar context), (list, builtin)
+
+=item Precedence Traps
+
+Precedence, Precedence, Precedence, Precedence, Precedence, Precedence,
+Precedence
+
+=item General Regular Expression Traps using s///, etc.
+
+Regular Expression, Regular Expression, Regular Expression, Regular
+Expression, Regular Expression, Regular Expression, Regular Expression,
+Regular Expression
+
+=item Subroutine, Signal, Sorting Traps
+
+(Signals), (Sort Subroutine), warn() won't let you specify a filehandle
+
+=item OS Traps
+
+(SysV), (SysV)
+
+=item Interpolation Traps
+
+Interpolation, Interpolation, Interpolation, Interpolation, Interpolation,
+Interpolation, Interpolation, Interpolation, Interpolation
+
+=item DBM Traps
+
+DBM, DBM
+
+=item Unclassified Traps
+
+C<require>/C<do> trap using returned value, C<split> on empty string with
+LIMIT specified
 
 =back
 
@@ -1009,6 +970,14 @@ PERL_ROOT (specific to the VMS port), SYS$LOGIN (specific to the VMS port)
 
 =back
 
+=head2 perldiag - various Perl diagnostics
+
+=over
+
+=item DESCRIPTION
+
+=back
+
 =head2 perllexwarn - Perl Lexical Warnings
 
 =over
@@ -1101,43 +1070,113 @@ listing
 
 =back
 
-=head2 perlopentut - tutorial on opening things in Perl
+=head2 perlvar - Perl predefined variables
 
 =over
 
 =item DESCRIPTION
 
-=item Open E<agrave> la shell
-
 =over
 
-=item Simple Opens
-
-=item Pipe Opens
+=item Predefined Names
 
-=item The Minus File
+$ARG, $_, $<I<digits>>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $',
+$LAST_PAREN_MATCH, $+, @LAST_MATCH_END, @+, $MULTILINE_MATCHING, $*,
+input_line_number HANDLE EXPR, $INPUT_LINE_NUMBER, $NR, $,
+input_record_separator HANDLE EXPR, $INPUT_RECORD_SEPARATOR, $RS, $/,
+autoflush HANDLE EXPR, $OUTPUT_AUTOFLUSH, $|, output_field_separator HANDLE
+EXPR, $OUTPUT_FIELD_SEPARATOR, $OFS, $,, output_record_separator HANDLE
+EXPR, $OUTPUT_RECORD_SEPARATOR, $ORS, $\, $LIST_SEPARATOR, $",
+$SUBSCRIPT_SEPARATOR, $SUBSEP, $;, $OFMT, $#, format_page_number HANDLE
+EXPR, $FORMAT_PAGE_NUMBER, $%, format_lines_per_page HANDLE EXPR,
+$FORMAT_LINES_PER_PAGE, $=, format_lines_left HANDLE EXPR,
+$FORMAT_LINES_LEFT, $-, @LAST_MATCH_START, @-, C<$`> is the same as
+C<substr($var, 0, $-[0])>, C<$&> is the same as C<substr($var, $-[0], $+[0]
+- $-[0])>, C<$'> is the same as C<substr($var, $+[0])>, C<$1> is the same
+as C<substr($var, $-[1], $+[1] - $-[1])>, C<$2> is the same as
+C<substr($var, $-[2], $+[2] - $-[2])>, C<$3> is the same as C<substr $var,
+$-[3], $+[3] - $-[3])>, format_name HANDLE EXPR, $FORMAT_NAME, $~,
+format_top_name HANDLE EXPR, $FORMAT_TOP_NAME, $^,
+format_line_break_characters HANDLE EXPR, $FORMAT_LINE_BREAK_CHARACTERS,
+$:, format_formfeed HANDLE EXPR, $FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A,
+$CHILD_ERROR, $?, $OS_ERROR, $ERRNO, $!, $EXTENDED_OS_ERROR, $^E,
+$EVAL_ERROR, $@, $PROCESS_ID, $PID, $$, $REAL_USER_ID, $UID, $<,
+$EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, $GID, $(,
+$EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $], $COMPILING, $^C,
+$DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, %^H, $INPLACE_EDIT, $^I, $^M,
+$OSNAME, $^O, $PERLDB, $^P, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80,
+0x100, 0x200, $LAST_REGEXP_CODE_RESULT, $^R, $EXCEPTIONS_BEING_CAUGHT, $^S,
+$BASETIME, $^T, $PERL_VERSION, $^V, $WARNING, $^W, ${^WARNING_BITS},
+${^WIDE_SYSTEM_CALLS}, $EXECUTABLE_NAME, $^X, $ARGV, @ARGV, @INC, @_, %INC,
+%ENV, $ENV{expr}, %SIG, $SIG{expr}
 
-=item Mixing Reads and Writes
+=item Error Indicators
 
-=item Filters 
+=item Technical Note on the Syntax of Variable Names
 
 =back
 
-=item Open E<agrave> la C
-
-=over
-
-=item Permissions E<agrave> la mode
+=item BUGS
 
 =back
 
-=item Obscure Open Tricks
+=head2 perllol - Manipulating Arrays of Arrays in Perl
 
 =over
 
-=item Re-Opening Files (dups)
+=item DESCRIPTION
 
-=item Dispelling the Dweomer
+=item Declaration and Access of Arrays of Arrays
+
+=item Growing Your Own
+
+=item Access and Printing
+
+=item Slices
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perlopentut - tutorial on opening things in Perl
+
+=over
+
+=item DESCRIPTION
+
+=item Open E<agrave> la shell
+
+=over
+
+=item Simple Opens
+
+=item Pipe Opens
+
+=item The Minus File
+
+=item Mixing Reads and Writes
+
+=item Filters 
+
+=back
+
+=item Open E<agrave> la C
+
+=over
+
+=item Permissions E<agrave> la mode
+
+=back
+
+=item Obscure Open Tricks
+
+=over
+
+=item Re-Opening Files (dups)
+
+=item Dispelling the Dweomer
 
 =item Paths as Opens
 
@@ -1167,224 +1206,223 @@ listing
 
 =back
 
-=head2 perlvar - Perl predefined variables
+=head2 perlretut - Perl regular expressions tutorial
 
 =over
 
 =item DESCRIPTION
 
+=item Part 1: The basics
+
 =over
 
-=item Predefined Names
+=item Simple word matching
 
-$ARG, $_, $<I<digits>>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $',
-$LAST_PAREN_MATCH, $+, @LAST_MATCH_END, @+, $MULTILINE_MATCHING, $*,
-input_line_number HANDLE EXPR, $INPUT_LINE_NUMBER, $NR, $,
-input_record_separator HANDLE EXPR, $INPUT_RECORD_SEPARATOR, $RS, $/,
-autoflush HANDLE EXPR, $OUTPUT_AUTOFLUSH, $|, output_field_separator HANDLE
-EXPR, $OUTPUT_FIELD_SEPARATOR, $OFS, $,, output_record_separator HANDLE
-EXPR, $OUTPUT_RECORD_SEPARATOR, $ORS, $\, $LIST_SEPARATOR, $",
-$SUBSCRIPT_SEPARATOR, $SUBSEP, $;, $OFMT, $#, format_page_number HANDLE
-EXPR, $FORMAT_PAGE_NUMBER, $%, format_lines_per_page HANDLE EXPR,
-$FORMAT_LINES_PER_PAGE, $=, format_lines_left HANDLE EXPR,
-$FORMAT_LINES_LEFT, $-, @LAST_MATCH_START, @-, C<$`> is the same as
-C<substr($var, 0, $-[0])>, C<$&> is the same as C<substr($var, $-[0], $+[0]
-- $-[0])>, C<$'> is the same as C<substr($var, $+[0])>, C<$1> is the same
-as C<substr($var, $-[1], $+[1] - $-[1])>, C<$2> is the same as
-C<substr($var, $-[2], $+[2] - $-[2])>, C<$3> is the same as C<substr $var,
-$-[3], $+[3] - $-[3])>, format_name HANDLE EXPR, $FORMAT_NAME, $~,
-format_top_name HANDLE EXPR, $FORMAT_TOP_NAME, $^,
-format_line_break_characters HANDLE EXPR, $FORMAT_LINE_BREAK_CHARACTERS,
-$:, format_formfeed HANDLE EXPR, $FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A,
-$CHILD_ERROR, $?, $OS_ERROR, $ERRNO, $!, $EXTENDED_OS_ERROR, $^E,
-$EVAL_ERROR, $@, $PROCESS_ID, $PID, $$, $REAL_USER_ID, $UID, $<,
-$EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, $GID, $(,
-$EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $], $COMPILING, $^C,
-$DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, %^H, $INPLACE_EDIT, $^I, $^M,
-$OSNAME, $^O, $PERLDB, $^P, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80,
-0x100, 0x200, $LAST_REGEXP_CODE_RESULT, $^R, $EXCEPTIONS_BEING_CAUGHT, $^S,
-$BASETIME, $^T, $PERL_VERSION, $^V, $WARNING, $^W, ${^WARNING_BITS},
-${^WIDE_SYSTEM_CALLS}, $EXECUTABLE_NAME, $^X, $ARGV, @ARGV, @INC, @_, %INC,
-%ENV, $ENV{expr}, %SIG, $SIG{expr}
+=item Using character classes
 
-=item Error Indicators
+\d is a digit and represents [0-9], \s is a whitespace character and
+represents [\ \t\r\n\f], \w is a word character (alphanumeric or _) and
+represents [0-9a-zA-Z_], \D is a negated \d; it represents any character
+but a digit [^0-9], \S is a negated \s; it represents any non-whitespace
+character [^\s], \W is a negated \w; it represents any non-word character
+[^\w], The period '.' matches any character but "\n", no modifiers (//):
+Default behavior.  C<'.'> matches any character except C<"\n">.  C<^>
+matches only at the beginning of the string and C<$> matches only at the
+end or before a newline at the end, s modifier (//s): Treat string as a
+single long line.  C<'.'> matches any character, even C<"\n">. C<^>
+matches only at the beginning of the string and C<$> matches only at the
+end or before a newline at the end, m modifier (//m): Treat string as a set
+of multiple lines.  C<'.'> matches any character except C<"\n">.  C<^> and
+C<$> are able to match at the start or end of I<any> line within the
+string, both s and m modifiers (//sm): Treat string as a single long line,
+but detect multiple lines.  C<'.'> matches any character, even C<"\n">. 
+C<^> and C<$>, however, are able to match at the start or end of I<any>
+line within the string
 
-=item Technical Note on the Syntax of Variable Names
+=item Matching this or that
 
-=back
+=item Grouping things and hierarchical matching
 
-=item BUGS
+0 Start with the first letter in the string 'a', 1 Try the first
+alternative in the first group 'abd', 2 Match 'a' followed by 'b'. So far
+so good, 3 'd' in the regexp doesn't match 'c' in the string - a dead end. 
+So backtrack two characters and pick the second alternative in the first
+group 'abc', 4 Match 'a' followed by 'b' followed by 'c'.  We are on a roll
+and have satisfied the first group. Set $1 to 'abc', 5 Move on to the
+second group and pick the first alternative 'df', 6 Match the 'd', 7 'f' in
+the regexp doesn't match 'e' in the string, so a dead end.  Backtrack one
+character and pick the second alternative in the second group 'd', 8 'd'
+matches. The second grouping is satisfied, so set $2 to 'd', 9 We are at
+the end of the regexp, so we are done! We have matched 'abcd' out of the
+string "abcde"
+
+=item Extracting matches
+
+=item Matching repetitions
+
+C<a?> = match 'a' 1 or 0 times, C<a*> = match 'a' 0 or more times, i.e.,
+any number of times, C<a+> = match 'a' 1 or more times, i.e., at least
+once, C<a{n,m}> = match at least C<n> times, but not more than C<m> times,
+C<a{n,}> = match at least C<n> or more times, C<a{n}> = match exactly C<n>
+times, Principle 0: Taken as a whole, any regexp will be matched at the
+earliest possible position in the string, Principle 1: In an alternation
+C<a|b|c...>, the leftmost alternative that allows a match for the whole
+regexp will be the one used, Principle 2: The maximal matching quantifiers
+C<?>, C<*>, C<+> and C<{n,m}> will in general match as much of the string
+as possible while still allowing the whole regexp to match, Principle 3: If
+there are two or more elements in a regexp, the leftmost greedy quantifier,
+if any, will match as much of the string as possible while still allowing
+the whole regexp to match.  The next leftmost greedy quantifier, if any,
+will try to match as much of the string remaining available to it as
+possible, while still allowing the whole regexp to match.  And so on, until
+all the regexp elements are satisfied, C<a??> = match 'a' 0 or 1 times. Try
+0 first, then 1, C<a*?> = match 'a' 0 or more times, i.e., any number of
+times, but as few times as possible, C<a+?> = match 'a' 1 or more times,
+i.e., at least once, but as few times as possible, C<a{n,m}?> = match at
+least C<n> times, not more than C<m> times, as few times as possible,
+C<a{n,}?> = match at least C<n> times, but as few times as possible,
+C<a{n}?> = match exactly C<n> times.  Because we match exactly C<n> times,
+C<a{n}?> is equivalent to C<a{n}> and is just there for notational
+consistency, Principle 3: If there are two or more elements in a regexp,
+the leftmost greedy (non-greedy) quantifier, if any, will match as much
+(little) of the string as possible while still allowing the whole regexp to
+match. The next leftmost greedy (non-greedy) quantifier, if any, will try
+to match as much (little) of the string remaining available to it as
+possible, while still allowing the whole regexp to match.  And so on, until
+all the regexp elements are satisfied, 0 Start with the first letter in the
+string 't', 1 The first quantifier '.*' starts out by matching the whole
+string 'the cat in the hat', 2 'a' in the regexp element 'at' doesn't match
+the end of the string. Backtrack one character, 3 'a' in the regexp
+element 'at' still doesn't match the last letter of the string 't', so
+backtrack one more character, 4 Now we can match the 'a' and the 't', 5
+Move on to the third element '.*'.  Since we are at the end of the string
+and '.*' can match 0 times, assign it the empty string, 6 We are done!
+
+=item Building a regexp
+
+specifying the task in detail,, breaking down the problem into smaller
+parts,, translating the small parts into regexps,, combining the regexps,,
+and optimizing the final combined regexp
+
+=item Using regular expressions in Perl
 
 =back
 
-=head2 perlmod - Perl modules (packages and symbol tables)
+=item Part 2: Power tools
 
 =over
 
-=item DESCRIPTION
+=item More on characters, strings, and character classes
 
-=over
+=item Compiling and saving regular expressions
 
-=item Packages
+=item Embedding comments and modifiers in a regular expression
 
-=item Symbol Tables
+=item Non-capturing groupings
 
-=item Package Constructors and Destructors
+=item Looking ahead and looking behind
 
-=item Perl Classes
+=item Using independent subexpressions to prevent backtracking
 
-=item Perl Modules
+=item Conditional expressions
 
-=back
+=item A bit of magic: executing Perl code in a regular expression
 
-=item SEE ALSO
+=item Pragmas and debugging
 
 =back
 
-=head2 perlpod - plain old documentation
+=item BUGS
 
-=over
+=item SEE ALSO
 
-=item DESCRIPTION
+=item AUTHOR AND COPYRIGHT
 
 =over
 
-=item Verbatim Paragraph
+=item Acknowledgments
 
-=item Command Paragraph
+=back
 
-=item Ordinary Block of Text
+=back
 
-=item The Intent
+=head2 perlref - Perl references and nested data structures
 
-=item Embedding Pods in Perl Modules
+=over
 
-=item Common Pod Pitfalls
+=item NOTE
 
-=back
+=item DESCRIPTION
 
-=item SEE ALSO
+=over
 
-=item AUTHOR
+=item Making References
 
-=back
+=item Using References
 
-=head2 perlstyle - Perl style guide
+=item Symbolic references
 
-=over
+=item Not-so-symbolic references
 
-=item DESCRIPTION
+=item Pseudo-hashes: Using an array as a hash
+
+=item Function Templates
 
 =back
 
-=head2 perlmodlib - constructing new Perl modules and finding existing ones
+=item WARNING
 
-=over
+=item SEE ALSO
 
-=item DESCRIPTION
+=back
 
-=item THE PERL MODULE LIBRARY
+=head2 perlre - Perl regular expressions
 
 =over
 
-=item Pragmatic Modules
-
-attributes, attrs, autouse, base, blib, bytes, charnames, constant,
-diagnostics, fields, filetest, integer, less, locale, open, ops, overload,
-re, sigtrap, strict, subs, utf8, vars, warnings
-
-=item Standard Modules
+=item DESCRIPTION
 
-AnyDBM_File, AutoLoader, AutoSplit, B, B::Asmdata, B::Assembler, B::Bblock,
-B::Bytecode, B::C, B::CC, B::Debug, B::Deparse, B::Disassembler, B::Lint,
-B::Showlex, B::Stackobj, B::Terse, B::Xref, Benchmark, ByteLoader, CGI,
-CGI::Apache, CGI::Carp, CGI::Cookie, CGI::Fast, CGI::Pretty, CGI::Push,
-CGI::Switch, CPAN, CPAN::FirstTime, CPAN::Nox, Carp, Carp::Heavy,
-Class::Struct, Cwd, DB, DB_File, Devel::SelfStubber, DirHandle, Dumpvalue,
-English, Env, Exporter, Exporter::Heavy, ExtUtils::Command,
-ExtUtils::Embed, ExtUtils::Install, ExtUtils::Installed, ExtUtils::Liblist,
-ExtUtils::MM_Cygwin, ExtUtils::MM_OS2, ExtUtils::MM_Unix, ExtUtils::MM_VMS,
-ExtUtils::MM_Win32, ExtUtils::MakeMaker, ExtUtils::Manifest,
-ExtUtils::Mkbootstrap, ExtUtils::Mksymlists, ExtUtils::Packlist,
-ExtUtils::testlib, Fatal, Fcntl, File::Basename, File::CheckTree,
-File::Compare, File::Copy, File::DosGlob, File::Find, File::Path,
-File::Spec, File::Spec::Functions, File::Spec::Mac, File::Spec::OS2,
-File::Spec::Unix, File::Spec::VMS, File::Spec::Win32, File::Temp,
-File::stat, FileCache, FileHandle, FindBin, Getopt::Long, Getopt::Std,
-I18N::Collate, IO, IPC::Open2, IPC::Open3, Math::BigFloat, Math::BigInt,
-Math::Complex, Math::Trig, NDBM_File, Net::Ping, Net::hostent, Net::netent,
-Net::protoent, Net::servent, O, ODBM_File, Opcode, Pod::Checker, Pod::Find,
-Pod::Html, Pod::InputObjects, Pod::LaTeX, Pod::Man, Pod::ParseUtils,
-Pod::Parser, Pod::Plainer, Pod::Select, Pod::Text, Pod::Text::Color,
-Pod::Text::Termcap, Pod::Usage, SDBM_File, Safe, Search::Dict, SelectSaver,
-SelfLoader, Shell, Socket, Symbol, Term::ANSIColor, Term::Cap,
-Term::Complete, Term::ReadLine, Test, Test::Harness, Text::Abbrev,
-Text::ParseWords, Text::Soundex, Text::Wrap, Tie::Array, Tie::Handle,
-Tie::Hash, Tie::RefHash, Tie::Scalar, Tie::SubstrHash, Time::Local,
-Time::gmtime, Time::localtime, Time::tm, UNIVERSAL, User::grent,
-User::pwent
+i, m, s, x
 
-=item Extension Modules
+=over
 
-=back
+=item Regular Expressions
 
-=item CPAN
+cntrl, graph, print, punct, xdigit
 
-Language Extensions and Documentation Tools, Development Support, Operating
-System Interfaces, Networking, Device Control (modems) and InterProcess
-Communication, Data Types and Data Type Utilities, Database Interfaces,
-User Interfaces, Interfaces to / Emulations of Other Programming Languages,
-File Names, File Systems and File Locking (see also File Handles), String
-Processing, Language Text Processing, Parsing, and Searching, Option,
-Argument, Parameter, and Configuration File Processing,
-Internationalization and Locale, Authentication, Security, and Encryption,
-World Wide Web, HTML, HTTP, CGI, MIME, Server and Daemon Utilities,
-Archiving and Compression, Images, Pixmap and Bitmap Manipulation, Drawing,
-and Graphing, Mail and Usenet News, Control Flow Utilities (callbacks and
-exceptions etc), File Handle and Input/Output Stream Utilities,
-Miscellaneous Modules, Africa, Asia, Australasia, Central America, Europe,
-North America, South America
+=item Extended Patterns
 
-=item Modules: Creation, Use, and Abuse
+C<(?#text)>, C<(?imsx-imsx)>, C<(?:pattern)>, C<(?imsx-imsx:pattern)>,
+C<(?=pattern)>, C<(?!pattern)>, C<(?<=pattern)>, C<(?<!pattern)>, C<(?{
+code })>, C<(??{ code })>, C<< (?>pattern) >>,
+C<(?(condition)yes-pattern|no-pattern)>, C<(?(condition)yes-pattern)>
 
-=over
+=item Backtracking
 
-=item Guidelines for Module Creation
+=item Version 8 Regular Expressions
 
-Do similar modules already exist in some form?, Try to design the new
-module to be easy to extend and reuse, Some simple style guidelines, Select
-what to export, Select a name for the module, Have you got it right?,
-README and other Additional Files, A description of the
-module/package/extension etc, A copyright notice - see below, Prerequisites
-- what else you may need to have, How to build it - possible changes to
-Makefile.PL etc, How to install it, Recent changes in this release,
-especially incompatibilities, Changes / enhancements you plan to make in
-the future, Adding a Copyright Notice, Give the module a
-version/issue/release number, How to release and distribute a module, Take
-care when changing a released module
+=item Warning on \1 vs $1
 
-=item Guidelines for Converting Perl 4 Library Scripts into Modules
+=item Repeated patterns matching zero-length substring
 
-There is no requirement to convert anything, Consider the implications,
-Make the most of the opportunity, The pl2pm utility will get you started,
-Adds the standard Module prologue lines, Converts package specifiers from '
-to ::, Converts die(...) to croak(...), Several other minor changes
+=item Combining pieces together
 
-=item Guidelines for Reusing Application Code
+C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>,
+C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>,
+C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>,
+C<(?(condition)yes-pattern|no-pattern)>
 
-Complete applications rarely belong in the Perl Module Library, Many
-applications contain some Perl code that could be reused, Break-out the
-reusable code into one or more separate module files, Take the opportunity
-to reconsider and redesign the interfaces, In some cases the 'application'
-can then be reduced to a small
+=item Creating custom RE engines
 
 =back
 
-=item NOTE
+=item BUGS
+
+=item SEE ALSO
 
 =back
 
-=head2 perlmodinstall - Installing CPAN Modules
+=head2 perlform - Perl formats
 
 =over
 
@@ -1392,492 +1430,534 @@ can then be reduced to a small
 
 =over
 
-=item PREAMBLE
-
-B<DECOMPRESS> the file, B<UNPACK> the file into a directory, B<BUILD> the
-module (sometimes unnecessary), B<INSTALL> the module
+=item Format Variables
 
 =back
 
-=item HEY
+=item NOTES
 
-=item AUTHOR
+=over
 
-=item COPYRIGHT
+=item Footers
+
+=item Accessing Formatting Internals
 
 =back
 
-=head2 perlnewmod - preparing a new module for distribution
+=item WARNINGS
+
+=back
+
+=head2 perllocale - Perl locale handling (internationalization and
+localization)
 
 =over
 
 =item DESCRIPTION
 
+=item PREPARING TO USE LOCALES
+
+=item USING LOCALES
+
 =over
 
-=item Warning
+=item The use locale pragma
 
-=item What should I make into a module?
+=item The setlocale function
 
-=item Step-by-step: Preparing the ground
+=item Finding locales
 
-Look around, Check it's new, Discuss the need, Choose a name, Check again
+=item LOCALE PROBLEMS
 
-=item Step-by-step: Making the module
+=item Temporarily fixing locale problems
 
-Start with F<h2xs>, Use L<strict|strict> and L<warnings|warnings>, Use
-L<Carp|Carp>, Use L<Exporter|Exporter> - wisely!, Use L<plain old
-documentation|perlpod>, Write tests, Write the README
+=item Permanently fixing locale problems
 
-=item Step-by-step: Distributing your module
+=item Permanently fixing your system's locale configuration
 
-Get a CPAN user ID, C<perl Makefile.PL; make test; make dist>, Upload the
-tarball, Announce to the modules list, Announce to clpa, Fix bugs!
+=item Fixing system locale configuration
+
+=item The localeconv function
 
 =back
 
-=item AUTHOR
+=item LOCALE CATEGORIES
 
-=item SEE ALSO
+=over
+
+=item Category LC_COLLATE: Collation
+
+=item Category LC_CTYPE: Character Types
+
+=item Category LC_NUMERIC: Numeric Formatting
+
+=item Category LC_MONETARY: Formatting of monetary amounts
+
+=item LC_TIME
+
+=item Other categories
 
 =back
 
-=head2 perltrap - Perl traps for the unwary
+=item SECURITY
 
-=over
+B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):,
+B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>),
+B<Matching operator> (C<m//>):, B<Substitution operator> (C<s///>):,
+B<Output formatting functions> (printf() and write()):, B<Case-mapping
+functions> (lc(), lcfirst(), uc(), ucfirst()):, B<POSIX locale-dependent
+functions> (localeconv(), strcoll(), strftime(), strxfrm()):, B<POSIX
+character class tests> (isalnum(), isalpha(), isdigit(), isgraph(),
+islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()):
 
-=item DESCRIPTION
+=item ENVIRONMENT
+
+PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY,
+LC_NUMERIC, LC_TIME, LANG
+
+=item NOTES
 
 =over
 
-=item Awk Traps
+=item Backward compatibility
 
-=item C Traps
+=item I18N:Collate obsolete
 
-=item Sed Traps
+=item Sort speed and memory use impacts
 
-=item Shell Traps
+=item write() and LC_NUMERIC
 
-=item Perl Traps
+=item Freely available locale definitions
 
-=item Perl4 to Perl5 Traps
+=item I18n and l10n
 
-Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical
-Traps, General data type traps, Context Traps - scalar, list contexts,
-Precedence Traps, General Regular Expression Traps using s///, etc,
-Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps
+=item An imperfect standard
 
-=item Discontinuance, Deprecation, and BugFix traps
+=back
 
-Discontinuance, Deprecation, BugFix, Discontinuance, Discontinuance,
-Discontinuance, BugFix, Discontinuance, Discontinuance, BugFix,
-Discontinuance, Deprecation, Discontinuance, Discontinuance
+=item BUGS
 
-=item Parsing Traps
+=over
 
-Parsing, Parsing, Parsing, Parsing
+=item Broken systems
 
-=item Numerical Traps
+=back
 
-Numerical, Numerical, Numerical, Bitwise string ops
+=item SEE ALSO
 
-=item General data type traps
+=item HISTORY
 
-(Arrays), (Arrays), (Hashes), (Globs), (Globs), (Scalar String),
-(Constants), (Scalars), (Variable Suicide)
+=back
 
-=item Context Traps - scalar, list contexts
+=head2 perlunicode - Unicode support in Perl
 
-(list context), (scalar context), (scalar context), (list, builtin)
+=over
 
-=item Precedence Traps
+=item DESCRIPTION
 
-Precedence, Precedence, Precedence, Precedence, Precedence, Precedence,
-Precedence
+=over
 
-=item General Regular Expression Traps using s///, etc.
+=item Important Caveat
 
-Regular Expression, Regular Expression, Regular Expression, Regular
-Expression, Regular Expression, Regular Expression, Regular Expression,
-Regular Expression
+Input and Output Disciplines, Regular Expressions, C<use utf8> still needed
+to enable a few features
 
-=item Subroutine, Signal, Sorting Traps
+=item Byte and Character semantics
 
-(Signals), (Sort Subroutine), warn() won't let you specify a filehandle
+=item Effects of character semantics
 
-=item OS Traps
+=item Character encodings for input and output
 
-(SysV), (SysV)
+=back
 
-=item Interpolation Traps
+=item CAVEATS
 
-Interpolation, Interpolation, Interpolation, Interpolation, Interpolation,
-Interpolation, Interpolation, Interpolation, Interpolation
+=item SEE ALSO
 
-=item DBM Traps
+=back
 
-DBM, DBM
+=head2 perlipc - Perl interprocess communication (signals, fifos, pipes,
+safe subprocesses, sockets, and semaphores)
 
-=item Unclassified Traps
+=over
 
-C<require>/C<do> trap using returned value, C<split> on empty string with
-LIMIT specified
+=item DESCRIPTION
+
+=item Signals
+
+=item Named Pipes
+
+=over
+
+=item WARNING
 
 =back
 
+=item Using open() for IPC
+
+=over
+
+=item Filehandles
+
+=item Background Processes
+
+=item Complete Dissociation of Child from Parent
+
+=item Safe Pipe Opens
+
+=item Bidirectional Communication with Another Process
+
+=item Bidirectional Communication with Yourself
+
 =back
 
-=head2 perlport - Writing portable Perl
+=item Sockets: Client/Server Communication
 
 =over
 
-=item DESCRIPTION
+=item Internet Line Terminators
 
-Not all Perl programs have to be portable, Nearly all of Perl already I<is>
-portable
+=item Internet TCP Clients and Servers
 
-=item ISSUES
+=item Unix-Domain TCP Clients and Servers
+
+=back
+
+=item TCP Clients with IO::Socket
 
 =over
 
-=item Newlines
+=item A Simple Client
 
-=item Numbers endianness and Width
+C<Proto>, C<PeerAddr>, C<PeerPort>
 
-=item Files and Filesystems
+=item A Webget Client
 
-=item System Interaction
+=item Interactive Client with IO::Socket
 
-=item Interprocess Communication (IPC)
+=back
 
-=item External Subroutines (XS)
+=item TCP Servers with IO::Socket
 
-=item Standard Modules
+Proto, LocalPort, Listen, Reuse
 
-=item Time and Date
+=item UDP: Message Passing
 
-=item Character sets and character encoding
+=item SysV IPC
 
-=item Internationalisation
+=item NOTES
 
-=item System Resources
+=item BUGS
 
-=item Security
+=item AUTHOR
 
-=item Style
+=item SEE ALSO
 
 =back
 
-=item CPAN Testers
+=head2 perlfork - Perl's fork() emulation
 
-Mailing list: cpan-testers@perl.org, Testing results:
-http://testers.cpan.org/
+=over
 
-=item PLATFORMS
+=item SYNOPSIS
+
+=item DESCRIPTION
 
 =over
 
-=item Unix
+=item Behavior of other Perl features in forked pseudo-processes
 
-=item DOS and Derivatives
+$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept
+filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to
+files, directories and network sockets
 
-Build instructions for OS/2, L<perlos2>
+=item Resource limits
 
-=item S<Mac OS>
+=item Killing the parent process
 
-=item VMS
+=item Lifetime of the parent process and pseudo-processes
 
-=item VOS
+=item CAVEATS AND LIMITATIONS
 
-=item EBCDIC Platforms
+BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented,
+Global state maintained by XSUBs, Interpreter embedded in larger
+application, Thread-safety of extensions
 
-=item Acorn RISC OS
+=back
 
-=item Other perls
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
 
 =back
 
-=item FUNCTION IMPLEMENTATIONS
+=head2 perlnumber - semantics of numbers and numeric operations in Perl
 
 =over
 
-=item Alphabetical Listing of Perl Functions
-
--I<X> FILEHANDLE, -I<X> EXPR, -I<X>, alarm SECONDS, alarm, binmode
-FILEHANDLE, chmod LIST, chown LIST, chroot FILENAME, chroot, crypt
-PLAINTEXT,SALT, dbmclose HASH, dbmopen HASH,DBNAME,MODE, dump LABEL, exec
-LIST, fcntl FILEHANDLE,FUNCTION,SCALAR, flock FILEHANDLE,OPERATION, fork,
-getlogin, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam NAME,
-getgrnam NAME, getnetbyname NAME, getpwuid UID, getgrgid GID, getnetbyaddr
-ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent,
-getgrent, gethostent, getnetent, getprotoent, getservent, setpwent,
-setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN,
-setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent,
-endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob,
-ioctl FILEHANDLE,FUNCTION,SCALAR, kill SIGNAL, LIST, link OLDFILE,NEWFILE,
-lstat FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS,
-msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR,
-open FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink,
-select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget
-KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP,
-setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt
-SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS,
-shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, socketpair
-SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat EXPR, stat,
-symlink OLDFILE,NEWFILE, syscall LIST, sysopen
-FILEHANDLE,FILENAME,MODE,PERMS, system LIST, times, truncate
-FILEHANDLE,LENGTH, truncate EXPR,LENGTH, umask EXPR, umask, utime LIST,
-wait, waitpid PID,FLAGS
+=item SYNOPSIS
 
-=back
+=item DESCRIPTION
 
-=item CHANGES
+=item Storing numbers
 
-v1.47, 22 March 2000, v1.46, 12 February 2000, v1.45, 20 December 1999,
-v1.44, 19 July 1999, v1.43, 24 May 1999, v1.42, 22 May 1999, v1.41, 19 May
-1999, v1.40, 11 April 1999, v1.39, 11 February 1999, v1.38, 31 December
-1998, v1.37, 19 December 1998, v1.36, 9 September 1998, v1.35, 13 August
-1998, v1.33, 06 August 1998, v1.32, 05 August 1998, v1.30, 03 August 1998,
-v1.23, 10 July 1998
+=item Numeric operators and numeric conversions
 
-=item Supported Platforms
+=item Flavors of Perl numeric operations
 
-=item SEE ALSO
+Arithmetic operators except, C<no integer>, Arithmetic operators except,
+C<use integer>, Bitwise operators, C<no integer>, Bitwise operators, C<use
+integer>, Operators which expect an integer, Operators which expect a
+string
 
-=item AUTHORS / CONTRIBUTORS
+=item AUTHOR
 
-=item VERSION
+=item SEE ALSO
 
 =back
 
-=head2 perlsec - Perl security
+=head2 perlthrtut - tutorial on threads in Perl
 
 =over
 
 =item DESCRIPTION
 
-=over
-
-=item Laundering and Detecting Tainted Data
-
-=item Switches On the "#!" Line
+=item What Is A Thread Anyway?
 
-=item Cleaning Up Your Path
+=item Threaded Program Models
 
-=item Security Bugs
+=over
 
-=item Protecting Your Programs
+=item Boss/Worker
 
-=back
+=item Work Crew
 
-=item SEE ALSO
+=item Pipeline
 
 =back
 
-=head2 perlref - Perl references and nested data structures
+=item Native threads
 
-=over
+=item What kind of threads are perl threads?
 
-=item NOTE
+=item Threadsafe Modules
 
-=item DESCRIPTION
+=item Thread Basics
 
 =over
 
-=item Making References
-
-=item Using References
-
-=item Symbolic references
-
-=item Not-so-symbolic references
+=item Basic Thread Support
 
-=item Pseudo-hashes: Using an array as a hash
+=item Creating Threads
 
-=item Function Templates
+=item Giving up control
 
-=back
+=item Waiting For A Thread To Exit
 
-=item WARNING
+=item Errors In Threads
 
-=item SEE ALSO
+=item Ignoring A Thread
 
 =back
 
-=head2 perlre - Perl regular expressions
+=item Threads And Data
 
 =over
 
-=item DESCRIPTION
+=item Shared And Unshared Data
 
-i, m, s, x
+=item Thread Pitfall: Races
 
-=over
+=item Controlling access: lock()
 
-=item Regular Expressions
+=item Thread Pitfall: Deadlocks
 
-cntrl, graph, print, punct, xdigit
+=item Queues: Passing Data Around
 
-=item Extended Patterns
+=back
 
-C<(?#text)>, C<(?imsx-imsx)>, C<(?:pattern)>, C<(?imsx-imsx:pattern)>,
-C<(?=pattern)>, C<(?!pattern)>, C<(?<=pattern)>, C<(?<!pattern)>, C<(?{
-code })>, C<(??{ code })>, C<< (?>pattern) >>,
-C<(?(condition)yes-pattern|no-pattern)>, C<(?(condition)yes-pattern)>
+=item Threads And Code
 
-=item Backtracking
+=over
 
-=item Version 8 Regular Expressions
+=item Semaphores: Synchronizing Data Access
 
-=item Warning on \1 vs $1
+Basic semaphores, Advanced Semaphores
 
-=item Repeated patterns matching zero-length substring
+=item Attributes: Restricting Access To Subroutines
 
-=item Combining pieces together
+=item Subroutine Locks
 
-C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>,
-C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>,
-C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>,
-C<(?(condition)yes-pattern|no-pattern)>
+=item Methods
 
-=item Creating custom RE engines
+=item Locking A Subroutine
 
 =back
 
-=item BUGS
+=item General Thread Utility Routines
 
-=item SEE ALSO
+=over
 
-=back
+=item What Thread Am I In?
 
-=head2 perlform - Perl formats
+=item Thread IDs
 
-=over
+=item Are These Threads The Same?
 
-=item DESCRIPTION
+=item What Threads Are Running?
 
-=over
+=back
 
-=item Format Variables
+=item A Complete Example
 
-=back
+=item Conclusion
 
-=item NOTES
+=item Bibliography
 
 =over
 
-=item Footers
-
-=item Accessing Formatting Internals
+=item Introductory Texts
 
-=back
+=item OS-Related References
 
-=item WARNINGS
+=item Other References
 
 =back
 
-=head2 perllocale - Perl locale handling (internationalization and
-localization)
+=item Acknowledgements
 
-=over
+=item AUTHOR
 
-=item DESCRIPTION
+=item Copyrights
 
-=item PREPARING TO USE LOCALES
+=back
 
-=item USING LOCALES
+=head2 perlport - Writing portable Perl
 
 =over
 
-=item The use locale pragma
-
-=item The setlocale function
+=item DESCRIPTION
 
-=item Finding locales
+Not all Perl programs have to be portable, Nearly all of Perl already I<is>
+portable
 
-=item LOCALE PROBLEMS
+=item ISSUES
 
-=item Temporarily fixing locale problems
+=over
 
-=item Permanently fixing locale problems
+=item Newlines
 
-=item Permanently fixing your system's locale configuration
+=item Numbers endianness and Width
 
-=item Fixing system locale configuration
+=item Files and Filesystems
 
-=item The localeconv function
+=item System Interaction
 
-=back
+=item Interprocess Communication (IPC)
 
-=item LOCALE CATEGORIES
+=item External Subroutines (XS)
 
-=over
+=item Standard Modules
 
-=item Category LC_COLLATE: Collation
+=item Time and Date
 
-=item Category LC_CTYPE: Character Types
+=item Character sets and character encoding
 
-=item Category LC_NUMERIC: Numeric Formatting
+=item Internationalisation
 
-=item Category LC_MONETARY: Formatting of monetary amounts
+=item System Resources
 
-=item LC_TIME
+=item Security
 
-=item Other categories
+=item Style
 
 =back
 
-=item SECURITY
+=item CPAN Testers
 
-B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):,
-B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>),
-B<Matching operator> (C<m//>):, B<Substitution operator> (C<s///>):,
-B<Output formatting functions> (printf() and write()):, B<Case-mapping
-functions> (lc(), lcfirst(), uc(), ucfirst()):, B<POSIX locale-dependent
-functions> (localeconv(), strcoll(), strftime(), strxfrm()):, B<POSIX
-character class tests> (isalnum(), isalpha(), isdigit(), isgraph(),
-islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()):
+Mailing list: cpan-testers@perl.org, Testing results:
+http://testers.cpan.org/
 
-=item ENVIRONMENT
+=item PLATFORMS
 
-PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY,
-LC_NUMERIC, LC_TIME, LANG
+=over
 
-=item NOTES
+=item Unix
 
-=over
+=item DOS and Derivatives
 
-=item Backward compatibility
+Build instructions for OS/2, L<perlos2>
 
-=item I18N:Collate obsolete
+=item S<Mac OS>
 
-=item Sort speed and memory use impacts
+=item VMS
 
-=item write() and LC_NUMERIC
+=item VOS
 
-=item Freely available locale definitions
+=item EBCDIC Platforms
 
-=item I18n and l10n
+=item Acorn RISC OS
 
-=item An imperfect standard
+=item Other perls
 
 =back
 
-=item BUGS
+=item FUNCTION IMPLEMENTATIONS
 
 =over
 
-=item Broken systems
+=item Alphabetical Listing of Perl Functions
+
+-I<X> FILEHANDLE, -I<X> EXPR, -I<X>, alarm SECONDS, alarm, binmode
+FILEHANDLE, chmod LIST, chown LIST, chroot FILENAME, chroot, crypt
+PLAINTEXT,SALT, dbmclose HASH, dbmopen HASH,DBNAME,MODE, dump LABEL, exec
+LIST, fcntl FILEHANDLE,FUNCTION,SCALAR, flock FILEHANDLE,OPERATION, fork,
+getlogin, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam NAME,
+getgrnam NAME, getnetbyname NAME, getpwuid UID, getgrgid GID, getnetbyaddr
+ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent,
+getgrent, gethostent, getnetent, getprotoent, getservent, setpwent,
+setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN,
+setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent,
+endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob,
+ioctl FILEHANDLE,FUNCTION,SCALAR, kill SIGNAL, LIST, link OLDFILE,NEWFILE,
+lstat FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS,
+msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR,
+open FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink,
+select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget
+KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP,
+setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt
+SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS,
+shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, socketpair
+SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat EXPR, stat,
+symlink OLDFILE,NEWFILE, syscall LIST, sysopen
+FILEHANDLE,FILENAME,MODE,PERMS, system LIST, times, truncate
+FILEHANDLE,LENGTH, truncate EXPR,LENGTH, umask EXPR, umask, utime LIST,
+wait, waitpid PID,FLAGS
 
 =back
 
+=item CHANGES
+
+v1.47, 22 March 2000, v1.46, 12 February 2000, v1.45, 20 December 1999,
+v1.44, 19 July 1999, v1.43, 24 May 1999, v1.42, 22 May 1999, v1.41, 19 May
+1999, v1.40, 11 April 1999, v1.39, 11 February 1999, v1.38, 31 December
+1998, v1.37, 19 December 1998, v1.36, 9 September 1998, v1.35, 13 August
+1998, v1.33, 06 August 1998, v1.32, 05 August 1998, v1.30, 03 August 1998,
+v1.23, 10 July 1998
+
+=item Supported Platforms
+
 =item SEE ALSO
 
-=item HISTORY
+=item AUTHORS / CONTRIBUTORS
+
+=item VERSION
 
 =back
 
-=head2 perlunicode - Unicode support in Perl
+=head2 perlsec - Perl security
 
 =over
 
@@ -1885,21 +1965,18 @@ LC_NUMERIC, LC_TIME, LANG
 
 =over
 
-=item Important Caveat
+=item Laundering and Detecting Tainted Data
 
-Input and Output Disciplines, Regular Expressions, C<use utf8> still needed
-to enable a few features
+=item Switches On the "#!" Line
 
-=item Byte and Character semantics
+=item Cleaning Up Your Path
 
-=item Effects of character semantics
+=item Security Bugs
 
-=item Character encodings for input and output
+=item Protecting Your Programs
 
 =back
 
-=item CAVEATS
-
 =item SEE ALSO
 
 =back
@@ -2122,207 +2199,61 @@ to enable a few features
 
 =over
 
-=item An Object is Simply a Reference
-
-=item A Class is Simply a Package
-
-=item A Method is Simply a Subroutine
-
-=item Method Invocation
-
-=item WARNING
-
-=item Default UNIVERSAL methods
-
-isa(CLASS), can(METHOD), VERSION( [NEED] )
-
-=item Destructors
-
-=item Summary
-
-=item Two-Phased Garbage Collection
-
-=back
-
-=item SEE ALSO
-
-=back
-
-=head2 perlbot - Bag'o Object Tricks (the BOT)
-
-=over
-
-=item DESCRIPTION
-
-=item OO SCALING TIPS
-
-=item INSTANCE VARIABLES
-
-=item INSTANCE VARIABLE INHERITANCE
-
-=item OBJECT RELATIONSHIPS
-
-=item OVERRIDING SUPERCLASS METHODS
-
-=item USING RELATIONSHIP WITH SDBM
-
-=item THINKING OF CODE REUSE
-
-=item CLASS CONTEXT AND THE OBJECT
-
-=item INHERITING A CONSTRUCTOR
-
-=item DELEGATION
-
-=back
-
-=head2 perltie - how to hide an object class in a simple variable
-
-=over
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over
-
-=item Tying Scalars
-
-TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this
-
-=item Tying Arrays
-
-TIEARRAY classname, LIST, FETCH this, index, STORE this, index, value,
-DESTROY this
-
-=item Tying Hashes
-
-USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST, FETCH this, key, STORE
-this, key, value, DELETE this, key, CLEAR this, EXISTS this, key, FIRSTKEY
-this, NEXTKEY this, lastkey, DESTROY this
-
-=item Tying FileHandles
-
-TIEHANDLE classname, LIST, WRITE this, LIST, PRINT this, LIST, PRINTF this,
-LIST, READ this, LIST, READLINE this, GETC this, CLOSE this, DESTROY this
-
-=item The C<untie> Gotcha
-
-=back
-
-=item SEE ALSO
-
-=item BUGS
-
-=item AUTHOR
-
-=back
-
-=head2 perlipc - Perl interprocess communication (signals, fifos, pipes,
-safe subprocesses, sockets, and semaphores)
-
-=over
-
-=item DESCRIPTION
-
-=item Signals
-
-=item Named Pipes
-
-=over
-
-=item WARNING
-
-=back
-
-=item Using open() for IPC
-
-=over
-
-=item Filehandles
-
-=item Background Processes
-
-=item Complete Dissociation of Child from Parent
-
-=item Safe Pipe Opens
-
-=item Bidirectional Communication with Another Process
-
-=item Bidirectional Communication with Yourself
-
-=back
-
-=item Sockets: Client/Server Communication
-
-=over
-
-=item Internet Line Terminators
-
-=item Internet TCP Clients and Servers
-
-=item Unix-Domain TCP Clients and Servers
-
-=back
-
-=item TCP Clients with IO::Socket
-
-=over
-
-=item A Simple Client
-
-C<Proto>, C<PeerAddr>, C<PeerPort>
+=item An Object is Simply a Reference
 
-=item A Webget Client
+=item A Class is Simply a Package
 
-=item Interactive Client with IO::Socket
+=item A Method is Simply a Subroutine
 
-=back
+=item Method Invocation
 
-=item TCP Servers with IO::Socket
+=item WARNING
 
-Proto, LocalPort, Listen, Reuse
+=item Default UNIVERSAL methods
 
-=item UDP: Message Passing
+isa(CLASS), can(METHOD), VERSION( [NEED] )
 
-=item SysV IPC
+=item Destructors
 
-=item NOTES
+=item Summary
 
-=item BUGS
+=item Two-Phased Garbage Collection
 
-=item AUTHOR
+=back
 
 =item SEE ALSO
 
 =back
 
-=head2 perlnumber - semantics of numbers and numeric operations in Perl
+=head2 perlbot - Bag'o Object Tricks (the BOT)
 
 =over
 
-=item SYNOPSIS
-
 =item DESCRIPTION
 
-=item Storing numbers
+=item OO SCALING TIPS
 
-=item Numeric operators and numeric conversions
+=item INSTANCE VARIABLES
 
-=item Flavors of Perl numeric operations
+=item INSTANCE VARIABLE INHERITANCE
 
-Arithmetic operators except, C<no integer>, Arithmetic operators except,
-C<use integer>, Bitwise operators, C<no integer>, Bitwise operators, C<use
-integer>, Operators which expect an integer, Operators which expect a
-string
+=item OBJECT RELATIONSHIPS
 
-=item AUTHOR
+=item OVERRIDING SUPERCLASS METHODS
 
-=item SEE ALSO
+=item USING RELATIONSHIP WITH SDBM
+
+=item THINKING OF CODE REUSE
+
+=item CLASS CONTEXT AND THE OBJECT
+
+=item INHERITING A CONSTRUCTOR
+
+=item DELEGATION
 
 =back
 
-=head2 perlfork - Perl's fork() emulation
+=head2 perltie - how to hide an object class in a simple variable
 
 =over
 
@@ -2332,155 +2263,224 @@ string
 
 =over
 
-=item Behavior of other Perl features in forked pseudo-processes
+=item Tying Scalars
 
-$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept
-filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to
-files, directories and network sockets
+TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this
 
-=item Resource limits
+=item Tying Arrays
 
-=item Killing the parent process
+TIEARRAY classname, LIST, FETCH this, index, STORE this, index, value,
+DESTROY this
 
-=item Lifetime of the parent process and pseudo-processes
+=item Tying Hashes
 
-=item CAVEATS AND LIMITATIONS
+USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST, FETCH this, key, STORE
+this, key, value, DELETE this, key, CLEAR this, EXISTS this, key, FIRSTKEY
+this, NEXTKEY this, lastkey, DESTROY this
 
-BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented,
-Global state maintained by XSUBs, Interpreter embedded in larger
-application, Thread-safety of extensions
+=item Tying FileHandles
+
+TIEHANDLE classname, LIST, WRITE this, LIST, PRINT this, LIST, PRINTF this,
+LIST, READ this, LIST, READLINE this, GETC this, CLOSE this, DESTROY this
+
+=item The C<untie> Gotcha
 
 =back
 
+=item SEE ALSO
+
 =item BUGS
 
 =item AUTHOR
 
-=item SEE ALSO
-
 =back
 
-=head2 perlthrtut - tutorial on threads in Perl
+=head2 perlmod - Perl modules (packages and symbol tables)
 
 =over
 
 =item DESCRIPTION
 
-=item What Is A Thread Anyway?
+=over
 
-=item Threaded Program Models
+=item Packages
 
-=over
+=item Symbol Tables
 
-=item Boss/Worker
+=item Package Constructors and Destructors
 
-=item Work Crew
+=item Perl Classes
 
-=item Pipeline
+=item Perl Modules
 
 =back
 
-=item Native threads
-
-=item What kind of threads are perl threads?
+=item SEE ALSO
 
-=item Threadsafe Modules
+=back
 
-=item Thread Basics
+=head2 perlmodlib - constructing new Perl modules and finding existing ones
 
 =over
 
-=item Basic Thread Support
+=item DESCRIPTION
 
-=item Creating Threads
+=item THE PERL MODULE LIBRARY
 
-=item Giving up control
+=over
 
-=item Waiting For A Thread To Exit
+=item Pragmatic Modules
 
-=item Errors In Threads
+attributes, attrs, autouse, base, blib, bytes, charnames, constant,
+diagnostics, fields, filetest, integer, less, locale, open, ops, overload,
+re, sigtrap, strict, subs, utf8, vars, warnings
 
-=item Ignoring A Thread
+=item Standard Modules
 
-=back
+AnyDBM_File, AutoLoader, AutoSplit, B, B::Asmdata, B::Assembler, B::Bblock,
+B::Bytecode, B::C, B::CC, B::Debug, B::Deparse, B::Disassembler, B::Lint,
+B::Showlex, B::Stackobj, B::Terse, B::Xref, Benchmark, ByteLoader, CGI,
+CGI::Apache, CGI::Carp, CGI::Cookie, CGI::Fast, CGI::Pretty, CGI::Push,
+CGI::Switch, CPAN, CPAN::FirstTime, CPAN::Nox, Carp, Carp::Heavy,
+Class::Struct, Cwd, DB, DB_File, Devel::SelfStubber, DirHandle, Dumpvalue,
+English, Env, Exporter, Exporter::Heavy, ExtUtils::Command,
+ExtUtils::Embed, ExtUtils::Install, ExtUtils::Installed, ExtUtils::Liblist,
+ExtUtils::MM_Cygwin, ExtUtils::MM_OS2, ExtUtils::MM_Unix, ExtUtils::MM_VMS,
+ExtUtils::MM_Win32, ExtUtils::MakeMaker, ExtUtils::Manifest,
+ExtUtils::Mkbootstrap, ExtUtils::Mksymlists, ExtUtils::Packlist,
+ExtUtils::testlib, Fatal, Fcntl, File::Basename, File::CheckTree,
+File::Compare, File::Copy, File::DosGlob, File::Find, File::Path,
+File::Spec, File::Spec::Functions, File::Spec::Mac, File::Spec::OS2,
+File::Spec::Unix, File::Spec::VMS, File::Spec::Win32, File::Temp,
+File::stat, FileCache, FileHandle, FindBin, Getopt::Long, Getopt::Std,
+I18N::Collate, IO, IPC::Open2, IPC::Open3, Math::BigFloat, Math::BigInt,
+Math::Complex, Math::Trig, NDBM_File, Net::Ping, Net::hostent, Net::netent,
+Net::protoent, Net::servent, O, ODBM_File, Opcode, Pod::Checker, Pod::Find,
+Pod::Html, Pod::InputObjects, Pod::LaTeX, Pod::Man, Pod::ParseUtils,
+Pod::Parser, Pod::Plainer, Pod::Select, Pod::Text, Pod::Text::Color,
+Pod::Text::Termcap, Pod::Usage, SDBM_File, Safe, Search::Dict, SelectSaver,
+SelfLoader, Shell, Socket, Symbol, Term::ANSIColor, Term::Cap,
+Term::Complete, Term::ReadLine, Test, Test::Harness, Text::Abbrev,
+Text::ParseWords, Text::Soundex, Text::Wrap, Tie::Array, Tie::Handle,
+Tie::Hash, Tie::RefHash, Tie::Scalar, Tie::SubstrHash, Time::Local,
+Time::gmtime, Time::localtime, Time::tm, UNIVERSAL, User::grent,
+User::pwent
 
-=item Threads And Data
+=item Extension Modules
 
-=over
+=back
 
-=item Shared And Unshared Data
+=item CPAN
 
-=item Thread Pitfall: Races
+Language Extensions and Documentation Tools, Development Support, Operating
+System Interfaces, Networking, Device Control (modems) and InterProcess
+Communication, Data Types and Data Type Utilities, Database Interfaces,
+User Interfaces, Interfaces to / Emulations of Other Programming Languages,
+File Names, File Systems and File Locking (see also File Handles), String
+Processing, Language Text Processing, Parsing, and Searching, Option,
+Argument, Parameter, and Configuration File Processing,
+Internationalization and Locale, Authentication, Security, and Encryption,
+World Wide Web, HTML, HTTP, CGI, MIME, Server and Daemon Utilities,
+Archiving and Compression, Images, Pixmap and Bitmap Manipulation, Drawing,
+and Graphing, Mail and Usenet News, Control Flow Utilities (callbacks and
+exceptions etc), File Handle and Input/Output Stream Utilities,
+Miscellaneous Modules, Africa, Asia, Australasia, Central America, Europe,
+North America, South America
 
-=item Controlling access: lock()
+=item Modules: Creation, Use, and Abuse
 
-=item Thread Pitfall: Deadlocks
+=over
 
-=item Queues: Passing Data Around
+=item Guidelines for Module Creation
 
-=back
+Do similar modules already exist in some form?, Try to design the new
+module to be easy to extend and reuse, Some simple style guidelines, Select
+what to export, Select a name for the module, Have you got it right?,
+README and other Additional Files, A description of the
+module/package/extension etc, A copyright notice - see below, Prerequisites
+- what else you may need to have, How to build it - possible changes to
+Makefile.PL etc, How to install it, Recent changes in this release,
+especially incompatibilities, Changes / enhancements you plan to make in
+the future, Adding a Copyright Notice, Give the module a
+version/issue/release number, How to release and distribute a module, Take
+care when changing a released module
 
-=item Threads And Code
+=item Guidelines for Converting Perl 4 Library Scripts into Modules
 
-=over
+There is no requirement to convert anything, Consider the implications,
+Make the most of the opportunity, The pl2pm utility will get you started,
+Adds the standard Module prologue lines, Converts package specifiers from '
+to ::, Converts die(...) to croak(...), Several other minor changes
 
-=item Semaphores: Synchronizing Data Access
+=item Guidelines for Reusing Application Code
 
-Basic semaphores, Advanced Semaphores
+Complete applications rarely belong in the Perl Module Library, Many
+applications contain some Perl code that could be reused, Break-out the
+reusable code into one or more separate module files, Take the opportunity
+to reconsider and redesign the interfaces, In some cases the 'application'
+can then be reduced to a small
 
-=item Attributes: Restricting Access To Subroutines
+=back
 
-=item Subroutine Locks
+=item NOTE
 
-=item Methods
+=back
 
-=item Locking A Subroutine
+=head2 perlmodinstall - Installing CPAN Modules
 
-=back
+=over
 
-=item General Thread Utility Routines
+=item DESCRIPTION
 
 =over
 
-=item What Thread Am I In?
+=item PREAMBLE
 
-=item Thread IDs
+B<DECOMPRESS> the file, B<UNPACK> the file into a directory, B<BUILD> the
+module (sometimes unnecessary), B<INSTALL> the module
 
-=item Are These Threads The Same?
+=back
 
-=item What Threads Are Running?
+=item HEY
+
+=item AUTHOR
+
+=item COPYRIGHT
 
 =back
 
-=item A Complete Example
+=head2 perlnewmod - preparing a new module for distribution
 
-=item Conclusion
+=over
 
-=item Bibliography
+=item DESCRIPTION
 
 =over
 
-=item Introductory Texts
+=item Warning
 
-=item OS-Related References
+=item What should I make into a module?
 
-=item Other References
+=item Step-by-step: Preparing the ground
 
-=back
+Look around, Check it's new, Discuss the need, Choose a name, Check again
 
-=item Acknowledgements
+=item Step-by-step: Making the module
 
-=item AUTHOR
+Start with F<h2xs>, Use L<strict|strict> and L<warnings|warnings>, Use
+L<Carp|Carp>, Use L<Exporter|Exporter> - wisely!, Use L<plain old
+documentation|perlpod>, Write tests, Write the README
 
-=item Copyrights
+=item Step-by-step: Distributing your module
 
-=back
+Get a CPAN user ID, C<perl Makefile.PL; make test; make dist>, Upload the
+tarball, Announce to the modules list, Announce to clpa, Fix bugs!
 
-=head2 perldiag - various Perl diagnostics
+=back
 
-=over
+=item AUTHOR
 
-=item DESCRIPTION
+=item SEE ALSO
 
 =back