[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
David Lichteblau
dlichteblau at common-lisp.net
Wed Dec 28 23:11:22 UTC 2005
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>
More information about the Cxml-cvs
mailing list