Comments on the 4.1-alpha manual

[ramsdell@... (John D. Ramsdell)]

I read the 4.1 manual and would like to suggest that it be
reorganized.  The reason I would like to see it reorganized is that I
think the manual currently serves two purposes, and the two are
intermingled in a confusing way.  The manual is both a specification
of the Lua language and its standard library, and a description of a
specific implementation of the language that interfaces with and was
written in C.  I suggest that the manual be divided into three parts
that are mostly self contained.  Part 1 should be the language
definition, Part 2 should be a description of the standard library,
and Part 3 should be a description of the ANSI C implementation along
with its interface to C programs.  The documentation associated with a
conforming Java implementation of Lua should only be required to
replace Part 3, as the other two parts of the manual should be
accurate for Java.

Implementing the reorganization requires more work that simply moving
text within the document.  It requires changing text so that one knows
whether statements refer to the language definition or a specific
implementation.  For example, the lead sentence in Section 4, page 3
on garbage collection states:

   Lua does automatic memory management.

Does this mean that only the ANSI C version does garbage collection or
can a programmer assume that every conforming Lua implementation will
provide garbage collection.  The section on garbage collection also
describes two numbers that control garbage collection.  Does this mean
that every conforming Lua implementation will control garbage
collection the same way?  What about a Java implementation?

OTHER COMMENTS

(1) page 5, line -3:  The BNF for a var that is a table reference is
wrong.

   var -> exp '[' exp ']'

Does not agree with the specification in the end of the document.

(2) Document needs to be spell checked.

John