This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
; was Re: Perlbug 20000322.006 status +update
authorRobin Barker <RMBarker@cpan.org>
Fri, 22 Dec 2000 12:17:38 +0000 (12:17 +0000)
committerJarkko Hietaniemi <jhi@iki.fi>
Fri, 22 Dec 2000 15:29:40 +0000 (15:29 +0000)
Message-Id: <200012221217.MAA21332@tempest.npl.co.uk>

p4raw-id: //depot/perl@8228

18 files changed:
lib/CGI.pm
lib/CPAN.pm
lib/Pod/Select.pm
lib/Text/ParseWords.pm
lib/Win32.pod
pod/perl.pod
pod/perl5004delta.pod
pod/perl5005delta.pod
pod/perl56delta.pod
pod/perldelta.pod
pod/perldiag.pod
pod/perlembed.pod
pod/perlfaq4.pod
pod/perllocale.pod
pod/perlmodlib.pod
pod/perlrequick.pod
pod/perlretut.pod
pod/perlsub.pod

index 617c605..6b87054 100644 (file)
@@ -3530,12 +3530,18 @@ have several choices:
 
 =over 4
 
-=item 1. Use another name for the argument, if one is available.  For
-example, -value is an alias for -values.
+=item 1.
+
+Use another name for the argument, if one is available. 
+For example, -value is an alias for -values.
 
-=item 2. Change the capitalization, e.g. -Values
+=item 2.
 
-=item 3. Put quotes around the argument name, e.g. '-values'
+Change the capitalization, e.g. -Values
+
+=item 3.
+
+Put quotes around the argument name, e.g. '-values'
 
 =back
 
@@ -5669,6 +5675,7 @@ field.
 The second argument (-src) is also required and specifies the URL
 
 =item 3.
+
 The third option (-align, optional) is an alignment type, and may be
 TOP, BOTTOM or MIDDLE
 
@@ -6102,6 +6109,7 @@ Returns either the remote host name or IP address.
 if the former is unavailable.
 
 =item B<script_name()>
+
 Return the script name as a partial URL, for self-refering
 scripts.
 
@@ -6220,7 +6228,9 @@ Call B<nph()> with a non-zero parameter at any point after using CGI.pm in your
 
       CGI->nph(1)
 
-=item By using B<-nph> parameters in the B<header()> and B<redirect()>  statements:
+=item By using B<-nph> parameters
+
+in the B<header()> and B<redirect()>  statements:
 
       print $q->header(-nph=>1);
 
index daa34e8..ca89b50 100644 (file)
@@ -6625,8 +6625,10 @@ Your milage may vary...
 
 =over
 
-=item 1) I installed a new version of module X but CPAN keeps saying,
-      I have the old version installed
+=item 1)
+
+I installed a new version of module X but CPAN keeps saying,
+I have the old version installed
 
 Most probably you B<do> have the old version installed. This can
 happen if a module installs itself into a different directory in the
@@ -6638,14 +6640,18 @@ many people add this argument permanently by configuring
 
   o conf make_install_arg UNINST=1
 
-=item 2) So why is UNINST=1 not the default?
+=item 2)
+
+So why is UNINST=1 not the default?
 
 Because there are people who have their precise expectations about who
 may install where in the @INC path and who uses which @INC array. In
 fine tuned environments C<UNINST=1> can cause damage.
 
-=item 3) I want to clean up my mess, and install a new perl along with
-      all modules I have. How do I go about it?
+=item 3)
+
+I want to clean up my mess, and install a new perl along with
+all modules I have. How do I go about it?
 
 Run the autobundle command for your old perl and optionally rename the
 resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
@@ -6659,8 +6665,10 @@ Install the bundle file you produced in the first step with something like
 
 and you're done.
 
-=item 4) When I install bundles or multiple modules with one command
-      there is too much output to keep track of
+=item 4)
+
+When I install bundles or multiple modules with one command
+there is too much output to keep track of.
 
 You may want to configure something like
 
@@ -6670,8 +6678,9 @@ You may want to configure something like
 so that STDOUT is captured in a file for later inspection.
 
 
