> So... just to test stuff out before we move into production, would > people like to use the development web site to look at the > faq and the reference section: Good idea. I'm skipping the reference for a while (as long as there is no off-line version, since that's the only way for me to use it) and concentrate on the FAQ now. This started as a small innocent commentary, but now it's taking all my day and you know, I have to work too :). I tried to stay focused on comments and raise as few questions as possible. And you don't believe how much I learned today. Or maybe you do ,p . Anyway, now I can remember why Perl FAQs have (or should I say had) always something new when you read them again and again :). So here are the first five chapters, the latter half may come at some distant future. - Aleksi 1.x In the first chapter Perl is mentioned many times even with quote "Ruby will be a replacement for Perl" but other scripting languages are not mentioned. Makes one wonder the relationship or standing compared to Python, shell scripts, Lisp derivatives and the rest. We could give a example what are the platforms Ruby supports already. (And the fact that File.open("/dir/foo","r") should work everywhere.) 1.4 Don't mention 'The latest stable version of Ruby' unless you're going to update the faq with every minor release (usually FAQs have a little bit longer living time, many times even way longer that writer thought). 1.5 FTP mirror site list could be ordered by priority (capacity, avarage load, whatever) and that could be mentioned (maybe we wont have massive amount of download requests, but you never know when we will be /.ed ;). Reuben Thomas' comment could be indented denoting it to be a quote. 1.7 Mailing lists could have a small description right away. 1.10 The "Japanese" part of the book could be emphasized. 1.11 First mention to irb could be a hyperlink to 8.2. RFC could be linked too (I doubt many readers haven't ever heard of RFC). 2.1 "which reference nothing, and cause an error if used" Maybe we should change wording or note additionally that an error is a raised exception. "A variable holding the number 1, or the constant true," maybe we should change 'true' to 'false' or the number to something else, because this wording (could) gives me the wrong impression that 1 == true as in C, which doesn't hold with Ruby. Moreover we could say "But from the programmer's point of view it's easier to think 'a = 1' sets a to point (refer) to object Fixnum containing value 1 (even when the value is actually stored in 'a' itself). And a = a + 2 changes 'a' to refer to Fixnum(3)." 2.2 All the code examples should be in one order, whatever it happen to be. One possibility: 'what we are going to show with this example' 'the code' 'the analysis' This isn't good form automaticaaly because the reader spares some cycles trying to figure out if the comment is related to the predecing example or the next. Maybe every code block should be numbered and referred by number. Or maybe examples and commentary should be combined and separated from other subtopics somehow. - "A new scope for a local variable... and (4) a block definition." I think the first statement should incorporate all possible variations and then special case for the block should be explained in greater detail like it's done now. 2.4 Constants could have a example showing the four possibilities. 2.5 Should we note there's no way to do change local variable reference in called routine: def foo(bar) bar = 3 end zak = 2 foo(\zak) # => wont work print zak, "\n" # => expected to print 3 and it could be achieved through return value (zak = foo(zak)) or by wrapping variable into (anonymous) class passed in. And sometimes there's (fortunate or unfortunate) "side-effects": def change_a( b ) b.chop! end a = "str" change_a( a ) print a,"\n" # => st And maybe it should be noted that we're not changing the reference, so 'a' is pointing to the same object all the time. We change the internal state of the referenced object. <<Added when I was at 5.14. Maybe the whole thing here should be omitted and just point to look at 5.14, dunno, you tell me.>> 2.8 "1. Left hand side of a multiple assignment" => "the right most item in left hand side of a multiple assignment" Example for "2. Right hand side", "4. Actual arguments" and "5. In when clause". Item "3. Definition of method" example could be pointed (it's already in the beginning of the 2.8). 2.11 There could be a example for 2.11 how block modifies local parameter (and explanation it's relationship to Lisp or Perl -type closures.) 3. Maybe we should 'unshift' a chapter 'What is a block?' before current '3.1 What is an iterator'. 'iterator?' could be mentioned somewhere. (I think it's better to write if iterator? .. else .. end than catch try to catch error coming from Proc.new; if it isn't an error case to call a iterator without a block). 3.1 It might be because English is not my mother tongue, but I understand "The each method of the array data is passed the do...end block, and executes it repeatedly" as do |i| ... end is called once and 'i' gets reference to 'data.each'. Then I read the continuation the sentence 'passing in each of the array's elements.' and get confused. I probably would understand explanation like <<EOSThe each method of the array data passes each of the array's elements by repeated calls to do...end block. Variable 'i' inside the block refers to all element of the array one by one. EOS --- The binding difference example could be given with "parsed" parentheses: foobar (a, b) do .. end foobar (a, b { .. } ) 4.4 Clemens Hintze says: ... bengin ... end 4.5, and possibly many other places too It's hard too see (on my screen only, maybe) difference between Courier and Times, so I suggest splitting the code a +b # is parsed as 'a (+b)' and there's no method a defined a + b # is parsed correctly a+b # is parsed corerctly out from text. And it should be noted that it's all about call to a method named 'a' which is not defined. It could be about call to an unary method + (that is @+ <and here a link to 5.2 unary operator>) which happens to exist for Fixnums). 4.6 It's should be noted that it's the call to function s instead of '*10' which is not *what one expects* and '*10' is an expression which doesn't go through the parser even (because there's no unary-*-methods). 4.7 Change header to "Method call with passed hash don't work p {}' 4.8 It could be noted that 'pos = 1' creates or changes local variable. 'Receiver' should be defined before using the concept (link or local definition, this seems to be the first place where it's used). 4.9 It could be noted the meaning is different in double quoted string. a = '\1' #=> "\\1" reads \ as char and in double quote # it has be to doubled b = '\\1' #=> "\\1" reads \\ as transformation of char \ c = "\1" #=> "\001" reads \1 like octal notation d = "\\1" #=> "\\1" reads \\ as transformation of char \ 4.10 add <<-EOS So method call has higher precedence than logical operators which in turn have precedence over control structures.EOS 4.11 Uses different Question-answer structure than the rest of the FAQ. I like this way better, but then the rest of the FAQ should be reformatted. I have a feeling that p( nil || "") doesn't return "" while the FAQ says so. It prints "" and returns nil, doesn't it? 5.1 Example for "directly redefine [] in class String" class String def [](n) to-a[n] end end 5.3 add "and you can't hack around it easily (it wouldn't be good idea anyway:)." 5.4 and 5.5 could be moved to be the first thing in chapter 5. 5.7 "Will compile if age is a protected" or public "method, but not" 5.8 "The exception is the instance initializing method, initialize." which visiblity is xxx. 5.9 Funny English :). Header "Can an identifier beginning with a captial letter be a method name?" Answer: "Yes, you can, but we don't do it lightly!" 5.11 An example would be nice. 5.13 Maybe the warning could be emphasized like 4.10 "When in doubt, put the parentheses around method calls." 5.14 The actual argument isn't altered, but the object it points to is.