Lua 5.1 (alpha): Documentation "bug" and suggestions

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

5.4 String Manipulation

look for: string.gsub

after the gsub examples follow string.len, string.lower, etc and after some
more functions the gsub Patterns are explained which actually belong to
string.gsub

--------------------------------------------------------------------------

And some general tips on making the manual more (immediately) usable: 

I would like to see all the functions updated to also show the return
values. You always have to pick them out of the description text that
follows (if there is any hint, for example, getfenv doesn't explicitly
mention that it returns a table).

It would be more convenient if it were more like this:

copy, numSubst = string.gsub (s, pat, repl [, n])
success, [msg/arg1, arg2, ...] = pcall (f, arg1, arg2, ...)

--------------------------------------------------------------------------

Also, i personally feel that it is often confusing not to know what type of
value we're dealing with here. I wonder if this never occured to anyone
before because almost all scripts i look at don't follow any variable naming
convention at all. A variable "index" could be an integer, a string, or even
a table. This isn't clear without looking at the context, and that makes
reading (especially complex) scripts harder than it need be.

I've come up with a simple scheme for naming my variables which i've sticked
to for like 50.000 lines of Lua code:

nNumber = 123
	iInteger = 123 or rReal = 1.23 to differentiate where needed
sString = "a string"
bBoolean = true
tTable = {}
uUserdata = <someuserdata>
fFunction = function f() end
cCoroutine = co
hThread = <thread>
xUnknown (for values whose type is determined at runtime, eg a table index
can be both a string and an integer when walking through table elements)

An additional prefix "g" to mark global variables (visible even across
files). So that would make: gnGlobalNumber etc.
I have made some more rules for my "Lua styleguide" but these are the most
essential ones.

Personally, i feel that would make the documentation more readable if there
were some widely accepted naming convention for all types of Lua values. It
definetely makes scripts more readable. This has been known for decades, or
am i wrong? ;)

Giving variables reasonable names (and prefixed) seems to be neglected far
too often in the Lua community, if i may say so. I often find it hard to
read scripts as i have to keep in mind one extra information about each
variable: it's type. If i can't remember, I'll have to go back and scan
through the relevant parts again, eg looking up the type of value a function
returns. And then back again to where i was. ... Where was I? <sigh>

Sure, it's quicker to write everything in lowercase letters and stick to
variable names with at max 6 chars. Sure, it's hard to stick or even get
used to naming conventions when many Lua scripts are at most 200 lines. Yes,
i *felt* that, too. But it would still make it easier to understand the
scripts, even for the scripter (my personal experience tells me so). 

I've gotten myself this far that it actually *hurts* me to quote anyone's
code and *not* fix it up with my variable prefixes but leave it as is, with
their "subst" and "index" and "roles" and "connServ" and "myFunc" and "arg"
and "wresist" and "check" and "sock" and "whatnot". ;)

So, i don't want to hurt myself anymore: "sSubstitute" and "iIndex" and
"tRoles" and "cConnectServer" and "fMyFunc" and "xArg" and "nWindResistance"
and "bChecked" and "uSocket" and "bWhatNot". ;)

I must add: i'm also a writer, so the spelled out names come more natural to
me in both writing and reading than any clever abbreviation to save a
character here and there. I fear more to break my tongue while reading (if
only in my mind) names like "dbg" or "fnc" or "src" (spell it out, please,
DO IT ONCE!) than typing 2 or 3 extra letters on my keyboard. And it's
actually good training to learn to type faster while making less typo's.

I only use abbreviations in names that are used hundreds or a thousand
times, like a "con" table containing often used "console window" functions.

Ok, so i got carried away .... please don't hurt me, please don't! *G*


steffenj