[cxml-cvs] CVS update: cxml/doc/dom.html cxml/doc/quickstart.html cxml/doc/xmls-compat.html cxml/doc/cxml.css cxml/doc/installation.html cxml/doc/using.html
David Lichteblau
dlichteblau at common-lisp.net
Mon Dec 26 22:04:19 UTC 2005
Update of /project/cxml/cvsroot/cxml/doc
In directory common-lisp.net:/tmp/cvs-serv962/doc
Modified Files:
cxml.css installation.html using.html
Added Files:
dom.html quickstart.html xmls-compat.html
Log Message:
dokumentation aufgeteilt
Date: Mon Dec 26 23:04:10 2005
Author: dlichteblau
Index: cxml/doc/cxml.css
diff -u cxml/doc/cxml.css:1.1 cxml/doc/cxml.css:1.2
--- cxml/doc/cxml.css:1.1 Sat Jun 25 15:56:54 2005
+++ cxml/doc/cxml.css Mon Dec 26 23:04:10 2005
@@ -5,19 +5,33 @@
margin: 0em 2pt 1em 2em;
min-width: 15%;
padding: 0pt 5pt 5pt 5pt;
+ font-family: helvetica;
}
-div.sidebar ul {
+div.sidebar ul.main {
padding: 0pt 0pt 0pt 1em;
margin: 0 0 1em;
}
+div.sidebar ul.sub {
+ list-style-type: square;
+ padding: 0pt 0pt 0pt 1em;
+ margin: 0 0 1em;
+}
+
+div.sidebar ul.hack {
+ padding: 0 0 0 0;
+ margin: 0 0 1em;
+ list-style-type: none;
+}
+
body {
color: #000000;
background-color: #ffffff;
margin-right: 0pt;
margin-bottom: 10%;
padding-left: 30px;
+ font-family: helvetica;
}
h1,h2,h3 {
Index: cxml/doc/installation.html
diff -u cxml/doc/installation.html:1.4 cxml/doc/installation.html:1.5
--- cxml/doc/installation.html:1.4 Sun Dec 4 19:43:52 2005
+++ cxml/doc/installation.html Mon Dec 26 23:04:10 2005
@@ -7,35 +7,6 @@
</head>
<body>
<div class="sidebar">
- <p>
- <a href="../README.html">CXML Homepage</a>
- </p>
- <ul>
- <li>
- <a href="installation.html">Installing Closure XML</a>
- <ul>
- <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"><b>Compilation</b></a></li>
- <li><a href="installation.html#tests">Tests</a></li>
- </ul>
- </li>
- <li>
- <a href="using.html">Using Closure XML</a>
- <ul>
- <li><a href="using.html#quickstart"><b>Quick-Start Example</b></a></li>
- <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 Utility Functions</a></li>
- <li><a href="using.html#xmls">XMLS Compatibility</a></li>
- <li><a href="using.html#rods">Dealing with Rods</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>
- <li><a href="using.html#dom">DOM Notes</a></li>
- </ul>
- </li>
- </ul>
</div>
<h1>Installation of Closure XML</h1>
Index: cxml/doc/using.html
diff -u cxml/doc/using.html:1.5 cxml/doc/using.html:1.6
--- cxml/doc/using.html:1.5 Mon Dec 12 00:56:46 2005
+++ cxml/doc/using.html Mon Dec 26 23:04:10 2005
@@ -7,80 +7,17 @@
</head>
<body>
<div class="sidebar">
- <p>
- <a href="../README.html">CXML Homepage</a>
- </p>
- <ul>
- <li>
- <a href="installation.html">Installing Closure XML</a>
- <ul>
- <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"><b>Compilation</b></a></li>
- <li><a href="installation.html#tests">Tests</a></li>
- </ul>
- </li>
- <li>
- <a href="using.html">Using Closure XML</a>
- <ul>
- <li><a href="using.html#quickstart"><b>Quick-Start Example</b></a></li>
- <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 Utility Functions</a></li>
- <li><a href="using.html#xmls">XMLS Compatibility</a></li>
- <li><a href="using.html#rods">Dealing with Rods</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>
- <li><a href="using.html#dom">DOM Notes</a></li>
- </ul>
- </li>
- </ul>
</div>
- <h1>Using Closure XML</h1>
-
- <a name="quickstart"/>
- <h3>Quick-Start Example</h3>
-
- <p>
- Make sure to <a href="installation.html#installation">install and load</a> cxml first.
- </p>
-
- <p>Create a test file called <tt>example.xml</tt>:</p>
- <pre>* <b>(with-open-file (s "example.xml" :direction :output)
- (write-string "<test a='b'><child/></test>" s))</b></pre>
-
- <p>Parse <tt>example.xml</tt> into a DOM tree (<a href="#parser">read
- more</a>):</p>
- <pre>* <b>(cxml:parse-file "example.xml" (dom:make-dom-builder))</b>
-#<DOM-IMPL::DOCUMENT @ #x72206172>
-;; save result for later:
-* <b>(defparameter *example* *)</b>
-*EXAMPLE*</pre>
-
- <p>Inspect the DOM tree (<a href="#dom">read more</a>):</p>
- <pre>* <b>(dom:document-element *example*)</b>
-#<DOM-IMPL::ELEMENT test @ #x722b6ba2>
-* <b>(dom:tag-name (dom:document-element *example*))</b>
-"test"
-* <b>(dom:child-nodes (dom:document-element *example*))</b>
-#(#<DOM-IMPL::ELEMENT child @ #x722b6d8a>)
-* <b>(dom:get-attribute (dom:document-element *example*) "a")</b>
-"b"</pre>
-
- <p>Serialize the DOM document back into a stream (<a
- href="#serialization">read more</a>):</p>
- <pre><b>(cxml:unparse-document *example* *standard-output*)</b>
-<test a="b"><child></child></test></pre>
-
- <p>As an alternative to DOM, parse into xmls-compatible list
- structure (<a href="#xmls">read more</a>):</p>
- <pre>* <b>(cxml:parse-file "example.xml" (cxml-xmls:make-xmls-builder))</b>
-("test" (("a" "b")) ("child" NIL))</pre>
+ <h1>Using the SAX parser</h1>
<a name="parser"/>
<h3>Parsing and Validating</h3>
<p>
+ CXML is implemented as a SAX parser. (Refer to <a
+ href="dom.html#parser">make-dom-builder</a> for information about
+ DOM.)
+ </p>
+ <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>
@@ -175,16 +112,29 @@
<a name="serialization"/>
<h3>Serialization</h3>
<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>
- Serialize a DOM document object. These convenience functions are
- wrappers around <tt>dom:map-document</tt>.
+ Serialization is performed using <tt>sink</tt> objects. A sink
+ is an output stream for runes. There are different kinds of sinks
+ for output to lisp streams, vectors, etc.
+ </p>
+ <p>
+ Technically, sinks are SAX handlers that write XML output for SAX
+ events sent to them. In practise, user code would normally not
+ generate those SAX events manually, and instead use a function
+ like <a href="dom.html#serialization">dom:map-document</a> or <a
+ href="xmls-compat.html">xmls-compat:map-node</a> to serialize an
+ in-memory document.
+ </p>
+ <p>
+ In addition to <tt>map-document</tt>, cxml has a set of
+ convenience macros for serialization (see below for
+ <tt>with-xml-output</tt>, <tt>with-element</tt>, etc).
+ </p>
+
+ <p>
+ <div class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK (stream &rest keys) => sink</div>
+ <div class="def">Function CXML:MAKE-OCTET-VECTOR-SINK (&rest keys) => sink</div>
+ Return a handle suitable for event-based XML serialization.
</p>
- <ul>
- <li><tt>document</tt> -- a DOM document object</li>
- <li><tt>stream</tt> -- a Common Lisp stream with element-type
- <tt>character</tt></li>
- </ul>
<p>Keyword arguments:</p>
<ul>
<li>
@@ -231,12 +181,6 @@
characters written by <tt>unparse-document</tt> are really UTF-8
bytes encoded as characters.
</p>
-
- <p>
- <div class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK (stream &rest keys) => sink</div>
- <div class="def">Function CXML:MAKE-OCTET-VECTOR-SINK (&rest keys) => sink</div>
- Return a handle suitable for event-based XML serialization.
- </p>
<p>
These function provide the low-level mechanism used by the DOM
serialization functions. To serialize a document without building
@@ -272,7 +216,7 @@
</foo></pre>
<p>
(Note that these functions accept both strings and rods, so we
- could write <tt>"foo"</tt> instead of <tt>#"foo"</tt> above.)
+ can write <tt>"foo"</tt> instead of <tt>#"foo"</tt> above.)
</p>
<p>
@@ -303,7 +247,7 @@
(sax:end-document sink))</pre>
<a name="misc"/>
- <h3>Miscellaneous Utility Functions</h3>
+ <h3>Miscellaneous SAX handlers</h3>
<p>
<div class="def">Function CXML:MAKE-VALIDATOR (dtd root)</div>
Create a SAX handler which validates against a DTD instance.
@@ -337,82 +281,11 @@
<p>
Return a SAX handler that performs <a
href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/namespaces-algorithms.html#normalizeDocumentAlgo">DOM
- 3-style namespace normalization</a> on Attribute lists in
+ 3-style namespace normalization</a> on attribute lists in
<tt>start-element</tt> events before passing them on the next
handler.
</p>
- <a name="xmls"/>
- <h3>XMLS Compatibility</h3>
- <p>
- Like other XML parsers written in Lisp, CXML can work with
- documents represented as list structures. The specific model
- implemented by cxml is compatible with the <a
- href="http://common-lisp.net/project/xmls/">xmls parser</a>. Xmls
- list structures are a simpler and faster alternative to full DOM
- document trees. They also serve as an example showing how to
- implement user-defined document models as an independent layer
- over the the base parser (c.f. <tt>xml/xmls-compat.lisp</tt> in
- the cxml distribution). However, note that the list structures do
- not include all information available in DOM documents and are
- sometimes more difficult to work wth since many DOM functions
- cannot be implemented on them.
- </p>
- <p>
- <div class="def">Function CXML-XMLS:MAKE-XMLS-BUILDER (&key include-default-values)</div>
- Create a SAX handler which builds XMLS list structures.
- If <tt>include-default-values</tt> is true, default values for
- attributes declared in a DTD are included as attributes in the
- xmls output. <tt>include-default-values</tt> is true by default
- and can be set to <tt>nil</tt> to suppress inclusion of default
- values.
- </p>
- <p>
- Example:
- </p>
- <pre>(cxml:parse-file "test.xml" (cxml-xmls:make-xmls-builder))</pre>
- <p>
- <div class="def">Function CXML-XMLS:MAP-NODE (handler node &key include-xmlns-attributes)</div>
- Traverse an XMLS document/node and call SAX functions as if an XML
- representation of the document were processed by a SAX parser.
- </p>
- <p>
- Use this function to serialize XMLS data. For example, we could
- define a replacement for <tt>xmls:write-xml</tt> like this:
- </p>
- <pre>(defun write-xml (stream node &key indent)
- (let ((sink (cxml:make-character-stream-sink
- stream :canonical nil :indentation indent)))
- (cxml-xmls:map-node sink node)))</pre>
- <p>
- <div class="def">Function CXML-XMLS:MAKE-NODE (&key name ns attrs
- children) => xmls node</div>
- Build a list node of the form
- (<em>name</em> ((<em>name</em> <em>value</em>)<em>*</em>) <em>child*</em>).
- </p>
- <p>
- The node list's <tt>car</tt> can also be a cons of local <tt>name</tt>
- and namespace prefix <tt>ns</tt>.
- <em>fixme:</em> It is unclear to me how namespaces are meant to
- work in xmls, since xmls documentation differs from how xmls
- actually works in current releases. Usually applications need to
- know both the namespace prefix <em>and</em> the namespace URI. We
- currently follow the xmls <em>implementation</em> and use the
- namespace prefix instead of following its <em>documentation</em> which
- shows the URI. We do not follow xmls in munging xmlns attribute
- values. Attributes themselves have namespaces and it is not clear
- to me how that works in xmls.
- </p>
- <p>
- <div class="def">Accessor CXML-XMLS:NODE-NAME (node)</div>
- <div class="def">Accessor CXML-XMLS:NODE-NS (node)</div>
- <div class="def">Accessor CXML-XMLS:NODE-ATTRS (node)</div>
- <div class="def">Accessor CXML-XMLS:NODE-CHILDREN (node)</div>
- Accessors for xmls node data.
- </p>
- <p>
- </p>
-
<a name="rods"/>
<h3>Dealing with Rods</h3>
<p>
@@ -648,102 +521,5 @@
<p>
<i>fixme</i>: For more information on these functions refer to the docstrings.
</p>
-
-
- <a name="dom"/>
- <h2>DOM Notes</h2>
- <p>
- CXML implements the DOM Level 2 Core interfaces. For details
- on DOM, please refer to the <a
- href="http://www.w3.org/TR/DOM-Level-2-Core/core.html">specification</a>.
- </p>
- <p>
- However, note that there is no "standard" DOM mapping for Lisp. DOM
- is <a
- href="http://www.w3.org/TR/DOM-Level-2-Core/idl-definitions.html">specified
- in CORBA IDL</a>, but it refrains from using object-oriented IDL
- features, allowing for a much more natural Lisp implemenation than
- the the ordinary IDL/Lisp mapping would. The mapping chosen for
- cxml is explained below.
- </p>
-
- <h3>Example</h3>
- <pre>XML(97): (dom:node-type
- (dom:document-element
- (cxml:parse-file "~/test.xml" (dom:make-dom-builder))))
-:ELEMENT</pre>
-
- <h3>CXML-specific functions</h3>
- <p>
- <div class="def">Function DOM:MAKE-DOM-BUILDER ()</div>
- Create a SAX handler which builds a DOM document. Example:
- </p>
- <pre>(cxml:parse-file "test.xml" (dom:make-dom-builder))</pre>
-
- <p>
- <div class="def">Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values)</div>
- Traverse a DOM document and call SAX functions as if an XML
- representation of the document were processed by a SAX parser.
- </p>
- <p>
- <tt>dom:map-document</tt> is the low-level building-block used to
- implement the <a href="#serialization">serialization functions</a>
- like <tt>unparse-document</tt>, but can also be used directly.
- </p>
-
- <h3>DOM/Lisp mapping</h3>
- <p>
- Differences between CXML's DOM and the direct IDL/Lisp mapping:
- </p>
- <ul>
- <li>
- DOM function names are symbols in the <tt>DOM</tt> package (not
- the <tt>OP</tt> package).
- </li>
- <li>
- DOM functions have proper required arguments, not a huge
- <tt>&rest</tt> lambda list.
- </li>
- <li>
- Although most IDL interfaces are implemented as CLOS classes by
- CXML, the Lisp types of DOM objects is not documented and cannot
- be relied upon. A node's type can be determined using
- <tt>dom:node-type</tt> instead.
- </li>
- <li>
- <tt>DOMString</tt> is mapped to <tt>rod</tt>, which is either
- an <tt>(unsigned-byte 16)</tt> array type or a string type.
- </li>
- <li>
- The IDL/Lisp mapping maps CORBA enums to Lisp keywords.
- Unfortunately, the DOM IDL does not use enums. Instead,
- both exception types and node types are defined integer
- constants. CXML chooses to ignore this definition and uses
- keywords instead.
- </li>
- <li>
- DOM uses StudlyCaps. Lisp programmers don't. We
- insert <tt>#\-</tt> before every upper case letter preceded by a
- lower case letter and before every upper case letter which is
- followed by a lower case letter, but preceded by a capital
- letter. This algorithms leads to the natural Lisp spelling
- of DOM function names.
- </li>
- <li>
- Implementation note: DOM's <tt>NodeList</tt> does not
- necessarily map to a native "sequence" type. (For example,
- node lists are objects in Java, not arrays.)
- <tt>NodeList</tt> is specified to reflect changes done after a
- node list was created, so node lists cannot be Lisp lists.
- (A node list could be implemented as a CLOS object pointing to
- said list though.) Instead, CXML currently implements node
- lists as adjustable vectors. Note that code which relies on
- this implementation and uses Lisp sequence functions
- instead of sticking to <tt>dom:item</tt> and <tt>dom:length</tt>
- is not portable. As a compromise, you can use our
- extensions <tt>dom:map-node-list</tt> or
- <tt>dom:do-node-list</tt>, which can be implemented portably.
- </li>
- </ul>
</body>
</html>
More information about the Cxml-cvs
mailing list