-=item 5) I am not root, how can I install a module in a personal
-      directory?
+=item 5)
+
+I am not root, how can I install a module in a personal directory?
 
 You will most probably like something like this:
 
@@ -6694,14 +6703,17 @@ or setting the PERL5LIB environment variable.
 Another thing you should bear in mind is that the UNINST parameter
 should never be set if you are not root.
 
-=item 6) How to get a package, unwrap it, and make a change before
-      building it?
+=item 6)
+
+How to get a package, unwrap it, and make a change before building it?
 
   look Sybase::Sybperl
 
-=item 7) I installed a Bundle and had a couple of fails. When I
-      retried, everything resolved nicely. Can this be fixed to work
-      on first try?
+=item 7)
+
+I installed a Bundle and had a couple of fails. When I
+retried, everything resolved nicely. Can this be fixed to work
+on first try?
 
 The reason for this is that CPAN does not know the dependencies of all
 modules when it starts out. To decide about the additional items to
@@ -6718,21 +6730,27 @@ definition file manually. It is planned to improve the metadata
 situation for dependencies on CPAN in general, but this will still
 take some time.
 
-=item 8) In our intranet we have many modules for internal use. How
-      can I integrate these modules with CPAN.pm but without uploading
-      the modules to CPAN?
+=item 8)
+
+In our intranet we have many modules for internal use. How
+can I integrate these modules with CPAN.pm but without uploading
+the modules to CPAN?
 
 Have a look at the CPAN::Site module.
 
-=item 9) When I run CPAN's shell, I get error msg about line 1 to 4,
-      setting meta input/output via the /etc/inputrc file.
+=item 9)
+
+When I run CPAN's shell, I get error msg about line 1 to 4,
+setting meta input/output via the /etc/inputrc file.
 
 Some versions of readline are picky about capitalization in the
 /etc/inputrc file and specifically RedHat 6.2 comes with a
 /etc/inputrc that contains the word C<on> in lowercase. Change the
 occurrences of C<on> to C<On> and the bug should disappear.
 
-=item 10) Some authors have strange characters in their names.
+=item 10)
+
+Some authors have strange characters in their names.
 
 Internally CPAN.pm uses the UTF-8 charset. If your terminal is
 expecting ISO-8859-1 charset, a converter can be activated by setting
index d86d823..e7c820f 100644 (file)
@@ -109,33 +109,39 @@ Some example section specifications follow.
 
 =over 4
 
-=item
+=item *
+
 Match the C<NAME> and C<SYNOPSIS> sections and all of their subsections:
 
 C<NAME|SYNOPSIS>
 
-=item
+=item *
+
 Match only the C<Question> and C<Answer> subsections of the C<DESCRIPTION>
 section:
 
 C<DESCRIPTION/Question|Answer>
 
-=item
+=item *
+
 Match the C<Comments> subsection of I<all> sections:
 
 C</Comments>
 
-=item
+=item *
+
 Match all subsections of C<DESCRIPTION> I<except> for C<Comments>:
 
 C<DESCRIPTION/!Comments>
 
-=item
+=item *
+
 Match the C<DESCRIPTION> section but do I<not> match any of its subsections:
 
 C<DESCRIPTION/!.+>
 
-=item
+=item *
+
 Match all top level sections but none of their subsections:
 
 C</!.+>
index 2a6afc3..23eace9 100644 (file)
@@ -214,21 +214,27 @@ demonstrating:
 =over 4
 
 =item 0
+
 a simple word
 
 =item 1
+
 multiple spaces are skipped because of our $delim
 
 =item 2
+
 use of quotes to include a space in a word
 
 =item 3
+
 use of a backslash to include a space in a word
 
 =item 4
+
 use of a backslash to remove the special meaning of a double-quote
 
 =item 5
+
 another simple word (note the lack of effect of the
 backslashed double-quote)
 
index 64361f8..303374b 100644 (file)
@@ -175,7 +175,9 @@ function.
 system boot. Resolution is limited to system timer ticks (about 10ms
 on WinNT and 55ms on Win9X).
 
