From 75c6d56ffcbcaa4db2be52e703ceb82ac7cd80fc Mon Sep 17 00:00:00 2001
From: David Rose <david@ddrose.com>
Date: Mon, 3 Jun 2002 17:24:22 +0000
Subject: [PATCH] update docs for ppremake 1.1

---
 panda/src/doc/ppremake-syntax.txt    | 56 +++++++++++++++++++++++++++-
 panda/src/doc/ppremake-variables.txt | 10 +++++
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/panda/src/doc/ppremake-syntax.txt b/panda/src/doc/ppremake-syntax.txt
index f085be35fc..fb315385f1 100644
--- a/panda/src/doc/ppremake-syntax.txt
+++ b/panda/src/doc/ppremake-syntax.txt
@@ -113,8 +113,25 @@ Simple commands:
   #print <text>
 
     Outputs the indicated text to standard error as soon as it is
-    encountered.  This is primarily useful for debugging ppremake
-    scripts.
+    encountered.  This is useful for debugging ppremake scripts; and
+    is also a good way to report warnings or status information to the
+    user.
+
+  #printvar <varname> [<varname2> ... ]
+
+    Outputs the literal contents of the named variable(s) to standard
+    error.  The output is similar to what you would get if you executed:
+      #print <varname> = "$[<varname>]" 
+    except the variable contents are not themselves expanded, making
+    it possible to view the exact literal contents of the variables.
+    Note that the variable names should be given without the enclosing
+    $[ ... ] syntax.
+
+  #mkdir <dirname> [<dirname2> ... ]
+
+    Creates the indicated directory names, if they do not already
+    exist.  This will also implicitly create any intervening directory
+    names that are necessary.
 
   #include <filename>
 
@@ -191,6 +208,25 @@ Simple commands:
     #defer, which can only shadow a variable in an enclosing scope,
     but cannot change the parent variable itself).
 
+  #push <count> <varname> [<varname2> ... ]
+
+    Copies the definition of the named variable(s) into the enclosing
+    dynamic scope.  This is primarily useful for defining variables
+    within an #forscopes or #formap block that must be preserved
+    outside the block; normally, since the code within these blocks
+    executes within a different scope, invoking the #define command
+    within these blocks will define a variable only within the
+    referenced scope, and the variable will not be available outside
+    the block.
+
+    The solution is to "push" the variable definition into the
+    immediately enclosing block, which will be the body of the
+    function that invoked the #forscopes command.  It will be as if
+    the variable were defined immediately outside the #forscopes.
+    Normally, a count of 1 should be used; if multiple nested blocks
+    must be pushed through, the count can be increased to indicated
+    the number of levels of nesting.
+
   #map <varname> <key_varname>(<scope_names>)
 
     Defines a new map variable.  A map variable is a unique construct
@@ -282,6 +318,22 @@ Block commands:
     <iterator> is created with the value of the current key, and the
     code is also evaluated within the associated scope.
 
+  #while <condition>
+    ..
+  #end <condition>
+
+    A general while loop, this repeated executes the nested block of
+    code as long as <condition> remains true, i.e. nonempty.
+
+  #for <varname> <start>,<end>[,<increment>]
+    ..
+  #end <varname>
+
+    A specialized iterative loop.  The variable named by <varname> is
+    initialized to the <start> value, then the contents of the loop
+    are repeated, adding <increment> each time, until the variable
+    reaches the <end> value.
+
   #defsub <subname> <params>
     ..
   #end <subname>
diff --git a/panda/src/doc/ppremake-variables.txt b/panda/src/doc/ppremake-variables.txt
index 0db52e397d..153ab21681 100644
--- a/panda/src/doc/ppremake-variables.txt
+++ b/panda/src/doc/ppremake-variables.txt
@@ -412,6 +412,16 @@ value is either the empty string (false) or a nonempty string (true).
     The above all have the obvious semantic meaning, based on a
     numerical comparison of <op1> and <op2>.
 
+  $[+ <op1>,<op2>]
+  $[- <op1>,<op2>]
+  $[- <op1>]
+  $[* <op1>,<op2>]
+  $[/ <op1>,<op2>]
+  $[% <op1>,<op2>]
+    The above perform the appropriate arithmetic operation on <op1>
+    and <op2> (or on <op1> only, in the case of unary minus).  The
+    operation is always integer.
+
   $[not <expr>] - returns true (nonempty) if the expression is empty,
     and false (empty) if the expression is nonempty.