From 0f0fef8b46d7d41715ed4c1446c06fbbc62747b4 Mon Sep 17 00:00:00 2001
From: driAn <adrian26ch@yahoo.de>
Date: Sat, 17 May 2008 20:50:48 +0000
Subject: [PATCH] docs

git-svn-id: svn://svn.code.sf.net/p/actiongame/code/trunk/ac@2017 e016b1c5-ed68-44aa-a2f7-31cac88cffde
---
 docs/reference.xml                      | 32 +++++-----
 docs/styles/cuberef.css                 | 30 ++++++++-
 docs/transformations/cuberef2xhtml.xslt | 82 ++++++++++++++++++-------
 3 files changed, 105 insertions(+), 39 deletions(-)

diff --git a/docs/reference.xml b/docs/reference.xml
index 01d0ff6a..ee9fc484 100644
--- a/docs/reference.xml
+++ b/docs/reference.xml
@@ -60,16 +60,13 @@
           </arguments>
           <return token="N" description="the modulo value"/>
         </command>
-        <variable name="numargs">
-          <value token="V" description="" minValue="0" maxValue="25" defaultValue="0" />
-        </variable>
         <command name="=">
           <description>Determines if two values are equal.</description>
           <arguments>
             <argument token="A" description="first value"/>
             <argument token="B" description="second value"/>
           </arguments>
-          <return token="N" description="the equality" valueNotes="1 (true) or 0 (false)"/>
+          <return token="N" description="the equality" valueNotes="1 (equal) or 0 (unequal)"/>
         </command>
         <command name="&lt;">
           <description>Determines if a value is smaller than a second value.</description>
@@ -77,7 +74,7 @@
             <argument token="A" description="the first value"/>
             <argument token="B" description="the second value"/>
           </arguments>
-          <return token="N" description="the re" valueNotes="1 (true) or 0 (false)"/>
+          <return token="N" description="the comparison" valueNotes="1 (smaller) or 0 (not smaller)"/>
         </command>
         <command name="&gt;">
           <description>Determines if a value is bigger than a second value.</description>
@@ -85,10 +82,14 @@
             <argument token="A" description="the first value"/>
             <argument token="B" description="the second value"/>
           </arguments>
-          <return token="N" description="the equality" valueNotes="1 (true) or 0 (false)"/>
+          <return token="N" description="the comparison" valueNotes="1 (bigger) or 0 (not bigger)"/>
         </command>
         <command name="rnd">
-        <argument token="A" description="" valueNotes="value" />
+          <description>Random value</description>
+          <arguments>
+            <argument token="A" description="The upper limit of the random value" valueNotes="" />
+          </arguments>
+          <return token="R" description="The random value" valueNotes="larger or equal 0 and smaller than A"/>
         </command>
         <command name="strcmp">
           <description>Determines if two strings are equal.</description>
@@ -96,7 +97,7 @@
             <argument token="A" description="the first string"/>
             <argument token="B" description="the second string"/>
           </arguments>
-          <return token="N" description="the equality" valueNotes="1 (true) or 0 (false)"/>
+          <return token="N" description="the equality" valueNotes="1 (equal) or 0 (unequal)"/>
         </command>
         <command name="if">
           <description>Controls the script flow based on a boolean expression.</description>
@@ -161,16 +162,11 @@
         </command>
         <command name="concat">
           <description>Concatenates multiple strings with spaces inbetween.</description>
-          <remarks>
-            <remark>
-              The newly created string is saved to the alias 's'.
-            </remark>
-          </remarks>
           <examples>
             <example>
               <code>
                 <![CDATA[
-                  alias a "hello"; concat $a "world"; echo $s
+                  alias a "hello"; echo (concat $a "world")
                 ]]>
               </code>
               <explanation>
@@ -182,6 +178,7 @@
             <argument token="S" description="the first string"/>
             <variableArgument token="..." description="collection of strings to concatenate"/>
           </arguments>
+          <return token="R" description="The newly created string"/>
         </command>
         <command name="concatword">
           <description>Concatenates multiple strings.</description>
@@ -194,7 +191,7 @@
             <example>
               <code>
                 <![CDATA[
-                  alias a "Cube"; concatword $a "Script"; echo $s
+                  alias a "Cube"; echo (concatword $a "Script")
                 ]]>
               </code>
               <explanation>
@@ -206,6 +203,7 @@
             <argument token="S" description="the first string"/>
             <variableArgument token="..." description="collection of strings to concatenate"/>
           </arguments>
+          <return token="R" description="The newly created string"/>
         </command>
         <command name="at">
           <description>Grabs a word out of a string.</description>
@@ -254,6 +252,10 @@
             <argument token="C" description="the command to execute"/>
           </arguments>
         </command>