-=item Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
+=item
+
+Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
 
 [EXT] Shutsdown the specified MACHINE, notifying users with the
 supplied MESSAGE, within the specified TIMEOUT interval. Forces
index aa4e77f..0d2c1c3 100644 (file)
@@ -192,56 +192,83 @@ rewrite that provides the following additional benefits:
 
 =over 4
 
-=item * modularity and reusability using innumerable modules 
+=item *
+
+modularity and reusability using innumerable modules 
 
 Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
 
-=item * embeddable and extensible 
+=item *
+
+embeddable and extensible 
 
 Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
 L<perlguts>, and L<xsubpp>.
 
-=item * roll-your-own magic variables (including multiple simultaneous DBM implementations)
+=item *
+
+roll-your-own magic variables (including multiple simultaneous DBM implementations)
 
 Described in L<perltie> and L<AnyDBM_File>.
 
-=item * subroutines can now be overridden, autoloaded, and prototyped
+=item *
+
+subroutines can now be overridden, autoloaded, and prototyped
 
 Described in L<perlsub>.
 
-=item * arbitrarily nested data structures and anonymous functions
+=item *
+
+arbitrarily nested data structures and anonymous functions
 
 Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
 
-=item * object-oriented programming
+=item *
+
+object-oriented programming
 
 Described in L<perlobj>, L<perltoot>, and L<perlbot>.
 
-=item * compilability into C code or Perl bytecode
+=item *
+
+compilability into C code or Perl bytecode
 
 Described in L<B> and L<B::Bytecode>.
 
-=item * support for light-weight processes (threads)
+=item *
+
+support for light-weight processes (threads)
 
 Described in L<perlthrtut> and L<Thread>.
 
-=item * support for internationalization, localization, and Unicode 
+=item *
+
+support for internationalization, localization, and Unicode 
 
 Described in L<perllocale> and L<utf8>.
 
-=item * lexical scoping
+=item *
+
+lexical scoping
 
 Described in L<perlsub>.
 
-=item * regular expression enhancements
+=item *
+
+regular expression enhancements
 
 Described in L<perlre>, with additional examples in L<perlop>.
 
-=item * enhanced debugger and interactive Perl environment, with integrated editor support
+=item *
+
+enhanced debugger and interactive Perl environment,
+with integrated editor support
 
 Described in L<perldebug>.
 
-=item * POSIX 1003.1 compliant library
+=item *
+
+POSIX 1003.1 compliant library
 
 Described in L<POSIX>.
 
index 7151d86..429cba9 100644 (file)
@@ -1432,7 +1432,7 @@ assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves
 like a list when you assign to it, and provides a list context to its
 subscript, which can do weird things if you're expecting only one subscript.
 
-=item Stub found while resolving method `%s' overloading `%s' in package `%s'
+=item Stub found while resolving method `%s' overloading `%s' in %s
 
 (P) Overloading resolution over @ISA tree may be broken by importing stubs.
 Stubs should never be implicitly created, but explicit calls to C<can>
index d863453..4b50f40 100644 (file)
@@ -63,11 +63,15 @@ the new features in this release.
 
 =over 4
 
-=item Core sources now require ANSI C compiler
+=item *
+
+Core sources now require ANSI C compiler
 
 An ANSI C compiler is now B<required> to build perl.  See F<INSTALL>.
 
-=item All Perl global variables must now be referenced with an explicit prefix
+=item *
+
+All Perl global variables must now be referenced with an explicit prefix
 
 All Perl global variables that are visible for use by extensions now
 have a C<PL_> prefix.  New extensions should C<not> refer to perl globals
@@ -87,7 +91,9 @@ support may cease in a future release.
 
 See L<perlguts/"API LISTING">.
 
-=item Enabling threads has source compatibility issues
+=item *
+
+Enabling threads has source compatibility issues
 
 Perl built with threading enabled requires extensions to use the new
 C<dTHR> macro to initialize the handle to access per-thread data.
@@ -859,7 +865,7 @@ are outside the range which can be represented by integers internally.
 One possible workaround is to force Perl to use magical string
 increment by prepending "0" to your numbers.
 
