Improvements in the manual

Several small improvements, in particular a new subsection consolidating
all status codes in the API.

1 files changed, 64 insertions, 46 deletions

diff --git a/manual/manual.of b/manual/manual.of
index d5b4a572..3ba82b09 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -96,6 +96,14 @@ is particularly attractive
 for small machines and embedded systems.
 (See macro @id{LUA_32BITS} in file @id{luaconf.h}.)
 
+Unless stated otherwise,
+any overflow when manipulating integer values @def{wrap around},
+according to the usual rules of two-complement arithmetic.
+(In other words,
+the actual result is the unique representable integer
+that is equal modulo @M{2@sp{n}} to the mathematical result,
+where @M{n} is the number of bits of the integer type.)
+
 Lua has explicit rules about when each subtype is used,
 but it also converts between them automatically as needed @see{coercion}.
 Therefore,
@@ -1098,8 +1106,11 @@ if its value fits in an integer or it is a hexadecimal constant,
 it denotes an integer;
 otherwise (that is, a decimal integer numeral that overflows),
 it denotes a float.
-(Hexadecimal integer numerals that overflow @emph{wrap around};
-they always denote an integer value.)
+Hexadecimal numerals with neither a radix point nor an exponent
+always denote an integer value;
+if the value overflows, it @emph{wraps around}
+to fit into a valid integer.
+
 Examples of valid integer constants are
 @verbatim{
 3   345   0xff   0xBEBADA
@@ -1712,12 +1723,7 @@ Modulo is defined as the remainder of a division
 that rounds the quotient towards minus infinity (floor division).
 
 In case of overflows in integer arithmetic,
-all operations @emphx{wrap around},
-according to the usual rules of two-complement arithmetic.
-(In other words,
-they return the unique representable integer
-that is equal modulo @M{2@sp{n}} to the mathematical result,
-where @M{n} is the number of bits of the integer type.)
+all operations @emphx{wrap around}.
 }
 
 @sect3{bitwise| @title{Bitwise Operators}
@@ -2364,9 +2370,8 @@ and
 (that is, the element at @N{the top})
 and index @M{-n} represents the first element.
 
-}
 
