updating libxslt tutorial to include param support

Mon Jul 23 09:32:27 MDT 2001 John Fleck <jfleck@inkstain.net>

	* updating libxslt tutorial to include param support

doc/tutorial/libxslttutorial.xml

@@ -26,7 +26,7 @@
       <surname>Fleck</surname>
     </author>
     <releaseinfo>
-      This is version 0.2 of the libxslt Tutorial
+      This is version 0.3 of the libxslt Tutorial
     </releaseinfo>
   </articleinfo>
   <abstract>
@@ -136,7 +136,7 @@
 
       <para>Second, set <varname>xmlLoadExtDtdDefaultValue</varname> equal to
 	<parameter>1</parameter>. This tells <application>libxml</application>
-	to load external entity subsets. If you do not do this and the file your
+	to load external entity subsets. If you do not do this and your
 	input file includes entities through external subsets, you will get
 	errors.</para>
     </sect2>
@@ -145,7 +145,7 @@
       <para>Parsing the stylesheet takes a single function call, which takes a
 	variable of type <type>xmlChar</type>:
 	<programlisting>
-	  <varname>cur</varname> = xsltParseStylesheetFile((const xmlChar *)argv[1]);
+	  <varname>cur</varname> = xsltParseStylesheetFile((const xmlChar *)argv[i]);
 	</programlisting>
 	In this case, I cast the stylesheet file name, passed in as a
 	command line argument, to <emphasis>xmlChar</emphasis>. The return value
@@ -160,7 +160,7 @@
       <title>Parse the Input File</title>
       <para>Parsing the input file takes a single function call:
 	<programlisting>
-doc = xmlParseFile(argv[2]);
+doc = xmlParseFile(argv[i]);
 	</programlisting>
 	It returns an <emphasis>xmlDocPtr</emphasis>, a struct in memory that
 	contains the document tree. It can be manipulated directly, but for this
@@ -174,13 +174,13 @@ doc = xmlParseFile(argv[2]);
 	in memory, apply the stylesheet to the document. The
 	function that does this is <function>xsltApplyStylesheet</function>:
 	<programlisting>
-res = xsltApplyStylesheet(cur, doc, NULL);
+res = xsltApplyStylesheet(cur, doc, params);
 	</programlisting>
-	For parameters, the function takes an xsltStylesheetPtr and an
+	The function takes an xsltStylesheetPtr and an
 	xmlDocPtr, the values returned by the previous two functions. The third
-	parameter, NULL in this case, can be used to pass parameters to the
-	stylesheet. It is a NULL-terminated array of name/value pairs of const
-	char's.
+	variable, <varname>params</varname> can be used to pass
+	<acronym>XSLT</acronym> parameters to the stylesheet. It is a
+	NULL-terminated array of name/value pairs of const char's.
       </para>
     </sect2>
 
@@ -206,6 +206,37 @@ xsltSaveResultToFile(stdout, res, cur);
       </para>
     </sect2>
 
+    <sect2 id="parameters">
+      <title>Parameters</title>
+      <para>
+	In <acronym>XSLT</acronym>, parameters may be used as a way to pass
+	additional information to a
+	stylesheet. <application>libxslt</application> accepts
+	<acronym>XSLT</acronym> parameters as one of the values passed to
+	<function>xsltApplyStylesheet</function>.
+      </para>
+      
+      <para>
+	In the tutorial example and in <application>xsltproc</application>,
+	on which the tutorial example is based, parameters to be passed take the
+	form of key-value pairs. The program collects them from command line
+	arguments, inserting them in the array <varname>params</varname>, then
+	passes them to the function. The final element in the array is set to
+	<parameter>NULL</parameter>.
+
+	<note>
+	  <para>
+	    If a parameter being passed is a string rather than an
+	    <acronym>XSLT</acronym> node, it must be escaped. For the tutorial
+	    program, that would be done as follows:
+	    <command>tutorial]$ ./libxslt_tutorial --param rootid "'asect1'"
+	    stylesheet.xsl filename.xml</command>
+	  </para>
+	</note>
+      </para>
+
+    </sect2>
+
     <sect2 id="cleanup">
       <title>Cleanup</title>
       <para>After you are finished, <application>libxslt</application> and