Merge remote-tracking branch 'upstream/master' into usermarksusermarks

1 files changed, 397 insertions, 467 deletions

diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index 9dbd2d4de5..aafdd5c43e 100644
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@@ -20,76 +20,10 @@
                  See |luaref-copyright| for copyright and licenses.
 
 
-                                   CONTENTS
-                                 ============
-
-           1   INTRODUCTION........................|luaref-intro|
-
-           2   THE LANGUAGE........................|luaref-language|
-           2.1   Lexical Conventions...............|luaref-langLexConv|
-           2.2   Values and Types..................|luaref-langValTypes|
-           2.2.1   Coercion........................|luaref-langCoercion|
-           2.3   Variables.........................|luaref-langVariables|
-           2.4   Statements........................|luaref-langStats|
-           2.4.1   Chunks..........................|luaref-langChunks|
-           2.4.2   Blocks..........................|luaref-langBlocks|
-           2.4.3   Assignment......................|luaref-langAssign|
-           2.4.4   Control Structures..............|luaref-langContStructs|
-           2.4.5   For Statement...................|luaref-langForStat|
-           2.4.6   Function Calls as Statements....|luaref-langFuncStat|
-           2.4.7   Local Declarations..............|luaref-langLocalDec|
-           2.5   Expressions.......................|luaref-langExpressions|
-           2.5.1   Arithmetic Operators............|luaref-langArithOp|
-           2.5.2   Relational Operators............|luaref-langRelOp|
-           2.5.3   Logical Operators...............|luaref-langLogOp|
-           2.5.4   Concatenation...................|luaref-langConcat|
-           2.5.5   The Length Operator.............|luaref-langLength|
-           2.5.6   Precedence......................|luaref-langPrec|
-           2.5.7   Table Constructors..............|luaref-langTableConst|
-           2.5.8   Function Calls..................|luaref-langFuncCalls|
-           2.5.9   Function Definitions............|luaref-langFuncDefs|
-           2.6   Visibility Rules..................|luaref-langVisibRules|
-           2.7   Error Handling....................|luaref-langError|
-           2.8   Metatables........................|luaref-langMetatables|
-           2.9   Environments......................|luaref-langEnvironments|
-           2.10   Garbage Collection...............|luaref-langGC|
-           2.10.1   Garbage-Collection Metamethods.|luaref-langGCMeta|
-           2.10.2   Weak Tables....................|luaref-langWeaktables|
-           2.11   Coroutines.......................|luaref-langCoro|
-
-           3   THE APPLICATION PROGRAM INTERFACE...|luaref-api|
-           3.1   The Stack.........................|luaref-apiStack|
-           3.2   Stack Size........................|luaref-apiStackSize|
-           3.3   Pseudo-Indices....................|luaref-apiPseudoIndices|
-           3.4   C Closures........................|luaref-apiCClosures|
-           3.5   Registry..........................|luaref-apiRegistry|
-           3.6   Error Handling in C...............|luaref-apiError|
-           3.7   Functions and Types...............|luaref-apiFunctions|
-           3.8   The Debug Interface...............|luaref-apiDebug|
-
-           4   THE AUXILIARY LIBRARY...............|luaref-aux|
-           4.1   Functions and Types...............|luaref-auxFunctions|
-
-           5   STANDARD LIBRARIES..................|luaref-lib|
-           5.1   Basic Functions...................|luaref-libBasic|
-           5.2   Coroutine Manipulation............|luaref-libCoro|
-           5.3   Modules...........................|luaref-libModule|
-           5.4   String Manipulation...............|luaref-libString|
-           5.4.1   Patterns........................|luaref-libStringPat|
-           5.5   Table Manipulation................|luaref-libTable|
-           5.6   Mathematical Functions............|luaref-libMath|
-           5.7   Input and Output Facilities.......|luaref-libIO|
-           5.8   Operating System Facilities.......|luaref-libOS|
-           5.9   The Debug Library.................|luaref-libDebug|
-
-           A   BIBLIOGRAPHY........................|luaref-bibliography|
-           B   COPYRIGHT & LICENSES................|luaref-copyright|
-           C   LUAREF DOC..........................|luaref-doc|
-
+Type |gO| to see the table of contents.
 
 ==============================================================================
 1  INTRODUCTION                                                   *luaref-intro*
-==============================================================================
 
 Lua is an extension programming language designed to support general
 procedural programming with data description facilities.  It also offers good
