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

Hi,

From: Dave Thomas <[e-mail]>
Subject: [ruby-talk:01694] Conventions for our Ruby book
Date: 02 Mar 2000 11:38:37 -0600

> The other thing we like about this approach is that the method
> signatures are valid Ruby syntax.

I think it's a good approach.  However, "String.downcase" (to refer
String#downcase) is syntactically valid, but semantically not.  So, I
think, "String.downcase" is not so good.

> Existing Ruby documentation gets around this by using the '#'
> notation. It would say "see String#downcase" to refer to an instance
> method in String.
> 
> Although its a good differentiator, it worries us slightly, because it 
> isn't Ruby syntax. We though it might be confusing.
> 
> 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?

In reference section, I don't worry about newcomer's confusion.
Newcomers are too new to be confused in the reference section!!  So, I
think, '#' is not so bad for newcomers, unless there are hundreds of
'#'s per page.  (I think, newcomers would be attracted in introductory
sections, TOC, index, and brief look of the reference)

IMHO, the point is beginners, who begin to use the reference section.
The important is how to make understand beginners, who read the book,
as fast as you can.  It have to be explained in early sections,
in introductory part of the reference section, and in index too.


From another point of view, '#' is already used in several ruby
documents, including matz's book and mailing lists.  IMO, making
newcommers and beginners familier with the '#' notation is good
strategy, for Ruby (I mean not only for the book).

To follow the strategy, I recommend '#' rather than
<i>String</i>.downcase.  And about your book, '#' might be in other
font than that of Ruby codes.


FYI, In matz's book, Class#instance_method notation is used, and it's
explained in footnote (p.55 in section 2).  I think, this means, '#'
is thought to be ordinal, at least by matz.  And AFAIK, in ruby-list
there is no complaint about '#' of matz's book.  (Is this wrong?
please correct)

Regards,
Hiwada
--
Kazuhiro HIWADA <[e-mail]>
excuse my buggy english