+        <variable name="numargs">
+          <description>The number of arguments passed to the current alias</description>
+          <value token="V" description="numargs" minValue="0" maxValue="25" defaultValue="0" readOnly="true"/>
+        </variable>        
       </identifiers>    
     </section>
     <section name="Gameplay">
diff --git a/docs/styles/cuberef.css b/docs/styles/cuberef.css
index 7c4840ed..a08625fb 100644
--- a/docs/styles/cuberef.css
+++ b/docs/styles/cuberef.css
@@ -255,4 +255,32 @@ div.section div.identifier div.references a.external
 div.section div.identifier div.references span.none
 {
 	
-}
\ No newline at end of file
+}
+
+/* examples */
+
+div.section div.identifier div.examples
+{
+    margin: 0;
+    padding : 0;
+}
+
+div.section div.identifier div.examples div.code
+{
+    margin: 10px 0 10px 0;
+    padding: 0;
+}
+
+div.section div.identifier div.examples div.exampleExplanation
+{
+    margin: 0;
+    padding: 0;
+}
+
+
+/* return value */
+
+div.section div.identifier div.return
+{
+}
+
diff --git a/docs/transformations/cuberef2xhtml.xslt b/docs/transformations/cuberef2xhtml.xslt
index 59ab216a..96059a22 100644
--- a/docs/transformations/cuberef2xhtml.xslt
+++ b/docs/transformations/cuberef2xhtml.xslt
@@ -11,16 +11,18 @@
 
   
   <xsl:template match="t:key">
-    <xsl:choose>
-      <xsl:when test="@name">
-        <xsl:value-of select="@name"/>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:value-of select="@alias"/>
-      </xsl:otherwise>
-    </xsl:choose>
+    <i>
+      <xsl:choose>
+        <xsl:when test="@name">
+          <xsl:value-of select="@name"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="@alias"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </i>
     <xsl:if test="@description">
-      <xsl:text>, </xsl:text>
+      <xsl:text> - </xsl:text>
       <xsl:value-of select="@description"/>
     </xsl:if>
   </xsl:template>
@@ -281,29 +283,63 @@
                       </xsl:if>
                       
                       <!-- return value -->
+                      
                       <xsl:if test="t:return">
                         <p>
-                          Return value: <xsl:value-of select="t:return/@description"/>
+                          Return value: <xsl:value-of select="t:return/@description"/> <xsl:if test="t:return/@valueNotes">, <xsl:value-of select="t:return/@valueNotes"/></xsl:if>
                         </p>
                       </xsl:if>
                       
+                      <!--
+                      <xsl:if test="t:return">
+                        <div class="return">
+                          <table>
+                            <tr>
+                              <th>Return</th>
+                              <th>Description</th>
+                              <th>Values</th>
+                            </tr>
+                            <tr>
+                              <td class="token">
+                                <xsl:value-of select="@token"/>
+                              </td>
+                              <td class="description">
+                                <xsl:value-of select="@description"/>
+                                <xsl:if test="@optional">
+                                  <xsl:text> (optional)</xsl:text>
+                                </xsl:if>
+                              </td>
+                              <td class="values">
+                                <xsl:value-of select="@valueNotes"/>
+                              </td>
+                            </tr>
+                            <xsl:for-each select="t:arguments/*">
+
+                            </xsl:for-each>
+                          </table>
+                        </div>
+                      </xsl:if>
+                      -->
+                        
                       <!-- default keys -->
                       <xsl:if test="t:defaultKeys/*">
                         <div class="defaultKeys">
-                          <xsl:choose>
-                            <xsl:when test="count(t:defaultKeys/*) = 1">
-                              <xsl:text>default key: </xsl:text>
-                              <xsl:apply-templates select="t:defaultKeys/*"/>
-                            </xsl:when>
-                            <xsl:otherwise>
-                              <xsl:text>default keys:</xsl:text>
-                              <br/>
-                              <xsl:for-each select="t:defaultKeys/*">
-                                <xsl:apply-templates select="."/>
+                          <p>
+                            <xsl:choose>
+                              <xsl:when test="count(t:defaultKeys/*) = 1">
+                                <xsl:text>default key: </xsl:text>
+                                <xsl:apply-templates select="t:defaultKeys/*"/>
+                              </xsl:when>
+                              <xsl:otherwise>
+                                <xsl:text>default keys:</xsl:text>
                                 <br/>
-                              </xsl:for-each>
-                            </xsl:otherwise>
-                          </xsl:choose>
+                                <xsl:for-each select="t:defaultKeys/*">
+                                  <xsl:apply-templates select="."/>
+                                  <br/>
+                                </xsl:for-each>
+                              </xsl:otherwise>
+                            </xsl:choose>
+                          </p>
                         </div>
                       </xsl:if>