[cxml-cvs] CVS cxml/doc

[dlichteblau]

Update of /project/cxml/cvsroot/cxml/doc
In directory clnet:/tmp/cvs-serv1313/doc

Modified Files:
	GNUmakefile index.xml sax.xml 
Log Message:
new function cxml:parse


--- /project/cxml/cvsroot/cxml/doc/GNUmakefile	2007/03/04 18:30:40	1.2
+++ /project/cxml/cvsroot/cxml/doc/GNUmakefile	2007/07/07 20:47:38	1.3
@@ -2,4 +2,5 @@
 
 %.html: %.xml html.xsl
 	xsltproc html.xsl $< >$@.tmp
+	chmod -w *.html
 	mv $@.tmp $@
--- /project/cxml/cvsroot/cxml/doc/index.xml	2007/07/05 20:58:15	1.12
+++ /project/cxml/cvsroot/cxml/doc/index.xml	2007/07/07 20:47:38	1.13
@@ -63,6 +63,7 @@
 	Fixed build on non-Unicode lisps.  Fixed parsing on
 	non-Unicode lisps.  Fixed Unicode detection on OpenMCL.
       </li>
+      <li>New function <tt>cxml:parse</tt>.</li>
       <li>Serialization no longer defaults to canonical form.</li>
       <li>Fixed octet array argument to make-source.</li>
       <li>
@@ -83,11 +84,11 @@
     </ul>
     <p class="nomargin"><tt>rel-2007-05-26</tt></p>
     <ul class="nomargin">
-      <li><b>cxml.asd has been split up into <tt>cxml.asd</tt> for the
+      <li>cxml.asd has been split up into <tt>cxml.asd</tt> for the
       XML parser and <tt>runes.asd</tt> for the runes package, in
       preparation of a complete split of the two systems.  Future CXML
       releases will use separate tarballs for <tt>runes</tt>
-      and <tt>cxml</tt>.</b></li>
+      and <tt>cxml</tt>.</li>
       <li>xml:base support (SAX and Klacks only, not yet used in DOM).
       See documentation <a href="sax.html#saxparser">here</a> and <a
       href="klacks.html#locator">here</a>.</li>
--- /project/cxml/cvsroot/cxml/doc/sax.xml	2007/07/01 18:56:09	1.5
+++ /project/cxml/cvsroot/cxml/doc/sax.xml	2007/07/07 20:47:38	1.6
@@ -43,17 +43,63 @@
     </p>
 
     <h3>Parsing and Validating</h3>
+    <div style="border: 1px dotted black;
+		width: 70%;
+		padding: 1em">
+    <p>
+      Old-style convenience functions:
+    </p>
+    <div style="font-weight: bold">Function CXML:PARSE-FILE (pathname handler &key ...)</div>
+    <p style="margin-left: 2em">Same as <tt>cxml:parse</tt> with a pathname argument.
+      (But note that <tt>cxml:parse-file</tt> interprets string
+      arguments as namestrings, while <tt>cxml:parse</tt> expects
+      literal XML documents.)
+    </p>
+    <div style="font-weight: bold">Function CXML:PARSE-STREAM (stream handler &key ...)</div>
+    <p style="margin-left: 2em">Same as <tt>cxml:parse</tt> with a stream argument.</p>
+    <div style="font-weight: bold">Function CXML:PARSE-OCTETS (octets handler &key ...)</div>
+    <p style="margin-left: 2em">Same as <tt>cxml:parse</tt> with an octet vector argument.</p>
+    <div style="font-weight: bold">Function CXML:PARSE-ROD (rod handler &key ...)</div>
+    <p style="margin-left: 2em">Same as <tt>cxml:parse</tt> with a string argument.</p>
+    </div>
+
+    <h4>
+      New all-in-one parser interface:
+    </h4>
+    <div class="def">Function CXML:PARSE (input handler &key ...)</div>
     <p>
-      <div class="def">Function CXML:PARSE-FILE (pathname handler &key ...)</div>
-      <div class="def">Function CXML:PARSE-STREAM (stream handler &key ...)</div>
-      <div class="def">Function CXML:PARSE-OCTETS (octets handler &key ...)</div>
-      <div class="def">Function CXML:PARSE-ROD (rod handler &key ...)</div>
-      Parse an XML document. 
+      Parse an XML document, where input is a string, pathname, octet
+      vector, or stream.
       Return values from this function depend on the SAX handler used.<br/>
       Arguments:
     </p>
     <ul>
-      <li><tt>pathname</tt> -- a Common Lisp pathname</li>
+      <li>
+	<tt>input</tt> -- one of:<br/>
+	<ul>
+	  <li>
+	    <tt>pathname</tt> -- a Common Lisp pathname.  
+	    Open the file specified by the pathname and create a source for
+	    the resulting stream.  See below for information on how to
+            close the stream.
+	  </li>
+	  <li><tt>stream</tt> -- a Common Lisp stream with element-type
+            <tt>(unsigned-byte 8)</tt>.  See below for information on how to
+            close the stream.
+	  </li>
+	  <li>
+	    <tt>octets</tt> -- an <tt>(unsigned-byte 8)</tt> array.
+	    The array is parsed directly, and interpreted according to the
+	    encoding it specifies.
+	  </li>
+	  <li>
+	    <tt>string</tt>/<tt>rod</tt> -- a rod (or <tt>string</tt> on
+	    unicode-capable implementations).
+	    Parses an XML document from the input string that has already
+	    undergone external-format decoding.
+	  </li>
+	</ul>
+      </li>
       <li><tt>stream</tt> -- a Common Lisp stream with element-type
         <tt>(unsigned-byte 8)</tt></li>
       <li><tt>octets</tt> -- an <tt>(unsigned-byte 8)</tt> array</li>