Merge remote branch 'upstream/master'

Conflicts:
	CREDITS
	sections/scope.pod

CREDITS

@@ -221,3 +221,12 @@ E: celtic@sairyx.org
 
 N: Eduardo Santiago
 E: esm@cpan.org
+
+N: Andy Lester
+E: andy@petdance.com
+
+N: Steve Dickinson
+E: dsdickinson@gmail.com
+
+N: Kurt Edmiston
+E: hurdlecrew@gmail.com

sections/anonymous_functions.pod

@@ -22,12 +22,13 @@ input with behavior:
     (
         plus     => \&add_two_numbers,
         minus    => \&subtract_two_numbers,
+        times    => \&multiply_two_numbers,
         # ... and so on
     );
 
     sub add_two_numbers      { $_[0] + $_[1] }
-
     sub subtract_two_numbers { $_[0] - $_[1] }
+    sub multiply_two_numbers { $_[0] * $_[1] }
 
     sub dispatch
     {

sections/arrays.pod

@@ -227,7 +227,7 @@ used as its index:
 =begin programlisting
 
     # function called in list context
-    my @cats = @cats[ get_cat_indices() ];
+    my @hungry_cats = @cats[ get_cat_indices() ];
 
 =end programlisting
 
@@ -267,7 +267,7 @@ X<builtins; C<shift>>
 X<builtins; C<unshift>>
 
 Similarly, C<unshift> and C<shift> add elements to and remove an element from
-the start of an array:
+the start of an array, respectively:
 
 =begin programlisting
 

sections/autoload.pod

@@ -8,7 +8,7 @@ program:
 
 =begin programlisting
 
-    #! perl
+    #!/usr/bin/perl
 
     use Modern::Perl;
 

sections/chapter_02.pod

@@ -13,7 +13,7 @@ people. I<People> make a community worth joining and preserving and expanding.
 The Perl community is strong and healthy. It welcomes willing participants at
 all levels, from novices to core developers. Take advantage of the knowledge
 and experience of countless other Perl programmers, and you'll become a better
-programmer. 
+programmer.
 
 L<perl_community>
 

sections/closures.pod

@@ -84,8 +84,6 @@ lexical environment:
 
 =end programlisting
 
-=begin sidebar
-
 Because C<make_iterator()> does not return these lexicals by value or by
 reference, no other Perl code besides the closure can access them. They're
 encapsulated as effectively as any other lexical encapsulation, although any

sections/context_philosophy.pod

@@ -162,7 +162,7 @@ data.  You've probably already noticed that Perl's flexible about figuring out
 if you have a number or a string and converting between the two as you want
 them. In exchange for not having to declare (or at least track) explicitly what
 I<type> of data a variable contains or a function produces, Perl's type
-contexts that tell the compiler how to treat data.
+contexts provide hints that tell the compiler how to treat data.
 
 X<builtins; C<eq>>
 
@@ -197,7 +197,7 @@ X<builtins; C<==>>
 
 The C<eq> operator treats its operands as strings by enforcing I<string
 context> on them.  The C<==> operator imposes I<numeric context>. In numeric
-context, both strings evaluate to numbers C<0> (L<numeric_coercion>).
+context, both strings evaluate to C<0> (L<numeric_coercion>).
 
 X<boolean context>
 X<context; boolean>

sections/control_flow.pod

@@ -346,6 +346,7 @@ using an undefined value might raise a warning:
 
 =begin programlisting
 
+    my $barbeque;
     if (defined $barbeque and $barbeque eq 'pork shoulder') { ... }
 
 =end programlisting
@@ -708,6 +709,21 @@ X<destructive update>
 To prevent such an infinite C<while> loop, use a I<destructive update> of the
 C<@values> array by modifying the array with each loop iteration:
 
+=begin programlisting
+
+    while (@values)
+    {
+        my $value = shift @values;
+        say $value;
+    }
+
+=end programlisting
+
+=begin sidebar
+
+Modifying C<@values> inside of the C<while> condition check also works, but it
+has some subtleties related to the truthiness of each value.
+
 =begin programlisting
 
     while (my $value = shift @values)
@@ -717,6 +733,12 @@ C<@values> array by modifying the array with each loop iteration:
 
 =end programlisting
 
+This loop will exit as soon as it reaches an element that evaluates to a false
+value, not necessarily when it has exhausted the array. That may be the desired
+behavior, but is often surprising to novices.
+
+=end sidebar
+
 X<loops; C<until>>
 
 The I<until> loop reverses the sense of the test of the C<while> loop.

sections/cpan.pod

@@ -69,26 +69,34 @@ X<CPAN; C<CPAN.pm>>
 X<CPAN; C<CPANPLUS>>
 
 Modern Perl installations include two clients to connect to, search, download,
-build, test, and install CPAN distributions, CPAN.pm and CPANPLUS. A newer
-alternative is also available, though it is not part of the core distribution.
-For the most part, each of these clients is equivalent for basic installation.
-This book recommends the use of CPAN.pm solely due to its ubiquity. With a
-recent version (as of this writing, 1.9800 is the latest stable release),
-module installation is reasonably easy. Start the client with:
+build, test, and install CPAN distributions, CPAN.pm and CPANPLUS. For the most
+part, each of these clients is equivalent for basic installation. This book
+recommends the use of CPAN.pm solely due to its ubiquity. With a recent version
+(as of this writing, 1.9800 is the latest stable release), module installation
+is reasonably easy. Start the client with:
 
-=begin programlisting
+=begin screen
 
     $ B<cpan>
 
-=end programlisting
+=end screen
 
-To install a distribution:
+To install a distribution within the client:
 
-=begin programlisting
+=begin screen
+
+    $ B<cpan>
+    cpan[1]> B<install Modern::Perl>
+
+=end screen
+
+... or to install directly from the command line:
+
+=begin screen
 
     $ B<cpan Modern::Perl>
 
-=end programlisting
+=end screen
 
 X<CPAN; C<CPAN.pm>>
 
@@ -118,25 +126,25 @@ projects help to make this possible.
 C<App::cpanminus> is a relatively new CPAN client with goals of speed,
 simplicity, and zero configuration. Install it with C<cpan App::cpanminus>, or:
 
-=begin programlisting
+=begin screen
 
     $ B<curl -LO http://xrl.us/cpanm>
     $ B<chmod +x cpanm>
 
-=end programlisting
+=end screen
 
 C<App::perlbrew> is a system to manage and to switch between your own
 installations of multiple versions and configurations of Perl. Installation is
 as easy as:
 
-=begin programlisting
+=begin screen
 
     $ B<curl -LO http://xrl.us/perlbrew>
     $ B<chmod +x perlbrew>
     $ B<./perlbrew install>
     $ B<perldoc App::perlbrew>
 
-=end programlisting
+=end screen
 
 X<CPAN; local::lib>
 X<CPAN; App::local::lib::helper>
@@ -145,7 +153,7 @@ The C<local::lib> CPAN distribution allows you to install and to manage
 distributions in your own user directory, rather than for the system as a
 whole. This is an effective way to maintain CPAN distributions without
 affecting other users. Installation is somewhat more involved than the previous
-two distributions, though C<App::local::lib::helper> can simplify.  See
+two distributions, though C<App::local::lib::helper> can simplify the process.  See
 U<http://search.cpan.org/perldoc?local::lib> and
 U<http://search.cpan.org/perldoc?App::local::lib::helper> for more details.
 

sections/expressivity.pod

@@ -64,24 +64,19 @@ X<baby Perl>
 Perl's expressivity also allows novices to write useful programs without having
 to understand everything. The resulting code is often called I<baby Perl>, in
 the sense that most everyone wants to help babies learn to communicate well.
-Everyone begins as a novice. Through practice and leaning from more experienced
+Everyone begins as a novice. Through practice and learning from more experienced
 programmers, you will understand and adopt more powerful idioms and techniques.
 
-For example, a Perl novice might triple a list of numbers by writing:
+For example, an experienced Perl hacker might triple a list of numbers by
+writing:
 
 =begin programlisting
 
-    my @tripled;
-    my $count = @numbers;
-
-    for (my $i = 0; $i < $count; $i++)
-    {
-        $tripled[$i] = $numbers[$i] * 3;
-    }
+    my @tripled = map { $_ * 3 } @numbers;
 
 =end programlisting
 
-A Perl adept might write:
+... and a Perl adept might write:
 
 =begin programlisting
 
@@ -94,17 +89,26 @@ A Perl adept might write:
 
 =end programlisting
 
-An experienced Perl hacker might write:
+... while a novice might start with:
 
 =begin programlisting
 
-    my @tripled = map { $_ * 3 } @numbers;
+    my @tripled;
+    my $count = @numbers;
+
+    for (my $i = 0; $i < $count; $i++)
+    {
+        $tripled[$i] = $numbers[$i] * 3;
+    }
 
 =end programlisting
 
+All three approaches accomplish the same thing, but each takes advantage of
+Perl in a different way.
+
 Experience writing Perl will help you to focus on I<what> you want to do rather
 than I<how> to do it. Even so, Perl will happily run simple programs. You can
 design and refine your programs for clarity, expressivity, reuse, and
 maintainability, in part or in whole. Take advantage of this flexibility and
-pragmatism: it's far better to accomplish your task effectively now than to write a
-conceptually pure and beautiful program next year.
+pragmatism: it's far better to accomplish your task effectively now than to
+write a conceptually pure and beautiful program next year.

sections/files.pod

@@ -65,8 +65,6 @@ Z<file_modes_table>
 
 =headrow
 
-=row
-
 =cell Symbols
 
 =cell Explanation

sections/functions.pod

@@ -133,8 +133,8 @@ code uses C<shift> or list unpacking:
 
 =begin sidebar
 
-Remember that the array builtins default to C<@_> as operand within functions.
-Take advantage of this idiom.
+Remember that the array builtins use C<@_> as the default operand I<within
+functions>. Take advantage of this idiom.
 
 =end sidebar
 
@@ -245,7 +245,7 @@ immediately followed by its value. Hash assignment inside C<show_pets()> works
 essentially as the more explicit assignment to C<%pet_names_and_types> does.
 
 This flattening is often useful, but beware of mixing scalars with flattened
-aggregates in parameter lists. To write C<show_pets_of_type()> function, where
+aggregates in parameter lists. To write a C<show_pets_of_type()> function, where
 one parameter is the type of pet to display, pass that type as the I<first>
 parameter (or use C<pop> to remove it from the end of C<@_>):
 

sections/globals.pod

@@ -123,7 +123,9 @@ reading input a line at a time. By default, this is your platform-specific
 newline character sequence. If you undefine this value, Perl will attempt to
 read the entire file into memory. If you set this value to a I<reference> to an
 integer, Perl will try to read that many I<bytes> per record (so beware of
-Unicode concerns).
+Unicode concerns). If you set this value to an empty string (C<''>), Perl will
+read in a paragraph at a time, where a paragraph is a chunk of text followed by
+an arbitrary number of newlines.
 
 X<C<$.>>
 X<global variables; C<$.>>

