Re: Comments on the 4.1-alpha manual

[Tom Wrensch <twrensch@...>]

On 1 Aug 2001, John D. Ramsdell wrote:

> 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 have also been considering suggesting breaking up the manual for just
this reason.

> 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.

My suggestion is similar, but somewhat simpler. I suggest  breaking it
into two manuals. One which is a definition of Lua, including the standard
libraries. The second would describe the C API and such.


> 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.

My reasons are somewhat different. There are (very roughly) two kinds of
Lua users: those who are embedding the language in something or otherwise
working with and extending the C implementation in some way, and those who
are using the language itself either as a stand-alone.  Those who are
writing just Lua code don't need or necessarily want to know about the
C-implementation interface. If nothing else it might save a few trees when
those of us who like paper versions print out the manual.

 
> 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.   <..snip..>

This brings up a good point I had not considered. Separating into two (or
more) manuals would help improve the seperation  between the language and
its C implementation. Even if no non-C versions are ever created I feel
that the disciplin this sepration would encourage would be helpful.

  - Tom Wrensch