From: Johan Holmberg <holmberg@...>
Date: 2001-12-14T21:15:56+09:00
Subject: [ruby-talk:28500] A Review of "Ruby in a Nutshell" book


Hi !

An elegant language deserves an elegant book. This one isn't.

The book starts with a short description of the "Language Basics"
(31 pages). This is followed by the main part of the book (130 pages),
consisting of two chapters describing the classes and modules that is
part of the standard Ruby distribution. This is followed by two short
chapters called "Ruby Tools" and "Ruby Updates".

This organisation is quite OK, but I miss an index with all available
classes/modules. The "Contents" section at the beginning of the book
should have contained a list of the classes/modules, and what page to
find them on. And the classes are not sorted alphabetically either,
making it very hard to find them.

I also find it strange that the new methods since 1.6.5 hasn't been
incorporated in the normal text. They are now listed in the last chapter
("Ruby Updates"), without any explanation of what the methods do.

But the real problems with the book are of another sort.
I wonder if anyone has bothered to proof-read the text at all.
It is chock full of incorrect examples, and the English is often
difficult to read.

I started reading with high hopes: what could be better than a book
from the inventor of the language ? But I soon started to be
irritated by the numerous errors in the examples, and after a while
I switched "mental mode" and started to look for further errors. And
I found a lot .... Some examples:

   - on page 11, the example showing  here-documents has incorrect
     indentation. A bit ironic, since the point of one of the
     examples is to show allowed ways to indent here-documents.

   - On page 64 the method "Array.slice" is documented. But the
     example is for "String.slice!", i.e. wrong class and wrong method.

   - On page 75-76 examples for "IO::forech" and "IO.each_line" uses a
     variable "lib", that isn't defined anywhere. Should obviously
     have been "line".

   - the layout of code showing the syntax of the language is often
     poor. On page 22 for example, "def" is described. But the example
     is hard to read, due to lack of indentation, and minimal
     difference in "font appearance" between literal text and
     meta-variables.

   - on page 18 the description of "range operators" in conditionals
     is backwards. "left" and "right" should change places.
     Now it incorrectly says:

        "In conditionals they return true from the point right operand
         is true until left operand is true"

   - Often the fonts used in the text are inconsistently used.
     On page 31 the meta-variable "symbol" have different font in the
     different syntax examples. In other places there are lots of
     similar errors, for example upper/lower-case errors, etc .etc.

I could go on for quite a while describing similar defects. (I filled
two A4 sheets with notes while reading through the book yesterday)

The effect of all these things, is that I feel it is quite unpleasant
to read the text, and I don't trust the content (especially the
examples).

I think Ruby deserves better books.
(like the one from Thomas/Hunt: "Programming Ruby")

It's a mystery to me that O'Reilly publishes such a
poorly proof-read book.

I didn't want to write this, but I had to ....

/Johan Holmberg