cxml-cvs

Download

cxml-cvs@common-lisp.net

May 2007

1 participants
11 discussions

[cxml-cvs] CVS cxml/doc
by dlichteblau 01 May '07

01 May '07

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"/> - <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">Quick-Start Example</a> + <a href="quickstart.html">Quick-Start Example / FAQ</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>). + <h3>See also</h3> + + Relax NG validation is available as a separate + project: <a href="">cxml-rng</a>. + + + <a name="changes"/> - <h2>Recent Changes</h2> + <h3>Recent Changes</h3> <tt>rel-2007-xx-yy</tt> <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> Make sure to <a href="installation.html#installation">install and load</a> cxml first. - Create a test file called <tt>example.xml</tt>: + <h3> + On this page + </h3> + <page-index/> + + + To try the following examples, create a test file + called <tt>example.xml</tt>: + <pre>* (with-open-file (s "example.xml" :direction :output) (write-string "<test a='b'><child/></test>" s))</pre> + <heading>Parsing a file</heading> + Parse <tt>example.xml</tt> into a DOM tree (<a href="sax.html#parser">read more</a>): <pre>* (cxml:parse-file "example.xml" (cxml-dom:make-dom-builder)) #<DOM-IMPL::DOCUMENT @ #x72206172> + ;; save result for later: * (defparameter *example* *) *EXAMPLE*</pre> + <heading>Using DOM</heading> + Inspect the DOM tree (<a href="sax.html#dom">read more</a>): <pre>* (dom:document-element *example*) #<DOM-IMPL::ELEMENT test @ #x722b6ba2> -* (dom:tag-name (dom:document-element *example*)) + +* (dom:tag-name (dom:document-element *example*)) "test" -* (dom:child-nodes (dom:document-element *example*)) + +* (dom:child-nodes (dom:document-element *example*)) #(#<DOM-IMPL::ELEMENT child @ #x722b6d8a>) -* (dom:get-attribute (dom:document-element *example*) "a") + +* (dom:get-attribute (dom:document-element *example*) "a") "b"</pre> + <heading>Serializing DOM</heading> + Serialize the DOM document back into a file (<a href="sax.html#serialization">read more</a>): - <pre>(with-open-file (out "example.out" :direction :output :element-type '(unsigned-byte 8)) - (dom:map-document (cxml:make-octet-stream-sink out) *example*))</pre> + <pre>(with-open-file (out "example.out" :direction :output :element-type '(unsigned-byte 8)) + (dom:map-document (cxml:make-octet-stream-sink out) *example*)</pre> + + <heading>Parsing into XMLS-like lists</heading> + + + 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. + As an alternative to DOM, parse into xmls-compatible list structure (<a href="xmls-compat.html">read more</a>): <pre>* (cxml:parse-file "example.xml" (cxml-xmls:make-xmls-builder)) ("test" (("a" "b")) ("child" NIL))</pre> + + 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>. + + + <pre>* (with-open-file (out "example.out" :direction :output :element-type '(unsigned-byte 8)) + (cxml-xmls:map-node (cxml:make-octet-stream-sink out) + '("test" (("a" "b")) ("child" nil))))</pre> + + <heading>Parsing incrementally using Klacks</heading> + 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>): <pre>* (klacks:with-open-source - (s (cxml:make-source #p"example.xml")) + (s (cxml:make-source #p"example.xml")) (loop - for key = (klacks:peek s) + for key = (klacks:peek s) while key do (case key (:start-element - (format t "~A {" (klacks:current-qname s))) + (format t "~A {" (klacks:current-qname s))) (:end-element (format t "}"))) - (klacks:consume s))) + (klacks:consume s))) test {child {}}</pre> + + <heading>Writing XML</heading> + + + Serialization is always done using sinks, which accept SAX events, + but there are convenience functions and macros to make that easier + to use: + + <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> + + Prints this to <tt>stream</tt>: + + <pre><foo xyz="abc"> + <bar blub="bla"></bar> + Hi there. +</foo></pre> + + <heading>Help! CXML says 'URI scheme :HTTP not supported'</heading> + + + 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. + + + + 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 catalog to make CXML find DTDs in the local + filesystem automatically. + </li> + <li> + Teach CXML actually load DTDs using HTTP. + </li> + </ul> + + + + Here are the example files for the following solutions to this + problem: + + + <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'> +<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> + + + 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: + + + <pre>(let ((uri "http://www.lichteblau.com/blubba/dtdexample.dtd") + (pathname "dtdexample.dtd")) + (flet ((resolver (pubid sysid) + (declare (ignore pubid)) + (when (puri:uri= sysid (puri:parse-uri uri)) + (open pathname :element-type '(unsigned-byte 8))))) + (cxml:parse-file "dtdexample.xml" (cxml-dom:make-dom-builder) :entity-resolver #'resolver)))</pre> + + + <heading>Can I skip loading of DTDs entirely?</heading> + + + Yes and no. + + + Yes, you can force CXML to do this, see the following example. + + + + 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. + + + + The trick to make CXML skip the DTD is to pretend that it is empty + by returning a zero-length stream instead: + + + <pre>(flet ((resolver (pubid sysid) + (declare (ignore pubid sysid)) + (flexi-streams:make-in-memory-input-stream nil))) + (cxml:parse-file "dtdexample.xml" (cxml-dom:make-dom-builder) :entity-resolver #'resolver))</pre> + + <heading> + Catalogs: How can I use the HTML DTD installed by my distribution? + </heading> + + + Rather than writing an entity resolver function yourself, CXML can + use XML catalogs to find DTDs and entity files on your local system. + + + 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. + + By default, CXML looks for the catalog in /etc/xml/catalog + (Linux) and /usr/local/share/xml/catalog.ports (FreeBSD). + + <pre>* (setf cxml:*catalog* (cxml:make-catalog)) +* (cxml:parse-file "test.xhtml" (cxml-dom:make-dom-builder))</pre> + + <heading> + Can I load DTDs through HTTP? + </heading> + + + Sure, just use an entity-resolver function that does it. + + + Install <a href="http://weitz.de/drakma/">Drakma</a> and try this: + + <pre>(flet ((resolver (pubid sysid) + (declare (ignore pubid)) + (when (eq (puri:uri-scheme sysid) :http) + (drakma:http-request sysid :want-stream t)))) + (cxml:parse-file "dtdexample.xml" (cxml-dom:make-dom-builder) :entity-resolver #'resolver))</pre> </documentation>

1 0