From: Michael G. Schwern <schwern@pobox.com>
Date: Tue, 13 May 2003 18:33:05 +0000 (-0700)
Subject: New introduction
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6014d0cb2904bf89033c6aa0d3dbb1d1600d6994;p=p5sagit%2Fp5-mst-13.2.git

New introduction
Message-ID: <20030514013305.GB22001@windhund.schwern.org>

p4raw-id: //depot/perl@20154
---

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 5ddd7e1..9aec074 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -4,23 +4,27 @@ perlsyn - Perl syntax
 
 =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>.)
-
-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 or defined-or operator, so don't do that.
+A Perl program consists of a sequence of declarations and statements
+which run from the top to the bottom.  Loops, subroutines and other
+control structures allow you to jump around within the code.
+
+Perl is a B<free-form> language, you can format and indent it however
+you like.  Whitespace mostly serves to separate tokens, unlike
+languages like Python where it is an important part of the syntax.
+
+Many of Perl's syntactic elements are B<optional>.  Rather than
+requiring you to put parenthesis around every function call and
+declare every variable, you can often leave such explicit elements off
+and Perl will figure out what you meant.  This is known as B<Do What I
+Mean>, abbreviated B<DWIM>.  It allows programmers to be B<lazy> and to
+code in a style which they are comfortable.
+
+Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
+Bourne Shell, Smalltalk, Lisp and even English.  Other
+languages have borrowed syntax from Perl, particularly its regular
+expression extensions.  So if you have programmed in another language
+you will see familiar pieces in Perl.  They often work the same, but
+see L<perltrap> for information about how they differ.
 
 =head2 Declarations
 
@@ -79,6 +83,12 @@ like an ordinary statement, and is elaborated within the sequence of
 statements as if it were an ordinary statement.  That means it actually
 has both compile-time and run-time effects.
 
+=head2 Comments
+
+Text from a C<"#"> character until the end of the line is a comment,
+and is ignored.  Exceptions include C<"#"> inside a string or regular
+expression.
+
 =head2 Simple Statements
 
 The only kind of simple statement is an expression evaluated for its
diff --git a/pod/perltrap.pod b/pod/perltrap.pod
index 6a6a443..d8f667c 100644
--- a/pod/perltrap.pod
+++ b/pod/perltrap.pod
@@ -18,6 +18,11 @@ Accustomed B<awk> users should take special note of the following:
 
 =item *
 
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with C<-n> or C<-p>.
+
+=item *
+
 The English module, loaded via
 
     use English;
@@ -174,7 +179,9 @@ Variables begin with "$", "@" or "%" in Perl.
 
 =item *
 
-Comments begin with "#", not "/*".
+Comments begin with "#", not "/*" or "//".  Perl may interpret C/C++
+comments as division operators, unterminated regular expressions or
+the defined-or operator.
 
 =item *
 
@@ -206,6 +213,11 @@ Seasoned B<sed> programmers should take note of the following:
 
 =item *
 
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with C<-n> or C<-p>.
+
+=item *
+
 Backreferences in substitutions use "$" rather than "\".
 
 =item *