@@ -120,14 +54,13 @@ Lua means "moon" in Portuguese and is pronounced LOO-ah.
 
 ==============================================================================
 2  THE LANGUAGE                                                *luaref-language*
-==============================================================================
 
 This section describes the lexis, the syntax, and the semantics of Lua. In
 other words, this section describes which tokens are valid, how they can be
 combined, and what their combinations mean.
 
 The language constructs will be explained using the usual extended BNF
-notation, in which { `a` } means 0 or more `a`'s, and [ `a` ] means an optional `a`.
+notation, in which `{ a }` means 0 or more `a`'s, and `[ a ]` means an optional `a`.
 
 ==============================================================================
 2.1  Lexical Conventions                                    *luaref-langLexConv*
@@ -203,7 +136,7 @@ For convenience, when the opening long bracket is immediately followed by a
 newline, the newline is not included in the string. As an example, in a system
 using ASCII (in which `a` is coded as 97, newline is coded as 10, and `1` is
 coded as 49), the five literals below denote the same string:
->
+>lua
        a = 'alo\n123"'
        a = "alo\n123\""
        a = '\97lo\10\04923"'
@@ -292,7 +225,7 @@ parameter passing, and function returns always manipulate references to such
 values; these operations do not imply any kind of copy.
 
 The library function `type` returns a string describing the type of a given
-value (see |luaref-type|).
+value (see |luaref-type()|).
 
 ------------------------------------------------------------------------------
 2.2.1  Coercion                                            *luaref-langCoercion*
@@ -303,7 +236,7 @@ string to a number, following the usual conversion rules. Conversely, whenever
 a number is used where a string is expected, the number is converted to a
 string, in a reasonable format. For complete control of how numbers are
 converted to strings, use the `format` function from the string library (see
-|luaref-string.format|).
+|string.format()|).
 
 ==============================================================================
 2.3  Variables                                            *luaref-langVariables*
@@ -344,13 +277,13 @@ has its own reference to an environment, so that all global variables in this
 function will refer to this environment table. When a function is created, it
 inherits the environment from the function that created it. To get the
 environment table of a Lua function, you call `getfenv` (see
-|luaref-getfenv|). To replace it, you call `setfenv` (see |luaref-setfenv|).
+|lua_getfenv()|). To replace it, you call `setfenv` (see |luaref-setfenv()|).
 (You can only manipulate the environment of C functions through the debug
 library; see |luaref-libDebug|.)
 
 An access to a global variable `x` is equivalent to `_env.x`, which in turn is
 equivalent to
