Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??

chromatic:

I've read a bit of it, and here are my notes so far:

Chapter 1

When you mention Baby perl, I'd suggest including a sidebar giving examples, such as:

# new programmer from C/C++ background my $count = @array_of_stuff; for (my $index=0; $index<$count; ++$index) { $array_of_stuff[$index] = $array_of_stuff[$index]*3; } # Baby perl (?) my @new_array; for (@array_of_stuff) { push @new_array, $_*3; } @array_of_stuff = @new_array; # More advanced: operate on the whole list @array_of_stuff = map { $_*3 } @array_of_stuff

In Numeric, String, and Boolean Context, first I'd move:

In exchange for not having to declare (or at least track) explicitly what type of data a variable contains or a function produces, Perl offers specific type contexts that tell the compiler how to treat a given value during an operation.

to the end of the first paragraph. I'd then change:

In exchange for not having to declare (or at least track) explicitly what type of data a variable contains or a function produces, Perl offers specific type contexts that tell the compiler how to treat a given value during an operation. The eq operator treats its operands as strings by enforcing string context on them. The == operator enforces numeric context.

to something like:

The code fails because the == operator enforces numeric context (e.g., it treats both 'alice' and 'bob' as numbers, and both are 0 in numeric context). You use the eq operator to specify string context for the comparison.

In the section The Default Scalar Variable you may want to change "best example a linguistic" to "best example of a linguistic".

In the same section, you have a snippet of code including:

say "'$uncle'"

Which may give a confusing error message to someone reading the book. (Generally, when reading a programming book, I keep a couple editor windows open and try executing all the snippets I find, and make variations to verify I understand what's being said, and to solidify what I'm told.) So if someone is noodling around and tries the snippet, they'll get an error since "say" isn't enabled by default. You might want to add a sidebar earlier in the chapter giving them an example of how they can follow along in the book. Something like telling them to add the module with the -M switch on all your examples, or a use statement at the start of their test files or some such. (In fact, I'd suggest you have a template for them to use for their experiments, and then run all your snippets in the template to ensure that no syntax errors pop up. This can give you an opportunity to enforce the mantra "always use strict and warnings". Then, if you have "answers" at the end of your book, you can include the complete bit using your template.)

Chapter 3

I've not finished this chapter yet. But I wanted to get you these notes before they become stale and useless...

In the Names section, I'd move the paragraph starting "When the utf8 pragma" into the introduction--specifically into the sidebar suggested earlier with the template. Then you have an opportunity to have them add it to the template (or not) as they see fit.

In the paragraph starting "These rules only apply to literal names found", I don't follow what you mean in the first sentence. If you're referring to the stuff just before the utf8 bit, then I'd change "literal" to "variable" and /, and I'd put the sentence after the end of the invalid perl identifiers list, fleshing it out a bit to make a paragraph. (When you say literal, I think stuff in single/double quotes, so it makes the sentence feel somewhat "off".)

As for the rest of the paragraph, I'd hold that for later (probably in the hash section) as many won't know what a symbolic lookup is, and you'll have the chance to explain that in the hash section.


I'll try to find some time to continue reading later.

...roboticus


In reply to Re: Modern Perl: The Book: The Draft by roboticus
in thread Modern Perl: The Book: The Draft by chromatic

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Domain Nodelet?
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this?Last hourOther CB clients
    Other Users?
    Others having a coffee break in the Monastery: (5)
    As of 2024-09-07 11:02 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      No recent polls found

      Notices?
      erzuuli‥ 🛈The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.