From: Dave Thomas <Dave@...>
Date: 2000-03-02T11:38:37-06:00
Subject: [ruby-talk:01694] Conventions for our Ruby book


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

This works well when you want to illustrate the difference between
mutating and non-mutating functions:


    str.downcase  ->   aString

    str.downcase! ->   str


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

However, at other times we need to talk about a method and give its
name. For example, we might say "see Dir.new" for more
information". The problem here is when referencing instance methods.

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?

Thanks


Dave