->
+>lua
        gettable_event(_env, "x")
 <
 where `_env` is the environment of the running function. (The `_env` variable is
@@ -433,13 +366,13 @@ before the adjustment (except when the call is enclosed in parentheses; see
 
 The assignment statement first evaluates all its expressions and only then are
 the assignments performed. Thus the code
->
+>lua
        i = 3
        i, a[i] = i+1, 20
 <
 sets `a[3]` to 20, without affecting `a[4]` because the `i` in `a[i]` is evaluated (to
 3) before it is assigned 4. Similarly, the line
->
+>lua
        x, y = y, x
 <
 exchanges the values of `x` and `y`.
@@ -452,7 +385,7 @@ defined or callable in Lua. We use it here only for explanatory purposes.)
 
 An assignment to a global variable `x = val` is equivalent to the
 assignment `_env.x = val`, which in turn is equivalent to
->
+>lua
        settable_event(_env, "x", val)
 <
 where `_env` is the environment of the running function. (The `_env` variable is
@@ -517,19 +450,20 @@ The `block` is repeated for `name` starting at the value of the first `exp`, unt
 it passes the second `exp` by steps of the third `exp`. More precisely,
 a `for` statement like
 
-       `for var =`  `e1, e2, e3`  `do`  `block`  `end`
+       `for var =  e1, e2, e3  do  block  end`
 
-is equivalent to the code:
+is equivalent to the code: >lua
 
-       `do`
-         `local`  `var, limit, step`  `= tonumber(e1), tonumber(e2), tonumber(e3)`
-         `if not (`  `var`  `and`  `limit`  `and`  `step`  `) then error() end`
-         `while (`  `step`  `>0 and`  `var`  `<=`  `limit`  `)`
-                 `or (`  `step`  `<=0 and`  `var`  `>=`  `limit`  `) do`
-            `block`
-            `var`  `=`  `var`  `+`  `step`
-         `end`
-       `end`
+       do
+         local  var, limit, step  = tonumber(e1), tonumber(e2), tonumber(e3)
+         if not (  var  and  limit  and  step  ) then error() end
+         while (  step  >0 and  var  <=  limit  )
+                 or (  step  <=0 and  var  >=  limit  ) do
+            block
+            var  =  var  +  step
+         end
+       end
+<
 
 Note the following:
 
@@ -555,18 +489,18 @@ A `for` statement like
 
        `for`  `var1, ..., varn`  `in`  `explist`  `do`  `block`  `end`
 
-is equivalent to the code:
-
-       `do`
-         `local`  `f, s, var`  `=`  `explist`
-         `while true do`
-             `local`  `var1, ..., varn`  `=`  `f(s, var)`
-             `var`  `=`  `var1`
-             `if`  `var`  `== nil then break end`
-             `block`
-         `end`
-       `end`
+is equivalent to the code: >lua
 
+       do
+         local  f, s, var  =  explist
+         while true do
+             local  var1, ..., varn  =  f(s, var)
+             var  =  var1
+             if  var  == nil then break end
+             block
+         end
+       end
+<
 Note the following:
 
  - `explist` is evaluated only once. Its results are an iterator function,
@@ -634,7 +568,7 @@ they are explained in |luaref-langFuncDefs|.
 Binary operators comprise arithmetic operators (see |luaref-langArithOp|),
 relational operators (see |luaref-langRelOp|), logical operators (see
 |luaref-langLogOp|), and the concatenation operator (see |luaref-langConcat|).
-Unary operators comprise the unary minus (see |luaref-labgArithOp|), the unary
+Unary operators comprise the unary minus (see |luaref-langArithOp|), the unary
 `not` (see |luaref-langLogOp|), and the unary length operator (see
 |luaref-langLength|).
 
@@ -648,7 +582,7 @@ adjusts the result list to one element, discarding all values except the first
 one.
 
 Here are some examples:
->
+>lua
        f()                -- adjusted to 0 results
        g(f(), x)          -- f() is adjusted to 1 result
        g(x, f())          -- g gets x plus all results from f()
@@ -681,7 +615,7 @@ or strings that can be converted to numbers (see |luaref-langCoercion|), then al
 operations have the usual meaning. Exponentiation works for any exponent. For
 instance, `x^(-0.5)` computes the inverse of the square root of `x`. Modulo is
 defined as
->
+>lua
        a % b == a - math.floor(a/b)*b
 <
 That is, it is the remainder of a division that rounds the quotient towards
@@ -808,11 +742,11 @@ key `exp1` and value `exp2`. A field of the form `name = exp` is equivalent to
 `["name"] = exp`. Finally, fields of the form `exp` are equivalent to
 `[i] = exp`, where `i` are consecutive numerical integers, starting with 1.
 Fields in the other formats do not affect this counting. For example,
->
+>lua
        a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
 <
 is equivalent to
->
+>lua
        do
          local t = {}
          t[f(1)] = g
@@ -868,7 +802,7 @@ argument list is a single new table. A call of the form `f'` `string` `'`
 As an exception to the free-format syntax of Lua, you cannot put a line break
 before the `(` in a function call. This restriction avoids some ambiguities
 in the language. If you write
->
+>lua
        a = f
        (g).x(a)
 <
@@ -886,7 +820,7 @@ function. Note that a tail call only happens with a particular syntax, where
 the `return` has one single function call as argument; this syntax makes the
 calling function return exactly the returns of the called function. So, none
 of the following examples are tail calls:
->
+>lua
        return (f(x))        -- results adjusted to 1
        return 2 * f(x)
        return x, f(x)       -- additional results
@@ -967,7 +901,7 @@ expression is used as the last element of a list of expressions, then no
 adjustment is made (unless the call is enclosed in parentheses).
 
 As an example, consider the following definitions:
->
+>lua
        function f(a, b) end
        function g(a, b, ...) end
        function r() return 1,2,3 end
@@ -1008,7 +942,7 @@ is syntactic sugar for
 Lua is a lexically scoped language. The scope of variables begins at the first
 statement after their declaration and lasts until the end of the innermost
 block that includes the declaration. Consider the following example:
->
+>lua
        x = 10                -- global variable
        do                    -- new block
          local x = x         -- new `x`, with value 10
@@ -1033,7 +967,7 @@ function.
 
 Notice that each execution of a local statement defines new local variables.
 Consider the following example:
->
+>lua
        a = {}
        local x = 20
        for i=1,10 do
@@ -1050,13 +984,13 @@ them share the same `x`.
 
 Because Lua is an embedded extension language, all Lua actions start from
 C code in the host program calling a function from the Lua library (see
-|luaref-lua_pcall|). Whenever an error occurs during Lua compilation or
+|lua_pcall()|). Whenever an error occurs during Lua compilation or
 execution, control returns to C, which can take appropriate measures (such as
 print an error message).
 
 Lua code can explicitly generate an error by calling the `error` function (see
-|luaref-error|). If you need to catch errors in Lua, you can use
-the `pcall` function (see |luaref-pcall|).
+|luaref-error()|). If you need to catch errors in Lua, you can use
+the `pcall` function (see |luaref-pcall()|).
 
 ==============================================================================
 2.8  Metatables                         *luaref-metatable* *luaref-langMetatables*