-=item Recursive inheritance detected while looking for method '%s' in package '%s'
+=item Recursive inheritance detected while looking for method '%s' %s
 
 (F) More than 100 levels of inheritance were encountered while invoking a
 method.  Probably indicates an unintended loop in your inheritance hierarchy.
index d11f908..a0c4b06 100644 (file)
@@ -2631,7 +2631,9 @@ but still allowed it.
 
 In Perl 5.6.0 and later, C<"$$1"> always means C<"${$1}">.
 
-=item delete(), values() and C<\(%h)> operate on aliases to values, not copies
+=item
+
+delete(), values() and C<\(%h)> operate on aliases to values, not copies
 
 delete(), each(), values() and hashes in a list context return the actual
 values in the hash, instead of copies (as they used to in earlier
index 8ea61b3..3c26282 100644 (file)
@@ -314,7 +314,7 @@ distribution.
 map() that changes the size of the list should now work faster.
 
 =item *
+
 sort() has been changed to use mergesort internally as opposed to the
 earlier quicksort.  For very small lists this may result in slightly
 slower sorting times, but in general the speedup should be at least
@@ -469,7 +469,7 @@ Regular expressions on references and overloaded scalars now work.
 scalar() now forces scalar context even when used in void context.
 
 =item *
-       
+
 sort() arguments are now compiled in the right wantarray context
 (they were accidentally using the context of the sort() itself).
 
index a27dde7..abbdea7 100644 (file)
@@ -1785,7 +1785,7 @@ instead on the filehandle.)
 values cannot be returned in subroutines used in lvalue context.  See
 L<perlsub/"Lvalue subroutines">.
 
-=item Lookbehind longer than %d not implemented before << HERE in reges m/%s/
+=item Lookbehind longer than %d not implemented before << HERE %s
 
 (F) There is currently a limit on the length of string which lookbehind can
 handle. This restriction may be eased in a future release. The << HERE shows in
@@ -2770,7 +2770,7 @@ declared or defined with a different function prototype.
 {min,max} construct. The << HERE shows in the regular expression about where
 the problem was discovered. See L<perlre>.
 
-=item Quantifier unexpected on zero-length expression before << HERE in regex m/%s/
+=item Quantifier unexpected on zero-length expression before << HERE %s
 
 (W regexp) You applied a regular expression quantifier in a place where
 it makes no sense, such as on a zero-width assertion.  Try putting the
@@ -2961,18 +2961,18 @@ before now.  Check your control flow.
 shows in the regular expression about where the problem was discovered. See
 L<perlre>.
 
-=item Sequence (?{...}) not terminated or not {}-balanced in regex m/%s/
+=item Sequence (?{...}) not terminated or not {}-balanced in %s
 
 (F) If the contents of a (?{...}) clause contains braces, they must balance
 for Perl to properly detect the end of the clause. See L<perlre>.
 
-=item Sequence (?%s...) not implemented before << HERE mark in regex m/%s/
+=item Sequence (?%s...) not implemented before << HERE mark in %s
 
 (F) A proposed regular expression extension has the character reserved but
 has not yet been written. The << HERE shows in the regular expression about
 where the problem was discovered. See L<perlre>.
 
-=item Sequence (?%s...) not recognized before << HERE mark in regex m/%s/
+=item Sequence (?%s...) not recognized before << HERE mark in %s
 
 (F) You used a regular expression extension that doesn't make sense.
 The << HERE shows in the regular expression about
