Addressed copyedit questions.

chromatic · chromatic · commit 297a21fe6417 · 2015-09-29T16:33:28.000-07:00
diff --git a/sections/attributes.pod b/sections/attributes.pod
@@ -3,7 +3,7 @@
 Z<attributes>
 
 Named entities in Perl--variables and functions--can have additional metadata
-attached in the form of I<attributes>. These are form arbitrary names and
+attached in the form of I<attributes>. These attributes are arbitrary names and
 values used with certain types of metaprogramming (L<code_generation>).
 
 Attribute declaration syntax is awkward, and using attributes effectively is
diff --git a/sections/chapter_00.pod b/sections/chapter_00.pod
@@ -101,7 +101,9 @@ appreciate this.
 
 This book would not have been possible without questions, comments,
 suggestions, advice, wisdom, and encouragement from many, many people. In
-particular, the author and editor thank:
+particular, the author thanks this edition's tech reviewers Andy Lester, Sean
+Lindsay, and Mohsen Jokar as well as Michael Swaine, editor of this edition.
+Contributors to this and previous editions include:
 
 L<credits>
 
diff --git a/sections/closures.pod b/sections/closures.pod
@@ -216,9 +216,9 @@ function which takes several parameters:
 =end programlisting
 
 Myriad customization possibilities might work very well in a full-sized ice
-cream store, but for a drive-through ice cream cart where you only serve French
-vanilla ice cream on Cavendish bananas, every call to C<make_sundae()> passes
-arguments that never change.
+cream store, but for an ice cream cart where you only serve French vanilla ice
+cream on Cavendish bananas, every call to C<make_sundae()> passes arguments
+that never change.
 
 X<partial application>
 
diff --git a/sections/files.pod b/sections/files.pod
@@ -475,7 +475,7 @@ C<file()> function to create an object representing a file:
 
 =end programlisting
 
-You can get File objects from directories and vice versa:
+You can get file objects from directories and vice versa:
 
 =begin programlisting
 
diff --git a/sections/functions.pod b/sections/functions.pod
@@ -112,9 +112,9 @@ use list assignment, but you may also access individual elements by index:
 
 =end programlisting
 
-You may also C<unshift>, C<push>, C<pop>, C<splice>, and slice C<@_>. Remember
-that the array builtins use C<@_> as the default operand I<within functions>,
-so that C<my $name = shift;> works. Take advantage of this idiom.
+You may also C<unshift>, C<push>, C<pop>, C<splice>, and use slices of C<@_>.
+Remember that the array builtins use C<@_> as the default operand I<within
+functions>, so that C<my $name = shift;> works. Take advantage of this idiom.
 
 To access a single scalar parameter from C<@_>, use C<shift>, an index of
 C<@_>, or lvalue list context parentheses. Otherwise, Perl will happily
@@ -541,10 +541,10 @@ X<C<Carp>>
 X<C<Carp>; C<croak()>>
 X<C<Carp>; C<carp()>>
 
-The standard C<Carp> module uses C<caller> to report errors and throwing
-warnings in functions. When used in place of C<die> in library code, C<croak()>
-throws an exception from the point of view of its caller. C<carp()> reports a
-warning from the file and line number of its caller (L<producing_warnings>).
+The standard C<Carp> module uses C<caller> to enhance error and warning
+messages. When used in place of C<die> in library code, C<croak()> throws an
+exception from the point of view of its caller. C<carp()> reports a warning
+from the file and line number of its caller (L<producing_warnings>).
 
 Use C<caller> (or C<Carp>) when validating parameters or preconditions of a
 function to indicate that whatever called the function did so erroneously.
diff --git a/sections/idioms.pod b/sections/idioms.pod
@@ -53,8 +53,8 @@ turns an ordinary list into an obvious list of pairs of arguments:
 
 =end programlisting
 
-Unpacks these parameters into a hash and treat that hash as if it were a single
-argument:
+You can unpack these parameters into a hash and treat that hash as if it were
+a single argument:
 
 =begin programlisting
 