@@ -1074,10 +1008,10 @@ previous example, the event is "add" and the metamethod is the function that
 performs the addition.
 
 You can query the metatable of any value through the `getmetatable` function
-(see |luaref-getmetatable|).
+(see |luaref-getmetatable()|).
 
 You can replace the metatable of tables through the `setmetatable` function (see
-|luaref-setmetatable|). You cannot change the metatable of other types from Lua
+|luaref-setmetatable()|). You cannot change the metatable of other types from Lua
 (except using the debug library); you must use the C API for that.
 
 Tables and userdata have individual metatables (although multiple tables and
@@ -1109,7 +1043,7 @@ given object, we use the expression
        metatable(obj)[event]
 <
 This should be read as
->
+>lua
        rawget(metatable(obj) or {}, event)
 <
 That is, the access to a metamethod does not invoke other metamethods, and the
@@ -1123,13 +1057,13 @@ the `+` operation.
 The function `getbinhandler` below defines how Lua chooses a handler for a
 binary operation. First, Lua tries the first operand. If its type does not
 define a handler for the operation, then Lua tries the second operand.
->
+>lua
        function getbinhandler (op1, op2, event)
          return metatable(op1)[event] or metatable(op2)[event]
        end
 <
 By using this function, the behavior of the `op1 + op2` is
->
+>lua
        function add_event (op1, op2)
          local o1, o2 = tonumber(op1), tonumber(op2)
          if o1 and o2 then  -- both operands are numeric?
@@ -1170,7 +1104,7 @@ with the function `pow` (from the C math library) as the primitive operation.
 "unm":                                                                 *__unm()*
 ------
 the unary `-` operation.
->
+>lua
        function unm_event (op)
          local o = tonumber(op)
          if o then  -- operand is numeric?
@@ -1190,7 +1124,7 @@ the unary `-` operation.
 "concat":                                                           *__concat()*
 ---------
 the `..` (concatenation) operation.
->
+>lua
        function concat_event (op1, op2)
          if (type(op1) == "string" or type(op1) == "number") and
             (type(op2) == "string" or type(op2) == "number") then
@@ -1208,7 +1142,7 @@ the `..` (concatenation) operation.
 "len":                                                                 *__len()*
 ------
 the `#` operation.
->
+>lua
        function len_event (op)
          if type(op) == "string" then
            return strlen(op)         -- primitive string length
@@ -1233,7 +1167,7 @@ The function `getcomphandler` defines how Lua chooses a metamethod for
 comparison operators. A metamethod only is selected when both objects being
 compared have the same type and the same metamethod for the selected
 operation.
->
+>lua
        function getcomphandler (op1, op2, event)
          if type(op1) ~= type(op2) then return nil end
          local mm1 = metatable(op1)[event]
@@ -1242,7 +1176,7 @@ operation.
        end
 <
 The "eq" event is defined as follows:
->
+>lua
        function eq_event (op1, op2)
          if type(op1) ~= type(op2) then  -- different types?
            return false   -- different objects
@@ -1264,7 +1198,7 @@ The "eq" event is defined as follows:
 "lt":                                                                   *__lt()*
 -----
 the `<` operation.
->
+>lua
        function lt_event (op1, op2)
          if type(op1) == "number" and type(op2) == "number" then
            return op1 < op2   -- numeric comparison
@@ -1285,7 +1219,7 @@ the `<` operation.
 "le":                                                                   *__le()*
 -----
 the `<=` operation.
->
+>lua
        function le_event (op1, op2)
          if type(op1) == "number" and type(op2) == "number" then
            return op1 <= op2   -- numeric comparison
@@ -1313,7 +1247,7 @@ to `not (b < a)`.
 "index":                                                             *__index()*
 --------
 The indexing access `table[key]`.
->
+>lua
        function gettable_event (table, key)
          local h
          if type(table) == "table" then
@@ -1335,7 +1269,7 @@ The indexing access `table[key]`.
 "newindex":                                                       *__newindex()*
 -----------
 The indexing assignment `table[key] = value`.
->
+>lua
        function settable_event (table, key, value)
          local h
          if type(table) == "table" then
@@ -1357,7 +1291,7 @@ The indexing assignment `table[key] = value`.
 "call":                                                               *__call()*
 -------
 called when Lua calls a value.
->
+>lua
        function function_event (func, ...)
          if type(func) == "function" then
            return func(...)   -- primitive call
@@ -1385,8 +1319,8 @@ convenience feature for programmers to associate a table to a userdata.
 
 Environments associated with threads are called global environments. They are
 used as the default environment for their threads and non-nested functions
-created by the thread (through `loadfile` |luaref-loadfile|, `loadstring`
-|luaref-loadstring| or `load` |luaref-load|) and can be directly accessed by C
+created by the thread (through `loadfile` |luaref-loadfile()|, `loadstring`
+|luaref-loadstring()| or `load` |luaref-load()|) and can be directly accessed by C
 code (see |luaref-apiPseudoIndices|).
 
 Environments associated with C functions can be directly accessed by C code
@@ -1399,10 +1333,10 @@ used as the default environment for other Lua functions created by the
 function.
 
 You can change the environment of a Lua function or the running thread by
-calling `setfenv` (see |luaref-setenv|). You can get the environment of a Lua
-function or the running thread by calling `getfenv` (see |luaref-getfenv|). To
-manipulate the environment of other objects (userdata, C functions, other
-threads) you must use the C API.
+calling `setfenv`. You can get the environment of a Lua function or the
+running thread by calling `getfenv` (see |lua_getfenv()|). To manipulate the
+environment of other objects (userdata, C functions, other threads) you must
+use the C API.
 
 ==============================================================================
 2.10  Garbage Collection                                         *luaref-langGC*
@@ -1432,8 +1366,8 @@ collector too slow and may result in the collector never finishing a cycle.
 The default, 2, means that the collector runs at "twice" the speed of memory
 allocation.
 
-You can change these numbers by calling `lua_gc` (see |luaref-lua_gc|) in C or
-`collectgarbage` (see |luaref-collectgarbage|) in Lua. Both get percentage
+You can change these numbers by calling `lua_gc` (see |lua_gc()|) in C or
+`collectgarbage` (see |luaref-collectgarbage()|) in Lua. Both get percentage
 points as arguments (so an argument of 100 means a real value of 1). With
 these functions you can also control the collector directly (e.g., stop and
 restart it).
@@ -1452,7 +1386,7 @@ Garbage userdata with a field `__gc` in their metatables are not collected
 immediately by the garbage collector. Instead, Lua puts them in a list. After
 the collection, Lua does the equivalent of the following function for each
 userdata in that list:
->
+>lua
        function gc_event (udata)
          local h = metatable(udata).__gc
          if h then
@@ -1496,12 +1430,12 @@ multithread systems, however, a coroutine only suspends its execution by
 explicitly calling a yield function.
 
 You create a coroutine with a call to `coroutine.create` (see
-|luaref-coroutine.create|). Its sole argument is a function that is the main
+|coroutine.create()|). Its sole argument is a function that is the main
 function of the coroutine. The `create` function only creates a new coroutine
 and returns a handle to it (an object of type `thread`); it does not start the
 coroutine execution.
 
