[q2x] OT: Lua questions

[Nick Trout]

> > Have you read the papers on Lua?
> 
> Which ones, the 7 year old DDJ papers?  Or the four year old random
> symposium presentations? =P

:) 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. There have been
a significant number of changes and Lua is now regarded as a standalone
language, which I don't think it was back then.

> I'm not saying they are obligated to provide documentation, but
> adoption right now is at a much lower rate than it would be simply
> because all help has to be done through lua-l.

I guess they are a little understaffed for full docs. I don't know how
much English being their second language affects this (excellent as
their English is). It may just be time. The few pages I have done took
ages. Docs do seem like a luxury on a lot of projects, although I agree
with you about their usefulness.

> And the problem with that is that lua-l is now mostly experts like
> you, Thatcher, etc. and so when I get on there, I feel like a fucking
> dumbass asking questions.

Brian, noone would call you a dumbass to your face ;-D. And anyway you
could wipe the floor with me with graphics and networking knowledge! I
feel the same way on gdalgorithms :). 

> > The docs for Lua are very concise and excellent.
> 
> haha.  "Concise", is that we call it now? =)

Terse then :)
 
> The reference manual is woefully lacking in documentation on even the
> most basic aspects of stuff.  It took me forever how to do table
> iteration, and most of it was just guessing on my part because huge
> gaps are there.

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.
Newbie questions do seem to have died down so maybe the tutorial has had
an effect. The lua-users project does seem to get a significant number
of hits, I don't know if the wiki is included in this.

> > excellent work. One of the first things I look for in a software
> > project is decent documentation also.
> 
> To me it ALL starts with the documentation, because that shows me how
> interested the developers are in getting other people on board.  I've
> seen open source projects that effectively just say "read the headers,
> if you're good, you'll figure it out".  And they can kiss my ass =)

:D he he.

Yep, assume makes an ass of you and me.

> The complete lack of comments in the Lua source code sure as shit
> doesn't help their cause much either.

It is a bit cryptic I must admit. The main saving grace is there isn't
that much of it! One of the reasons that I have stuck with Lua is the
infrequency with which I have had to look at the source. It's really
very stable, and since 5 you can do all your customisation with the
vanilla build.

> > AFAIK my wiki docs are the
> > most complete syntax introduction.
> 
> Yes, they are, and you've done a great job, but I feel bad that the
> onus has fallen on you for this.  can you imagine what the situation
> would be like if you weren't doing that?

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.

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.

Nick