--- doc/homework/xml.html	2002/05/23 21:17:19	1.4
+++ doc/homework/xml.html	2002/06/06 07:14:18	1.5
@@ -23,7 +23,8 @@
 	<i>$Apache::lonxml::debug</i> - debugging control
       </li>
       <li>
-	<i>@Apache::lonxml::pwd</i> - path to the directory containing the file currently being processed 
+	<i>@Apache::lonxml::pwd</i> - path to the directory containing
+	the file currently being processed
       </li>
       <li>
 	<i>@Apache::lonxml::outputstack</i> <br />
@@ -41,12 +42,12 @@
 	(images, and links)
       </li>
       <li>
-	<i>#Apache::lonxml::metamode</i> - some output is turned off,
+	<i>$Apache::lonxml::metamode</i> - some output is turned off,
 	the meta target wants a specific subset, use &lt;output&gt; to
 	guarentee that the catianed data will be in the parsing output
       </li>
       <li>
-	<i>#Apache::lonxml::evaluate</i> - controls whether
+	<i>$Apache::lonxml::evaluate</i> - controls whether
 	run::evaluate actually derefences variable references
       </li>
       <li>
@@ -66,15 +67,43 @@
 	<i>$Apache::lonxml::request</i> - current Apache request
 	object, or undef
       </li>
+      <li>
+	<i>$Apache::lonxml::curdepth</i> - current depth of the
+	overall parse depth. Will be a string like: 2_3_1 (first tag
+	in the third second level tag in the second toplevel tag). It
+	gets set by callsub, and can be used in Perl tag
+	implementations. It relies upon the internal globals:
+	<i>@Apache::lonxml::depthcounter</i>,
+	<i>$Apache::lonxml::depth</i>,
+	<i>$Apache::lonxml::olddepth</i>
+      </li>
+      <li>
+	<i>$Apache::lonxml::prevent_entity_encode</i> - By default the
+	xmlparser will try to rencode any 8-bit characters into HTML
+	Entity Codes, If this is set to a true value it will be
+	prevented.
     </ul>
-	
+
+    <p>
+      In common usage, <i>$Apache::lonxml::prevent_entity_encode</i>,
+      <i>$Apache::lonxml::evaluate</i>,
+      <i>$Apache::lonxml::metamode</i>,
+      <i>$Apache::lonxml::import</i>, should never be set to a value
+      directly, but rather incremented when you want the effect on,
+      and decremented when you want the effect off.
+    </p>
+    
     <h3>Notable Perl subroutines</h3>
     <p>
       If not specified these functions are in Apache::lonxml
     </p>
     <ul>
       <li>
-	<i>xmlparse</i> - see the XMLPARSE figure
+	<i>xmlparse</i> - see the XMLPARSE figure - also not callable
+	from inside a tag, if one needs to restart parsing, either
+	create add a new LCParser to the parser stack parser using the
+	newparser function, or call inner_xmlparser, see the xmlparse
+	function in scripttag.pm
       </li>
       <li>
 	<i>recurse</i> - acts just like <i>xmlparse</i>, except it
@@ -105,6 +134,17 @@
 	for this setup. Uses form.grade_ parameters, if the user is
 	allowed to mgr in the course
       </li>
+      <li>
+	<i>setup_globals</i> - initializes all lonxml globals when
+	xmlparse is called. If you intend to create a new target you
+	will likely need to tweak how the globals are setup upon start
+	up.
+      </li>
+      <li>
+	<i>init_safespace</i> - creates Holes to external functions,
+	creates some global variables, and set the permitted operators
+	of the global Safespace intepreter.
+      </li>
     </ul>
     <h3>Functions Tag Handlers can use</h3>
     <p>
@@ -137,14 +177,48 @@
 	Apache::scripttag::start_script for an example of usage.)
       </li>
       <li>
-	<i>get_param</i> - 4 arguments, firsth is a scaler sting of
+	<i>get_param</i> - 4 arguments, first is a scaler sting of
 	the argument needed, second is a reference to the parser
 	arguments stack, third is a reference to the Safe space, and
 	fourth is an optional "context" value. This subroutine allows
 	a tag to get a tag argument, after being interpolated inside
 	the Safe space. This should be used if the tag might use a
 	safe space variable reference for the tag argument. (See
-	Apaceh::scripttag::start_script for an example.)
+	Apache::scripttag::start_script for an example.)
+	
+	This version only handles scalar variables.
+      </li>
+      <li>
+	<i>get_param_var</i> - 4 arguments, first is a scaler sting of
+	the argument needed, second is a reference to the parser
+	arguments stack, third is a reference to the Safe space, and
+	fourth is an optional "context" value. This subroutine allows
+	a tag to get a tag argument, after being interpolated inside
+	the Safe space. This should be used if the tag might use a
+	safe space variable reference for the tag argument. (See
+	Apache::scripttag::start_script for an example.)
+	
+	This version can handle list or hash variables properly.
+      </li>
+      <li>
+	<i>description</i> - 1 argument, the token object. This will
+	return the textual decription of the current tag from the
+	insertlist.tab file.
+      </li>
+      <li>
+	<i>whichuser</i> - 0 arguments. This will take a look at the
+	current environment setting and return the current $symb,
+	$courseid, $udom, $uname. You should always use this function
+	if you want to determine who the current user is. (Since a
+	instructor might be trying to view a students version of a
+	resource.)
+      </li>
+      <li>
+	<i>inner_xmlparse</i> - 6 arguments, the target, an array
+	pointer to the current stack of tags, and array pointer to the
+	current stack of tag arguments, an array pointer to the
+	current stack of LCParser's, a pointer to the current Safe
+	space, a pointer to the hash of current style definitions
       </li>
       <li>
 	<i>newparser</i> - 3 args, first is a reference to the parser
@@ -165,7 +239,14 @@ sub BEGIN {
 }
 </pre>
 	Would tell xmlparse that in Apache::scripttag it can find
-	handlers for &lt;script&gt; and &lt;display&gt;
+	handlers for &lt;script&gt; and &lt;display&gt;, if one
+	regsiters a tag that was already registered the previous one
+	is remembered and will be restored on a deregister.
+      </li>
+      <li>
+	<i>deregister</i> - used to remove a previously registered tag
+	implementation. It will restore the previous registration if
+	there was one.
       </li>
       <li>
 	<i>startredirection</i> - used when a tag wants to save a
@@ -184,7 +265,7 @@ sub BEGIN {
 	a reference to the Safe space, 3 a string to be evaluated
 	before the first arg. This subroutine will do variable
 	interpolation and simple function interpolations on the first
-	argument. (See Apache::lonxml::xmlparse for an example.)
+	argument. (See Apache::lonxml::inner_xmlparse for an example.)
       </li>
       <li>
 	<i>Apache::run::run</i> - 2 args, first a string, second a
@@ -220,7 +301,7 @@ sub BEGIN {
     <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
 <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
 <!-- hhmts start -->
-Last modified: Thu May 23 17:19:29 EDT 2002
+Last modified: Thu Jun  6 01:16:44 EDT 2002
 <!-- hhmts end -->
   </body>
 </html>