lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

On Feb 2, 2012, at 12:45 PM, David Favro wrote:

> On 02/02/2012 10:10 AM, Jay Carlson wrote:
>>> - It's really difficult to find good tutorials or examples for LUA.
>> If you have not read it already, ISBN 8590379825. In my opinion, the
>> best-written "here's my language" book since K&R.[2]
> Yet, append to the original complaint, "... available for free on the
> internet" and you are left with very little.  Someone who is dabbling,
> trying out several different languages, is not likely to want to buy a book
> just to get the basics of the language before deciding whether to get in
> deeper.  

Well, we certainly survived without it before Lua 5.0, for some definition of "we" and "survive".

SGML and the OSI network stack died by a) being broken things you had to *pay* people to work on, and b) having very high starting friction for getting involved. This is a cycle; when intellectually curious people bounce off the door to your project, you often end up with more brokenness because they're the ones who see things with outsider eyes, and they're also the kinds of people most likely to help fix problems. OK, some standards groups are just broken anyway (53!?) but the better ones tended to leave their last release-candidate document somewhere on the net.

One of the pragmatic arguments for Open Source software is that you do not need to purchase and track licenses. A $1/seat license costs much more than that to administer, and running out of seats or fighting with some license management software can idle many people. But even a site license is a pain; the cost could be a penny, and it would still be a barrier to adoption. (Apple, and Google are making a lot of money by reducing that pain, at least for individuals.)

> Lua's reference manual is minimalist to the point of being spartan -- I like
> a minimalist reference manual so I can get just what I need without a lot of
> fluff, but this one lacks even such 'redundancies' as return-value
> documentation for functions in the IO library, relying instead on an 'unless
> otherwise stated' coda in the introduction to the library, the existence of
> which someone who went straight to function entry would not know.  

I've been screwed by this several times, although I can't remember exactly how or when. I think there are a number of places where adding internal hypertext links between sections would have helped--there's a lot of bouncing between top and bottom. Reading and understanding the document at leisure seems to be the expected use. A lot of the time I'm digging in the manual because I don't remember the arguments for some function, and I don't remember things like that tonumber() will mutate the stack slot. (Actually I remember that particular case ALL THE TIME now...)

One thing that would have helped me was "Many functions on failure return nil followed by a description of the error; this allows the idiom

   v = assert(f(x))

to either take a successful value of f, or for f's error message to be printed as part of the assertion."

I'm no dummy, but it took me forever to notice this. Much of the power of Lua is in how its pieces fit together (JavaScript's pieces don't) but authorial intent is very thin in the reference manual. 

I think this problem has become more prominent after 4.0; in 5.0 you have to put together a lot of puzzle pieces to figure out how to intercept all reads and writes to a table, to use my favorite example. This is not a criticism of clean and orthogonal design--fewer mechanisms are better--but it almost feels like some of the combinations then ought to be documented.

*One* library with an examples directory would perhaps do this, but to my taste most of the stdlibs have been too big and/or constraining. I dunno, maybe exactly what I want is out there, but there's no mechanism for consensus-forming, and upstream (hi!) does not seem to be interested in any "not Lua, but what we like to do" collection along side. Does lposix come with an endorsement?[1]

IMO there is not much leadership or even mechanisms for indicating consensus for libraries (and language), and this is a big problem for a battery-less language. Mike Pall is in the fascinating situation of being able to say "5.2 is useless for me and my users" and have a significant part of the user base follow--this is novel in the taciturn Lua language design milieu.

> There's a
> real need for an _annotated_ reference manual, which briefly explains the
> real-world implications of the terse statements of syntactic grammar and raw
> semantic value.

Volunteers? Note you can fork the manual (like luai). There's no reason it can't be mechanically transformed into wiki pages. I think a sputnik host would be better, but I'm not sure if it would attract attention and long-term maintenance.

If you want an ego-driven goal, the annotated manual should end up #1 or #2 in search results. Done right, it is more useful, and search engines do notice this.

Putting third-party changebars with links alongside PiL 5.0 is technically and legally feasible, but I don't think you'll get many takers.

For libraries, I'd love a way for people to be able to signal approval of parts ("I use this part of Penlight whenever I want to do X") by signing their names; not a democracy, but a better way of doing it than spamming some mailing list with WANT and DO NOT WANT.


[1]: Kepler seemed like it had a partial, implicit endorsement, despite the disclaimers. There was a lot of half-baked stuff in early kepler, but you've seen my code, a lot of it isn't baked either. But it rarely if ever looks like it's marked or destined to be canonical.