Improved line and pagebreaking for chapter 11.

sections/barewords.pod

@@ -115,14 +115,11 @@ Constants declared with the C<constant> pragma are usable as barewords:
     use constant NAME     => 'Bucky';
     use constant PASSWORD => '|38fish!head74|';
 
-    ...
-
     return unless $name eq NAME && $pass eq PASSWORD;
 
 =end programlisting
 
-Note that these constants do I<not> interpolate in double-quoted strings, for
-example.
+Note that these constants do I<not> interpolate in double-quoted strings.
 
 X<prototypes; barewords>
 
@@ -139,15 +136,6 @@ No matter how cautiously you code, barewords still produce ambiguous code. You
 can avoid most uses, but you will encounter several types of barewords in
 legacy code.
 
-=head3 Bareword filehandles
-
-X<barewords; filehandles>
-
-Prior to lexical filehandles (L<lexical_filehandles>), all file and directory
-handles used barewords. You can almost always safely rewrite this code to use
-lexical filehandles; the exceptions are C<STDIN>, C<STDOUT>, and C<STDERR>.
-Fortunately, Perl's parser recognizes these.
-
 =head3 Bareword function calls
 
 X<barewords; function calls>
@@ -162,8 +150,7 @@ accordingly.
 
 X<barewords; hash values>
 
-Along similar lines, old code may not take pains to quote the I<values> of hash
-pairs appropriately:
+Some old code may not take pains to quote the I<values> of hash pairs:
 
 =begin programlisting
 
@@ -180,6 +167,15 @@ When neither the C<Floyd()> nor C<Annette()> functions exist, Perl will
 interpret these barewords as strings. C<strict 'subs'> will produce an error in
 this situation.
 
+=head3 Bareword filehandles
+
+X<barewords; filehandles>
+
+Prior to lexical filehandles (L<lexical_filehandles>), all file and directory
+handles used barewords. You can almost always safely rewrite this code to use
+lexical filehandles; the exceptions are C<STDIN>, C<STDOUT>, and C<STDERR>.
+Fortunately, Perl's parser recognizes these.
+
 =head3 Bareword sort functions
 
 X<barewords; sort functions>

sections/indirect_objects.pod

@@ -69,7 +69,7 @@ variable I<seems> obvious, but it is not:
 =begin programlisting
 
     # DOES NOT WORK AS WRITTEN
-    say $config->{output} "This is a diagnostic message!";
+    say $config->{output} 'Fun diagnostic message!';
 
 =end programlisting
 
@@ -87,7 +87,7 @@ subexpression which produces the intended invocant:
 
 =begin programlisting
 
-    say B<{>$config->{output}B<}> "This is a diagnostic message!";
+    say B<{>$config->{output}B<}> 'Fun diagnostic message!';
 
 =end programlisting
 

sections/prototypes.pod

@@ -54,13 +54,11 @@ emulate:
 
 =begin screen
 
-    $ B<perl -E "say prototype 'CORE::system' // 'undef' ">
-    undef
-    # You can't emulate builtin function C<system>'s calling convention.
+    B<say prototype 'CORE::system' // 'undef'>
+    # undef; cannot emulate builtin C<system>
 
-    $ B<perl -E "say prototype 'CORE::prototype' // 'undef' ">
-    undef
-    # Builtin function C<prototype> has no prototype.
+    B<say prototype 'CORE::prototype' // 'undef'>
+    # undef; builtin C<prototype> has no prototype
 
 =end screen
 
@@ -111,7 +109,8 @@ incoming arguments:
 
     my @nums = 1 .. 10;
 
-    say "They're equal, whatever that means!" if numeric_equality @nums, 10;
+    say 'They're equal, whatever that means!'
+        if numeric_equality @nums, 10;
 
 =end programlisting
 
@@ -197,9 +196,9 @@ and an optional description of the test:
     use Test::Exception;
 
     throws_ok
-        { my $not_an_object; $not_an_object->some_method() }
-        qr/Can't call method "some_method" on an undefined value/,
-        'Calling a method on an undefined invocant should throw exception';
+        { my $unobject; $unobject->yoink() }
+        qr/Can't call method "yoink" on an undefined/,
+        'Method on undefined invocant should fail';
 
 =end programlisting
 
