Re: Documentation (was Re: PIL 4 Just Arrived!!!)

[nobody <nobody+lua-list@...>]

> I think there is a legacy effect. Lua was originally presented as a C
> library with a scripting language interface. Gradually, through years
> of drift, Lua is for most people a standalone scripting language.

That's (still) one of the strong points of Lua: It's a language as a
library, not some framework-like closed-off world.  Few languages offer
anything like that.

> Maybe it is time that the C API documentaion is relegated to after 
> that of the standard libraries if not branded "Appendix".

I (partially) disagree, but I do think some (small) improvements should
be made:  Right now, there's stuff relevant to lua-only users that's
hidden in the C API part of the refman, which most of them tend to skip.
This should be moved out of there (or at least referenced from the
relevant places).

Some examples:

 *  lua_resume explicitly states that the stack is not unwound,
    coroutine.resume doesn't.

 *  xpcall changes a "message handler" which is a C-level Lua concept,
    and that this handler is not called for memory allocation errors is
    only stated under lua_pcall.  Which means you should really use it
    just for getting tracebacks, not for handling arbitrary error
    conditions (as "message handler" might suggest).

And I think there were some other things that I can't recall right
now... and __name maybe should be mentioned elsewhere, too. (Or not?)

Another thing that might be surprising for non-C-users is that the
refman states something like "Lua handles embedded zeros in strings" but
does not say that parts of the standard library don't.  (Mostly the
stuff passed through from the OS (which is entirely expected if you know
C) but also error and assert, which could surprise you by cutting off
error messages if you try include offending values in them.)  There's
also the case where `("%s"):format"foo\0bar" == "foo"` even though the
string for '%s' only "should not include \0s if there are formatting
modifiers" or something like that...

(In the other direction, I'd love to see the C API part subsectioned
similar to the description of the standard libraries.  At present, lua.h
is more clearly arranged than the refman...)

-- Marco