integrate cfgperl changes into mainline, fix conflicts

p4raw-id: //depot/perl@2620

1 files changed, 30 insertions, 120 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0f8a0609c5..f9bd2c56ad 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -135,10 +135,8 @@ C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your perl program
 
-C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<else>, C<elsif>,
-C<eval>, C<exit>, C<for>, C<foreach>, C<goto>, C<if>, C<last>,
-C<next>, C<redo>, C<return>, C<sub>, C<unless>, C<wantarray>,
-C<while>, C<until>
+C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
+C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
 =item Keywords related to scoping
 
@@ -680,14 +678,14 @@ L<perlipc/"Sockets: Client/Server Communication">.
 =item continue BLOCK
 
 Actually a flow control statement rather than a function.  If there is a
-C<continue> BLOCK attached to a BLOCK (typically in a L</while> or
-L</foreach>), it is always executed just before the conditional is about to
-be evaluated again, just like the third part of a L</for> loop in C.  Thus
+C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
+C<foreach>), it is always executed just before the conditional is about to
+be evaluated again, just like the third part of a C<for> loop in C.  Thus
 it can be used to increment a loop variable, even when the loop has been
 continued via the C<next> statement (which is similar to the C C<continue>
 statement).
 
-L</last>, L</next>, or L</redo> may appear within a C<continue>
+C<last>, C<next>, or C<redo> may appear within a C<continue>
 block. C<last> and C<redo> will behave as if they had been executed within
 the main block. So will C<next>, but since it will execute a C<continue>
 block, it may be more entertaining.
@@ -706,8 +704,6 @@ Omitting the C<continue> section is semantically equivalent to using an
 empty one, logically enough. In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
-See also L<perlsyn>.
-
 =item cos EXPR
 
 Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
@@ -953,12 +949,11 @@ as the first line of the handler (see L<perlvar/$^S>).
 
 Not really a function.  Returns the value of the last command in the
 sequence of commands indicated by BLOCK.  When modified by a loop
-modifier such as L</while> or L</until>, executes the BLOCK once
-before testing the loop condition.  (On other statements the loop
-modifiers test the conditional first.)
+modifier, executes the BLOCK once before testing the loop condition.
+(On other statements the loop modifiers test the conditional first.)
 
 C<do BLOCK> does I<not> count as a loop, so the loop control statements
-L</next>, L</last> or L</redo> cannot be used to leave or restart the block.
+C<next>, C<last> or C<redo> cannot be used to leave or restart the block.
 
 =item do SUBROUTINE(LIST)
 
@@ -1077,12 +1072,6 @@ only in a different order:
 
 See also C<keys()>, C<values()> and C<sort()>.
 
-=item else BLOCK
-
-=item elsif (EXPR) BLOCK
-
-See L</if>.
-
 =item eof FILEHANDLE
 
 =item eof ()
@@ -1454,38 +1443,6 @@ Here's a mailbox appender for BSD systems.
 
 See also L<DB_File> for other flock() examples.
 
-=item for (INITIAL; WHILE; EACH) BLOCK
-
-Do INITIAL, enter BLOCK while EXPR is true, at the end of each round
-do EACH. For example:
-
-	for ($i = 0, $j = 0; $i < 10; $i++) {
-		if ($i % 3 == 0) { $j++ }
-		print "i = $i, j = $j\n";
-	}
-
-See L<perlsyn> for more details.  See also L</foreach>, a twin of
-C<for>, L</while> and L</until>, close cousins of L<for>, and
-L</last>, L</next>, and L</redo> for additional control flow.
-
-=item foreach LOOPVAR (LIST) BLOCK
-
-Enter BLOCK as LOOPVAR set in turn to each element of LIST.
-For example:
-
-	foreach $rolling (@stones) { print "$rolling stone\n" }
-
-	foreach my $file (@files)  { print "file $file\n" }
-
-The LOOPVAR is optional and defaults to C<$_>.  If the elements are
-modifiable (as opposed to constants or tied variables) you can modify them.
-
-	foreach (@words) { tr/abc/xyz/ }
-
-See L<perlsyn> for more details.  See also L</for>, a twin of
-C<foreach>, L</while> and L</until>, close cousins of L<for>, and
-L</last>, L</next>, and L</redo> for additional control flow.
-
 =item fork
 
 Does a fork(2) system call.  Returns the child pid to the parent process,