sections/handling_warnings.pod

@@ -57,11 +57,11 @@ X<C<Carp>; verbose>
 
 C<Carp>'s verbose mode adds backtraces to all warnings produced by C<carp()> and C<croak()> (L<reporting_errors>) throughout the entire program:
 
-=begin programlisting
+=begin screen
 
     $ perl -MCarp=verbose my_prog.pl
 
-=end programlisting
+=end screen
 
 Use C<Carp> when writing modules (L<modules>) instead of C<warn> or C<die>.
 

sections/hashes.pod

@@ -7,9 +7,9 @@ X<hashes>
 A I<hash> is a first-class Perl data structure which associates string keys
 with scalar values. In the same way that the name of a variable corresponds to
 a storage location, a key in a hash refers to a value. Think of a hash like you
-would a telephone book: use your friend's name to look up her number. Other
-languages call hashes I<tables>, I<associative arrays>, I<dictionaries>, or
-I<maps>.
+would a telephone book: use the names of your friends to look up their numbers.
+Other languages call hashes I<tables>, I<associative arrays>, I<dictionaries>,
+or I<maps>.
 
 Hashes have two important properties: they store one scalar per unique key and
 they provide no specific ordering of keys.
@@ -438,7 +438,7 @@ you can safely ignore.
 In list context, a hash evaluates to a list of key/value pairs similar to what
 you receive from the C<each> operator.  However, you I<cannot> iterate over
 this list the same way you can iterate over the list produced by C<each>, lest