@@ -3163,7 +3163,7 @@ assignment or as a subroutine argument for example).
 (F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but
 a version of the setuid emulator somehow got run anyway.
 
-=item Switch (?(condition)... contains too many branches before << HERE in regex m/%s/
+=item Switch (?(condition)... contains too many branches before << HE%s
 
 (F) A (?(condition)if-clause|else-clause) construct can have at most two
 branches (the if-clause and the else-clause). If you want one or both to
@@ -3813,7 +3813,7 @@ anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
 reference variables in outer subroutines are called or referenced, they
 are automatically rebound to the current values of such variables.
 
-=item Variable length lookbehind not implemented before << HERE in regex m/%s/
+=item Variable length lookbehind not implemented before << HERE in %s
 
 (F) Lookbehind is allowed only for subexpressions whose length is fixed and
 known at compile time. The << HERE shows in the regular expression about where
index 6e3db32..57d1bdb 100644 (file)
@@ -37,25 +37,45 @@ Read on...
 
 =over 5
 
-=item Compiling your C program
+=item *
 
-=item Adding a Perl interpreter to your C program
+Compiling your C program
 
-=item Calling a Perl subroutine from your C program
+=item *
 
-=item Evaluating a Perl statement from your C program
+Adding a Perl interpreter to your C program
 
-=item Performing Perl pattern matches and substitutions from your C program
+=item *
 
-=item Fiddling with the Perl stack from your C program
+Calling a Perl subroutine from your C program
 
-=item Maintaining a persistent interpreter
+=item *
 
-=item Maintaining multiple interpreter instances
+Evaluating a Perl statement from your C program
 
-=item Using Perl modules, which themselves use C libraries, from your C program
+=item *
 
-=item Embedding Perl under Win32
+Performing Perl pattern matches and substitutions from your C program
+
+=item *
+
+Fiddling with the Perl stack from your C program
+
+=item *
+
+Maintaining a persistent interpreter
+
+=item *
+
+Maintaining multiple interpreter instances
+
+=item *
+
+Using Perl modules, which themselves use C libraries, from your C program
+
+=item *
+
+Embedding Perl under Win32
 
 =back 
 
index 23bc666..1198f18 100644 (file)
@@ -948,7 +948,9 @@ ordered and whether you wish to preserve the ordering.
 
 =over 4
 
-=item a) If @in is sorted, and you want @out to be sorted:
+=item a)
+
+If @in is sorted, and you want @out to be sorted:
 (this assumes all true values in the array)
 
     $prev = 'nonesuch';
@@ -959,22 +961,30 @@ uniq(1)'s behavior of removing only adjacent duplicates.  The ", 1"
 guarantees that the expression is true (so that grep picks it up)
 even if the $_ is 0, "", or undef.
 
-=item b) If you don't know whether @in is sorted:
+=item b)
+
+If you don't know whether @in is sorted:
 
     undef %saw;
     @out = grep(!$saw{$_}++, @in);
 
-=item c) Like (b), but @in contains only small integers:
+=item c)
+
+Like (b), but @in contains only small integers:
 
     @out = grep(!$saw[$_]++, @in);
 
-=item d) A way to do (b) without any loops or greps:
+=item d)
+
+A way to do (b) without any loops or greps:
 
     undef %saw;
     @saw{@in} = ();
     @out = sort keys %saw;  # remove sort if undesired
 
-=item e) Like (d), but @in contains only small positive integers:
+=item e)
+
+Like (d), but @in contains only small positive integers:
 
     undef @ary;
     @ary[@in] = @in;
index f0c64c7..d37664c 100644 (file)
@@ -678,16 +678,22 @@ the locale:
 
 =over 4
 
-=item B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):
+=item  *
+
+B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):
 
 Scalar true/false (or less/equal/greater) result is never tainted.
 
-=item B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
+=item  *
+
+B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
 
 Result string containing interpolated material is tainted if
 C<use locale> is in effect.
 
