For now reword the sysread/syswrite description to

[p5sagit/p5-mst-13.2.git] / pod / perltrap.pod

diff --git a/pod/perltrap.pod b/pod/perltrap.pod
index 753e721..48a886a 100644 (file)
--- a/pod/perltrap.pod
+++ b/pod/perltrap.pod
@@ -143,9 +143,9 @@ gives you.
 
 =back
 
-=head2 C Traps
+=head2 C/C++ Traps
 
-Cerebral C programmers should take note of the following:
+Cerebral C and C++ programmers should take note of the following:
 
 =over 4
 
@@ -159,13 +159,14 @@ You must use C<elsif> rather than C<else if>.
 
 =item *
 
-The C<break> and C<continue> keywords from C become in
-Perl C<last> and C<next>, respectively.
-Unlike in C, these do I<not> work within a C<do { } while> construct.
+The C<break> and C<continue> keywords from C become in Perl C<last>
+and C<next>, respectively.  Unlike in C, these do I<not> work within a
+C<do { } while> construct.  See L<perlsyn/"Loop Control">.
 
 =item *
 
-There's no switch statement.  (But it's easy to build one on the fly.)
+There's no switch statement.  (But it's easy to build one on the fly,
+see L<perlsyn/"Basic BLOCKs and Switch Statements">)
 
 =item *
 
@@ -651,6 +652,16 @@ are to used around the name.
     # perl4 prints: {a}
     # perl5 prints: 2
 
+=item * Parsing
+
+When perl sees C<map {> (or C<grep {>), it has to guess whether the C<{>
+starts a BLOCK or a hash reference. If it guesses wrong, it will report
+a syntax error near the C<}> and the missing (or unexpected) comma.
+
+Use unary C<+> before C<{> on a hash reference, and unary C<+> applied
+to the first thing in a BLOCK (after C<{>), for perl to guess right all
+the time. (See L<perlfunc/map>.)
+
 =back
 
 =head2 Numerical Traps
@@ -662,18 +673,24 @@ operands, or output from same.
 
 =item * Numerical
 
-Formatted output and significant digits
+Formatted output and significant digits.  In general, Perl 5
+tries to be more precise.  For example, on a Solaris Sparc:
 
     print 7.373504 - 0, "\n";
     printf "%20.18f\n", 7.373504 - 0;
 
     # Perl4 prints:
-    7.375039999999996141
-    7.37503999999999614
+    7.3750399999999996141
+    7.375039999999999614
 
     # Perl5 prints:
     7.373504
-    7.37503999999999614
+    7.375039999999999614
+
+Notice how the first result looks better in Perl 5.
+
+Your results may vary, since your floating point formatting routines
+and even floating point format may be slightly different.
 
 =item * Numerical
 
@@ -688,7 +705,7 @@ If in doubt:
 
 Assignment of return values from numeric equality tests
 does not work in perl5 when the test evaluates to false (0).
-Logical tests now return an null, instead of 0
+Logical tests now return a null, instead of 0
 
     $p = ($test == 1);
     print $p,"\n";
@@ -1328,13 +1345,12 @@ within certain expressions, statements, contexts, or whatever.
 
 =item * Interpolation
 
-Double-quoted strings may no longer end with an unescaped $ or @.
+Double-quoted strings may no longer end with an unescaped $.
 
     $foo = "foo$";
-    $bar = "bar@";
-    print "foo is $foo, bar is $bar\n";
+    print "foo is $foo\n";
 
-    # perl4 prints: foo is foo$, bar is bar@
+    # perl4 prints: foo is foo$
     # perl5 errors: Final $ should be \$ or $name
 
 Note: perl5 DOES NOT error on the terminating @ in $bar
@@ -1420,13 +1436,26 @@ perl4 programs which unconsciously rely on the bugs in earlier perl versions.
 
 =item * Interpolation
 
-You also have to be careful about array references.
+You also have to be careful about array and hash brackets during
+interpolation.
+
+    print "$foo["
+
+    perl 4 prints: [
+    perl 5 prints: syntax error
 
     print "$foo{"
 
     perl 4 prints: {
     perl 5 prints: syntax error
 
+Perl 5 is expecting to find an index or key name following the respective
+brackets, as well as an ending bracket of the appropriate type.  In order
+to mimic the behavior of Perl 4, you must escape the bracket like so.
+
+    print "$foo\[";
+    print "$foo\{";
+
 =item * Interpolation
 
 Similarly, watch out for: