From 335957800b1ef787dc3cd1d3ca8931c0839d91bb Mon Sep 17 00:00:00 2001 From: helixhorned Date: Thu, 24 Oct 2013 17:48:19 +0000 Subject: [PATCH] Lunatic doc: add Lua source code highlighting using GNU Source-highlight. DONT_BUILD. git-svn-id: https://svn.eduke32.com/eduke32@4113 1a8010ca-5511-0410-912e-c29ae57300e0 --- polymer/eduke32/source/lunatic/doc/Makefile | 11 +++++++++-- polymer/eduke32/source/lunatic/doc/lunatic.txt | 17 ++++++++++++++++- .../eduke32/source/lunatic/doc/lunatic_sh.style | 10 ++++++++++ 3 files changed, 35 insertions(+), 3 deletions(-) create mode 100644 polymer/eduke32/source/lunatic/doc/lunatic_sh.style diff --git a/polymer/eduke32/source/lunatic/doc/Makefile b/polymer/eduke32/source/lunatic/doc/Makefile index a0a4aa3c9..85b4bf824 100644 --- a/polymer/eduke32/source/lunatic/doc/Makefile +++ b/polymer/eduke32/source/lunatic/doc/Makefile @@ -1,7 +1,14 @@ FILES=lunatic.html lunacon.html -%.html: %.txt - asciidoc $< +# NOTE: the 'source-highlight-args' attribute is not present in the default +# AsciiDoc distribution. It has to be hacked into its +# filters/source/source-highlight-filter.conf like this: +# +# filter="source-highlight -f xhtml -s {language} (...)" +# --> +# filter="source-highlight {source-highlight-args} -f xhtml -s {language} (...)" +%.html: %.txt Makefile lunatic_sh.style + asciidoc -v -a source-highlight-args="--style-file=$(shell pwd)/lunatic_sh.style" $< all: $(FILES) diff --git a/polymer/eduke32/source/lunatic/doc/lunatic.txt b/polymer/eduke32/source/lunatic/doc/lunatic.txt index 5913ae474..9ba2f3bcf 100644 --- a/polymer/eduke32/source/lunatic/doc/lunatic.txt +++ b/polymer/eduke32/source/lunatic/doc/lunatic.txt @@ -6,6 +6,7 @@ Helixhorned :icons: :toc: +:language: lua [red]*DRAFT DRAFT DRAFT* @@ -202,6 +203,7 @@ will place them into this ``hidden'' table. Assuming no subsequent *`return`* is placed at file scope, this table will be the one obtained by a `require` for the module at the client side. +[source] .Example file using using `module` ---------- -- Import section: cache everything the module needs into locals @@ -230,7 +232,8 @@ possible to return its table directly instead of using `module`. However, due to the way modules are loaded, a trailing *`return`* statement must be wrapped in a *`do`*...*`end`* block, like this: -.Example module `MyEnemyDefs.lua` explicitly returning table +.Example module `MyEnemyDefs.lua` explicitly returning a table +[source] ---------- local args = { ... } do return { @@ -431,6 +434,7 @@ event or actor code, the behavior is undefined. Composite variables can be used in various ways. All of them allow indexing with an integer value from `0` to some maximum (sometimes the size of the array minus one, but occasionally less). For example, the code snippet +[source] ---------- local sec = sector[0] ---------- @@ -439,6 +443,7 @@ This reference can then be used to both read and write its members. Various structures also provide _methods_ in Lunatic to modify their state, usable with Lua's `v:func(args...)` syntax. Building on the previous example, +[source] ---------- local cz = sec:ceilingzat(wall[sec.wallptr]) ---------- @@ -449,6 +454,7 @@ Finally, some composite variables offer _static data_, which can contain functions or tables of constants. These are accessed using the dot notation on the composite variable, *not* its constituents. For instance, the following can be used to change the sector number of the sprite with index `i` manually: +[source] ---------- sprite.changesect(i, sectnum) ---------- @@ -545,6 +551,7 @@ Returns a number containing the bits of `bf` bitwise ANDed with those in .Examples ========== After the lines setting sprite `i` to 33% translucent and blocking, +[source] ---------- local CS = sprite.CSTAT local spr = sprite[i] @@ -594,6 +601,7 @@ member names given below. .Different ways of accessing the same member ========== After the code lines +[source] ---------- local sec = sector[0] local ceil = sec.ceiling @@ -859,6 +867,7 @@ top. However, the per-tile z offset is not taken into account. Unconditionally sets the position of `spr` to `pos`, which can be anything indexable with `x`, `y` and `z`. Thus, in effect a shorthand for + +[source] ---------- spr.x, spr.y, spr.z = pos.x, pos.y, pos.z ---------- @@ -901,6 +910,7 @@ the game world, or `sectnum` is an invalid sector index, an error is thrown. Updates the sector number of the sprite with index `i`, in effect setting `sprite[i]`'s sector number to the result of + +[source] ---------- updatesector(sprite[i].pos, sprite[i].sectnum, flags) ---------- @@ -1014,6 +1024,7 @@ Sets the AI of actor `a` to `ai`, which must be an object returned by <>. In addition to setting the current AI ID of the actor, `a:set_ai(ai)` is equivalent to the sequence + +[source] ---------- a:set_action(ai.act) a:set_move(ai.mov, ai.movflags) @@ -1098,6 +1109,7 @@ themselves being of signed 16-bit integer type. The array can be indexed with valid weapon numbers, or weapon names. In the following (constructed) example, the first player's current pistol ammo count is set to that of the currently selected weapon: +[source] ---------- local ps = player[0] ps.ammo_amount.PISTOL = ps.ammo_amount[ps.curr_weapon] @@ -1556,6 +1568,7 @@ keys. Since the vector types are compound objects, they are always passed around by reference. For example, consider executing +[source] ---------- v = xmath.vec3(0, 1) w = v @@ -1730,6 +1743,7 @@ code increments its hidden ``action tics'' counter by four (= 120/30).] .Equivalent `action` definitions ========== Each of the following calls return an action with the same public members: +[source] ---------- con.action{0, 4, delay=20} con.action{0, 4, 1, 1, 20} @@ -1792,6 +1806,7 @@ transfers control to the beginning of the next in the chain if it exists. .`con.longjmp` with chained events ========== The following two chained `EVENT_JUMP` definitions, +[source] ---------- gameevent{"JUMP", function(_, pli) print("jump:first") diff --git a/polymer/eduke32/source/lunatic/doc/lunatic_sh.style b/polymer/eduke32/source/lunatic/doc/lunatic_sh.style new file mode 100644 index 000000000..24a4dff5c --- /dev/null +++ b/polymer/eduke32/source/lunatic/doc/lunatic_sh.style @@ -0,0 +1,10 @@ +// Custom style file for GNU Source-highlight, derived from its default.style + +bgcolor "white"; // the background color for documents +context gray; // the color for context lines (when specified with line ranges) + +keyword darkblue b; // for language keywords +string "#116611" f; // for strings and chars +specialchar pink f; // for special chars, e.g., \n, \t, \\ +comment "#444444" i, noref; // for comments +cbracket red; // for block brackets (e.g. {, })