-When you first call `coroutine.resume` (see |luaref-coroutine.resume|),
+When you first call `coroutine.resume` (see |coroutine.resume()|),
 passing as its first argument the thread returned by `coroutine.create`, the
 coroutine starts its execution, at the first line of its main function. Extra
 arguments passed to `coroutine.resume` are passed on to the coroutine main
@@ -1516,7 +1450,7 @@ main function. In case of errors, `coroutine.resume` returns `false` plus an
 error message.
 
 A coroutine yields by calling `coroutine.yield` (see
-|luaref-coroutine.yield|). When a coroutine yields, the corresponding
+|coroutine.yield()|). When a coroutine yields, the corresponding
 `coroutine.resume` returns immediately, even if the yield happens inside
 nested function calls (that is, not in the main function, but in a function
 directly or indirectly called by the main function). In the case of a yield,
@@ -1526,7 +1460,7 @@ its execution from the point where it yielded, with the call to
 `coroutine.yield` returning any extra arguments passed to `coroutine.resume`.
 
 Like `coroutine.create`, the `coroutine.wrap` function (see
-|luaref-coroutine.wrap|) also creates a coroutine, but instead of returning
+|coroutine.wrap()|) also creates a coroutine, but instead of returning
 the coroutine itself, it returns a function that, when called, resumes the
 coroutine. Any arguments passed to this function go as extra arguments to
 `coroutine.resume`. `coroutine.wrap` returns all the values returned by