-@sect2{stacksize| @title{Stack Size}
+@sect3{stacksize| @title{Stack Size}
 
 When you interact with the Lua API,
 you are responsible for ensuring consistency.
@@ -2391,7 +2396,7 @@ you should use @Lid{lua_checkstack}.
 
 }
 
-@sect2{@title{Valid and Acceptable Indices}
+@sect3{@title{Valid and Acceptable Indices}
 
 Any function in the API that receives stack indices
 works only with @emphx{valid indices} or @emphx{acceptable indices}.
@@ -2433,6 +2438,8 @@ which behaves like a nil value.
 
 }
 
+}
+
 @sect2{c-closure| @title{C Closures}
 
 When a @N{C function} is created,
@@ -2552,6 +2559,33 @@ However, there is no guarantee about stack space.
 To push anything on the stack,
 the panic function must first check the available space @see{stacksize}.
 
+
+@sect3{statuscodes|@title{Status Codes}
+
+Several functions that report errors in the API use the following
+status codes to indicate different kinds of errors or other conditions:
+@description{
+
+@item{@defid{LUA_OK} (0)| no errors.}
+
+@item{@defid{LUA_ERRRUN}| a runtime error.}
+
+@item{@defid{LUA_ERRMEM}|
+@x{memory allocation error}.
+For such errors, Lua does not call the @x{message handler}.
+}
+
+@item{@defid{LUA_ERRERR}| error while running the @x{message handler}.}
+
+@item{@defid{LUA_ERRSYNTAX}| syntax error during precompilation.}
+
+@item{@defid{LUA_YIELD}| the thread (coroutine) yields.}
+
+}
+These constants are defined in the header file @id{lua.h}.
+
+}
+
 }
 
 @sect2{continuations|@title{Handling Yields in C}
@@ -3407,19 +3441,6 @@ If there are no errors,
 function on top of the stack.
 Otherwise, it pushes an error message.
 
-The return values of @id{lua_load} are:
-@description{
-
-@item{@Lid{LUA_OK}| no errors;}
-
-@item{@defid{LUA_ERRSYNTAX}|
-syntax error during precompilation;}
-
-@item{@Lid{LUA_ERRMEM}|
-@x{memory allocation (out-of-memory) error};}
-
-}
-
 The @id{lua_load} function uses a user-supplied @id{reader} function
 to read the chunk @seeC{lua_Reader}.
 The @id{data} argument is an opaque value passed to the reader function.
@@ -3437,6 +3458,11 @@ a @id{NULL} value is equivalent to the string @St{bt}.
 so the reader function must always leave the stack
 unmodified when returning.
 
+@id{lua_load} can return
+@Lid{LUA_OK}, @Lid{LUA_ERRSYNTAX}, or @Lid{LUA_ERRMEM}.
+The function may also return other values corresponding to
+errors raised by the read function @see{statuscodes}.
+
 If the resulting function has upvalues,
 its first upvalue is set to the value of the @x{global environment}
 stored at index @id{LUA_RIDX_GLOBALS} in the registry @see{registry}.
@@ -3590,25 +3616,8 @@ information to the error object, such as a stack traceback.
 Such information cannot be gathered after the return of @Lid{lua_pcall},
 since by then the stack has unwound.
 
-The @Lid{lua_pcall} function returns one of the following constants
-(defined in @id{lua.h}):
-@description{
-
-@item{@defid{LUA_OK} (0)|
-success.}
-
-@item{@defid{LUA_ERRRUN}|
-a runtime error.
-}
-
-@item{@defid{LUA_ERRMEM}|
-@x{memory allocation error}.
-For such errors, Lua does not call the @x{message handler}.
-}
-
-@item{@defid{LUA_ERRERR}|
-error while running the @x{message handler}.
-}
+The @Lid{lua_pcall} function returns one of the following status codes:
+@Lid{LUA_OK}, @Lid{LUA_ERRRUN}, @Lid{LUA_ERRMEM}, or @Lid{LUA_ERRERR}.
 
 }
 
@@ -3624,7 +3633,7 @@ int lua_pcallk (lua_State *L,
 @apii{nargs + 1,nresults|1,-}
 
 This function behaves exactly like @Lid{lua_pcall},
-but allows the called function to yield @see{continuations}.
+except that it allows the called function to yield @see{continuations}.
 
 }
 
@@ -4002,7 +4011,7 @@ or returned by the body function.
 @Lid{LUA_YIELD} if the coroutine yields,
 @Lid{LUA_OK} if the coroutine finishes its execution
 without errors,
-or an error code in case of errors @seeC{lua_pcall}.
+or an error code in case of errors @see{statuscodes}.
 In case of errors,
 the error object is on the top of the stack.
 
@@ -4153,7 +4162,7 @@ Returns the status of the thread @id{L}.
 The status can be @Lid{LUA_OK} for a normal thread,
 an error code if the thread finished the execution
 of a @Lid{lua_resume} with an error,
-or @defid{LUA_YIELD} if the thread is suspended.
+or @Lid{LUA_YIELD} if the thread is suspended.
 
 You can call functions only in threads with status @Lid{LUA_OK}.
 You can resume threads with status @Lid{LUA_OK}
@@ -6263,6 +6272,7 @@ which is true if the call succeeds without errors.
 In such case, @id{pcall} also returns all results from the call,
 after this first result.
 In case of any error, @id{pcall} returns @false plus the error object.
+Note that errors caught by @id{pcall} do not call a message handler.
 
 }
 
@@ -8950,6 +8960,14 @@ not a float.
 }
 
 @item{
+Literal decimal integer constants that overflow are read as floats,
+instead of wrapping around.
+You can use hexadecimal notation for such constants if you
+want the old bevhavior
+(reading them as integers with wrap around).
+}
+
+@item{
 The use of the @idx{__lt} metamethod to emulate @id{__le}
 has been removed.
 When needed, this metamethod must be explicitly defined.