Last night I was looking over the book, and a few cases in src/operators.pod
where code is spaced so that operators line up vertically. This seems
reasonable in concept, but in practice this code comes right after the
precedence section and that makes it look confusing to me. For example:
say 3 === 3; # 1
say 'a' === 'a'; # 1
Really emphasizes "say 3" and seems to imply that "say 3" and "=== 3" are
distinct in some way. I think this would be just as readable if it were:
say 3 === 3; # 1
say 'a' === 'a'; # 1
There's no particular reason to line up the === operators, I think. This
occurs again, later on:
say 10 <=> 5; # +1
say 10 leg 5; # because '1' lt '5'
say 'ab' leg 'a'; # +1, lexicographic comparison
And again, I don't think there's a real need to line up the operators, here.
On an unrelated note, m-dashes and n-dashes are mixed together in the
resulting document in ways that I don't fully understand. It looks like
spaces around the "--" may be to blame, here. It looks like unspaced (such
as it is just before "an object representing that file" in basics.pod) the
-- becomes an n-dash and when surrounded by whitespace (e.g. in
operators.pod before "after reading the chapter") it becomes an m-dash, but
that's just a guess.
What's frustrating, about that is that "comparisons—== and eq—there" from
the output of operators.pod is very hard to read either way, even though
it's fine in the POD. I think parentheticals might be better suited and less
prone to the vagaries of typesetting in many of these cases. In other cases
commas might suit just as well, e.g.:
"The upshot of this is that, after reading the chapter on writing classes
and methods, you ..."
I have some additional comments that I'm going to send tonight as diffs,
since they address the language used in several places, rather than
structural/formatting elements as above.
--
Aaron Sherman
Email or GTalk: a...@ajs.com
http://www.ajs.com/~ajs
