lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

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