fix miniswig using wrong stack numbers in functions with HSQUIRRELVM arguments

[supertux.git] / docs / scripting / scripting.xml

diff --git a/docs/scripting/scripting.xml b/docs/scripting/scripting.xml
index 69b8043..637de97 100644 (file)
--- a/docs/scripting/scripting.xml
+++ b/docs/scripting/scripting.xml
@@ -22,17 +22,19 @@ Suite 330, Boston, MA 02111-1307, USA.
 
 -->
 <!--<?xml-stylesheet type="text/xsl" href="/home/ondra/src/docbook-xsl-1.68.1/xhtml/docbook.xsl" ?>-->
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V5.0/EN" "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
 
 <article xml:lang="en">
 
-<artheader>
+<articleinfo>
 <title>SuperTux Scripting Documentation</title>
 <author><firstname>Ondra</firstname><surname>Hosek</surname></author>
-</artheader>
+</articleinfo>
 <para>Since May 2005, SuperTux sports a Squirrel scripting interface useful for level designers who want to add some interactive pep to their levels. This document poses as a reference article for those who want to explore the various objects of the SuperTux scripting model.</para>
 <sect1><title>What is Squirrel?</title>
-<para>One of your first questions might be, &quot;What does a rodent have to do with a penguin?&quot; <link xlink:href="http://squirrel.sourceforge.net/">Squirrel</link> is a language with a syntax not much unlike other C-like languages (C, C++, Java, ...). In the current implementation, it is integrated as elements in the SuperTux level files.</para>
+<para>One of your first questions might be, &quot;What does a rodent have to do
+with a penguin?&quot; <ulink url="http://squirrel.sourceforge.net/">Squirrel</ulink> is a language with a syntax not much unlike other C-like languages (C, C++, Java, ...). In the current implementation, it is integrated as elements in the SuperTux level files.</para>
 </sect1>
 <sect1><title>Squirrel, Scheme and SuperTux</title>
 <para>I have no clue if the developers simply chose Squirrel just because the name so nicely integrates into the series of words &quot;SuperTux&quot; and &quot;Scheme&quot;. Currently, the Squirrel code is integrated in string arguments of Scheme elements in SuperTux level files. (Whew.) This is an example code block inside a level:
@@ -56,10 +58,34 @@ When this level loads, the screen fades out completely during two and a half sec
 
 <sect1><title>Object reference</title>
 <para>If you are interested in an object and what cans of worms you can open with it, this section is for you.</para>
-<para>&quot;(NYI)&quot; after the function name symbolises functions that haven't been implemented yet. Calling them will result in a line being printed to standard output informing anybody who reads it that the script is using a function that actually doesn't exist. (Win32 users will happily ignore this, because they simply start the application by opening it with Explorer. Unix users are going to be more interested of what SuperTux can actually tell them, so it's better if you don't use non-existent functions in your scripts.)</para>
+<para>&quot;(NYI)&quot; after the function name symbolises functions that haven't been implemented yet. Calling them will result in a line being printed to standard output informing anybody who reads it that the script is using a function that actually doesn't exist. (Win32 users will happily ignore this, because they simply start the application by opening it with Explorer. Unix users are going to be more interested in what SuperTux can actually tell them, so it's better if you don't use non-existent functions in your scripts.)</para>
+
+<sect2><title>Global Functions</title>
+<para>These global functions access basic or generic methods of SuperTux. They are called without an object name.</para>
+
+<sect3><title>display_text_file</title>
+<para>Usage: <code>display_text_file(string filename)</code></para>
+<para>Effect: Displays the SuperTux text file named <code>filename</code>. (The path is relative to the level file.)</para>
+<para>See also: SuperTux file format reference, SuperTux texts</para>
+</sect3>
+
+<sect3><title>set_wakeup_time</title>
+<para>Usage: <code>set_wakeup_time(float waketime)</code></para>
+<para>Effect: When used before a call to <code>suspend()</code>, the script only stays suspended for <code>waketime</code> seconds.</para>
+</sect3>
+
+<sect3><title>translate</title>
+<para>Usage: <code>translate(string text)</code></para>
+<para>Returns: Translated string</para>
+<para>Effect: Translates <code>text</code> into the user's locale.</para>
+<para>Note: This construct is not yet recognised by XGetText, and so is subject to change.</para>
+</sect3>
+
+</sect2>
 
 <sect2><title>DisplayEffect</title>
 <para><code>DisplayEffect</code> is an interface for toying with the display.</para>
+
 <sect3><title>fade_out</title>
 <para>Usage: <code>DisplayEffect.fade_out(float fadetime)</code></para>
 <para>Effect: Gradually fades out the screen to black for the next <code>fadetime</code> seconds.</para>
@@ -253,7 +279,7 @@ WOOT.set_animation("left");
 
 <sect3><title>set_visible</title>
 <para>Usage: <code>Text.set_visible(bool visible)</code></para>
-<para>Effect: Shows or hides the text abruptly (drastic counterpart to <code>fade_in</code> and <code>fade_out</code>.</para>
+<para>Effect: Shows or hides the text abruptly (drastic counterpart to <code>fade_in</code> and <code>fade_out</code>).</para>
 </sect3>
 
 </sect2>