@@ -219,9 +218,9 @@ You may use C<throws_ok()> without taking advantage of the prototype:
     use Test::Exception;
 
     throws_okB<(>
-        B<sub> { my $not_an_object; $not_an_object->some_method() }B<,>
-        qr/Can't call method "some_method" on an undefined value/,
-        'Calling a method on an undefined invocant should throw exception'B<)>;
+        B<sub> { my $unobject; $unobject->yoink() }B<,>
+        qr/Can't call method "yoink" on an undefined/,
+        'Method on undefined invocant should fail' B<)>;
 
 =end programlisting
 
@@ -235,7 +234,6 @@ with C<sort>N<Ben Tilly suggested this example.>:
     sub length_sort ($$)
     {
         my ($left, $right) = @_;
-
         return length($left) <=> length($right);
     }
 

sections/tie.pod

@@ -11,10 +11,10 @@ translates to a specific method call.
 X<builtins; C<tie>>
 X<C<Tie::File>>
 
-The C<tie> builtin originally allowed the use of hashes stored on disk, so that
-Perl could access files larger than could easily fit in memory. The core module
-C<Tie::File> provides a similar system, and allows you to treat files as if
-they were arrays.
+The C<tie> builtin originally allowed you to use disk space as the backing
+memory for hashes, so that Perl could access files larger than could easily fit
+in memory. The core module C<Tie::File> provides a similar system, and allows
+you to treat files as if they were arrays.
 
 X<C<Tie::StdScalar>>
 X<C<Tie::StdArray>>
@@ -26,14 +26,14 @@ the core modules C<Tie::StdScalar>, C<Tie::StdArray>, and C<Tie::StdHash> for
 specific details. Start by inheriting from one of those classes, then override
 any specific methods you need to modify.
 
-=begin sidebar
+=begin tip When Class and Package Names Collide
 
 If C<tie> weren't confusing enough, C<Tie::Scalar>, C<Tie::Array>, and
 C<Tie::Hash> define the necessary interfaces to tie scalars, arrays, and
 hashes, but C<Tie::StdScalar>, C<Tie::StdArray>, and C<Tie::StdHash> provide
 the default implementations.
 
-=end sidebar
+=end tip
 
 =head2 Tying Variables
 
@@ -62,9 +62,11 @@ use C<tied> in a boolean context, however.
 =head2 Implementing Tied Variables
 
 To implement the class of a tied variable, inherit from a core module such as
-C<Tie::StdScalar>, then override the specific methods for the operations you
-want to change.  In the case of a tied scalar, these are likely C<FETCH> and
-C<STORE>, possibly C<TIESCALAR()>, and probably not C<DESTROY()>.
+C<Tie::StdScalar>N<C<Tie::StdScalar> lacks its own F<.pm> file, so use
+C<Tie::Scalar> to make it available.>, then override the specific methods for
+the operations you want to change.  In the case of a tied scalar, these are
+likely C<FETCH> and C<STORE>, possibly C<TIESCALAR()>, and probably not
+C<DESTROY()>.
 
 You can create a class which logs all reads from and writes to a scalar with
 very little code:
@@ -100,13 +102,6 @@ very little code:
 Assume that the C<Logger> class method C<log()> takes a string and the number
 of frames up the call stack of which to report the location.
 
-=begin tip Using C<Tie::StdScalar>
-
-C<Tie::StdScalar> lacks its own F<.pm> file; C<use Tie::Scalar;> to make it
-available.
-
-=end tip
-
 Within the C<STORE()> and C<FETCH()> methods, C<$self> works as a blessed
 scalar.  Assigning to that scalar reference changes the value of the scalar and
 reading from it returns its value.
@@ -116,13 +111,13 @@ array and hash references, respectively.  The C<perldoc perltie> documentation
 explains the copious methods they support, as you can read or write multiple
 values from them, among other operations.
 
-=begin sidebar
+=begin tip Isn't C<tie> Fun?
 
 The C<-norequire> option prevents the C<parent> pragma from attempting to load
 a file for C<Tie::StdScalar>, as that module is part of the file
 F<Tie/Scalar.pm>.
 
-=end sidebar
+=end tip
 
 =head2 When to use Tied Variables