Good work, Bill.  This should be posted here once a month, like a FAQ.  My
comments are interleaved below.  All are strictly IMO.

From: "William Djaja Tjokroaminata" <billtj / z.glue.umd.edu>


> Things That Newcomers to Ruby Should Know
> =========================================
>
> 0) Resources:
>
> HOME PAGE: http://www.ruby-lang.org/en/
> FAQ      : http://www.rubycentral.com/faq/
> PITFALL  : http://rwiki.jin.gr.jp/cgi-bin/rw-cgi.rb?cmd=view;name=pitfall
> ONLINE TUTORIAL/DOC/BOOK: http://www.rubycentral.com/book/
>
> 1) Use "ruby -w" instead of simply "ruby" to get helpful warnings.  If not
> invoking "ruby" directly, we can use instead:
>
> win32:
> C:\> set RUBYOPT=w
>  or
> pressing F5 (to execute script) in the Scite editor will give you warnings
> (and F4 will position at problematic line).
>
> unix:
> sh# export RUBYOPT="w"
>  or
> csh# setenv RUBYOPT "w"

This could be briefer: "set environment variable RUBYOPT to 'w'".  The ability
to set environment variables can be assumed in this community.

> 2) The String#[Fixnum] method does not return the "character" (which is a
> string of length one) at the Fixnum position, but instead the character
> code at the position (however, this may change in the future).  Currently,
> to get the character, use String#[Fixnum,1] instead.

It is useful for newbies to know about #chr, #ord and ?x syntax as well.

> 3) Be aware of the lexical scoping interaction between local variables and
> block local variables.  If a local variable is already defined before the
> block, then the block will use (and quite possibly) modify the local
> variable; in this case the block does not introduce a new scope.
>
> 4) In Ruby, there are two sets of logical operators: [!, &&, ||] and [not,
> and, or].  [!, &&, ||]'s precedence is higher than the assignments (=, %=,
> ~=, /=, etc.) while [not, and, or]'s precedence is lower.  Also note that
> while &&'s precedence is higher than ||'s, the and's precedence is the
> same as the or's.
>
> 5) In the case statement
>
>     case obj
>     when obj1
>         ....
>
> it is the "===" method which is invoked, not the "==" method.  Also, the
> order is "obj1 === obj" and not "obj === obj1".

An example of usage would bde really good here.  There are three interesting
cases: classes, regexen and ranges.

> 6) Array.new(2, Hash.new) returns an array with two elements referencing
> the same, indentical hash, and not two independent hashes.

Would read better as
  Array.new(2, {})  -->  [{}, {}]
    but the array elements are identical objects, not independent hashes.

> 7) After reading data from a file and putting them into variables, the
> data type is really String.  To convert them into numbers, use the
> "to_i" or "to_f" methods.  If you use the "+" operator to add the
> "numbers" without calling the conversion methods, for example, you will
> simply concatenate the strings.
>
> An alternative is to use "scanf" (http://www.rubyhacker.com/code/scanf).
>
> 8) It is advisable not to write some white space before the opening '(' in
> a method call; else, Ruby with $VERBOSE set to true may give you a
> warning.
>
> 9) The "dot" for method call is the strongest operator.  So for example,
> while in some other languages the number after the dot in a floating point
> number is optional, it is not in Ruby.  For example, 1.e6 will try to call
> the method "e6" of the object 1 (which is a Fixnum).  You have to write
> 1.0e6.
>
> However, notice that although the dot is the strongest operator, its
> precedence with respect to method name may be different with different
> Ruby versions.  At least in Ruby 1.6.7, "puts (1..3).length" will give you
> a syntax error; you should write "puts((1..3).length)" instead.
>
> 10) The notation "Class#method" in a documentation is used only to
> represent an instance method of an object of class Class.  It is not a
> Ruby syntax at all.  A class method in a documentation, on the other hand,
> is usually represented as "Class.method" (which is a valid Ruby syntax).

s/in a documentation/(in documentation|in a document)/g

I think the whole paragraph would read better as:
  The notation Class#method (or just #method) is an unofficial way to talk
  about methods which is widely used in the Ruby community.  In Ruby syntax
  and proper documentation, the notation "Class.method" is used.

> -----

998) Many more introductory pitfalls, as well as advice for Perl and Python
programmers, are included in "The Ruby Way" (see "Resources").

Gavin