[ruby-talk:01269] Re: Draft of the updated Ruby FAQ

Wow! Thanks for taking the time with such a detailed reply.

Clemens Hintze <[e-mail]> writes:

> GENERAL REMARKS
> 
> - May I propose that Ruby code samples are *not* enclosed in <HR>
>   tags. It is difficult for my eyes to recognize that all these parts
>   belonging to the same answer! IMHO, different font (and/or
>   additional indentation) for Ruby code should be enough.

I agree it's ugly. We actually wrote the document using the linuxdoc
sgml markup, and converted it using their standard filters. At some
point we'll have a look at how it does the formatting, but right now
our time is limited.

> 1.4 What is the history of Ruby?
>    ... wanted a genuine object-oriented, easy-to-use object-oriented
>    scripting language.
> 
> Perhaps delete one 'object-oriented'? If matz agrees, of course!

I don't want to change a direct quote. To be honest, if I wanted to
delete a word in the preceedind quote, it'd be 'scripting'--I think
Ruby's far more general that that.

> 2.1 Does assignment generate a new copy of an object? 
>    ... All variables ... If they have not been initialized, they
>    reference the object nil. ...
> 
> This is not true for local variables. If they wasn't initialized, they
> are void. It is an error to use them!

Yup!

> 2.2 What is the scope of a local variable? 
>    ... A procedure block creates ...
> 
> Not only a procedure block. Every block does, AFAIK. As you have not
> explained, what procedure block means, I assume procedure block mean
> definition block of methods.

Nope - missed that wording during the edit. It should just be
'block'. I added an example of the locality of block variables across
threading.

> 2.6 Does assignment to a formal argument influence the actual argument? 
>    A formal argument is a local variable. Within a method, assigning
>    to a formal argument simply changes the object to which it points.
> 
> Could that be misunderstanding? I would understand this as: actual
> argument points to object A. Formal argument also. Now assignment to
> formal argument happens so object A is changed. That would be wrong! I
> assume you mean: formal argument now points to new object, whereas
> actual argument still points to A, yes?

Actually we're saying the same thing, but I guess we're not saying it
clearly ;-) I'll try again.

> 2.9 What does ``&'' prepended to an argument mean?
>    The ampersand character tells Ruby to expect a Proc object in place
>    of this parameter. A block following the method call will be
>    converted into a Proc object and assigned to the formal parameter.
> 
> I think the main purpose of that feature is reflected by the second
> sentence.

Agreed. I've changed it and added some examples.

> 2.10 Can I define a default value for a formal argument? 
> 
> Better reformulate it to "2.10 How can I define ..."?

OK

> 3.1 What is an iterator? 
>    An iterator is a method which is passed a block ...
> 
> IMHO, blocks are not passed, but attached to methods. If they would be
> passed, it could mean that they also are objects. But I feel they are
> not, at least not in Ruby's sense of objects.

That's a good point. I've changed it to 'method that accepts a block'

> 3.3 How is a block used in an iterator? 
>    There are three ways to execute a block from an iterator method:
>    ... (3) using Proc.new.
> 
> Proc.new creates an Proc instance from a attached block. But it does
> not execute it. This has do be done via 'call' anyway.

Yup - tightened up the wording.

> 
>    If a method definition ... , it will receive the block object. The
>    block may be called using method.call(args...).

and this one

> 4.1 What does :var mean? 
>    A colon followed ..., but the ``:'' form will create a local
>    variable if it doesn't already exist.
> 
> I could not verify it! I have tried 

You're right. It creates the symbol, but not as a variable or method.

> 4.10 What's the difference between ``or'' and ``\\''? 
> 
> I guess the ``\\'' should be ''||'', shouldn't them?

Picky picky... ;-)

>    =, .., ..., !, not, &amp;&amp;, and, |, or, ~, ::
> 
> I think you mean '&&' instead of &amp;&amp;, yes? I do not know right
> now, but can I overload '||'? I do not think so.

Just slightly over quoted ;-)  Fixed


> 5.7 What's the difference between private and protected? 
> 
> But the visibility thing is the same? That means protected is somewhat
> superfluos, isn't it (from the newbie point-of-view)?

No, because (for example)

   def <=>(other)
     func <=> other.func
   end

will work if 'func' is protected, but not if it's private. I've added
an example.

> 5.14 Why can destructive methods be dangerous? 
>    ...invoke a destructive method, the object references by all of
>    them will be changed.
> 
> Shouldn't that be '... the object referenced by ...'?

What can I say. 's' and 'd' _are_ next to each other on the keyboard.


> 6.3 What is a class instance variable? 
>    ... There is no way to access class instance variables from
>    instance methods.
> 
> That is not true so. They could access them via Singleton methods! So
> better add 'directly'.

I think I'd argue that one. When they use a singleton method, then
they're not accessing the variable, but the singleton method. What it
does is its business (encapsulation). I think that 'directly' would
just add confusion here.

> 7.21 Does Ruby have function pointers? 
>    A Proc object generated by Proc.new, proc, or lambda serves as a
>    function pointer. You can also get references to methods within a
>    particular object instance using Object.method.
> 
> Hmmm! This is not the same, IMO. A function pointer is a variable that
> points to a certain function. This function could be executed by
> calling it thru this variable. At any time you may let the variable
> point to another function. A Proc instance, cannot serves this
> pupose. A Proc instance *is* a callable object. But it cannot points
> to another one.

But a variable pointing to a proc object is effectively a function
pointer (or at least is used in the same way function pointers
are). I've changed the wording a tad.

>    o thread does not cause thrashing. 
> 
> What does that mean in opposition to processes spawned with 'fork'?

Just that fork may cause thrashing.



Once again, THANK YOU for going to all this trouble.

I've posted the updates based on these comments.

Dave