Update of /project/cxml/cvsroot/cxml/doc In directory clnet:/tmp/cvs-serv20218/doc
Modified Files: cxml.css html.xsl index.xml quickstart.xml Log Message: klacks:get-attribute; dribbling source fix; FAQ
--- /project/cxml/cvsroot/cxml/doc/cxml.css 2007/04/22 13:23:54 1.7 +++ /project/cxml/cvsroot/cxml/doc/cxml.css 2007/05/01 18:21:40 1.8 @@ -63,10 +63,15 @@ background-repeat: no-repeat; }
-h1,h2,h3 { +h1 { margin-left: -30px; }
+h2,h3 { + margin-left: -30px; + margin-top: 2em; +} + pre { background-color: #eeeeee; border: solid 1px #d0d0d0; --- /project/cxml/cvsroot/cxml/doc/html.xsl 2007/03/04 21:04:11 1.4 +++ /project/cxml/cvsroot/cxml/doc/html.xsl 2007/05/01 18:21:40 1.5 @@ -4,11 +4,11 @@ doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN" doctype-system="http://www.w3.org/TR/html4/loose.dtd%22/%3E
- <xsl:template match="@*|node()"> - xsl:copy - <xsl:apply-templates select="@*|node()"/> - </xsl:copy> -</xsl:template> + <xsl:template match="@*|node()"> + xsl:copy + <xsl:apply-templates select="@*|node()"/> + </xsl:copy> + </xsl:template>
<xsl:template match="documentation"> <html> @@ -38,7 +38,7 @@ <li> <ul class="hack"> <li> - <a href="quickstart.html"><b>Quick-Start Example</b></a> + <a href="quickstart.html"><b>Quick-Start Example / FAQ</b></a> </li> </ul> </li> @@ -85,4 +85,26 @@ </html> </xsl:template>
+ <xsl:template match="page-index"> + <ul> + <xsl:for-each select="//heading"> + <li> + <a href="#{generate-id()}"> + <xsl:copy> + <xsl:apply-templates select="node()"/> + </xsl:copy> + </a> + </li> + </xsl:for-each> + </ul> + </xsl:template> + + <xsl:template match="heading"> + <a name="{generate-id()}"/> + <h3> + <xsl:copy> + <xsl:apply-templates select="node()"/> + </xsl:copy> + </h3> + </xsl:template> </xsl:stylesheet> --- /project/cxml/cvsroot/cxml/doc/index.xml 2007/04/22 13:23:54 1.5 +++ /project/cxml/cvsroot/cxml/doc/index.xml 2007/05/01 18:21:40 1.6 @@ -48,8 +48,15 @@ information</a>). </p>
+ <h3>See also</h3> + <p> + Relax NG validation is available as a separate + project: <a href="">cxml-rng</a>. + </p> + + <a name="changes"/> - <h2>Recent Changes</h2> + <h3>Recent Changes</h3> <p class="nomargin"><tt>rel-2007-xx-yy</tt></p> <ul class="nomargin"> <li>xml:base support (SAX and Klacks only, not yet used in DOM). --- /project/cxml/cvsroot/cxml/doc/quickstart.xml 2007/02/18 12:35:50 1.1 +++ /project/cxml/cvsroot/cxml/doc/quickstart.xml 2007/05/01 18:21:40 1.2 @@ -1,56 +1,247 @@ <documentation title="CXML Quick-Start Example"> - <h1>Quick-Start Example</h1> + <h1>Quick-Start Example / FAQ</h1>
<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> + <h3> + On this page + </h3> + <page-index/> + + <p> + To try the following examples, 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>
+ <heading>Parsing a file</heading> + <p>Parse <tt>example.xml</tt> into a DOM tree (<a href="sax.html#parser">read more</a>):</p> <pre>* <b>(cxml:parse-file "example.xml" (cxml-dom:make-dom-builder))</b> #<DOM-IMPL::DOCUMENT @ #x72206172> + ;; save result for later: * <b>(defparameter *example* *)</b> *EXAMPLE*</pre>
+ <heading>Using DOM</heading> + <p>Inspect the DOM tree (<a href="sax.html#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> + +* (<b>dom:tag-name</b> (dom:document-element *example*)) "test" -* <b>(dom:child-nodes (dom:document-element *example*))</b> + +* (<b>dom:child-nodes</b> (dom:document-element *example*)) #(#<DOM-IMPL::ELEMENT child @ #x722b6d8a>) -* <b>(dom:get-attribute (dom:document-element *example*) "a")</b> + +* (<b>dom:get-attribute</b> (dom:document-element *example*) <b>"a"</b>) "b"</pre>
+ <heading>Serializing DOM</heading> + <p>Serialize the DOM document back into a file (<a href="sax.html#serialization">read more</a>):</p> - <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> + <pre>(with-open-file (out "example.out" :direction :output :element-type '(unsigned-byte 8)) + <b>(dom:map-document (cxml:make-octet-stream-sink out) *example*)</b></pre> + + <heading>Parsing into XMLS-like lists</heading> + + <p> + If DOM is not the representation you want to you, parsing into + other data structures is possible using the same SAX parser + function, while using a different handler. + The XMLS builder is included for compatibility with XMLS, and also + also sample code (see cxml/xml/xmls-compat.lisp) for your own + handlers. + </p>
<p>As an alternative to DOM, parse into xmls-compatible list structure (<a href="xmls-compat.html">read more</a>):</p> <pre>* <b>(cxml:parse-file "example.xml" (cxml-xmls:make-xmls-builder))</b> ("test" (("a" "b")) ("child" NIL))</pre>
+ <p> + Again, serialization into XML is done using a sink as a SAX + handler and a data-structure specific function to generate SAX + events for the document, in this case <tt>cxml-xmls:map-node</tt>. + </p> + + <pre>* (with-open-file (out "example.out" :direction :output :element-type '(unsigned-byte 8)) + (<b>cxml-xmls:map-node (cxml:make-octet-stream-sink out) + '("test" (("a" "b")) ("child" nil)))</b>)</pre> + + <heading>Parsing incrementally using Klacks</heading> + <p>Use klacks to read events from the parser incrementally. The following example looks only for :start-element and :end-element events and prints them (<a href="klacks.html">read more</a>):</p> <pre>* <b>(klacks:with-open-source - (s (cxml:make-source #p"example.xml")) + (s (cxml:make-source #p"example.xml"))</b> (loop - for key = (klacks:peek s) + for key = <b>(klacks:peek s)</b> while key do (case key (:start-element - (format t "~A {" (klacks:current-qname s))) + (format t "~A {" <b>(klacks:current-qname s)</b>)) (:end-element (format t "}"))) - (klacks:consume s)))</b> + <b>(klacks:consume s)</b>)) test {child {}}</pre> + + <heading>Writing XML</heading> + + <p> + Serialization is always done using sinks, which accept SAX events, + but there are convenience functions and macros to make that easier + to use: + </p> + <pre>(cxml:with-xml-output (cxml:make-octet-stream-sink stream :indentation 2 :canonical nil) + (cxml:with-element "foo" + (cxml:attribute "xyz" "abc") + (cxml:with-element "bar" + (cxml:attribute "blub" "bla")) + (cxml:text "Hi there.")))</pre> + <p> + Prints this to <tt>stream</tt>: + </p> + <pre><foo xyz="abc"> + <bar blub="bla"></bar> + Hi there. +</foo></pre> + + <heading>Help! CXML says 'URI scheme :HTTP not supported'</heading> + + <p> + By default, this error will occur when the DTD (or generally, any + entity) has an http:// URL as its system ID. CXML itself + understands only file:// URLs, but allows users to customize the + behaviour for all URLs. + </p> + + <p> + The are several solutions to this, covered in detail below: + <ul> + <li> + Load the DTD/entity from local files using an entity resolver + </li> + <li> + Skip parsing of the DTD/entity entirely by pretending it is + empty, again using an entity resolver. + </li> + <li> + Use a <em>catalog</em> to make CXML find DTDs in the local + filesystem automatically. + </li> + <li> + Teach CXML actually load DTDs using HTTP. + </li> + </ul> + </p> + + <p> + Here are the example files for the following solutions to this + problem: + </p> + + <a href="http://www.lichteblau.com/blubba/dtdexample.xml"> + <tt>dtdexample.xml</tt>:</a> + <pre><!DOCTYPE test SYSTEM 'http://www.lichteblau.com/blubba/dtdexample.dtd%27%3E +<test a='b'>blub<child/></test></pre> + + <a href="http://www.lichteblau.com/blubba/dtdexample.dtd"> + <tt>dtdexample.dtd</tt></a>: + <pre><!ELEMENT test (#PCDATA|child)*> +<!ATTLIST test + a CDATA #REQUIRED + > + +<!ELEMENT child EMPTY> +</pre> + + <heading>Loading DTDs from local files</heading> + + <p> + Use the :entity-resolver argument to <tt>parse-file</tt> to + specify a function that maps System IDs and Public IDs to local + files of your choice: + </p> + + <pre>(let ((uri "http://www.lichteblau.com/blubba/dtdexample.dtd") + (pathname "dtdexample.dtd")) + (flet ((resolver (pubid sysid) + (declare (ignore pubid)) + <b>(when (puri:uri= sysid (puri:parse-uri uri)) + (open pathname :element-type '(unsigned-byte 8)))</b>)) + (cxml:parse-file "dtdexample.xml" (cxml-dom:make-dom-builder) <b>:entity-resolver #'resolver</b>)))</pre> + + + <heading>Can I skip loading of DTDs entirely?</heading> + + <p> + Yes and no. + </p> + <p> + <i>Yes</i>, you can force CXML to do this, see the following example. + </p> + + <p> + But no, skipping the DTD will not actually work if the document + references entities declared in the DTD, especially since neither + SAX nor DOM are able to report unresolved entity references in + attributes. + </p> + + <p> + The trick to make CXML skip the DTD is to pretend that it is empty + by returning a zero-length stream instead: + </p> + + <pre>(flet ((resolver (pubid sysid) + (declare (ignore pubid sysid)) + <b>(flexi-streams:make-in-memory-input-stream nil)</b>)) + (cxml:parse-file "dtdexample.xml" (cxml-dom:make-dom-builder) <b>:entity-resolver #'resolver</b>))</pre> + + <heading> + Catalogs: How can I use the HTML DTD installed by my distribution? + </heading> + + <p> + Rather than writing an entity resolver function yourself, CXML can + use XML catalogs to find DTDs and entity files on your local system. + </p> + <p> + Catalogs are particularly helpful for DTDs that are + pre-installed. For example, most Linux distributions include a + package for the XHTML DTD. The DTD will reside in a + distribution-dependent location, which the central catalog file + points to. + </p> + <p>By default, CXML looks for the catalog in /etc/xml/catalog + (Linux) and /usr/local/share/xml/catalog.ports (FreeBSD). + </p> + <pre>* <b>(setf cxml:*catalog* (cxml:make-catalog))</b> +* (cxml:parse-file "test.xhtml" (cxml-dom:make-dom-builder))</pre> + + <heading> + Can I load DTDs through HTTP? + </heading> + + <p> + Sure, just use an entity-resolver function that does it. + </p> + <p> + Install <a href="http://weitz.de/drakma/">Drakma</a> and try this: + </p> + <pre>(flet ((resolver (pubid sysid) + (declare (ignore pubid)) + <b>(when (eq (puri:uri-scheme sysid) :http) + (drakma:http-request sysid :want-stream t))</b>)) + (cxml:parse-file "dtdexample.xml" (cxml-dom:make-dom-builder) <b>:entity-resolver #'resolver</b>))</pre> </documentation>
-
dlichteblau