-=item B<Matching operator> (C<m//>):
+=item  *
+
+B<Matching operator> (C<m//>):
 
 Scalar true/false result never tainted.
 
@@ -700,7 +706,9 @@ expression contains C<\w> (to match an alphanumeric character), C<\W>
 C<use locale> is in effect and the regular expression contains C<\w>,
 C<\W>, C<\s>, or C<\S>.
 
-=item B<Substitution operator> (C<s///>):
+=item  *
+
+B<Substitution operator> (C<s///>):
 
 Has the same behavior as the match operator.  Also, the left
 operand of C<=~> becomes tainted when C<use locale> in effect
@@ -708,22 +716,30 @@ if modified as a result of a substitution based on a regular
 expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of
 case-mapping with C<\l>, C<\L>,C<\u> or C<\U>.
 
-=item B<Output formatting functions> (printf() and write()):
+=item *
+
+B<Output formatting functions> (printf() and write()):
 
 Results are never tainted because otherwise even output from print,
 for example C<print(1/7)>, should be tainted if C<use locale> is in
 effect.
 
-=item B<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()):
+=item *
+
+B<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()):
 
 Results are tainted if C<use locale> is in effect.
 
-=item B<POSIX locale-dependent functions> (localeconv(), strcoll(),
+=item *
+
+B<POSIX locale-dependent functions> (localeconv(), strcoll(),
 strftime(), strxfrm()):
 
 Results are never tainted.
 
-=item B<POSIX character class tests> (isalnum(), isalpha(), isdigit(),
+=item *
+
+B<POSIX character class tests> (isalnum(), isalpha(), isdigit(),
 isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(),
 isxdigit()):
 
index 1810e00..d0bd1c9 100644 (file)
@@ -802,66 +802,87 @@ modules are:
 =over
 
 =item *
+
 Language Extensions and Documentation Tools
 
 =item *
+
 Development Support
 
 =item *
+
 Operating System Interfaces
 
 =item *
+
 Networking, Device Control (modems) and InterProcess Communication
 
 =item *
+
 Data Types and Data Type Utilities
 
 =item *
+
 Database Interfaces
 
 =item *
+
 User Interfaces
 
 =item *
+
 Interfaces to / Emulations of Other Programming Languages
 
 =item *
+
 File Names, File Systems and File Locking (see also File Handles)
 
 =item *
+
 String Processing, Language Text Processing, Parsing, and Searching
 
 =item *
+
 Option, Argument, Parameter, and Configuration File Processing
 
 =item *
+
 Internationalization and Locale
 
 =item *
+
 Authentication, Security, and Encryption
 
 =item *
+
 World Wide Web, HTML, HTTP, CGI, MIME
 
 =item *
+
 Server and Daemon Utilities
 
 =item *
+
 Archiving and Compression
 
 =item *
+
 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
 
 =item *
+
 Mail and Usenet News
 
 =item *
+
 Control Flow Utilities (callbacks and exceptions etc)
 
 =item *
+
 File Handle and Input/Output Stream Utilities
 
 =item *
+
 Miscellaneous Modules
 
 =back
@@ -1430,18 +1451,28 @@ Don't delete the original .pl file till the new .pm one works!
 
 =over 4
 
-=item Complete applications rarely belong in the Perl Module Library.
+=item *
+
+Complete applications rarely belong in the Perl Module Library.
 
-=item Many applications contain some Perl code that could be reused.
+=item *
+
+Many applications contain some Perl code that could be reused.
 
 Help save the world! Share your code in a form that makes it easy
 to reuse.
 
-=item Break-out the reusable code into one or more separate module files.
+=item *
+
+Break-out the reusable code into one or more separate module files.
 
-=item Take the opportunity to reconsider and redesign the interfaces.
+=item *
+
+Take the opportunity to reconsider and redesign the interfaces.
+
+=item *
 
-=item In some cases the 'application' can then be reduced to a small
+In some cases the 'application' can then be reduced to a small
 
 fragment of code built on top of the reusable modules. In these cases
 the application could invoked as:
index a14229c..3e29a4a 100644 (file)
@@ -166,24 +166,31 @@ Perl has several abbreviations for common character classes:
 =over 4
 
 =item *
+
 \d is a digit and represents [0-9]
 
 =item *
+
 \s is a whitespace character and represents [\ \t\r\n\f]
 
 =item *
+
 \w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_]
 
 =item *
+
 \D is a negated \d; it represents any character but a digit [^0-9]
 
 =item *
+
 \S is a negated \s; it represents any non-whitespace character [^\s]
 
 =item *
+
 \W is a negated \w; it represents any non-word character [^\w]
 
 =item *
+
 The period '.' matches any character but "\n"
 
 =back
index 2c449f8..a77b87e 100644 (file)
@@ -368,24 +368,31 @@ has several abbreviations for common character classes:
 =over 4
 
 =item *
+
 \d is a digit and represents [0-9]
 
 =item *
+
 \s is a whitespace character and represents [\ \t\r\n\f]
 
 =item *
+
 \w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_]
 
 =item *
+
 \D is a negated \d; it represents any character but a digit [^0-9]
 
 =item *
+
 \S is a negated \s; it represents any non-whitespace character [^\s]
 
 =item *
+
 \W is a negated \w; it represents any non-word character [^\w]
 
 =item *
+
 The period '.' matches any character but "\n"
 
 =back
@@ -451,22 +458,26 @@ and C<$> are able to match.  Here are the four possible combinations:
 =over 4
 
 =item *
+
 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.
 
 =item *
+
 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.
 
 =item *
+
 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.
 
 =item *
+
 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
@@ -602,32 +613,52 @@ of what perl does when it tries to match the regexp
 
 =over 4
 
-=item 0 Start with the first letter in the string 'a'.
+=item 0
+
+Start with the first letter in the string 'a'.
+
+=item 1
 
-=item 1 Try the first alternative in the first group 'abd'.
+Try the first alternative in the first group 'abd'.
 
-=item 2 Match 'a' followed by 'b'. So far so good.
+=item 2
 
-=item 3 'd' in the regexp doesn't match 'c' in the string - a dead
+Match 'a' followed by 'b'. So far so good.
+
+=item 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'.
 
-=item 4 Match 'a' followed by 'b' followed by 'c'.  We are on a roll
+=item 4
+
+Match 'a' followed by 'b' followed by 'c'.  We are on a roll
 and have satisfied the first group. Set $1 to 'abc'.
 
-=item 5 Move on to the second group and pick the first alternative
+=item 5
+
+Move on to the second group and pick the first alternative
 'df'.
 
-=item 6 Match the 'd'.
+=item 6
 
-=item 7 'f' in the regexp doesn't match 'e' in the string, so a dead
+Match the 'd'.
+
+=item 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'.
 
-=item 8 'd' matches. The second grouping is satisfied, so set $2 to
+=item 8
+
+'d' matches. The second grouping is satisfied, so set $2 to
 'd'.
 
-=item 9 We are at the end of the regexp, so we are done! We have
+=item 9
+
+We are at the end of the regexp, so we are done! We have
 matched 'abcd' out of the string "abcde".
 
 =back
@@ -770,18 +801,30 @@ meanings:
 
 =over 4
 
-=item * C<a?> = match 'a' 1 or 0 times
+=item *
 
-=item * C<a*> = match 'a' 0 or more times, i.e., any number of times
+C<a?> = match 'a' 1 or 0 times
 
-=item * C<a+> = match 'a' 1 or more times, i.e., at least once
+=item *
+
+C<a*> = match 'a' 0 or more times, i.e., any number of times
+
+=item *
 
-=item * C<a{n,m}> = match at least C<n> times, but not more than C<m>
+C<a+> = match 'a' 1 or more times, i.e., at least once
+
+=item *
+
+C<a{n,m}> = match at least C<n> times, but not more than C<m>
 times.
 
-=item * C<a{n,}> = match at least C<n> or more times
+=item *
+
+C<a{n,}> = match at least C<n> or more times
+
+=item *
 
-=item * C<a{n}> = match exactly C<n> times
+C<a{n}> = match exactly C<n> times
 
 =back
 
@@ -845,19 +888,23 @@ the principles above to predict which way the regexp will match:
 =over 4
 
 =item *
+
 Principle 0: Taken as a whole, any regexp will be matched at the
 earliest possible position in the string.
 
 =item *
+
 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.
 
 =item *
+
 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.
 
 =item *
+
 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
@@ -925,21 +972,33 @@ following meanings:
 
 =over 4
 
-=item * C<a??> = match 'a' 0 or 1 times. Try 0 first, then 1.
+=item *
+
+C<a??> = match 'a' 0 or 1 times. Try 0 first, then 1.
 
-=item * C<a*?> = match 'a' 0 or more times, i.e., any number of times,
+=item *
+
+C<a*?> = match 'a' 0 or more times, i.e., any number of times,
 but as few times as possible
 
-=item * C<a+?> = match 'a' 1 or more times, i.e., at least once, but
+=item *
+
+C<a+?> = match 'a' 1 or more times, i.e., at least once, but
 as few times as possible
 
-=item * C<a{n,m}?> = match at least C<n> times, not more than C<m>
+=item *
+
+C<a{n,m}?> = match at least C<n> times, not more than C<m>
 times, as few times as possible
 
-=item * C<a{n,}?> = match at least C<n> times, but as few times as
+=item *
+
+C<a{n,}?> = match at least C<n> times, but as few times as
 possible
 
-=item * C<a{n}?> = match exactly C<n> times.  Because we match exactly
+=item *
+
+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.
 
@@ -998,6 +1057,7 @@ quantifiers:
 =over 4
 
 =item *
+
 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
@@ -1019,23 +1079,37 @@ backtracking.  Here is a step-by-step analysis of the example
 
 =over 4
 
-=item 0 Start with the first letter in the string 't'.
+=item 0
+
+Start with the first letter in the string 't'.
 
-=item 1 The first quantifier '.*' starts out by matching the whole
+=item 1
+
+The first quantifier '.*' starts out by matching the whole
 string 'the cat in the hat'.
 
-=item 2 'a' in the regexp element 'at' doesn't match the end of the
+=item 2
+
+'a' in the regexp element 'at' doesn't match the end of the
 string.  Backtrack one character.
 
-=item 3 'a' in the regexp element 'at' still doesn't match the last
+=item 3
+
+'a' in the regexp element 'at' still doesn't match the last
 letter of the string 't', so backtrack one more character.
 
-=item 4 Now we can match the 'a' and the 't'.
+=item 4
+
+Now we can match the 'a' and the 't'.
 
-=item 5 Move on to the third element '.*'.  Since we are at the end of
+=item 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.
 
-=item 6 We are done!
+=item 6
+
+We are done!
 
 =back
 
@@ -1180,15 +1254,25 @@ This is our final regexp.  To recap, we built a regexp by
 
 =over 4
 
-=item * specifying the task in detail,
+=item *
+
+specifying the task in detail,
 
-=item * breaking down the problem into smaller parts,
+=item *
+
+breaking down the problem into smaller parts,
+
+=item *
 
-=item * translating the small parts into regexps,
+translating the small parts into regexps,
 
-=item * combining the regexps,
+=item *
+
+combining the regexps,
+
+=item *
 
-=item * and optimizing the final combined regexp.
+and optimizing the final combined regexp.
 
 =back
 
index ae128ce..cef8050 100644 (file)
@@ -699,7 +699,9 @@ I<must> use C<local> instead of C<my>.
 
 =over 4
 
-=item 1. You need to give a global variable a temporary value, especially $_.
+=item 1.
+
+You need to give a global variable a temporary value, especially $_.
 
 The global variables, like C<@ARGV> or the punctuation variables, must be 
 C<local>ized with C<local()>.  This block reads in F</etc/motd>, and splits
@@ -716,7 +718,9 @@ in C<@Fields>.
 It particular, it's important to C<local>ize $_ in any routine that assigns
 to it.  Look out for implicit assignments in C<while> conditionals.
 
-=item 2. You need to create a local file or directory handle or a local function.
+=item 2.
+
+You need to create a local file or directory handle or a local function.
 
 A function that needs a filehandle of its own must use
 C<local()> on a complete typeglob.   This can be used to create new symbol
@@ -746,7 +750,9 @@ a local alias.
 See L<perlref/"Function Templates"> for more about manipulating
 functions by name in this way.
 
-=item 3. You want to temporarily change just one element of an array or hash.
+=item 3.
+
+You want to temporarily change just one element of an array or hash.
 
 You can C<local>ize just one element of an aggregate.  Usually this
 is done on dynamics: