[ruby-talk:01697] Re: Conventions for our Ruby book

Hi,

In message "[ruby-talk:01694] Conventions for our Ruby book"
    on 00/03/02, Dave Thomas <[e-mail]> writes:

>In the reference section of our Ruby book, we show the signatures of
>(say) library methods. We use some typographic conventions to
>differentiate objects and classes. So, you might see something like
>
>   Dir.new( aString )  ->  aDir
>            ________       ____
>                |            |
>                 ----------------  object names are in italic

If you would use valid Ruby syntax, I'd like to propose:

   Dir.new( aString ) #=> #<Dir:object_id>

   str = "Foo"
   str.downcase       #=> "foo"
   str.downcase!      #=> str

>So, we were wondering what people thought. Is the '#' notation a good
>one? Will is confuse newcomers who pick up the book? Is there any
>alternative that might be easier to read (For example, String.new, but 
><i>String</i>.downcase)? What should we do?

Ruby doesn't have unbounded methods as first class data, so, I think
use of non-syntactic element `Klass#method' is better than syntactic
one.  Newcomers may be cofused though (this notaion should be included
in FAQ).  Maybe, `Notation' section at the beginning of your book will
help readers.

-- gotoken