@@ -1592,7 +1549,7 @@ is left as an exercise to the reader.
 The C<POSIX::getattr()> function can do this more portably on systems
 purporting POSIX compliance.
 See also the C<Term::ReadKey> module from your nearest CPAN site;
-details on CPAN can be found on L<perlmod/CPAN>.
+details on CPAN can be found on L<perlmodlib/CPAN>.
 
 =item getlogin
 
@@ -1892,24 +1849,6 @@ see L</oct>.)  If EXPR is omitted, uses C<$_>.
     print hex '0xAf'; # prints '175'
     print hex 'aF';   # same
 
-=item if (EXPR) BLOCK
-
-=item if (EXPR) BLOCK else BLOCK2
-
-=item if (EXPR) BLOCK elsif (EXPR2) BLOCK2
-
-Enter BLOCKs conditionally.  The first EXPR to return true
-causes the corresponding BLOCK to be entered, or, in the case
-of C<else>, the fall-through default BLOCK.
-
-Note 1: Perl wants BLOCKS, expressions won't do (like they do
-e.g. in C, C++, Java, Pascal).
-
-Note 2: It's C<elsif>, not C<elseif>.  You can have as many
-C<elsif>s as you want.
-
-See L<perlsyn> for more details.  See also C<unless>.
-
 =item import
 
 There is no builtin C<import()> function.  It is just an ordinary
@@ -2075,10 +2014,8 @@ C<continue> block, if any, is not executed:
 C<last> cannot be used to exit a block which returns a value such as
 C<eval {}>, C<sub {}> or C<do {}>.
 
-See also L</continue> for an illustration of how C<last>, L</next>, and
-L</redo> work.
-
-See also L<perlsyn>.
+See also L</continue> for an illustration of how C<last>, C<next>, and
+C<redo> work.
 
 =item lc EXPR
 
@@ -2288,10 +2225,8 @@ refers to the innermost enclosing loop.
 C<next> cannot be used to exit a block which returns a value such as
 C<eval {}>, C<sub {}> or C<do {}>.
 
-See also L</continue> for an illustration of how L</last>, C<next>, and
-L</redo> work.
-
-See also L<perlsyn>.
+See also L</continue> for an illustration of how C<last>, C<next>, and
+C<redo> work.
 
 =item no Module LIST
 
@@ -2302,8 +2237,9 @@ See the L</use> function, which C<no> is the opposite of.
 =item oct
 
 Interprets EXPR as an octal string and returns the corresponding
-value.  (If EXPR happens to start off with C<0x>, interprets it as
-a hex string instead.)  The following will handle decimal, octal, and
+value.  (If EXPR happens to start off with C<0x>, interprets it as a
+hex string.  If EXPR starts off with C<0b>, it is interpreted as a
+binary string.)  The following will handle decimal, binary, octal, and
 hex in the standard Perl or C notation:
 
     $val = oct($val) if $val =~ /^0/;
@@ -2527,7 +2463,7 @@ them, and automatically close whenever and however you leave that scope:
 	$first;					# Or here.
     }
 
-See L</seek()> for some details about mixing reading and writing.
+See L</seek> for some details about mixing reading and writing.
 
 =item opendir DIRHANDLE,EXPR
 
@@ -2912,7 +2848,7 @@ See L<perlipc/"UDP: Message Passing"> for examples.
 =item redo
 
 The C<redo> command restarts the loop block without evaluating the
-conditional again.  The L</continue> block, if any, is not executed.  If
+conditional again.  The C<continue> block, if any, is not executed.  If
 the LABEL is omitted, the command refers to the innermost enclosing
 loop.  This command is normally used by programs that want to lie to
 themselves about what was just input:
@@ -2937,11 +2873,9 @@ themselves about what was just input:
 C<redo> cannot be used to retry a block which returns a value such as
 C<eval {}>, C<sub {}> or C<do {}>.
 