@@ -1535,7 +1469,7 @@ coroutine. Any arguments passed to this function go as extra arguments to
 propagated to the caller.
 
 As an example, consider the next code:
->
+>lua
        function foo1 (a)
          print("foo", a)
          return coroutine.yield(2*a)
@@ -1569,7 +1503,6 @@ When you run it, it produces the following output:
 
 ==============================================================================
 3  THE APPLICATION PROGRAM INTERFACE                                *luaref-API*
-==============================================================================
 
 This section describes the C API for Lua, that is, the set of C functions
 available to the host program to communicate with Lua. All API functions and
@@ -1595,7 +1528,7 @@ Whenever Lua calls C, the called function gets a new stack, which is
 independent of previous stacks and of stacks of C functions that are still
 active. This stack initially contains any arguments to the C function and it
 is where the C function pushes its results to be returned to the caller (see
-|luaref-lua_CFunction|).
+|lua_CFunction()|).
 
                                                              *luaref-stackindex*
 For convenience, most query operations in the API do not follow a strict stack
@@ -1615,7 +1548,7 @@ if `1 <= abs(index) <= top`).
 When you interact with Lua API, you are responsible for ensuring consistency.
 In particular, you are responsible for controlling stack overflow. You can
 use the function `lua_checkstack` to grow the stack size (see
-|luaref-lua_checkstack|).
+|lua_checkstack()|).
 
 Whenever Lua calls C, it ensures that at least `LUA_MINSTACK` stack positions
 are available. `LUA_MINSTACK` is defined as 20, so that usually you do not
@@ -1626,7 +1559,7 @@ Most query functions accept as indices any value inside the available stack
 space, that is, indices up to the maximum stack size you have set through
 `lua_checkstack`. Such indices are called acceptable indices. More formally,
 we define an acceptable index as follows:
->
+>lua
     (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace)
 <
 Note that 0 is never an acceptable index.
@@ -1647,7 +1580,7 @@ pseudo-index `LUA_ENVIRONINDEX`.
 To access and change the value of global variables, you can use regular table
 operations over an environment table. For instance, to access the value of a
 global variable, do
->
+>c
        lua_getfield(L, LUA_GLOBALSINDEX, varname);
 <
 
@@ -1656,14 +1589,14 @@ global variable, do
 
 When a C function is created, it is possible to associate some values with it,
 thus creating a C closure; these values are called upvalues and are accessible
-to the function whenever it is called (see |luaref-lua_pushcclosure|).
+to the function whenever it is called (see |lua_pushcclosure()|).
 
 Whenever a C function is called, its upvalues are located at specific
 pseudo-indices. These pseudo-indices are produced by the macro
-`lua_upvalueindex` (see |luaref-lua_upvalueindex|). The first value associated
-with a function is at position `lua_upvalueindex(1)`, and so on. Any access to
-`lua_upvalueindex(` `n` `)`, where `n` is greater than the number of upvalues of
-the current function, produces an acceptable (but invalid) index.
+`lua_upvalueindex`. The first value associated with a function is at position
+`lua_upvalueindex(1)`, and so on. Any access to `lua_upvalueindex(` `n` `)`,
+where `n` is greater than the number of upvalues of the current function,
+produces an acceptable (but invalid) index.
 
 ==============================================================================
 3.5  Registry                               *luaref-registry* *luaref-apiRegistry*
@@ -1694,11 +1627,11 @@ Almost any function in the API may raise an error, for instance due to a
 memory allocation error. The following functions run in protected mode (that
 is, they create a protected environment to run), so they never raise an error:
 `lua_newstate`, `lua_close`, `lua_load`, `lua_pcall`, and `lua_cpcall` (see
-|luaref-lua_newstate|, |luaref-lua_close|, |luaref-lua_load|,
-|luaref-lua_pcall|, and |luaref-lua_cpcall|).
+|lua_newstate()|, |lua_close()|, |lua_load()|,
+|lua_pcall()|, and |lua_cpcall()|).
 
 Inside a C function you can raise an error by calling `lua_error`  (see
-|luaref-lua_error|).
+|lua_error()|).
 
 ==============================================================================
 3.7  Functions and Types                                   *luaref-apiFunctions*
