Improved formatting of chapter 1.

sections/context_philosophy.pod

@@ -120,7 +120,7 @@ contain. Both of these calls to C<find_chores()> occur in list context:
 
     my %results =
     (
-        cheap_operation     => $cheap_operation_results,
+        cheap_operation     => $cheap_results,
         expensive_operation => find_chores(), # OOPS!
     );
 
@@ -138,7 +138,7 @@ Use the C<scalar> operator to impose scalar context:
 
     my %results =
     (
-        cheap_operation     => $cheap_operation_results,
+        cheap_operation     => $cheap_results,
         expensive_operation => B<scalar> find_chores(),
     );
 
@@ -184,7 +184,7 @@ different, but they still compare the same:
 =begin programlisting
 
     my $alice = 'alice';
-    say "Catastrophic crypto fail!" if $alice == 'Bob';  # OOPS
+    say "Catastrophic crypto fail!" if $alice == 'Bob';
 
 =end programlisting
 

sections/expressivity.pod

@@ -5,17 +5,16 @@ Z<expressivity>
 X<Wall, Larry>
 X<Larry Wall>
 
-When Larry Wall created Perl, his studies of linguistics and human languages
-influenced his design. Notably, Perl allows you tremendous freedom to solve
-your problems, depending on your group style, the available time, the expected
+Larry Wall's his studies of linguistics and human languages influenced the
+design of Perl. The language allows you tremendous freedom to solve your
+problems, depending on your group style, the available time, the expected
 lifespan of the program, or even how creative you feel. You may write simple,
 straightforward code or integrate into larger, well-defined programs. You may
 select from multiple design paradigms, and you may eschew or embrace advanced
 features.
 
-Where other languages might suggest that one enforced way to write any
-operation is the right solution, Perl allows you to optimize for your most
-important criteria.
+Where other languages enforce one best way to write any code, Perl allows
+I<you> to decide what's most readable or useful or fun.
 
 X<TIMTOWTDI>
 X<Tim Toady>

sections/files.pod

@@ -25,7 +25,7 @@ you C<warn()> goes to C<STDERR>. This separation of output allows you to
 redirect useful output and errors to two different places--an output file and
 error logs, for example.
 
-=begin sidebar
+=begin tip The Many Names of C<DATA>
 
 X<C<DATA>>
 X<C<__DATA__>>
@@ -38,7 +38,7 @@ section. Any text which occurs after that token is available for reading from
 C<DATA>. This is useful for short, self-contained programs. See C<perldoc
 perldata> for more details.
 
-=end sidebar
+=end tip
 
 X<builtins; C<open>>
 

sections/implicit_ideas.pod

@@ -57,8 +57,8 @@ arguments:
 
 =begin programlisting
 
-    print;  # prints $_ to the currently selected filehandle
-    say;    # prints $_ to the currently selected filehandle
+    print;  # prints $_ to the current filehandle
+    say;    # prints $_ to the current filehandle,
             # with a trailing newline
 
 =end programlisting
@@ -140,7 +140,8 @@ X<builtins; C<grep>>
 
 =begin programlisting
 
-    say 'Brunch time!' if grep { /pancake mix/ } @pantry;
+    say 'Brunch time!'
+        if grep { /pancake mix/ } @pantry;
 
 =end programlisting
 
@@ -197,15 +198,13 @@ Use C<$_> as you would the word "it" in formal writing: sparingly, in small and
 
 X<builtins; C<...>>
 
-Perl 5.12 introduced the triple-dot (C<...>) operator. It's a complete
-statement on its own which acts as a placeholder for code you intend to fill in
-later. Perl will parse it as a complete statement, but will throw an exception
-that you're trying to run unimplemented code if you try to run it. See
-C<perldoc perlop> for more details.
+Perl 5.12 introduced the triple-dot (C<...>) operator as a placeholder for code
+you intend to fill in later. Perl will parse it as a complete statement, but
+will throw an exception that you're trying to run unimplemented code if you try
+to run it. See C<perldoc perlop> for more details.
 
 =end tip
 
-
 =head2 The Default Array Variables
 
 Z<default_array_variables>
