Re: Wikipedia Chooses Lua As Its New Template Language

[Alexander Gladysh <agladysh@...>]

On Tue, Feb 7, 2012 at 06:51, Tim Starling <tstarling@wikimedia.org> wrote:
> On 07/02/12 07:06, Roberto Ierusalimschy wrote:

>> ((About the manual, a simple search for both "math.log10" and "table.maxn"
>> will find references to them, explaining that they are deprecated.)
>
> Yes, but that won't tell you what they do or what their parameters
> are, or what "deprecated" means or what compatability flags need to be
> defined for them to be enabled.
>
> You could find out some of these things by reading the 5.1 manual. My
> concern is just that the 5.2 manual is not as convenient and useful as
> it could be, for users who don't know what Lua version they are using,
> or for users who are in the process of migrating code from 5.1 to 5.2.

FWIW, I, personally, believe Lua manual for the current version MUST
NOT advertise deprecated features in any way. Otherwise these features
would not die. And they MUST die — otherwise they would not be
deprecated.

Manual is for the people new to Lua as well. And new people are the
most prone to using whatever fits — they have no gut feeling for what
is right yet. Thus, they are to be protected from mistakingly using
deprecated stuff. (I work with people new to Lua quite a lot, and I
speak from personal experience.)

If people do not know what version of Lua they are using, well, I'm
not sure that they may be helped by introducing documentation for
deprecated features. Furthermore, I would say that listing these
features as deprecated in the current version should work quite well
as a hint that they need some other manual. But maybe adding a link to
"manuals for other Lua versions" page at the top of both
http://www.lua.org/manual/5.2/contents.html and
http://www.lua.org/manual/5.2/manual.html would do some good in that
matter.

As for people who do migration — they need a migration guide, not the manual.

My 2c.

Alexander.