AW: Lua 5.1 (alpha): Documentation

["steffenj" <steffenj@...>]

>what happens when you decide that a byte (bByte) today becomes an integer
>(iInteger) or a double (rReal).

what "happens" is that i do a "replace" or "replace in files" ... ;)

and well, it doesn't happen very often when you think about what you're
trying to do before actually coding it
from my experience that happens maybe once in 10.000 lines of code

but don't get me wrong, i'm more than glad that MS abandoned hungarian
notation, it's a bloated beast IMHO ... a good idea that went waaaaay too
far... C#/.NET code is much more readable than MFC code

but let's forget about hungarian notation, what i suggested is merely the
least common denominator adapted to Lua types


>He explained very carefully exactly what he meant by the word "type," but
>it didn't help. The damage was done...

Yep. I say: "prefix values with a single lowercase character to signal their
type". And i get "hungarian notation" in my face. I was like "Woaaah - don't
go there, don't even THINK about it!". :)


>You should not hesitate to xlat the docs to hungarian.

Maybe i will, and add some...
Ever since i've come across lua, i was constantly dissatisfied with the
manual because it's more like a programmer's technical reference than a real
"manual" as i understand the term. The target audience may be mostly
programmers (really?) but with Lua's popularity even among non-programmers
it may be time for a manual that is more suitable to beginners or simply
"inexperienced" lua users. I suggest a split between "manual" and "language
reference" should at least be considered.

What i'm personally missing most in the manual are more extensive and/or
readable examples. Here and there a few more words to explain all the
details, and maybe add some more explanations of the basics. A couple tips &
tricks as well, like how you can trash the garbage collector with string
concatenations and other common traps found only deep inside the Wiki.
Things that you will run into sooner or later and make yourself wonder why
some code is suddenly broken or slow.

Roberto's book helps but it still reads more like the manual with extra
information spread throughout. The Wiki is nice to have but you're always
unsure wether the information is up to date and mostly it's hard to find
what you are looking for. And still hard to find it again at a later time.

The LuaForge pages (eg LuaInterface, LuaSQL and compat5.1) also leave you
with a feeling as if everyone assumes that you will look at the sources
anyway and find things out yourself. The bits that are available help you
get started but leave you suffering for details. Like a function reference
for LuaInterface. Even considering a technically experienced audience for
these tools, the documentation could still be improved quite a lot if it
were written with the user in mind.

Tell me, am i expecting too much from these manuals? I mean there's a lot of
people working hard on Lua and the related tools and i respect that. Even
more so that everything is for free, which is a blessing. And i know how
hard it is to write good technical information about something you know
inside out.


steffenj