diff --git a/sections/operator_characteristics.pod b/sections/operator_characteristics.pod
@@ -149,11 +149,6 @@ X<C<//>; infix operator>
 X<C<|=>; infix operator>
 X<C<||=>; infix operator>
 X<C<//=>; infix operator>
-
-I<Infix> operators appear between their operands. Most mathematical operators
-are infix operators, such as the multiplication operator in C<$length
-* $width>.
-
 X<C<\>; prefix operator>
 X<C<~>; prefix operator>
 X<C<++>; prefix operator>
@@ -162,25 +157,31 @@ X<C<+>; prefix operator>
 X<C<->; prefix operator>
 X<C<!>; prefix operator>
 X<C<!!>; prefix operator>
-
-I<Prefix> operators precede their operands. I<Postfix> operators follow their
-operands. These operators tend to be unary, such as mathematic negation
-(C<-$x>), boolean negation (C<!$y>), and postfix increment (C<$z++>).
-
 X<C<()>; circumfix operator>
 X<C<{}>; circumfix operator>
 X<C<[]>; circumfix operator>
 X<C<//>; circumfix operator>
 X<C<``>; circumfix operator>
 X<C<''>; circumfix operator>
 X<C<"">; circumfix operator>
-
-I<Circumfix> operators surround their operands, as with the anonymous hash
-constructor (C<{ ... }>) and quoting operators (C<qq[ ... ]>).
-
 X<C<()>; postcircumfix operator>
 X<C<{}>; postcircumfix operator>
 X<C<[]>; postcircumfix operator>
 
-I<Postcircumfix> operators follow certain operands and surround others, as seen
+=over 4
+
+=item * I<Infix> operators appear between their operands. Most mathematical operators
+are infix operators, such as the multiplication operator in C<$length
+* $width>.
+
+=item * I<Prefix> operators precede their operands. I<Postfix> operators follow their
+operands. These operators tend to be unary, such as mathematic negation
+(C<-$x>), boolean negation (C<!$y>), and postfix increment (C<$z++>).
+
+=item * I<Circumfix> operators surround their operands, as with the anonymous hash
+constructor (C<{ ... }>) and quoting operators (C<qq[ ... ]>).
+
+=item * I<Postcircumfix> operators follow certain operands and surround others, as seen
 in hash and array element access (C<$hash{$x}> and C<$array[$y]>).
+
+=back
diff --git a/sections/packages.pod b/sections/packages.pod
@@ -169,7 +169,7 @@ at any point, either with a new package declaration:
 
 You can add to a package at any point during compilation or runtime, regardless
 of the current file, though building up a package from multiple declarations in
-multiple can make code difficult to spelunk.
+multiple files can make code difficult to spelunk.
 
 X<namespaces; multi-level>
 