-See also L</continue> for an illustration of how L</last>, L</next>, and
+See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
-See also L<perlsyn>.
-
 =item ref EXPR
 
 =item ref
@@ -3411,7 +3345,7 @@ busy multitasking system.
 
 For delays of finer granularity than one second, you may use Perl's
 C<syscall()> interface to access setitimer(2) if your system supports it,
-or else see L</select()> above.
+or else see L</select> above.
 
 See also the POSIX module's C<sigpause()> function.
 
@@ -3712,6 +3646,7 @@ In addition, Perl permits the following widely-supported conversions:
    %X	like %x, but using upper-case letters
    %E	like %e, but using an upper-case "E"
    %G	like %g, but with an upper-case "E" (if applicable)
+   %b	an unsigned integer, in binary
    %p	a pointer (outputs the Perl value's address in hexadecimal)
    %n	special: *stores* the number of characters output so far
         into the next variable in the parameter list 
@@ -4222,7 +4157,7 @@ Unlike C<dbmopen()>, the C<tie()> function will not use or require a module
 for you--you need to do that explicitly yourself.  See L<DB_File>
 or the F<Config> module for interesting C<tie()> implementations.
 
-For further details see L<perltie>, L<tied VARIABLE>.
+For further details see L<perltie>, L<"tied VARIABLE">.
 
 =item tied VARIABLE
 
@@ -4290,7 +4225,7 @@ If EXPR is omitted, merely returns the current umask.
 
 The Unix permission C<rwxr-x---> is represented as three sets of three
 bits, or three octal digits: C<0750> (the leading 0 indicates octal
-and isn't one of the the digits).  The C<umask> value is such a number
+and isn't one of the digits).  The C<umask> value is such a number
 representing disabled permissions bits.  The permission (or "mode")
 values you pass C<mkdir> or C<sysopen> are modified by your umask, so
 even if you tell C<sysopen> to create a file with permissions C<0777>,
@@ -4318,6 +4253,8 @@ not trying to restrict access for yourself, returns C<undef>.
 Remember that a umask is a number, usually given in octal; it is I<not> a
 string of octal digits.  See also L</oct>, if all you have is a string.
 
+
+
 =item undef EXPR
 
 =item undef
@@ -4344,13 +4281,6 @@ parameter.  Examples:
 
 Note that this is a unary operator, not a list operator.
 
-=item unless (EXPR) BLOCK
-
-The negative counterpart of L</if>.  If the EXPR returns false the
-BLOCK is entered.
-
-See also L<perlsyn>.
-
 =item unlink LIST
 
 =item unlink
@@ -4400,6 +4330,10 @@ The following efficiently counts the number of set bits in a bit vector:
 
     $setbits = unpack("%32b*", $selectmask);
 
+=item untie VARIABLE
+
+Breaks the binding between a variable and a package.  (See C<tie()>.)
+
 =item unshift ARRAY,LIST
 
 Does the opposite of a C<shift()>.  Or the opposite of a C<push()>,
@@ -4412,21 +4346,6 @@ Note the LIST is prepended whole, not one element at a time, so the
 prepended elements stay in the same order.  Use C<reverse()> to do the
 reverse.
 
-=item until (EXPR) BLOCK
-
-=item do BLOCK until (EXPR)
-
-Enter BLOCK until EXPR returns false.  The first form may avoid entering
-the BLOCK, the second form enters the BLOCK at least once.
-
-See L</do>, L</while>, and L</for>.
-
-See also L<perlsyn>.
-
-=item untie VARIABLE
-
-Breaks the binding between a variable and a package.  (See C<tie()>.)
-
 =item use Module LIST
 
 =item use Module
@@ -4646,15 +4565,6 @@ warnings (even the so-called mandatory ones).  An example:
 See L<perlvar> for details on setting C<%SIG> entries, and for more
 examples.
 
-=item while (EXPR) BLOCK
-
-=item do BLOCK while (EXPR)
-
-Enter BLOCK while EXPR is true.  The first form may avoid entering the
-BLOCK, the second form enters the BLOCK at least once.
-
-See also L<perlsyn>, L</for>, L</until>, and L</continue>.
-
 =item write FILEHANDLE
 
 =item write EXPR