@@ -253,6 +252,20 @@ command-line arguments to the program. Perl's array operations (including
 C<shift> and C<pop>) operate on C<@ARGV> implicitly outside of functions. You
 cannot use C<@_> when you mean C<@ARGV>.
 
+=begin tip C<readline>
+
+X<builtins; C<readline>>
+X<builtins; C<glob>>
+
+Perl's C<< <$fh> >> operator is the same as the C<readline> builtin.
+C<readline $fh> does the same thing as C<< <$fh> >>. As of Perl 5.10, a bare
+C<readline> behaves just like C<< <> >>, so you can now use C<readline>
+everywhere. For historic reasons, C<< <> >> is still more common, but consider
+using C<readline> as a more readable alternative. You probably prefer C<glob
+'*.html'> to C<< <*.html> >>, right? It's the same idea.
+
+=end tip
+
 X<null filehandle>
 
 C<ARGV> has one special case. If you read from the null filehandle C<< <> >>,
@@ -277,20 +290,6 @@ concatenated string in scalar context. If the behavior of C<reverse> sounds
 confusing, your instincts are correct. Perl 5 arguably should have separated
 "reverse a string" from "reverse a list".
 
-=begin tip C<readline>
-
-X<builtins; C<readline>>
-X<builtins; C<glob>>
-
-Perl's C<< <$fh> >> operator is the same as the C<readline> builtin.
-C<readline $fh> does the same thing as C<< <$fh> >>. As of Perl 5.10, a bare
-C<readline> behaves just like C<< <> >>, so you can now use C<readline>
-everywhere. For historic reasons, C<< <> >> is still more common, but consider
-using C<readline> as a more readable alternative. You probably prefer C<glob
-'*.html'> to C<< <*.html> >>, right? It's the same idea.
-
-=end tip
-
 If you run it with a list of files:
 
 =begin screen

sections/perldoc.pod

@@ -18,7 +18,7 @@ X<CPAN>
 X<metacpan>
 
 U<http://perldoc.perl.org/> hosts recent versions of the Perl documentation.
-The U<http://search.cpan.org/> and U<http://metacpan.org/> CPAN indexes provide
+CPAN indexes at U<http://search.cpan.org/> and U<http://metacpan.org/> provide
 documentation for all CPAN modules. Other Perl 5 distributions such as
 ActivePerl and Strawberry Perl provide local documentation in HTML formats.
 
@@ -52,8 +52,11 @@ the form of the documentation is remarkably consistent.
 
 C<perldoc perltoc> displays the table of contents of the core documentation,
 and C<perldoc perlfaq> displays the table of contents for Frequently Asked
-Questions about Perl 5. Skimming these files will give you a great overview of
-Perl 5.
+Questions about Perl 5. C<perldoc perlop> and C<perldoc perlsyn> document
+Perl's symbolic operators and syntactic constructs. C<perldoc perldiag>
+explains the meanings of Perl's warning messages. C<perldoc perlvar> lists all
+of Perl's symbolic variables. Skimming these files will give you a great
+overview of Perl 5.
 
 =end tip
 
@@ -79,14 +82,6 @@ displays the documentation for the variable which contains the current
 program's process id. Depending on your shell, you may have to quote the
 variable appropriately.
 
-=begin tip Deciphering Code
-
-C<perldoc perlop> and C<perldoc perlsyn> document Perl's symbolic operators and
-syntactic constructs. C<perldoc perldiag> explains the meanings of Perl's
-warning messages. C<perldoc perlvar> lists all of Perl's symbolic variables.
-
-=end tip
-
 The C<-l> option causes C<perldoc> to display the I<path> to the documentation
 file rather than the contents of the documentationN<Be aware that a module may
 have a separate F<.pod> file in addition to its F<.pm> file.>.
@@ -104,6 +99,3 @@ Perl 5's documentation system is I<POD>, or I<Plain Old Documentation>.
 C<perldoc perlpod> describes how POD works. Other POD tools include
 C<podchecker>, which validates the form of your POD, and C<Pod::Webserver>,
 which displays local POD as HTML through a minimal web server.
-
-X<CPAN; C<Pod::PseudoPod>>
-This book uses an extension of POD called C<Pod::PseudoPod>.