lua: docs: refresh and extend the documentation

Signed-off-by: Ferenc Wágner <wferi@niif.hu>

1 files changed, 93 insertions, 128 deletions

diff --git a/com32/lua/doc/syslinux.asc b/com32/lua/doc/syslinux.asc
index 87dbb662..95e0e44e 100644
--- a/com32/lua/doc/syslinux.asc
+++ b/com32/lua/doc/syslinux.asc
@@ -31,127 +31,130 @@ omitted when working interactively.
 SYSLINUX
 ~~~~~~~~
 
-.version()
+version()::
+Return the Syslinux version string.
 
-Returns version string
+derivative()::
+Return the running Syslinux derivative
+(the string +ISOLINUX+, +PXELINUX+ or +SYSLINUX+).
 
-.derivative()
+sleep(s)::
+Sleep for +s+ seconds.
 
-Returns running Syslinux's derivative (ISOLINUX, PXELINUX or SYSLINUX).
-
-.sleep(s)
-
-Sleep for +s+ seconds
-
-.msleep(ms)
-
-Sleep for +ms+ milliseconds
-
-.run_command(command)
+msleep(ms)::
+Sleep for +ms+ milliseconds.
 
+run_command(command)::
 Execute syslinux command line +command+.
-
++
 _Example_:
 ......................................................
 local sl = require "syslinux"
-sl.run_command("memdisk initrd=/dos/BIOS/FSC-P7935-108.img raw")
+sl.run_command "memdisk initrd=/dos/BIOS/FSC-P7935-108.img raw"
 ......................................................
 
-.run_default()
-
-FIXME
-
-.local_boot()
-
-FIXME
-
-.final_cleanup()
-
-FIXME
+run_default()::
+Execute the default command in the configuration.
 
-.boot_linux(kernel, cmdline, [mem_limit], [videomode])
+local_boot(type)::
+Do a local boot. The +type+ values are described in the documentation
+of the LOCALBOOT configuration item.
 
-FIXME
+final_cleanup(flags)::
+Restore sane hardware and software status before booting.  If +flags+
+is 3, keep the PXE and UNDI stacks in memory (see the _keeppxe_ option).
+Only needed in special circumstances.
 
-.IMAGE_TYPE
+boot_linux(kernel[,cmdline])::
+Load and boot the Linux kernel at path +kernel+.  Initramfs images are
+loaded according to the +initrd+ option in +cmdline+.  The
++BOOT_IMAGE+ parameter is added to the command line with the value of
++kernel+.
 
-A table containing the possible kernel types for +run_kernel_image()+.
+IMAGE_TYPE::
+A table mapping the various kernel type strings to the integer +type+
+parameter of +run_kernel_image()+.
 
-.run_kernel_image(kernel, cmdline, ipappend_flags, type)
+run_kernel_image(kernel, cmdline, ipappend_flags, type)::
+Load the specified +kernel+ and run it with +cmdline+.  See also the
+documentation of the IPAPPEND configuration item; +type+ is one of
+the values of the +IMAGE_TYPE+ table.
 
-Run the specified kernel. +type+ is one of the values of the +IMAGE_TYPE+ table.
+loadfile(filename)::
+Return a _file_ object with the contents of file +filename+ loaded.
+Its methods are:
 
-FIXME
+size():::
+Return the size of a loaded _file_.
 
-.loadfile(filname)
+name():::
+Return the name of a loaded _file_.
 
-Load file +filename+
+initramfs()::
+Return an empty _initramfs_ object.  Its methods are:
 
-.filesize(file)
+load(filename):::
+Load contents of +filename+ into an _initramfs_.
 
-Return size of +file+ (loaded by loadfile())
+add_file(filename[,data[,do_mkdir[,mode]]]):::
+Add +filename+ of +mode+ containing +data+ to an _initramfs_.
+If +do_mkdir+, create parent directories, too.  +mode+ defaults
+to 7*64+5*8+5 (which is 0755 in octal).
 
-.filename(file)
+size():::
+Returns the current size of an _initramfs_.
 
-Return name of +file+ (loaded by loadfile())
-
-.initramfs_init()
-
-Return empty initramfs object
-
-.initramfs_load_archive(initramfs, filename)
-
-Load contents of +filename+ into +initramfs+. Initialize
-+initramfs+ with initramfs_init() before use.
-
-.initramfs_add_file(initramfs, file)
-
-Adds +file+ to +initramfs+. +initramfs+ needs to be
-initialized, +file+ has been loaded by loadfile().
+boot_it(kernel[,initramfs,[cmdline]])::
+Boot the loaded +kernel+ (a _file_ object) with an optional
++initramfs+ (an _initramfs_ object or +nil+) and +cmdline+.
 
 _Example_:
 ......................................................
 local sl = require "syslinux"
 
-kernel = sl.loadfile("/SuSE-11.1/x86_64/linux")
-print ("File name: " .. sl.filename (kernel) .. " size: " .. sl.filesize (kernel))
+kernel = sl.loadfile "/SuSE-11.1/x86_64/linux"
+print("File name: " .. kernel:name() .. " size: " .. kernel:size())
 
