Permalink
Browse files

Addressed copyedit questions.

  • Loading branch information...
1 parent a5ff0d5 commit 297a21fe64173e71e8d294ff3666ebac70082d2b @chromatic committed Sep 29, 2015
View
2 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
View
4 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>
View
6 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>
View
2 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
View
14 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.
View
4 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
View
31 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
View
2 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>
View
10 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
View
4 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.
View
52 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
View
7 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

0 comments on commit 297a21f

Please sign in to comment.