Re: Lua short reference part 1 - draft 1

[Philippe Lhoste <PhiLho@...>]

> Here is the first draft of my "Lua short reference", part 1 (language and
> libraries - part 2 will cover the C API):
>
> http://www.erix.it/shortref-d1.pdf
>
> It is undoubtedly full of the most horrible mistakes and omissions, so
> feedback at any level is greatly appreciated.
>
> Please do not distribute this draft version.
>
>   Enrico

I first couldn't be able to download it, but since Virgil's message, I 
could.
It looks very nice and complete.

Notes:

"escape sequences are not interpreted between [[ ]]" .. "but newlines 
are allowed."

In t = {x=5, y=10; "yes", "no"}
the semi-colon is no longer required in Lua 5.0, but of course is still 
valid.
Perhaps you should mention ';' and ',' are equivalent.

"function ( ... ) body [return values] end": it is not obvious that 
ellipsis can go after an actual list of parameters.

"Object function getting extra arg self": you should find a way to 
mention that self is the first argument, ie. equivalent to "obj.name = 
function(self, ...) ... end"

Strictly speaking, you mention '..' operator several times before 
explaining its function.

tonumber: "Converts string x to a number in base b": I would rather 
write something like "Convert string x representing a number in base b 
to a decimal number" or something shorter :-)

GC: I don't know what KiB are... You should write KB, or Kbytes as in 
the manual.

I don't like much the notation "print ([, values])", it may be 
ambiguous, perhaps use "print(val[, val...])", or "print(args)" like you 
do elsewhere.

I am not sure to understand what "normalized fraction" (math.frexp and 
math.ldexp) is, but that's not your fault :-)

Typo: "(index -1 refers to the last charactr)." in note about string 
indexes.

Some of my remarks are irrelevant if you are not looking for 
exhaustivity, but I believe the more infos you put, the better.

I like that you details stuff that Lua team didn't mention explicitely 
because it is part of the C library... (math library, format patterns...)

I don't see why you mention two times io.stdxxx (in Complete I/O and 
Simple I/O).

io.input: "in the latter case the file is opened for reading" .. " in 
text mode". Same of io.output.


It looks like a lot of criticism, but that's just to help you improve 
your excellent reference. Obviously you put a lot of work in it, and it 
will be a valuable document to keep next to the keyboard when 
programming Lua.

Thank you for your efforts.

--
--=#=--=#=--=#=--=#=--=#=--=#=--=#=--=#=--=#=--
Philippe Lhoste (Paris -- France)
Professional programmer and amateur artist
http://jove.prohosting.com/~philho/ (outdated)
http://philho.multimania.com (in French, for files to download)
--=#=--=#=--=#=--=#=--=#=--=#=--=#=--=#=--=#=--