[PATCH] perlsyn man page Revamp - diff #1

--- ./tags/original-release/pod/perlsyn.pod	2003-02-19 17:42:05.000000000 +0200
+++ ./trunk/pod/perlsyn.pod	2003-02-19 18:21:26.000000000 +0200
@@ -4,29 +4,27 @@
 
 =head1 DESCRIPTION
 
-A Perl script consists of a sequence of declarations and statements.
-The sequence of statements is executed just once, unlike in B<sed>
-and B<awk> scripts, where the sequence of statements is executed
-for each input line.  While this means that you must explicitly
-loop over the lines of your input file (or files), it also means
-you have much more control over which files and which lines you look at.
-(Actually, I'm lying--it is possible to do an implicit loop with
-either the B<-n> or B<-p> switch.  It's just not the mandatory
-default like it is in B<sed> and B<awk>.)
+A Perl script consists of a sequence of declarations and statements.  The
+statements are executed one by one B<once>. Unlike B<awk> or B<sed> (in case
+you are familiar with these tools) where the sequence of statements is executed
+for each input line. While, it is possible to emulate this behavior , using the
+B<-n> or B<-p> switch, the default is to follow the standard of more
+conventional programming langauge, like C, LISP, the various dialects of Basic,
+and so on.
 
 Perl is, for the most part, a free-form language.  (The only exception
 to this is format declarations, for obvious reasons.)  Text from a
 C<"#"> character until the end of the line is a comment, and is
-ignored.  If you attempt to use C</* */> C-style comments, it will be
-interpreted either as division or pattern matching, depending on the
-context, and C++ C<//> comments just look like a null regular
-expression, so don't do that.
+ignored.  C-style C</* */> or C++ C<//> comments will do something else
+entirely, so don't use them. (and I mean it). 
 
 =head2 Declarations
 
 The only things you need to declare in Perl are report formats
-and subroutines--and even undefined subroutines can be handled
-through AUTOLOAD.  A variable holds the undefined value (C<undef>)
+and subroutines. (undefined subroutines can be handled
+through the AUTOLOAD feature as documented in L<perlsub>).  
+
+A variable holds the undefined value (C<undef>)
 until it has been assigned a defined value, which is anything
 other than C<undef>.  When used as a number, C<undef> is treated
 as C<0>; when used as a string, it is treated the empty string,
@@ -47,14 +45,13 @@
 
 are also always exempt from such warnings.
 
-A declaration can be put anywhere a statement can, but has no effect on
-the execution of the primary sequence of statements--declarations all
-take effect at compile time.  Typically all the declarations are put at
-the beginning or the end of the script.  However, if you're using
-lexically-scoped private variables created with C<my()>, you'll
-have to make sure
-your format or subroutine definition is within the same block scope
-as the my if you expect to be able to access those private variables.
+A declaration can be put anywhere a statement can, but has no effect on the
+execution of the primary sequence of statements - declarations all take effect
+at compile time.  Typically all the declarations are put at the beginning or
+the end of the script.  However, if you're using lexically-scoped private
+variables created with C<my()>, you'll have to make sure your format or
+subroutine definition is within the same block scope as the my if you expect to
+be able to access those private variables.
 
 Declaring a subroutine allows a subroutine name to be used as if it were a
 list operator from that point forward in the program.  You can declare a
@@ -64,10 +61,7 @@
     $me = myname $0 		or die "can't get myname";
 
 Note that myname() functions as a list operator, not as a unary operator;
-so be careful to use C<or> instead of C<||> in this case.  However, if
-you were to declare the subroutine as C<sub myname ($)>, then
-C<myname> would function as a unary operator, so either C<or> or
-C<||> would work.
+so be careful to use C<or> instead of C<||> in this case.  
 
 Subroutines declarations can also be loaded up with the C<require> statement
 or both loaded and imported into your namespace with a C<use> statement.
@@ -100,25 +94,32 @@
     until EXPR
     foreach EXPR
 
-The C<if> and C<unless> modifiers have the expected semantics,
-presuming you're a speaker of English.  The C<foreach> modifier is an
-iterator:  For each value in EXPR, it aliases C<$_> to the value and
-executes the statement.  The C<while> and C<until> modifiers have the
-usual "C<while> loop" semantics (conditional evaluated first), except
-when applied to a C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE
-statement), in which case the block executes once before the
+C<if> executes a block of statement (or a single statement) once if C<EXPR>
+evaluated to a true value. C<unless> executes it once if it did not. A false
+value is C<undef>, 0, the empty string, and the floating number 0.0. A true
+value is everything else. Normally, you'll wish to use comparison operators
+(C<==>, C<eq>, C<<<=>>, C<gt> or friends), regular expression matches or 
+other mechanisms that explicitly return a true or false value as a boolean
+expression there.
+
+C<while> and C<until> repeat the same block of statements while or until it is
+true. (I.e: C<until> iterates while it is false). The C<while> and C<until>
+modifiers have the usual "C<while> loop" semantics (conditional evaluated
+first), except when applied to a C<do>-BLOCK (or to the deprecated
+C<do>-SUBROUTINE statement), in which case the block executes once before the
 conditional is evaluated.  This is so that you can write loops like:
 
     do {
-	$line = <STDIN>;
+	    $line = <STDIN>;
 	...
     } until $line  eq ".\n";
 
-See L<perlfunc/do>.  Note also that the loop control statements described
-later will I<NOT> work in this construct, because modifiers don't take
-loop labels.  Sorry.  You can always put another block inside of it
-(for C<next>) or around it (for C<last>) to do that sort of thing.
-For C<next>, just double the braces:
+
+See L<perlfunc/do>.  Note also that the loop control statements described later
+will I<NOT> work in this construct, because modifiers don't take loop labels.
+Sorry.  You can always put another block inside of it (for C<next>) or around
+it (for C<last>) to do that sort of thing.  For C<next>, just double the
+braces:
 
     do {{
 	next if $x == $y;
@@ -134,6 +135,10 @@
 	    } while $x++ <= $z;
     }
 
+Finally, the C<foreach> modifier is an iterator:  For each value in EXPR, it
+aliases the special "default" variable C<$_> to the value and executes the
+statement.
+
 =head2 Compound statements
 
 In Perl, a sequence of statements that defines a scope is called a block.
@@ -157,7 +162,7 @@
     LABEL BLOCK continue BLOCK
 
 Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
-not statements.  This means that the curly brackets are I<required>--no
+not statements.  This means that the curly brackets are I<required> - no
 dangling statements allowed.  If you want to write conditionals without
 curly brackets there are several other ways to do it.  The following
 all do the same thing:
@@ -189,8 +194,11 @@
 If there is a C<continue> BLOCK, 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).
+when the loop has been continued via the C<next> statement, which is
+similar to the C C<continue> statement. As you see C<continue> in C, and
+C<continue> in Perl do entirely different things. It may be confusing
+at first, but this can usually be detected when the script is analyzed by
+the B<perl> interpreter.
 
 =head2 Loop Control
 

• [PATCH] perlsyn man page Revamp - diff #1 by Shlomi Fish