Re: 5.2-beta changes as an annotated reference manual

[Peter Cawley <lua@...>]

On Sat, Jun 25, 2011 at 4:38 PM, Peter Cawley <lua@corsix.org> wrote:
> Last May, I did a mechanical diff of 5.1.4 and 5.2-work3, and wrote up
> the changes [1]. As an experiment in different ways of presenting
> changes, I've just done a manual diff of the 5.1.4 and 5.2-beta-rc2
> reference manuals, and annotated the latter with the changes. The
> resulting document is:
>
> http://www.corsix.org/lua/5.2-beta-annotated/manual.html
>
> In doing so, I noted the following list of possible issues in the
> 5.2-beta-rc2 reference manual:
>
> 2.1 says "The expressions a[i] and a[j] denote the same table element
> if and only if i == j." -- should this make some reference to raw
> equality (as == can be overridden)?
> 2.3 says "before the error unwonds the stack" -- should this be unwinds?
> 2.5.1 says "after a userdata is marked, you can freely change the __gc
> field of its metatable" -- is the same not true of tables?
> 4.8 For alternations in their APII's, lua_getmetatable and lua_next
> use vertical bar, whereas lua_arith uses a slash.
> 4.8 The function lua_getuservalue is where lua_getfenv used to be,
> rather than being in the correct alphabetical order, likewise for
> lua_setuservalue.
> 4.8 The final paragraph for lua_newuserdata uses the term "marks" with
> a different meaning to the "marking" previously used when explaining
> __gc. The wording might also want to be slightly more careful about
> stating when a __gc metamethod can be called.
> 4.8 Should the return value of ua_pushliteral be changed to const char*?
> 4.9 The 'u' option to lua_getinfo doesn't mention isvararg or nparams.
> 4.9 Should lua_getstack say the same things about tail calls that
> debug.getinfo does?
> 4.9 There are brackets around the name of lua_upvalueid, and no other
> functions have such brackets.
> 5.1 luaL_checkversion seems to indicate a return type of void* rather than void.
> 5.1 luaL_fileresult uses a slash for its alternation, whereas
> luaL_getmetafield uses a vertical bar.
> 6.8 Should io.lines have a comma before the ellipses?
> 6.10 The function debug.getuservalue is where debug.getfenv used to
> be, rather than being in the correct alphabetical order, likewise for
> debug.setuservalue.
>
> [1] http://www.corsix.org/content/look-lua-52-work3
>

I've updated my annotated copy to rc5. I've also noticed one more
instance of inconsistent formatting: os.execute uses <code> around its
string argument possibilities, but other functions like file:setvbuf
and file:seek do not.