Suggestions for 5.1 Manual - Migration Help

[Gavin Kistner <gavin@...>]

I've been using Lua 5.0 for almost a year now, and am excited about  
much in 5.1. I downloaded it the day it was announced and have been  
playing with it since.

As a user, I was personally a little frustrated trying to figure out  
a few migration aspects. The 5.1 manual highlights incompatibilities  
between 5.1 and 5.0, but doesn't explain how to overcome them.  
Reading the entire 5.1 manual carefully would have solved these  
issues for me, but I submit that a 'changelist' should almost suffice  
to learn the new features. Re-reading the manual is difficult not  
only in terms of time, but also because the amount of "I've already  
seen that text before" encourages skimming, which would very easily  
lead to missing the key differences.

I suggest adding a little more depth in the following areas of the  
manual, in the Incompatibilities section:


* "The vararg system changed from the pseudo-argument arg with a  
table with the extra arguments to the vararg expression."

Since I haven't been on the list long enough, I didn't have any idea  
what the vararg expression was. I found the text "Vararg expressions,  
denoted by three dots (`...´), can only be used inside vararg  
functions; they are explained in 2.5.9." in the manual, and so jumped  
to 2.5.9 and read it. Nowhere does that section explain that  
"return ..." works (though it may be inferred) or, more importantly,  
that "{...}" creates a table from the varargs. I had to download and  
search the lua-l archive before I found out about "{...}". I see now  
that this (IMO, important) syntax is listed in the manual only at the  
end of the 2.5 intro as an example.

--> If 2.5.9 is the main section about varargs, include a mention of  
"{...}" in that section. Possibly also mention the select() function  
right here.

--> In the incompatibilities section, include a note like:
"To iterate over the varargs expression, you may use the select()  
function, or create a table from the varargs."
Follow that sentence with a single vararg function showing both  
techniques.


* "There was a subtle change in the scope of the implicit variables  
of the for statement and for the repeat statement."
--> This sentence should be followed up with a description of the  
change. A quick code example and a description of how the scope  
behaved in 5.0 versus 5.1 would suffice.


* "The long string/long comment syntax ([[...]]) does not allow  
nesting. You can use the new syntax ([=[...]=]) in these cases."
--> To quick-start people moving from 5.0 to 5.1, perhaps link to  
section 2.1 (sort of vague) or mention that the syntax includes an  
arbitrary number of equals signs. (Yes, this is described in section  
2.1.


* "Function table.setn was deprecated. Function table.getn  
corresponds to the new length operator (#); use the operator instead  
of the function."
--> Also mention (assuming I'm right about this) that the deprecation  
means that there is no longer the ability to have a table of a  
'length' different from its key/value pairs. (The 'n' value is not  
honored by the length operator, and setn() no longer exists to store  
something in a metatable.)

IMHO, saying that a function is deprecated usually implies that the  
functionality is to be achieved in a new manner. Now, the  
functionality is lost from the core of the language. (I'm actually OK  
with this change, but took me some experimenting to be sure that it  
was the case.



I very, very much love the manual, and appreciate the hard work that  
surely goes into it. The above is intended not to tear it apart, but  
to hopefully better it.



--
"When I am working on a problem I never think about beauty. I only  
think about how to solve the problem. But when I have finished, if  
the solution is not beautiful, I know it is wrong."
- R. Buckminster Fuller