(mercurial wasn't giving me a parsimonious diff.)  Summary: move manual.html's
description of the custom allocator from the lua_Alloc section to lua_newstate,
and briefly outline the risks associated with using lua_setallocf.

% diff -c manual.html manual.new.html
*** manual.html	2012-01-02 12:06:35.318316134 -0500
--- manual.new.html	2012-01-02 12:03:49.337493267 -0500
***************
*** 2848,2854 ****
  The type of the memory-allocation function used by Lua states.
  The allocator function must provide a
  functionality similar to <code>realloc</code>,
! but not exactly the same.
  Its arguments are
  <code>ud</code>, an opaque pointer passed to <a
href="#lua_newstate"><code>lua_newstate</code></a>;
  <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
--- 2848,2857 ----
  The type of the memory-allocation function used by Lua states.
  The allocator function must provide a
  functionality similar to <code>realloc</code>,
! but not exactly the same.  <b>Its semantics differ from those of the
!     custom allocator described
!     in <a href="#lua_newstate"><code>lua_newstate</code></a></b>, even
!     though they have the same signature.
  Its arguments are
  <code>ud</code>, an opaque pointer passed to <a
href="#lua_newstate"><code>lua_newstate</code></a>;
  <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
***************
*** 2874,2923 ****
  Lua is allocating memory for something else.


- <p>
- Lua assumes the following behavior from the allocator function:
-
-
- <p>
- When <code>nsize</code> is zero,
- the allocator should behave like <code>free</code>
- and return <code>NULL</code>.
-
-
- <p>
- When <code>nsize</code> is not zero,
- the allocator should behave like <code>realloc</code>.
- The allocator returns <code>NULL</code>
- if and only if it cannot fulfill the request.
- Lua assumes that the allocator never fails when
- <code>osize >= nsize</code>.
-
-
- <p>
- Here is a simple implementation for the allocator function.
- It is used in the auxiliary library by <a
href="#luaL_newstate"><code>luaL_newstate</code></a>.
-
- <pre>
-      static void *l_alloc (void *ud, void *ptr, size_t osize,
-                                                 size_t nsize) {
-        (void)ud;  (void)osize;  /* not used */
-        if (nsize == 0) {
-          free(ptr);
-          return NULL;
-        }
-        else
-          return realloc(ptr, nsize);
-      }
- </pre><p>
- Note that Standard C ensures
- that <code>free(NULL)</code> has no effect and that
- <code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>.
- This code assumes that <code>realloc</code> does not fail when shrinking a block.
- (Although Standard C does not ensure this behavior,
- it seems to be a safe assumption.)
-
-
-


  <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
--- 2877,2882 ----
***************
*** 3735,3743 ****
--- 3694,3740 ----
  The second argument, <code>ud</code>, is an opaque pointer that Lua
  passes to the allocator in every call.

+ <p>
+ Lua assumes the following behavior from the allocator function:
+

+ <p>
+ When <code>nsize</code> is zero,
+ the allocator should behave like <code>free</code>
+ and return <code>NULL</code>.
+
+
+ <p>
+ When <code>nsize</code> is not zero,
+ the allocator should behave like <code>realloc</code>.
+ The allocator returns <code>NULL</code>
+ if and only if it cannot fulfill the request.
+ Lua assumes that the allocator never fails when
+ <code>osize >= nsize</code>.


+ <p>
+ Here is a simple implementation for the allocator function.
+ It is used in the auxiliary library by <a
href="#luaL_newstate"><code>luaL_newstate</code></a>.
+
+ <pre>
+      static void *l_alloc (void *ud, void *ptr, size_t osize,
+                                                 size_t nsize) {
+        (void)ud;  (void)osize;  /* not used */
+        if (nsize == 0) {
+          free(ptr);
+          return NULL;
+        }
+        else
+          return realloc(ptr, nsize);
+      }
+ </pre><p>
+ Note that Standard C ensures
+ that <code>free(NULL)</code> has no effect and that
+ <code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>.
+ This code assumes that <code>realloc</code> does not fail when shrinking a block.
+ (Although Standard C does not ensure this behavior,
+ it seems to be a safe assumption.)

  <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
  <span class="apii">[-0, +1, <em>m</em>]</span>
***************
*** 4448,4459 ****
  <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>

  <p>
! Changes the allocator function of a given state to <code>f</code>
! with user data <code>ud</code>.
!
!
!
!

  <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
  <span class="apii">[-1, +0, <em>e</em>]</span>
--- 4445,4457 ----
  <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>

  <p>
! Changes the allocator function of a given state to <code>f</code> with
! user data <code>ud</code>.
! See <a href="#lua_newstate"><code>lua_newstate</code></a> for the
! semantics of this allocator.  Take care when assigning a new allocator
! with <code>lua_setallocf</code>, as by then the allocator passed
! to <code>lua_newstate</code> has been already used.  Any difference in
! the allocators' memory layouts is likely cause bugs in obscure ways.

  <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
  <span class="apii">[-1, +0, <em>e</em>]</span>