Lua 5.0 alpha documentation

[Philippe Lhoste <PhiLho@...>]

I finally had some time to finish reading the last Lua doc.

As always, it is a pleasant reading, the document is clear and well written. 
A bit terse in some areas though, some more examples in the library section 
would help...
I don't see it as a end user documentation: the C API is of no use for 
script writers, and references to C (a lot in the libraries, eg. strftime) 
should be expanded, as some users may not know this language.

I was surprise, confused but flattered to see my name in the 
Acknowledgements section... While I am still a newbie in most areas, mostly 
because I use Lua on my rare idle time, so I am not on a par with most cited 
users, I am surely a Lua evangelist :-) I even managed to use it at work, 
but that's the matter for another message.
BTW, I would like a 'e' at the end of my last name, thanks :-) I am not 
lost. ;-)

While I am on the subject of doc. glitches, I have a number of them to 
report. Some typos, most of them probably already corrected, but you never 
now... Some points that seems obscure to me, but you may disagree here.
I am aware the doc. is in alpha stage, of course, with many '???' sections, 
I just ignored these. Page numbers are from the PostScript file.

Page 23, you list a lua_isdataval function, but you don't explain its 
purpose, it doesn't seems to have a LUA_Txxx constant, or is it 
LUA_TLIGHTUSERDATA? If so, I suggest a name change of the function, for 
consistency, at least with the lua_pushlightuserdata function.

Page 34, you mention various lua_xxxlibopen functions. You forgot 
lua_dblibopen, and perhaps you should mention that lua_iolibopen is also 
managing the "operating system facilities" mentioned above.

Page 37, pcall: "Calls function func with the given arguments in protected 
mode." You should explain more what is this protected mode. It is explained 
earlier in the doc., but in the API section, which might be skipped by 
script writers.
script if an error is met, but instead returns the error message. Am I 
right?

Page 40, gfind isn't explained, but I already indicated it.

Page 44, perhaps you should indicate that trigonometric functions work with 
radian angles. The 4.0 documentation was stating the opposite, but I believe 
you changed your mind, so you should state it clearly. Again a reference to 
the C library...

Page 46, fh:close([handle]) You don't explain what is this handle... I 
understand that underlaying, it is the same function as io.close, but if it 
serves no purpose, perhaps you should omit this handle...

Page 49, debug.sethook "The string mask may have the following characteres" 
Perhaps "characters"?

Maybe it is just me, but I had some hard time figuring out the page 50. I 
think replacing "program" by "script" would help, but again, I may be the 
only one confused.

That's all for now, not bad for an alpha documentation :-)

-- 
--=#=--=#=--=#=--=#=--=#=--=#=--=#=--=#=--=#=--
Philippe Lhoste (Paris -- France)
Professional programmer and amateur artist
http://jove.prohosting.com/~philho/