> So... just to test stuff out before we move into production, would
> people like to use the development web site to look at the 
> faq and the reference section:

Good idea. I'm skipping the reference for a while (as long as there is no
off-line version, since that's the only way for me to use it) and
concentrate on the FAQ now.

This started as a small innocent commentary, but now it's taking all my day
and you know, I have to work too :). 

I tried to stay focused on comments and raise as few questions as possible.
And you don't believe how much I learned today. Or maybe you do ,p .

Anyway, now I can remember why Perl FAQs have (or should I say had) always
something new when you read them again and again :).

So here are the first five chapters, the latter half may come at some
distant future.

	- Aleksi


1.x
In the first chapter Perl is mentioned many times even with quote "Ruby will
be a replacement for Perl" but other scripting languages are not mentioned.
Makes one wonder the relationship or standing compared to Python, shell
scripts, Lisp derivatives and the rest.

We could give a example what are the platforms Ruby supports already. (And
the fact that File.open("/dir/foo","r") should work everywhere.)

1.4
Don't mention 'The latest stable version of Ruby' unless you're going to
update the faq with every minor release (usually FAQs have a little bit
longer living time, many times even way longer that writer thought).

1.5
FTP mirror site list could be ordered by priority (capacity, avarage load,
whatever) and that could be mentioned (maybe we wont have massive amount of
download requests, but you never know when we will be /.ed ;).

Reuben Thomas' comment could be indented denoting it to be a quote.

1.7 
Mailing lists could have a small description right away.

1.10 
The "Japanese" part of the book could be emphasized.

1.11 
First mention to irb could be a hyperlink to 8.2. RFC could be linked too (I
doubt many readers haven't ever heard of RFC).

2.1 

"which reference nothing, and cause an error if used" Maybe we should change
wording or note additionally that an error is a raised exception.

"A variable holding the number 1, or the constant true," maybe we should
change 'true' to 'false' or the number to something else, because this
wording (could) gives me the wrong impression that 1 == true as in C, which
doesn't hold with Ruby.

Moreover we could say "But from the programmer's point of view it's easier
to think 'a = 1' sets a to point (refer) to object Fixnum containing value 1
(even when the value is actually stored in 'a' itself). And a = a + 2
changes 'a' to refer to Fixnum(3)."

2.2 

All the code examples should be in one order, whatever it happen to be. One
possibility: 
'what we are going to show with this example'
'the code'
'the analysis'

This isn't good form automaticaaly because the reader spares some cycles
trying to figure out if the comment is related to the predecing example or
the next. Maybe every code block should be numbered and referred by number.
Or maybe examples and commentary should be combined and separated from other
subtopics somehow.

-

"A new scope for a local variable... and (4) a block definition."
I think the first statement should incorporate all possible variations and
then special case for the block should be explained in greater detail like
it's done now.

2.4
Constants could have a example showing the four possibilities.

2.5
Should we note there's no way to do change local variable reference in
called routine:

def foo(bar)
	bar = 3
end

zak = 2
foo(\zak)        # => wont work
print zak, "\n"  # => expected to print 3

and it could be achieved through return value (zak = foo(zak)) or by
wrapping variable into (anonymous) class passed in.

And sometimes there's (fortunate or unfortunate) "side-effects":
def change_a( b )
  b.chop!
end
a = "str"
change_a( a )
print a,"\n"  # => st

And maybe it should be noted that we're not changing the reference, so 'a'
is pointing to the same object all the time. We change the internal state of
the referenced object.

<<Added when I was at 5.14. Maybe the whole thing here should be omitted and
just point to look at 5.14, dunno, you tell me.>>


2.8
"1. Left hand side of a multiple assignment" => "the right most item in left
hand side of a multiple assignment"

Example for "2. Right hand side", "4. Actual arguments" and "5. In when
clause". Item "3. Definition of method" example could be pointed  (it's
already in the beginning of the 2.8).

2.11
There could be a example for 2.11 how block modifies local parameter (and
explanation it's relationship to Lisp or Perl -type closures.)

3.
Maybe we should 'unshift' a chapter 'What is a block?' before current '3.1
What is an iterator'.

'iterator?' could be mentioned somewhere. (I think it's better to write

  if iterator?
    ..
  else
    ..
  end

than catch try to catch error coming from Proc.new; if it isn't an error
case to call a iterator without a block).

3.1 
It might be because English is not my mother tongue, but I understand "The
each method of the array data is passed the do...end block, and executes it
repeatedly" as

  do |i| ... end 

is called once and 'i' gets reference to 'data.each'. Then I read the
continuation the sentence 'passing in each of the array's elements.' and get
confused.

I probably would understand explanation like <<EOSThe each method of the
array data passes each of the array's elements by repeated calls to do...end
block. Variable 'i' inside the block refers to all element of the array one
by one.
EOS

---
The binding difference example could be given with "parsed" parentheses:
foobar (a, b) do .. end
foobar (a, b { .. } )

4.4
Clemens Hintze says: ... bengin ... end

4.5, and possibly many other places too
It's hard too see (on my screen only, maybe) difference between Courier and
Times, so I suggest splitting the code 

  a +b   # is parsed as 'a (+b)' and there's no method a defined
  a + b  # is parsed correctly
  a+b    # is parsed corerctly 

out from text. And it should be noted that it's all about call to a method
named 'a' which is not defined. It could be about call to an unary method +
(that is @+ <and here a link to 5.2 unary operator>) which happens to exist
for Fixnums).

4.6
It's should be noted that it's the call to function s instead of '*10' which
is not *what one expects* and '*10' is an expression which doesn't go
through the parser even (because there's no unary-*-methods). 

4.7
Change header to "Method call with passed hash don't work   p {}'

4.8
It could be noted that 'pos = 1' creates or changes local variable.
'Receiver' should be defined before using the concept (link or local
definition, this seems to be the first place where it's used).

4.9
It could be noted the meaning is different in double quoted string.

a = '\1'  #=> "\\1"   reads \  as char and in double quote 
          #           it has be to doubled
b = '\\1' #=> "\\1"   reads \\ as transformation of char \
c = "\1"  #=> "\001"  reads \1 like octal notation
d = "\\1" #=> "\\1"   reads \\ as transformation of char \

4.10
add <<-EOS
So method call has higher precedence than logical operators which in turn
have precedence over control structures.EOS

4.11
Uses different Question-answer structure than the rest of the FAQ. I like
this way better, but then the rest of the FAQ should be reformatted.

I have a feeling that 
  p( nil || "")
doesn't return "" while the FAQ says so. It prints "" and returns nil,
doesn't it?

5.1
Example for "directly redefine [] in class String"
  class String
    def [](n)
      to-a[n]
    end
  end

5.3
add "and you can't hack around it easily (it wouldn't be good idea
anyway:)."

5.4 and 5.5 could be moved to be the first thing in chapter 5.

5.7
"Will compile if age is a protected" or public "method, but not"

5.8
"The exception is the instance initializing method, initialize." which
visiblity is xxx.

5.9
Funny English :).
Header "Can an identifier beginning with a captial letter be a method name?"
Answer: "Yes, you can, but we don't do it lightly!"

5.11
An example would be nice.

5.13
Maybe the warning could be emphasized like 4.10 "When in doubt, put the
parentheses around method calls."

5.14
The actual argument isn't altered, but the object it points to is.