-the loop never terminate:
+the loop will never terminate:
 
 =begin programlisting
 
@@ -621,7 +621,7 @@ To prevent someone from accidentally adding a hash key you did not intend
 (whether as a typo or from untrusted user input), use the C<lock_keys()>
 function to restrict the hash to its current set of keys. Any attempt to add a
 new key to the hash will raise an exception. This is lax security suitable only
-for preventing accidents; anyone can use theC<unlock_keys()> function to remove
+for preventing accidents; anyone can use the C<unlock_keys()> function to remove
 this protection.
 
 Similarly you can lock or unlock the existing value for a given key in the hash

sections/idioms.pod

@@ -462,9 +462,7 @@ This technique works on other in-place modification operators:
 =begin tip /r in Perl 5.14
 
 Perl 5.14 added the non-destructive substitution modifier C</r>, so that you
-can write:
-
-    C<my $normalized_name = $name =~ tr/A-Za-z//dcB<r>;>
+can write C<my $normalized_name = $name =~ tr/A-Za-z//dcB<r>;>.
 
 =end tip
 

sections/implicit_ideas.pod

@@ -24,7 +24,7 @@ C<$_> as the variable, but it's often unnecessary.
 X<builtins; C<chomp>>
 
 For example, the C<chomp> builtin removes any trailing newline sequence from
-the given stringN<See C<$/> for more precise details of its behavior.>:
+the given stringN<See C<perldoc -f chomp> and C<$/> for more precise details of its behavior.>:
 
 =begin programlisting
 

sections/indirect_objects.pod

@@ -109,7 +109,7 @@ For the limited case of filehandle operations, the dative use is so prevalent
 that you can use the indirect invocation approach if you surround your intended
 invocant with curly brackets. If you're using Perl 5.14 (or if you load
 C<IO::File> or C<IO::Handle>), you can use methods on lexical
-filehandlesN<<Almost no one does this for C<print> and C<say> though.>>.
+filehandlesN<Almost no one does this for C<print> and C<say> though.>.
 
 X<CPAN; C<Perl::Critic>>
 X<CPAN; C<Perl::Critic::Policy::Dynamic::NoIndirect>>