Improved docs.

lua.mod/doc/intro.bbdoc

@@ -1,56 +1,98 @@
-<div style="text-align: justify;">"<span style="font-style: italic;">Lua is an extension programming
-language designed to support general procedural programming with data
-description facilities. It also offers good support for object-oriented
-programming, functional programming, and data-driven programming. Lua
-is intended to be used as a powerful, light-weight scripting language
-for any program that needs one.</span> " (from "<a href="../lua-5.1.4/doc/contents.html">Lua 5.1 Reference
-Manual</a>" by Roberto Ierusalimschy, Luiz Henrique de
-Figueiredo, Waldemar Celes)<br/><br/>This module provides a
-BlitzMax interface to the Lua main and auxiliary APIs. It is almost
-complete, the only functions missing are those with variable argument
-lists (which are not yet supported by BlitzMax).<br/><br/>The
-axe.lua package also contains the full Lua 5.1.4 distribution. The Lua
-source code is completely integrated into the module, additional DLLs
-(or shared libraries, resp.) are no longer required.<br/><h2>Lua
-Documentation</h2>The Lua Reference Manual is part of this
-distribution and may be directly visited from here:<br/><ul><li><a href="../lua-5.1.4/doc/contents.html">Lua 5.1 Contents</a></li><li><a href="../lua-5.1.4/doc/manual.html">Lua 5.1 Reference Manual</a></li><li><a href="../lua-5.1.4/doc/readme.html">Lua 5.1 ReadMe</a></li></ul>Additional
-information can be found on the <a href="http://www.lua.org">Lua
-web site</a>; the <a href="http://lua-users.org/wiki/">Lua
-wiki</a> contains further material <a href="http://lua-users.org/wiki/BlitzMax">about this module</a>
-and related packages.<br/><h2>Introduction</h2>The
-following description is not meant as a tutorial, but may still help
-you to start Lua programming within BlitzMax. More API-related
-information can be found in the <a href="../lua-5.1.4/doc/manual.html#3">Lua Reference manual</a><br/><h3>Setting
-up a Lua VM</h3>Running&nbsp;Lua scripts always require the
-instantiation of at least one Lua VM:<br/><pre> local LuaState:byte ptr = luaL_newstate()</pre>The
-result of this instantiation is a pointer to a structure
-which&nbsp;contains the full state of the new VM and has to be
-passed as the first argument to almost any other Lua API function.<br/><br/>It
-is now time to "open" the intrinsic Lua libraries (note: these
-libraries are part of axe.lua now, external DLLs or shared libraries
-are not necessary):<br/><pre> luaL_openlibs(LuaState)</pre>Always
-initialize the Lua VM by opening its libraries unless you really know
-what you are doing!<br/><br/>Usually, creating a single Lua
-state is sufficient, even further (Lua) threads share the basic Lua
-state (and its associated environment).<br/><h3>Shutting
-down a Lua VM</h3>At the end, it's always a good idea to shut
-down the Lua VM<br/><pre> lua_close(LuaState)</pre>The
-Lua interpreter has now been terminated and its state variable is no
-longer valid.<br/><h3>Accessing Lua Globals</h3>The
-code<br/><pre>&nbsp; lua_pushstring(LuaState, "BMXString")<br/>  lua_setglobal (LuaState, "luaglobal")</pre>defines
-a global Lua variable (called&nbsp;<span style="font-family: Courier New,Courier,monospace;">luaglobal</span>)
-which contains a string (namely "<span style="font-family: Courier New,Courier,monospace;">BMXString</span>").<h3>Registering
-BlitzMax Functions</h3>In order to access BlitzMax features from
-within a Lua script, it is necessary to implement suitable BlitzMax
-functions and register them in the Lua VM.<br/><br/>Such
-BlitzMax functions typically look as follows:<br/><pre> function BMXName:int (LuaState:Byte Ptr)<br/>   ...      ' handling of parameters passed from Lua (if required)<br/>     ...    ' actual function body<br/>   ...      ' passing results back to Lua (if required)<br/>   return 0 ' number of values returned to Lua<br/> end function</pre>Such
-a function is then registered using<br/><pre> lua_register(LuaState, "luaname", BMXName)</pre>This
-command registers a BlitzMax function (called&nbsp;<span style="font-family: Courier New,Courier,monospace;">BMXName</span>)
-with the (global) name&nbsp;<span style="font-family: Courier New,Courier,monospace;">luaname</span>
-under Lua. Both names may be equal, but they do not have to.<br/><h3>Running
-Lua Scripts From Within BlitzMax</h3>The code<br/><pre> local Result:int = luaL_loadString(LuaState,LuaScript)<br/> if (Result &lt;&gt; 0) then<br/>   ' ERROR!!!<br/>   lua_close(LuaState) ' just to be complete<br/>   end<br/> end if</pre>loads
-and compiles a (BlitzMax) string containing a LuaScript. The result (of
-compilation) is left on the (Lua) stack.<br/><pre> lua_getfield(LuaState, LUA_GLOBALSINDEX, "debug")' get global "debug"<br/> lua_getfield(LuaState, -1, "traceback")       ' get "debug.traceback"<br/> lua_remove (LuaState, -2)           ' remove "debug" table from stack<br/><br/> Result = lua_pcall(LuaState,1,-1,-1)' use "debug.traceback" as err.hdlr<br/> if (Result &lt;&gt; 0) then<br/>   ' ERROR<br/>   lua_close(LuaState) ' just to be complete<br/>   end<br/> end if</pre>actually
-evaluates the previously loaded script. The initially mentioned Lua
-commands just prepare for proper error messages should the Lua script
-fail.</div>
+"*Lua is an extension programming language designed to support general procedural programming with data
+description facilities. It also offers good support for object-oriented programming, functional programming,
+and data-driven programming. Lua is intended to be used as a powerful, light-weight scripting language
+for any program that needs one.*" (from "[Lua 5.1 Reference Manual](https://www.lua.org/manual/5.1/manual.html)" by Roberto Ierusalimschy, Luiz Henrique de
+Figueiredo, Waldemar Celes)
+
+This module provides a BlitzMax interface to the Lua main and auxiliary APIs. It is almost
+complete, the only functions missing are those with variable argument lists (which are not supported by BlitzMax).
+
+The #Pub.Lua package contains the full Lua 5.1.4 distribution. The Lua source code is completely integrated into the module, additional DLLs
+(or shared libraries, resp.) are not required.
+
+# Introduction
+The following description is not meant as a tutorial, but may still help you to start Lua programming within BlitzMax.
+More API-related information can be found in the [Lua Reference manual](https://www.lua.org/manual/5.1/manual.html#3)
+
+## Setting up a Lua VM
+
+Running Lua scripts always require the instantiation of at least one Lua VM:
+```blitzmax
+Local LuaState:Byte Ptr = luaL_newstate()
+```
+The result of this instantiation is a pointer to a structure which contains the full state of the new VM and has to be
+passed as the first argument to almost any other Lua API function.
+
+It is now time to "open" the intrinsic Lua libraries (note: these libraries are part of #Pub.Lua now, external DLLs or shared libraries
+are not necessary):
+```blitzmax
+luaL_openlibs(LuaState)
+```
+Always initialize the Lua VM by opening its libraries unless you really know what you are doing!
+
+Usually, creating a single Lua state is sufficient, even further (Lua) threads share the basic Lua
+state (and its associated environment).
+
+## Shutting down a Lua VM
+At the end, it's always a good idea to shut down the Lua VM
+```blitzmax
+lua_close(LuaState)
+```
+The Lua interpreter has now been terminated and its state variable is no longer valid.
+
+### Accessing Lua Globals
+
+The code
+```blitzmax
+lua_pushstring(LuaState, "BMXString")
+lua_setglobal (LuaState, "luaglobal")
+```
+defines a global Lua variable (called `luaglobal`) which contains a string (namely "`BMXString`").
+
+## Registering BlitzMax Functions
+
+In order to access BlitzMax features from within a Lua script, it is necessary to implement suitable BlitzMax functions
+and register them in the Lua VM.
+
+Such BlitzMax functions typically look as follows:
+```blitzmax
+Function BMXName:int (LuaState:Byte Ptr)
+	...    ' handling of parameters passed from Lua (if required)
+	...    ' actual function body
+	...    ' passing results back to Lua (if required)
+	return 0 ' number of values returned to Lua
+End Function
+```
+Such a function is then registered using
+```blitzmax
+lua_register(LuaState, "luaname", BMXName)
+```
+This command registers a BlitzMax function (called `BMXName`) with the (global) name `luaname` under Lua.
+Both names may be equal, but they do not have to.
+
+##Running Lua Scripts From Within BlitzMax
+
+The code
+```blitzmax
+Local Result:int = luaL_loadString(LuaState,LuaScript)
+If Result <> 0 Then<br/>   ' ERROR!!!
+	lua_close(LuaState) ' just to be complete
+	End
+End If
+```
+loads and compiles a (BlitzMax) string containing a LuaScript. The result (of compilation) is left on the (Lua) stack.
+```blitzmax
+lua_getfield(LuaState, LUA_GLOBALSINDEX, "debug") ' get global "debug"
+lua_getfield(LuaState, -1, "traceback")           ' get "debug.traceback"
+lua_remove (LuaState, -2)                         ' remove "debug" table from stack
+
+Result = lua_pcall(LuaState,1,-1,-1)  ' use "debug.traceback" as err.hdlr
+
+If Result <> 0 Then
+	' ERROR
+	lua_close(LuaState) ' just to be complete
+	End
+End if
+```
+actually evaluates the previously loaded script. The initially mentioned Lua commands just prepare for proper error messages should the Lua script
+fail.