Lunatic doc: add appendix with hints on how to read Programming in Lua, 1st ed.

git-svn-id: https://svn.eduke32.com/eduke32@4035 1a8010ca-5511-0410-912e-c29ae57300e0

polymer/eduke32/source/lunatic/doc/lunatic.txt

@@ -117,6 +117,7 @@ function instead of looking it up in the global environment.
 *`printf(fmt, ...)`*::
 Calls `print` with the result of `string.format(fmt, ...)`.
 
+[[modules]]
 Writing and using modules
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -137,6 +138,7 @@ a named module is requested by passing its name to `require`. This searches for
 a matching module, loading and running it if the request happens for the first
 time.
 
+[[require]]
 ==== The function `require(modname, ...)`
 
 Attempts to find a Lua or Lunatic module named `modname`. The name can refer to
@@ -331,7 +333,7 @@ Contains the following members: `pos`, `dist`, `clock`, `ang`, `horiz`, `sect`.
 [[gv_RETURN]] `gv.RETURN`::
 A special variable that is used by the game to pass specific values to game
 events, or to examine values passed back from events and act upon them
-accordingly. Refer to <<Appendix_A,Appendix A>> for a list of how the various
+accordingly. Refer to <<Appendix_event_RETURN,Appendix B>> for a list of how the various
 events interpret this variable.
 
 Functions
@@ -1107,6 +1109,7 @@ horizontal and vertical texel sizes of each tile.
 Lunatic functions
 ~~~~~~~~~~~~~~~~~
 
+[[engine_iterators]]
 Engine-side iterators
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -1794,7 +1797,131 @@ APPENDICES FOLLOW
 :numbered!:
 
 [appendix]
-[[Appendix_A]]
+[[Appendix_Howto_read_PIL]]
+How to read _Programming in Lua_
+--------------------------------
+
+:PiL50: http://www.lua.org/pil/contents.html
+
+On the Lua homepage, the first edition of _Programming in Lua_ is
+{PiL50}[available] online. While targeting Lua 5.0, it still remains applicable
+to Lua 5.1 to a large extent. This section gives hints for reading it when
+learning to code for Lunatic.
+
+[float]
+==== http://www.lua.org/pil/p1.html[Preface]
+
+May be interesting to get an idea of the philisophy behind Lua.
+http://www.lua.org/pil/p1.3.html[A Few Typographical Conventions] should be
+read to be familiar with them.
+
+[float]
+==== http://www.lua.org/pil/1.html[1 -- Getting Started]
+
+Mentions the stand-alone Lua interpreter. When none is available, a LuaJIT
+stand-alone binary can be used for experimentation as well.
+
+[float]
+==== http://www.lua.org/pil/1.1.html[1.1 -- Chunks]
+
+Introduces chunks as the basic ``blocks'' of Lua code and notes how whitespace
+is treated. Mentions `dofile`, which is not available in Lunatic
+(<<require,`require`>> is preferred).
+
+[float]
+==== http://www.lua.org/pil/1.2.html[1.2 -- Global Variables]
+
+Section may be read, but usage of *`local`* variables is strongly recommended
+whereever possible. Also, trying to read a non-existent global or to write any
+value to the global environment gives an error in Lunatic (except that global
+writes are allowed in in <<modules,module>> context, i.e. after `module(...)`).
+
+[float]
+==== http://www.lua.org/pil/1.3.html[_1.3 -- Some Lexical Conventions_]
+
+Must read.
+
+[float]
+==== http://www.lua.org/pil/2.html[_2 -- Types and Values_]
+
+Must read, also subsections. However, ``2.7 -- Userdata and Threads'' is
+not relevant.
+
+[float]
+==== http://www.lua.org/pil/3.html[_3 -- Expressions_]
+
+Must read, also all subsections.
+
+[float]
+==== http://www.lua.org/pil/4.html[_4 -- Statements_]
+
+Must read, also all subsections.
+
+[float]
+==== http://www.lua.org/pil/5.htmlhttp://www.lua.org/pil/5.html[_5 -- Functions_]
+
+Must read, also all subsections. Subsection 5.2 mentions `io.write`, which is
+not available in Lunatic.
+
+[float]
+==== http://www.lua.org/pil/6.html[6 -- More about Functions]
+
+May be read (subsections as well) for a more complete understanding of
+functions in Lua, as well as the utility of lexical scoping.
+
+[float]
+==== http://www.lua.org/pil/7.html[_7 -- Iterators and the Generic_ `for`]
+
+May be read (subsections as well), but for basic programming, the knowledge of
+how to merely use (as opposed to write) iterators such as
+<<engine_iterators,`spritesofsect`>> suffices.
+
+[float]
+==== http://www.lua.org/pil/8.3.html[8.3 -- Errors]
+
+May be read. Provides guidelines on how to write error handling (status code
+vs. error).
+
+[float]
+==== http://www.lua.org/pil/8.4.html[8.4 -- Error Handling and Exceptions]
+
+May be read. Discusses protected calls, which should be used sparingly.
+
+[float]
+==== http://www.lua.org/pil/11.html[_11 -- Data Structures_]
+
+May be read, also subsections. The most relevant subsections are
+http://www.lua.org/pil/11.1.html[11.1 -- Arrays],
+http://www.lua.org/pil/11.5.html[11.5 -- Sets and Bags] and to some extent,
+http://www.lua.org/pil/11.6.html[11.6 -- String Buffers]. The way ``11.2 --
+Matrices and Multi-Dimensional Arrays'' suggests to construct matrices is
+rather memory-intensive; also it and ``11.3 -- Linked Lists'' and ``11.4 --
+Queues and Double Queues'' are not relevant to simple Lunatic coding.
+
+[float]
+==== http://www.lua.org/pil/15.html[15 -- Packages]
+
+Lua package system received various additions in 5.1, so the PiL first
+edition's section is out-of-sync. For Lunatic, the <<modules,modules>> section
+of this manual should be consulted.
+ +
+ +
+(The rest of Part II deals with advanced concepts not needed for simple Lunatic
+coding.)
+
+[float]
+==== http://www.lua.org/pil/19.3.html[19.3 -- Sort]
+
+May be read if needed.
+
+[float]
+==== http://www.lua.org/pil/20.html[20 -- The String Library]
+
+May be skimmed (also subsections), though ultimately the Lua Reference should
+be consulted for the exact semantics.
+
+[appendix]
+[[Appendix_event_RETURN]]
 Game event `RETURN` usage
 -------------------------