[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Comments on the 4.1-alpha manual
- From: Tom Wrensch <twrensch@...>
- Date: Wed, 1 Aug 2001 09:52:41 -0700 (PDT)
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
> 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