@@ -1706,7 +1639,7 @@ Inside a C function you can raise an error by calling `lua_error`  (see
 Here we list all functions and types from the C API in alphabetical order.
 
 lua_Alloc                                                          *lua_Alloc()*
->
+>c
     typedef void * (*lua_Alloc) (void *ud,
                                  void *ptr,
                                  size_t osize,
@@ -1715,7 +1648,7 @@ lua_Alloc                                                          *lua_Alloc()*
         The type of the memory-allocation function used by Lua states. The
         allocator function must provide a functionality similar to `realloc`,
         but not exactly the same. Its arguments are `ud`, an opaque pointer
-        passed to `lua_newstate` (see |luaref-lua_newstate|); `ptr`, a pointer
+        passed to `lua_newstate` (see |lua_newstate()|); `ptr`, a pointer
         to the block being allocated/reallocated/freed; `osize`, the original
         size of the block; `nsize`, the new size of the block. `ptr` is `NULL`
         if and only if `osize` is zero. When `nsize` is zero, the allocator
@@ -1729,8 +1662,8 @@ lua_Alloc                                                          *lua_Alloc()*
 
         Here is a simple implementation for the allocator function. It is used
         in the auxiliary library by `luaL_newstate` (see
-        |luaref-luaL_newstate|).
->
+        |luaL_newstate()|).
+>c
             static void *l_alloc (void *ud, void *ptr, size_t osize,
                                                        size_t nsize) {
               (void)ud;  (void)osize;  /* not used */
@@ -1747,7 +1680,7 @@ lua_Alloc                                                          *lua_Alloc()*
         behaviors.
 
 lua_atpanic                                                      *lua_atpanic()*
->
+>c
     lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
 <
         Sets a new panic function and returns the old one.
@@ -1761,7 +1694,7 @@ lua_atpanic                                                      *lua_atpanic()*
         stack.
 
 lua_call                                                            *lua_call()*
->
+>c
     void lua_call (lua_State *L, int nargs, int nresults);
 <
         Calls a function.
@@ -1785,11 +1718,11 @@ lua_call                                                            *lua_call()*
 
         The following example shows how the host program may do the equivalent
         to this Lua code:
->
+>lua
             a = f("how", t.x, 14)
 <
         Here it is in C:
->
+>c
             lua_getfield(L, LUA_GLOBALSINDEX, "f"); // function to be called
             lua_pushstring(L, "how");                        // 1st argument
             lua_getfield(L, LUA_GLOBALSINDEX, "t");   // table to be indexed
@@ -1804,7 +1737,7 @@ lua_call                                                            *lua_call()*
         practice.
 
 lua_CFunction                             *luaref-cfunction* *lua_CFunction()*
->
+>c
     typedef int (*lua_CFunction) (lua_State *L);
 <
         Type for C functions.
@@ -1813,7 +1746,7 @@ lua_CFunction                             *luaref-cfunction* *lua_CFunction()*
         following protocol, which defines the way parameters and results are
         passed: a C function receives its arguments from Lua in its stack in
         direct order (the first argument is pushed first). So, when the
-        function starts, `lua_gettop(L)` (see |luaref-lua_gettop|) returns the
+        function starts, `lua_gettop(L)` (see |lua_gettop()|) returns the
         number of arguments received by the function. The first argument (if
         any) is at index 1 and its last argument is at index `lua_gettop(L)`.
         To return values to Lua, a C function just pushes them onto the stack,
@@ -1825,7 +1758,7 @@ lua_CFunction                             *luaref-cfunction* *lua_CFunction()*
                                                        *luaref-cfunctionexample*
         As an example, the following function receives a variable number of
         numerical arguments and returns their average and sum:
->
+>c
             static int foo (lua_State *L) {
               int n = lua_gettop(L);    /* number of arguments */
               lua_Number sum = 0;
@@ -1844,7 +1777,7 @@ lua_CFunction                             *luaref-cfunction* *lua_CFunction()*
 <
 
 lua_checkstack                                                *lua_checkstack()*
->
+>c
     int lua_checkstack (lua_State *L, int extra);
 <
         Ensures that there are at least `extra` free stack slots in the stack.
@@ -1853,7 +1786,7 @@ lua_checkstack                                                *lua_checkstack()*
         the new size, it is left unchanged.
 
 lua_close                                                          *lua_close()*
->
+>c
     void lua_close (lua_State *L);
 <
         Destroys all objects in the given Lua state (calling the corresponding
@@ -1865,7 +1798,7 @@ lua_close                                                          *lua_close()*
         are not needed, to avoid growing too large.
 
 lua_concat                                                        *lua_concat()*
->
+>c
     void lua_concat (lua_State *L, int n);
 <
         Concatenates the `n` values at the top of the stack, pops them, and
@@ -1875,35 +1808,35 @@ lua_concat                                                        *lua_concat()*
         usual semantics of Lua (see |luaref-langConcat|).
 
 lua_cpcall                                                        *lua_cpcall()*
->
+>c
     int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
 <
         Calls the C function `func` in protected mode. `func` starts with only
         one element in its stack, a light userdata containing `ud`. In case of
         errors, `lua_cpcall` returns the same error codes as `lua_pcall` (see
-        |luaref-lua_pcall|), plus the error object on the top of the stack;
+        |lua_pcall()|), plus the error object on the top of the stack;
         otherwise, it returns zero, and does not change the stack. All values
         returned by `func` are discarded.
 
 lua_createtable                                              *lua_createtable()*
->
+>c
     void lua_createtable (lua_State *L, int narr, int nrec);
 <
         Creates a new empty table and pushes it onto the stack. The new table
         has space pre-allocated for `narr` array elements and `nrec` non-array
         elements. This pre-allocation is useful when you know exactly how many
         elements the table will have. Otherwise you can use the function
-        `lua_newtable`  (see |luaref-lua_newtable|).
+        `lua_newtable`  (see |lua_newtable()|).
 
 lua_dump                                                            *lua_dump()*
->
+>c
     int lua_dump (lua_State *L, lua_Writer writer, void *data);
 <
         Dumps a function as a binary chunk. Receives a Lua function on the top
         of the stack and produces a binary chunk that, if loaded again,
         results in a function equivalent to the one dumped. As it produces
         parts of the chunk, `lua_dump` calls function `writer` (see
-        |luaref-lua_Writer|) with the given `data` to write them.
+        |lua_Writer()|) with the given `data` to write them.
 
         The value returned is the error code returned by the last call to the
         writer; 0 means no errors.
@@ -1911,7 +1844,7 @@ lua_dump                                                            *lua_dump()*
         This function does not pop the Lua function from the stack.
 
 lua_equal                                                          *lua_equal()*
->
+>c
     int lua_equal (lua_State *L, int index1, int index2);
 <
         Returns 1 if the two values in acceptable indices `index1` and
@@ -1920,15 +1853,15 @@ lua_equal                                                          *lua_equal()*
         if any of the indices is non valid.
 
 lua_error                                                          *lua_error()*
->
+>c
     int lua_error (lua_State *L);
 <
         Generates a Lua error. The error message (which can actually be a Lua
         value of any type) must be on the stack top. This function does a long
-        jump, and therefore never returns (see |luaref-luaL_error|).
+        jump, and therefore never returns (see |luaL_error()|).
 
 lua_gc                                                                *lua_gc()*
->
+>c
     int lua_gc (lua_State *L, int what, int data);
 <
         Controls the garbage collector.
@@ -1936,46 +1869,46 @@ lua_gc                                                                *lua_gc()*
         This function performs several tasks, according to the value of the
         parameter `what`:
 
-        `LUA_GCSTOP`        stops the garbage collector.
-        `LUA_GCRESTART`     restarts the garbage collector.
-        `LUA_GCCOLLECT`     performs a full garbage-collection cycle.
-        `LUA_GCCOUNT`       returns the current amount of memory (in Kbytes) in
+        - `LUA_GCSTOP`      stops the garbage collector.
+        - `LUA_GCRESTART`   restarts the garbage collector.
+        - `LUA_GCCOLLECT`   performs a full garbage-collection cycle.
+        - `LUA_GCCOUNT`     returns the current amount of memory (in Kbytes) in
                           use by Lua.
-        `LUA_GCCOUNTB`      returns the remainder of dividing the current
+        - `LUA_GCCOUNTB`    returns the remainder of dividing the current
                           amount of bytes of memory in use by Lua by 1024.
-        `LUA_GCSTEP`        performs an incremental step of garbage collection.
+        - `LUA_GCSTEP`      pe