[q2x] OT: Lua questions

[Brian Hook]

> :) I suppose they are a bit dated now, but they do give an idea of
> what Lua is about. Really, one should be written about Lua 5. 

The language has changed enough that a lot of the interesting papers, 
notes, etc. are either misleading or just incorrect.

> Brian, noone would call you a dumbass to your face ;-D. 

Right, to my face =)

> I guess it's just a reference to me. I don't really go to the
> reference manual to learn much stuff. One of the reasons that
> motivated me to do the tutorial was to silence constant repetitive
> questions on lua-l.

Right-o, the kinds of questions I think I have asked =)

> It's really very stable, and since 5 you can do all your
> customisation with the vanilla build.

One thing I'd like to see is an op-code limiter so that you can avoid 
runaway/frozen scripts.  I'd retrofit that, but the code is bad enough 
that I don't feel like looking at it that closely =)

> Thanks very much. It's been quite an enjoyable learning experience
> doing it. I'd have thought more people might have put an oar in. I
> don't know if they feel intimidated because they feel like it's "my
> property". I certainly don't want people going in wholesale and
> rewriting it, but a few more contribs would have been nice. Perhaps
> its because wiki is a new concept to them.

Wiki is definitely a new thing for a lot of people, but you should 
probably go ahead and ask people for contribs?

> So here's a question, because I'm not 100% myself: how should the C
> API docs be presented? I was thinking of a section introducing
> binding, because I think it's an alien concept to most programmers
> coming into scripting. Then, how to set up a Lua environment,
> insert variables, pushing and pulling data, etc. And, possibly
> section on different strategies for embedding and building a
> project.

I'm a big believer in incremental learning.  Psychological studies 
have shown that humans don't like rote memorization, and they also 
have a hard time learning lots of things at once without context.

If I were structuring a tutorial, I would do it in a lot of small 
steps.  I'd also not use that interactive environment, since it 
obfuscates the code IMO.

So, for a C API:

Tutorial 1: What is binding, with an example
Tutorial 2: Lua calling C, example w/o args or return values
Tutorial 3: Lua calling C, w/ argos, no return values
Tutorial 4: Lua calling C, w/ args, w/ return values
Tutorial 5: C calling Lua, w/o args or return values
etc. etc.

Small snippets explaining exactly where everything is.  One of the 
hardest concepts to grasp is stack entry placement.  If people would 
just put freakin' comments whenever they access the stack so we have 
an idea of what the stack is supposed to look like at a given point, 
that would be awesome.

Okay, an example of crappy docs: the C API example in the reference 
manual.  They choose a completely contrived, overly complex example, 
such that you have no idea what's going on.  If they just used several 
smaller examples, I think a lot of people would "get it".

Brian