Re: Modern Perl: The Book: The Draft

[mr_mischief]

In chapter 3, where you mention "Interpolating undef into a string--or evaluating it in a string context--produces an uninitialized value warning, if you have warnings enabled.", I would consider adding " (and you usually should)" or something close to the end of the sentence, possibly with a reference to the appropriate section in chapter 12. Warnings and strictures are difficult to overemphasize for all but quick-and-dirty programs after all.

Also in chapter 3, you have a type in "It cheap, both in terms of code and memory, to use only the keys of a hash for storage." in the Hash Idioms section. We're missing a form of "to be", either "It's" or "It is".

Again in the hash idioms section, you have "Hashes can also serve many purposes named parameters passed to functions." which seems to have a word or two missing, like perhaps "such as".

s/intent/intend/ in "To prevent someone from accidentally adding a hash key you did not intent" in the Locking Hashes section of chapter 3.

Under Boolean Coercion in chapter 3, you use "truthiness" rather than "truthfulness" or some other wording. I've seen "truthiness", particularly in the Perl community, and it's easy enough to understand. I just thought a nonstandard usage was worth reconsidering even if reconsidering it means you still use it. My concern would be the impression left on those not familiar with it. You might even consider introducing it as a term as you would with "stringify" and others, since it is both nonstandard English and denotes a specific meaning with slightly different connotations from "truthfulness".

In the Autovivication section in ch. 3, you have the following sentence: "You can also check for the existence of specific hash keys and the number of elements in arrays before dereferencing each level of a complex data structure, but that can produce tedious, length code which many Perl programmers prefer to avoid." in which "length" should be "lengthy".

In chapter 4's Arity section, I think "Grouping parentheses clarify, yet watch out for confusion in code such as:" reads better starting as "Use grouping parentheses".

In Chapter 5, your State vs. Closures section has a recursive link to the section.

In your Drawbacks of AUTOLOAD section in chapter 5, you have an improperly escaped entity in "naïve", such that it currently reads "naiumlve" instead.

In Chapter 6, in your The qr// Operator and Regex Combinations section, one of your examples is missing a closing slash after '$field'.

Your character classes in chapter 6 are kind of tacked on to the section Metacharacters. The prose reads very clearly this way and the examples follow well as is, so I'm not sure if your intent was to only define character classes or also to have a section header for them.

Still in the Metacharacters section, you have the sentence "Just as the word and digit class metacharacters (\w and \d) have negations, so to you can negate a character class.". I'm thinking s/so too you can/so too can you/ to make that read more clearly.

In chapter 7 in the Methods section, you have the following sentence which seems half-edited: "The invocant of a method in Perl 5 method is its first argument."; the second instance of "method" seems out of place.

The first paragraph of your Polymorphism section has a closing parenthesis which no matching open parenthesis. When reading, I inserted the open parenthesis such that the phrase "(into a single place)" is the parenthetical.

Moving on to chapter 8, in your Writing Maintainable Perl section, under the "name entities well" bullet point, you have the sentence "The ease with which you can name these entities system reveals your understanding of the problem and the cohesion of your design." in which the word "system" seems simply superfluous. Maybe accidentally left in during a rewording?

In the Running Tests section of chapter 9, the following sentence has a doubled word: "The core module Test::Harness interprets TAP and and displays only the most pertinent information."

In your exporting example featuring the functions monkey_dance and monkey_sleep, you've currently got @EXPORT_OK where it seems you want @EXPORT instead.

In chapter 10, in your section on the Schwartzian Transform, you have, "Suppose you want to print a list of extensions and co-workers sorted by their names, not their extensions. In other words, you need to sort a hash by its keys." s/keys/values/ there.

In chapter 11, there exists a paragraph in the Prototypes section that is, in its entirety, "A prototype is a piece of optional metadata attached to a function declaration. Novices commonly assume that these ". That thought isn't finished elsewhere, and that seems a good place to go ahead and finish it.

In chapter 12, the Missing Defaults section is missing some punctuation, and around that missing punctuation is a little confusing content. "Perl 5 added many great new features, but it also kept compatibility with the previous seven Sixteen years later, the best way to write clean, maintainable, powerful, and succinct Perl 5 code is very different from Perl 5.000.". I can easily guess that there should be a period between "seven" and "Sixteen". It's less obvious what "seven" itself means in context. Seven versions before 5? Seven previous years? Yes, in 1994 it'd been seven years since Perl 1.0 was released, but that's not clear to the uninitiated. Perhaps s/seven Sixteen/seven years of Perl's history. Sixteen/ makes it more clear.

I also, between your chapter on what to avoid in 11 and the pointers on what to add to default behavior in chapter 12 was left wondering where and whether 2-argument vs. 3-argument open could be mentioned. I'm not sure where exactly I'd put it if I were writing, and not entirely sure if it would make the cut. I'd at least consider putting it somewhere, and I was a little surprised I didn't see the tip somewhere among the mentions of IO::Handle, lexical filehandles, and such.

[chromatic]

Thanks for all of this review! How would you like me to credit you in the book?

[mr_mischief]

I sign all my professional work as "Christopher E. Stith".

It would be quite nice see my name in such a clear and useful volume. I'm considering transitioning to tech writer or proofreader if I decide to go back to school. A credit in your book would be a fine addition to my portfolio for that.

In any event, I appreciate the chance to read and comment on the manuscript. It was a pleasure. I've been meaning actually to give it another read through, and I'll see if there's anything I didn't see the first time. If you get a newer draft ready, I'd be happy to read that, too.