diff --git a/sections/perl_community.pod b/sections/perl_community.pod
@@ -57,10 +57,9 @@ X<RT>
 X<Best Practical>
 
 Best Practical Solutions (U<http://bestpractical.com/>) maintains an
-installation of their popular request tracking system, RT, for CPAN authors as
-well as Perl development. Every CPAN distribution has its own RT queue on
-U<http://rt.cpan.org/>. Perl itself has a ticket queue at
-U<http://rt.perl.org/>.
+installation of RT, its popular request-tracking system, for Perl development.
+Perl's queue is U<http://rt.perl.org/>. Every CPAN distribution has its own
+queue on U<http://rt.cpan.org/>.
 
 X<Perl 5 Porters>
 X<p5p>
@@ -105,9 +104,6 @@ meetings. In particular, the community-run YAPC--Yet Another Perl
 Conference--is a successful, local, low-cost conference model held on multiple
 continents. See U<http://yapc.org/>.
 
-The Perl Foundation wiki lists other events at
-U<http://www.perlfoundation.org/perl5/index.cgi?perl_events>.
-
 X<Perl Mongers>
 
 Hundreds of local Perl Mongers groups get together frequently for technical
diff --git a/sections/regular_expressions.pod b/sections/regular_expressions.pod
@@ -438,8 +438,8 @@ The C<\d> metacharacter matches Unicode digits:
 
 =end programlisting
 
-C<Regexp::English>
-C<CPAN; C<Regexp::English>>
+X<Regexp::English>
+X<CPAN; C<Regexp::English>>
 
 ... though in this case, the C<Regexp::English> module has a much better phone
 number regex already written for you.
diff --git a/sections/style.pod b/sections/style.pod
@@ -21,7 +21,9 @@ understanding of the idioms and techniques and style of your programming
 language, and good taste. You can develop all of these by concentrating on a
 few principles.
 
-I<Remove duplication.> Bugs lurk in sections of repeated and similar code--when
+=over 4
+
+=item * I<Remove duplication.> Bugs lurk in sections of repeated and similar code--when
 you fix a bug in one piece of code, did you fix it in others? When you updated
 one section, did you update the others?
 
@@ -30,24 +32,26 @@ objects, and roles to extract duplicate code into distinct components which
 accurately model the domain of the problem. The best designs sometimes allow
 you to add features by I<removing> code.
 
-I<Name entities well.> Your code tells a story. Every name you choose for a
+=item * I<Name entities well.> Your code tells a story. Every name you choose for a
 variable, function, module, class, and role allows you to clarify or obfuscate
 your intent. Choose your names carefully. If you're having trouble choosing
 good names, you may need to rethink your design or study your problem in more
 detail.
 
-I<Avoid unnecessary cleverness.> Concise code is good, when it reveals the
+=item * I<Avoid unnecessary cleverness.> Concise code is good, when it reveals the
 intention of the code. Clever code hides your intent behind flashy tricks.
 Perl allows you to write the right code at the right time. Choose the most
 obvious solution when possible. Experience and good taste will guide you.
 
 Some problems require clever solutions. When this happens, encapsulate this
 code behind a simple interface and document your cleverness.
 
-I<Embrace simplicity.> If everything else is equal, a simpler program is easier
+=item * I<Embrace simplicity.> If everything else is equal, a simpler program is easier
 to maintain than a complex program. Simplicity means knowing what's most
 important and doing just that.
 
+=back
+
 Sometimes you need powerful, robust code. Sometimes you need a one-liner.
 Simplicity means building only what you need. This is no excuse to avoid error
 checking or modularity or validation or security. Simple code can use advanced
@@ -64,63 +68,71 @@ want to write. C programmers often write C-style Perl, just as Java programmers
 write Java-style Perl and Lisp programmers write Lispy Perl. Effective Perl
 programmers write Perlish Perl by embracing the language's idioms.
 
-I<Understand community wisdom.> Perl programmers often debate techniques and
-idioms fiercely. Perl programmers also often share their work, and not just on
-the CPAN. Pay attention; there's not always one and only one best way to do
-things. The interesting discussions happen about the tradeoffs between various
-ideals and styles.
-
-CPAN developers, Perl Mongers, and mailing list participants have hard-won
-experience solving problems in myriad ways. Talk to them. Read their code. Ask
-questions. Learn from them and let them guide--and learn from--you.
-
 X<CPAN; C<Perl::Critic>>
 X<CPAN; C<Perl::Tidy>>
 X<CPAN; C<CPAN::Mini>>
 X<CPAN; C<Carton>>
 X<CPAN; C<Pinto>>
 
-I<Follow community norms.> Perl is a community of toolsmiths who solve broad
+=over 4
+
+=item * I<Understand community wisdom.> Perl programmers often debate techniques and
+idioms fiercely. Perl programmers also often share their work, and not just on
+the CPAN. Pay attention; there's not always one and only one best way to do
+things. The interesting discussions happen about the tradeoffs between various
+ideals and styles.
+
+=item * I<Follow community norms.> Perl is a community of toolsmiths who solve broad
 problems, including static code analysis (C<Perl::Critic>), reformatting
 (C<Perl::Tidy>), and private distribution systems (C<CPAN::Mini>, C<Carton>,
 C<Pinto>). Take advantage of the CPAN infrastructure; follow the CPAN model of
 writing, documenting, packaging, testing, and distributing your code.
 
-I<Read code.> Join a mailing list such as Perl Beginners
+=item * I<Read code.> Join a mailing list such as Perl Beginners
 (U<http://learn.perl.org/faq/beginners.html>) and otherwise immerse yourself in
 the communityN<U<http://www.perl.org/community.html>>. Read code and try to
 answer questions--even if you never post your answers, writing code to solve
 one problem every work day will teach you an enormous amount very quickly.
 
+=back
+
+CPAN developers, Perl Mongers, and mailing list participants have hard-won
+experience solving problems in myriad ways. Talk to them. Read their code. Ask
+questions. Learn from them and let them guide--and learn from--you.
+
 =head1 Writing Effective Perl
 
 X<efficacy>
 
 Writing maintainable code means designing maintainable code. Good design comes
 from good habits.
 
-I<Write testable code.> Writing an effective test suite (L<testing>) exercises
+=over 4
+
+=item * I<Write testable code.> Writing an effective test suite (L<testing>) exercises
 the same design skills as writing effective code. Code is code. Good tests also
 give you the confidence to modify a program while keeping it running correctly.
 
-I<Modularize.> Enforce encapsulation and abstraction boundaries. Find the right
+=item * I<Modularize.> Enforce encapsulation and abstraction boundaries. Find the right
 interfaces between components. Name things well and put them where they belong.
 Modularity forces you to think about similarities and differences and points of
 communication where your design fits together. Find the pieces that don't fit
 well. Revise your design until they do fit.
 
-I<Follow sensible coding standards.> Effective guidelines discuss error
+=item * I<Follow sensible coding standards.> Effective guidelines discuss error
 handling, security, encapsulation, API design, project layout, and other facets
 of maintainable code. Excellent guidelines help developers communicate with
 each other with code. If you look at a new project and nothing surprises you,
 that's great! Your job is to solve problems with code. Let your code--and the
 infrastructure around it--speak clearly.
 
-I<Exploit the CPAN.> Perl programmers solve problems, then share those
+=item * I<Exploit the CPAN.> Perl programmers solve problems, then share those
 solutions. The CPAN is a force multiplier; search it first for a solution or
 partial solution to your problem. Invest time in research to find full or
 partial solutions you can reuse. It will pay off.
 
+=back
+
 If you find a bug, report it. Patch it, if possible. Submit a failing test
 case. Fix a typo. Ask for a feature. Say "Thank you!" Then, when you're ready,
 When you're ready--when you create something new or fix something old in a
diff --git a/sections/universal.pod b/sections/universal.pod
@@ -18,7 +18,8 @@ invoking package or class. If you provide a version number as an optional
 parameter, the method will throw an exception if the queried C<$VERSION> is not
 equal to or greater than the parameter.
 
-Given a C<HowlerMonkey> module of version C<1.23>:
+Given a C<HowlerMonkey> module of version C<1.23>, its C<VERSION()> method
+behaves as:
 
 =begin programlisting
 
@@ -46,7 +47,7 @@ composition, role application, or any other mechanism.
 
 The default implementation of C<DOES()> falls back to C<isa()>, because
 inheritance is one mechanism by which a class may do a role. Given a
-C<Cappuchin>:
+C<Cappuchin>, its C<DOES()> method behaves as:
 
 =begin programlisting
 
@@ -136,7 +137,7 @@ a true value if its invocant is or derives from the named class, or if the
 invocant is a blessed reference to the given type.
 
 Given an object C<$pepper> (a hash reference blessed into the C<Monkey> class,
-which inherits from the C<Mammal> class):
+which inherits from the C<Mammal> class), its C<isa()> method behaves as:
 
 =begin programlisting
 
