Re: What manuals should and should not say

[Sean Conner <sean@...>]

It was thus said that the Great Paul Merrell once stated:
> 
> PIL is not a book for novices. They lack the vocabulary to understand
> it or the manual. As an example, take a look at this excerpt from the
> v. 5.3 Reference Manual:
> 
> >>>
> The following strings denote other tokens:
> 
>      +     -     *     /     %     ^     #
>      &     ~     |     <<    >>    //
>      ==    ~=    <=    >=    <     >     =
>      (     )     {     }     [     ]     ::
>      ;     :     ,     .     ..    ...
> 
> <<<
> 
> That's the entire explanation of those tokens. I'm 3 or 4 years into
> working with Lua and I still haven't the slightest glimmer what the
> ellipsis is for. And unless I've missed it, that explanation is also
> missing from PIL.

  While the manual might be better off with an index or something at the end
that links to the definition of each function and operator, the information
*is* in the manual.  The token '..' is described in section 2.4 as the
concat operator.  The token '...' is described in section 3.4 as the
variable argument list (and are further described in section 3.4.11).

> The Manual and PIL are riddled with terms that are basically
> meaningless to a novice. With some terms, one can get a glimmer
> courtesy of Google, but most often you get their meaning in other
> programming languages and have to hope that the meaning is similar in
> Lua.

  Could you give a few examples?  A glossary might be nice to add as well to
the manual.

  -spc