-initrd = sl.loadfile("/SuSE-11.1/x86_64/initrd")
-print ("File name: " .. sl.filename (initrd) .. " size: " .. sl.filesize (initrd))
+initrd1 = "/SuSE-11.1/x86_64/initrd"
 
-initrd = sl.initramfs_init()
-sl.initramfs_load_archive(initrd, "/SuSE-11.1/x86_64/initrd")
+initrd = sl.initramfs()
+initrd:load(initrd1)
+print ("File name: " .. initrd1 .. " size: " .. initrd:size())
 
 sl.boot_it(kernel, initrd, "init=/bin/bash")
 ......................................................
 
-.KEY
-
+KEY::
 Table containing the return values of +get_key()+ for special (eg. function)
 keys.
 
-.KEY_CTRL(key)
-
+KEY_CTRL(key)::
 Return the code for the Ctrl-modified version of the given ASCII code.
 
-.get_key(timeout)
-
+get_key(timeout)::
 Wait at most +timeout+ ms for a key press.
 Return the ASCII code of the pressed key, some other value of the +KEY+
 table, or +KEY.NONE+ on timeout.
 
+config_file()::
+Return the path of the current config file.
 
-DMI
-~~~
+ipappend_strs()::
+Return the table of SYSAPPEND (formerly IPAPPEND) strings.  See also
+the documentation of those configuration items.
 
-.supported()
+reboot([warm_boot])::
+Reboot.  If +warm_boot+ is nonzero, perform a warm reboot.
 
-Returns +true+ if DMI is supported on machine, +false+ otherwise.
 
-.gettable()
+DMI
+~~~
+
+supported()::
+Return true if DMI is supported on machine, false otherwise.
 
-Returns a list of key-value pairs. The key is one of the DMI property strings:
-FIXME list
+gettable()::
+Return DMI info as a nested table.
 
 _Example_:
 ......................................................
@@ -185,16 +188,14 @@ end
 PCI
 ~~~
 
-.getinfo()
-
-Return list of value pairs (device_index, device) of all PCI devices.
-
-.getidlist(filename)
+getinfo()::
+Return the table of all PCI devices, keyed by the device index.
+Each device is described by a table of its properties.
 
+getidlist(filename)::
 Load a tab separated list of PCI IDs and their description. 
 Sample files can be found here: http://pciids.sourceforge.net/
 
-
 _Example_:
 ......................................................
 local pci = require "pci"
@@ -214,74 +215,38 @@ end
 VESA
 ~~~~
 
-.getmodes()
-
+getmodes()::
 Return list of available VESA modes.
-
++
 _Example_:
 ......................................................
 local vesa = require "vesa"
 
--- get nice output
-printf = function(s,...)
-           return io.write(s:format(...))
-         end
-
--- list available vesa modes
 for mind,mode in pairs(vesa.getmodes()) do
-   printf("%04x: %dx%dx%d\n", mode.mode, mode.hres, mode.vres, mode.bpp)
+   print (string.format ("%04x: %dx%dx%d", mode.mode, mode.hres, mode.vres, mode.bpp))
 end
 ......................................................
 
+setmode()::
+Set the 640x480 VESA mode.
 
-.setmode()
-
-Set (only currently supported) VESA mode.
-
-.load_background(filename)
-
-Load +filename+ from TFTP, and use it as background image.
+load_background(filename)::
+Load +filename+ (a PNG, JPEG or LSS-16 format image), and tile it as
+background image.  The text already present is not erased.
 
 _Example_:
 ......................................................
 local sl = require "syslinux"
 local vesa = require "vesa"
 
--- get nice output
-printf = function(s,...)
-           return io.write(s:format(...))
-         end
-
--- lets go to graphics land
 vesa.setmode()
+vesa.load_background "sample2.jpg"
 
-printf("Hello World! - VESA mode")
-
--- some text to display "typing style"
-textline=[[
-From syslinux GSOC 2009 home page:
-
-Finish the Lua engine
-
-We already have a Lua interpreter integrated with the Syslinux build. However, right now it is not very useful. We need to create a set of bindings to the Syslinux functionality, and have an array of documentation and examples so users can use them.
-
-This is not a documentation project, but the documentation deliverable will be particularly important for this one, since the intended target is system administrators, not developers.
-]]
-
-
--- do display loop
--- keep in mind: background change will not erase text!
-while ( true ) do
-
-vesa.load_background("/background1.jpg")
-
-sl.sleep(1)
-
-for i = 1, #textline do
-    local c = textline:sub(i,i)
-    printf("%s", c)
+for c in string.gmatch ("Hello World! - VESA mode", ".") do
+    io.write (c)
     sl.msleep(200)
 end
 
-sl.sleep(10)
+vesa.load_background "PXE-RRZE_small.jpg"
+sl.sleep(3)
 ......................................................