[cxml-cvs] CVS update: cxml/doc/dom.html cxml/doc/installation.html cxml/doc/quickstart.html cxml/doc/using.html cxml/doc/xmls-compat.html
Update of /project/cxml/cvsroot/cxml/doc In directory common-lisp.net:/tmp/cvs-serv577/doc Modified Files: dom.html installation.html quickstart.html using.html xmls-compat.html Log Message: sink reorganization Date: Thu Dec 29 00:11:19 2005 Author: dlichteblau Index: cxml/doc/dom.html diff -u cxml/doc/dom.html:1.4 cxml/doc/dom.html:1.5 --- cxml/doc/dom.html:1.4 Tue Dec 27 21:17:33 2005 +++ cxml/doc/dom.html Thu Dec 29 00:11:19 2005 @@ -7,6 +7,52 @@ </head> <body> <div class="sidebar"> + <p> + <a href="../README.html">CXML Homepage</a> + </p> + <ul class="main"> + <li> + <a href="installation.html">Installing Closure XML</a> + <ul class="sub"> + <li><a href="installation.html#download"><b>Download</b></a></li> + <li><a href="installation.html#implementations">Implementation-specific notes</a></li> + <li><a href="installation.html#compilation">Compilation</a></li> + <li><a href="installation.html#tests">Tests</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li> + <a href="using.html#quickstart"><b>Quick-Start Example</b></a> + </li> + </ul> + </li> + <li> + <a href="using.html">SAX parser</a> + <ul class="sub"> + <li><a href="using.html#parser">Parsing and Validating</a></li> + <li><a href="using.html#serialization">Serialization</a></li> + <li><a href="using.html#misc">Miscellaneous SAX handlers</a></li> + <li><a href="using.html#rods">Recoders</a></li> + <li><a href="using.html#dtdcache">Caching of DTD Objects</a></li> + <li><a href="using.html#catalogs">XML Catalogs</a></li> + <li><a href="using.html#sax">SAX Interface</a></li> + </ul> + </li> + <li> + <a href="using.html">DOM implementation</a> + <ul class="sub"> + <li><a href="dom.html#parser">Parsing with the DOM builder</a></li> + <li><a href="dom.html#serialization">Serialization</a></li> + <li><a href="dom.html#mapping">DOM/Lisp mapping</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li><a href="xmls-compat.html">XMLS Builder</a></li> + </ul> + </li> + </ul> </div> <h1>The DOM implementation</h1> @@ -54,14 +100,9 @@ <a name="serialization"/> <h3>Serializing DOM</h3> <p> - The technique used to serialize a DOM document is to use a SAX - serialization sink as the argument to <tt>dom:map-document</tt>, - which generates SAX events for the DOM tree. - </p> - <p> - In addition, there are convenience functions like - <tt>unparse-document</tt> as a thin wrapper around - <tt>map-document</tt>. + To serialize a DOM document, use a SAX serialization sink as the + argument to <tt>dom:map-document</tt>, which generates SAX events + for the DOM tree. </p> <p> Applications dealing with namespaces might want to inject a @@ -98,34 +139,6 @@ suppress recoding in this case. </li> </ul> - - <p> - <div class="def">Function CXML:UNPARSE-DOCUMENT (document stream &rest keys)</div> - <div class="def">Function CXML:UNPARSE-DOCUMENT-TO-OCTETS (document &rest keys) => vector</div> - </p> - <p> - Serialize a DOM document object. These convenience functions are - wrappers around <tt>dom:map-document</tt>. - </p> - <p>Keyword arguments are passed on to the sink. C.f. <a - href="using.html#serialization">cxml:make-octet-vector-sink</a>.</p> - <p>Notes:</p> - <ul> - <li> - If keyword argument <tt>canonical</tt> is specified as 2, a - doctype declaration will be written that includes notations - declared in the document. - </li> - </ul> - <p> - <tt>unparse-document-to-octets</tt> returns an <tt>(unsigned-byte - 8)</tt> array, whereas <tt>unparse-document</tt> writes - characters. <tt>unparse-document</tt> is useful together - with <tt>with-output-to-string</tt>. However, note that the - resulting document in both cases is UTF-8 encoded, so the - characters written by <tt>unparse-document</tt> are really UTF-8 - bytes encoded as characters. - </p> <a name="mapping"/> <h3>DOM/Lisp mapping</h3> Index: cxml/doc/installation.html diff -u cxml/doc/installation.html:1.6 cxml/doc/installation.html:1.7 --- cxml/doc/installation.html:1.6 Tue Dec 27 21:01:12 2005 +++ cxml/doc/installation.html Thu Dec 29 00:11:19 2005 @@ -7,6 +7,52 @@ </head> <body> <div class="sidebar"> + <p> + <a href="../README.html">CXML Homepage</a> + </p> + <ul class="main"> + <li> + <a href="installation.html">Installing Closure XML</a> + <ul class="sub"> + <li><a href="installation.html#download"><b>Download</b></a></li> + <li><a href="installation.html#implementations">Implementation-specific notes</a></li> + <li><a href="installation.html#compilation">Compilation</a></li> + <li><a href="installation.html#tests">Tests</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li> + <a href="using.html#quickstart"><b>Quick-Start Example</b></a> + </li> + </ul> + </li> + <li> + <a href="using.html">SAX parser</a> + <ul class="sub"> + <li><a href="using.html#parser">Parsing and Validating</a></li> + <li><a href="using.html#serialization">Serialization</a></li> + <li><a href="using.html#misc">Miscellaneous SAX handlers</a></li> + <li><a href="using.html#rods">Recoders</a></li> + <li><a href="using.html#dtdcache">Caching of DTD Objects</a></li> + <li><a href="using.html#catalogs">XML Catalogs</a></li> + <li><a href="using.html#sax">SAX Interface</a></li> + </ul> + </li> + <li> + <a href="using.html">DOM implementation</a> + <ul class="sub"> + <li><a href="dom.html#parser">Parsing with the DOM builder</a></li> + <li><a href="dom.html#serialization">Serialization</a></li> + <li><a href="dom.html#mapping">DOM/Lisp mapping</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li><a href="xmls-compat.html">XMLS Builder</a></li> + </ul> + </li> + </ul> </div> <h1>Installation of Closure XML</h1> Index: cxml/doc/quickstart.html diff -u cxml/doc/quickstart.html:1.3 cxml/doc/quickstart.html:1.4 --- cxml/doc/quickstart.html:1.3 Tue Dec 27 21:01:12 2005 +++ cxml/doc/quickstart.html Thu Dec 29 00:11:19 2005 @@ -83,10 +83,10 @@ * <b>(dom:get-attribute (dom:document-element *example*) "a")</b> "b"</pre> - <p>Serialize the DOM document back into a stream (<a + <p>Serialize the DOM document back into a file (<a href="using.html#serialization">read more</a>):</p> - <pre><b>(cxml:unparse-document *example* *standard-output*)</b> -<test a="b"><child></child></test></pre> + <pre><b>(with-open-file (out "example.out" :direction :output :element-type '(unsigned-byte 8)) + (dom:map-document (cxml:make-octet-stream-sink out) *example*))</b></pre> <p>As an alternative to DOM, parse into xmls-compatible list structure (<a href="xmls-compat.html">read more</a>):</p> Index: cxml/doc/using.html diff -u cxml/doc/using.html:1.9 cxml/doc/using.html:1.10 --- cxml/doc/using.html:1.9 Tue Dec 27 21:01:12 2005 +++ cxml/doc/using.html Thu Dec 29 00:11:19 2005 @@ -7,6 +7,52 @@ </head> <body> <div class="sidebar"> + <p> + <a href="../README.html">CXML Homepage</a> + </p> + <ul class="main"> + <li> + <a href="installation.html">Installing Closure XML</a> + <ul class="sub"> + <li><a href="installation.html#download"><b>Download</b></a></li> + <li><a href="installation.html#implementations">Implementation-specific notes</a></li> + <li><a href="installation.html#compilation">Compilation</a></li> + <li><a href="installation.html#tests">Tests</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li> + <a href="using.html#quickstart"><b>Quick-Start Example</b></a> + </li> + </ul> + </li> + <li> + <a href="using.html">SAX parser</a> + <ul class="sub"> + <li><a href="using.html#parser">Parsing and Validating</a></li> + <li><a href="using.html#serialization">Serialization</a></li> + <li><a href="using.html#misc">Miscellaneous SAX handlers</a></li> + <li><a href="using.html#rods">Recoders</a></li> + <li><a href="using.html#dtdcache">Caching of DTD Objects</a></li> + <li><a href="using.html#catalogs">XML Catalogs</a></li> + <li><a href="using.html#sax">SAX Interface</a></li> + </ul> + </li> + <li> + <a href="using.html">DOM implementation</a> + <ul class="sub"> + <li><a href="dom.html#parser">Parsing with the DOM builder</a></li> + <li><a href="dom.html#serialization">Serialization</a></li> + <li><a href="dom.html#mapping">DOM/Lisp mapping</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li><a href="xmls-compat.html">XMLS Builder</a></li> + </ul> + </li> + </ul> </div> <h1>Using the SAX parser</h1> @@ -137,12 +183,70 @@ <tt>with-xml-output</tt>, <tt>with-element</tt>, etc). </p> + <div style="background-color: #ddddff"> + Portable sinks:<br/> + <span class="def">Function CXML:MAKE-OCTET-VECTOR-SINK (&rest keys) => sink</span><br/> + <span class="def">Function CXML:MAKE-OCTET-STREAM-SINK (stream &rest keys) => sink</span><br/> + <span class="def">Function CXML:MAKE-ROD-SINK (&rest keys) => sink</span><br/> + <br/> + Only on Lisps with Unicode support:<br/> + <span class="def">Function CXML:MAKE-STRING-SINK</span> -- alias for <tt>cxml:make-rod-sink</tt><br/> + <span class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK (stream &rest keys) => sink</span><br/> + <br/> + Only on Lisps <em>without</em> Unicode support:<br/> + <span class="def">Function CXML:MAKE-STRING-SINK/UTF8 (&rest keys) => sink</span><br/> + <span class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK/UTF8 (stream &rest keys) => sink</span><br/> + </div> <p> - <div class="def">Function CXML:MAKE-OCTET-STREAM-SINK (stream &rest keys) => sink</div> - <div class="def">Function CXML:MAKE-OCTET-VECTOR-SINK (&rest keys) => sink</div> - <div class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK (stream &rest keys) => sink</div> Return a SAX serialization handle. </p> + <ul> + <li> + The <tt>-octet-</tt> functions write the document encoded into + UTF-8. + <tt>make-octet-stream-sink</tt> works with Lisp streams of + element-type <tt>(unsigned-byte 8)</tt>. + <tt>make-octet-vector-sink</tt> returns a vector of + <tt>(unsigned-byte 8)</tt>. + </li> + <li> + <tt>make-character-stream-sink</tt> works with character + streams. It serializes the document into characters <em>without + encoding it into an external format</em>. When using these + functions, <em>take care to avoid encoding the result into + an incorrect external format</em>. (Note that characters undergo + external format conversion when written to a character stream. + If the document's XML declaration specifies an encoding, make + sure to specify this encoding as the external format if and when + writing the serialized document to a character stream. If the + document does not specify an encoding, either UTF-8 or UTF-16 + must be used.) This function is available only on Lisps with + unicode support. + </li> + <li> + <tt>make-rod-sink</tt> serializes the document into a vector of + runes <em>without encoding it into an external format</em>. + (On Lisp with unicode support, the result will be a string; + otherwise, a vector of character codes will be returned.) + The warnings given for <tt>make-character-stream-sink</tt> + apply to this function as well. + </li> + <li> + The <tt>/utf8</tt> functions write the document encoded into + characters representing a UTF-8 encoding. + When using these functions, <em>take care to avoid encoding the + result</em> into an external format for a second time. (Note + that characters undergo external format conversion when written + to a character stream. Since these functions already perform + external format conversion, make sure to specify an external + format that does "nothing" if and when writing the serialized document + to a character stream. ISO-8859-1 external formats usually + achieve the desired effect.) + <tt>make-character-stream-sink/utf8</tt> works with character streams. + <tt>make-string-sink/utf8</tt> returns a string. + These functions are available only on Lisps without unicode support. + </li> + </ul> <p>Keyword arguments:</p> <ul> <li> @@ -170,6 +274,16 @@ <tt>NIL</tt>: Use a more readable non-canonical representation. </li> </ul> + <p> + An internal subset will be included in the result regardless of + the <tt>canonical</tt> setting. It is the responsibility of the + caller to not report an internal subset for + canonical <= 1, or only notations as required for + canonical = 2. For example, the + <tt>include-doctype</tt> argument to <tt>dom:map-document</tt> + should be set to <tt>nil</tt> for the former behaviour and + <tt>:canonical-notations</tt> for the latter. + </p> <p> With an <tt>indentation</tt> level, pretty-print the XML by inserting additional whitespace. Note that indentation Index: cxml/doc/xmls-compat.html diff -u cxml/doc/xmls-compat.html:1.1 cxml/doc/xmls-compat.html:1.2 --- cxml/doc/xmls-compat.html:1.1 Mon Dec 26 23:04:10 2005 +++ cxml/doc/xmls-compat.html Thu Dec 29 00:11:19 2005 @@ -7,6 +7,52 @@ </head> <body> <div class="sidebar"> + <p> + <a href="../README.html">CXML Homepage</a> + </p> + <ul class="main"> + <li> + <a href="installation.html">Installing Closure XML</a> + <ul class="sub"> + <li><a href="installation.html#download"><b>Download</b></a></li> + <li><a href="installation.html#implementations">Implementation-specific notes</a></li> + <li><a href="installation.html#compilation">Compilation</a></li> + <li><a href="installation.html#tests">Tests</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li> + <a href="using.html#quickstart"><b>Quick-Start Example</b></a> + </li> + </ul> + </li> + <li> + <a href="using.html">SAX parser</a> + <ul class="sub"> + <li><a href="using.html#parser">Parsing and Validating</a></li> + <li><a href="using.html#serialization">Serialization</a></li> + <li><a href="using.html#misc">Miscellaneous SAX handlers</a></li> + <li><a href="using.html#rods">Recoders</a></li> + <li><a href="using.html#dtdcache">Caching of DTD Objects</a></li> + <li><a href="using.html#catalogs">XML Catalogs</a></li> + <li><a href="using.html#sax">SAX Interface</a></li> + </ul> + </li> + <li> + <a href="using.html">DOM implementation</a> + <ul class="sub"> + <li><a href="dom.html#parser">Parsing with the DOM builder</a></li> + <li><a href="dom.html#serialization">Serialization</a></li> + <li><a href="dom.html#mapping">DOM/Lisp mapping</a></li> + </ul> + </li> + <li> + <ul class="hack"> + <li><a href="xmls-compat.html">XMLS Builder</a></li> + </ul> + </li> + </ul> </div> <h1>XMLS Builder</h1>
participants (1)
-
dlichteblau＠common-lisp.net