[cxml-cvs] CVS cxml/doc
dlichteblau
dlichteblau at common-lisp.net
Sun Feb 18 12:35:50 UTC 2007
Update of /project/cxml/cvsroot/cxml/doc
In directory clnet:/tmp/cvs-serv24418/doc
Added Files:
GNUmakefile dom.xml html.xsl index.xml installation.xml
klacks.xml quickstart.xml sax.xml xmls-compat.xml
Removed Files:
dom.html installation.html klacks.html quickstart.html
using.html xmls-compat.html
Log Message:
use xsl to build the html documentation from xml
--- /project/cxml/cvsroot/cxml/doc/GNUmakefile 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/GNUmakefile 2007/02/18 12:35:50 1.1
all: dom.html index.html installation.html klacks.html quickstart.html sax.html xmls-compat.html
%.html: %.xml html.xsl
xsltproc html.xsl $< >$@
--- /project/cxml/cvsroot/cxml/doc/dom.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/dom.xml 2007/02/18 12:35:50 1.1
<documentation title="CXML W3C DOM">
<h1>W3C DOM</h1>
<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>
<a name="parser"/>
<h3>Parsing into DOM</h3>
<p>
To parse an XML document into a DOM tree, use the SAX parser with a
DOM builder as the SAX handler. Example:
</p>
<pre>(cxml:parse-file "test.xml" (cxml-dom:make-dom-builder))</pre>
<p>
<div class="def">Function CXML-DOM:MAKE-DOM-BUILDER ()</div>
Create a SAX handler which builds a DOM document.
<p>
</p>
This functions returns a DOM builder that will work with the default
configuration of the SAX parser and is guaranteed to use
characters/strings instead of runes/rods, if that makes a
difference on the Lisp in question.
<p>
</p>
This is the same as <tt>rune-dom:make-dom-builder</tt> on Lisps
with Unicode support, and the same as
<tt>utf8-dom:make-dom-builder</tt> otherwise.
</p>
<p>
<div class="def">Function RUNE-DOM:MAKE-DOM-BUILDER ()</div>
Create a SAX handler which builds a DOM document using runes and rods.
</p>
<p>
<div class="def">Function UTF8-DOM:MAKE-DOM-BUILDER ()</div>
(Only on Lisps without Unicode support:)
Create a SAX handler which builds a DOM document using
UTF-8-encoded strings.
</p>
<a name="serialization"/>
<h3>Serializing DOM</h3>
<p>
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
<a href="sax.html#misc">namespace normalizer</a> into the
sink chain.
</p>
<p>
<div class="def">Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values include-doctype)</div>
Traverse a DOM document and call SAX functions as if an XML
representation of the document was processed by a SAX parser.
</p>
<p>Keyword arguments:</p>
<ul>
<li>
<tt>include-xmlns-attributes</tt> -- defaults to
<tt>sax:*include-xmlns-attributes*</tt>
</li>
<li>
<tt>include-doctype</tt> -- One of <tt>nil</tt> (no doctype
declaration), <tt>:full-internal-subset</tt> (include a doctype
declaration and the full internal subset), or
<tt>:canonical-notations</tt> (write a doctype declaration
with an internal subset including only notations, as required
for canonical serialization).
</li>
<li>
<tt>include-default-values</tt> -- include attribute nodes with nil
<tt>dom:specified</tt>.
</li>
<li>
<tt>recode</tt> -- (ignored on Lisps with Unicode support.) If
true, recode UTF-8 strings to rods. Defaults to true if used
with a UTF-8 DOM document. It can be set to false manually to
suppress recoding in this case.
</li>
</ul>
<a name="mapping"/>
<h3>DOM/Lisp mapping</h3>
<p>
Note that there is no "standard" DOM mapping for Lisp.
</p>
<p>
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.
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>
</documentation>
--- /project/cxml/cvsroot/cxml/doc/html.xsl 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/html.xsl 2007/02/18 12:35:50 1.1
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="html"
indent="yes"
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="documentation">
<html>
<head>
<title>
<xsl:value-of select="@title"/>
</title>
<link rel="stylesheet" type="text/css" href="cxml.css"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<div class="sidebar">
<div class="sidebar-title">
<a href="index.html">Closure XML</a>
</div>
<div class="sidebar-main">
<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="quickstart.html"><b>Quick-Start Example</b></a>
</li>
</ul>
</li>
<li>
<a href="sax.html">SAX parsing and serialization</a>
<ul class="sub">
<li><a href="sax.html#parser">Parsing and Validating</a></li>
<li><a href="sax.html#serialization">Serialization</a></li>
<li><a href="sax.html#misc">Miscellaneous SAX handlers</a></li>
<li><a href="sax.html#rods">Recoders</a></li>
<li><a href="sax.html#dtdcache">Caching of DTD Objects</a></li>
<li><a href="sax.html#catalogs">XML Catalogs</a></li>
<li><a href="sax.html#sax">SAX Interface</a></li>
</ul>
</li>
<li>
<a href="klacks.html">Klacks parser</a>
<ul class="sub">
<li><a href="klacks.html#parsing">Parsing incrementally</a></li>
<li><a href="klacks.html#sax">Bridging Klacks and SAX</a></li>
</ul>
</li>
<li>
<a href="dom.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>
</div>
<xsl:apply-templates/>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
--- /project/cxml/cvsroot/cxml/doc/index.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/index.xml 2007/02/18 12:35:50 1.1
<documentation title="Closure XML">
<h1>Closure XML Parser</h1>
<p>An XML parser written in Common Lisp.</p>
<p>
Closure XML was written by <a
href="http://www.stud.uni-karlsruhe.de/~unk6/">Gilbert Baumann</a>
(unk6 at rz.uni-karlsruhe.de) as part of the Closure web
browser.<br/>
Contributions to the parser by
</p>
<ul>
<li>
Henrik Motakef (hmot at henrik-motakef.de)<br/>
(SAX layer; namespace support)
</li>
<li>
<a href="mailto:david at lichteblau.com">David Lichteblau</a> for <a
href="http://www.knowledgetools.de">knowledgeTools</a>
(conversion into an independent package; DOM bug fixing; validation)
and <a href="http://www.headcraft.de/">headcraft</a>
(most september/october 2004 changes) and privately (changes
since then).
</li>
</ul>
<p>
CXML implements a <a
href="http://www.w3.org/TR/REC-xml-names/">namespace-aware</a>,
validating <a
href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0</a>
parser as well as the <a
href="http://www.w3.org/TR/DOM-Level-2-Core/">DOM Level 2 Core</a>
interfaces. Two parser interfaces are offered, one SAX-like, the
other similar to StAX.
</p>
<p>
CXML is licensed under Lisp-LGPL.
</p>
<p>
Send bug reports to <a
href="mailto:cxml-devel at common-lisp.net">cxml-devel at common-lisp.net</a>
(<a
href="http://common-lisp.net/cgi-bin/mailman/listinfo/cxml-devel">list
information</a>).
</p>
<a name="changes"/>
<h2>Recent Changes</h2>
<p class="nomargin"><tt>rel-2007-xx-yy</tt></p>
<ul class="nomargin">
<li>New StAX-like parser interface.</li>
<li>Serialization fixes (thanks to Nathan Bird, Donavon Keithley).</li>
<li>characters.lisp cleanup (thanks to Nathan Bird).</li>
<li>Namespace normalizer bugfixes.</li>
<li>Minor changes: clone-node on document as an extension. DOM
class hierarchy reworked. New function parse-empty-document.
Fixed the DOM serializer to not throw away local names.
Fixed a long-standing bug in the parser for documents without a
doctype. ANSI conformance fixes.</li>
</ul>
<p class="nomargin"><tt>rel-2006-01-05</tt></p>
<ul class="nomargin">
<li>Implemented DOM 2 Core.</li>
<li>Error handling overhaul.</li>
<li>UTF-8 string support in DOM on Lisps without Unicode characters.</li>
<li>Sink API has been changed.</li>
<li>Support internal subset serialization.</li>
<li>Whitespace normalizer.</li>
<li>Gilbert Baumann has clarified the license as Lisp-LGPL.</li>
<li>Use trivial-gray-streams.</li>
</ul>
<p class="nomargin"><tt>rel-2005-06-25</tt></p>
<ul class="nomargin">
<li>Port to OpenMCL (thanks to Rudi Schlatte).</li>
<li>Port to LispWorks (thanks to Edi Weitz).</li>
<li>Minor new features: <tt>include-default-values</tt> argument to
<tt>make-xmls-builder</tt>; <tt>handler</tt> argument
to <tt>parse-dtd-stream</tt>; SAX proxy class</li>
<li>Various bugfixes.</li>
</ul>
<p class="nomargin"><tt>patch-357</tt> (2004-10-10)</p>
<ul class="nomargin">
<li>Auto-detect unicode support for better asdf-installability.</li>
<li>Use the puri library for Sys-ID handling.</li>
<li>Semi-automatic caching of DTD instances.</li>
<li>Support user-defined entity resolvers.</li>
<li>Support for Oasis XML Catalogs.</li>
<li>xhtmlgen version of Franz htmlgen.</li>
<li>Fixes for SBCL's unicode support.</li>
</ul>
<p class="nomargin"><tt>patch-306</tt> (2004-09-03)</p>
<ul class="nomargin">
<li>Event-based serialization which does not require DOM documents</li>
<li>XMLS compatiblity</li>
<li>minor bugfixes (thread safety; should work on clisp again)</li>
</ul>
<p class="nomargin"><tt>patch-279</tt> (2004-05-11)</p>
<ul class="nomargin">
<li>Validation</li>
<li>bugfixes; XHTML DTD parses again; corrected SAX entity handling</li>
</ul>
<p class="nomargin"><tt>patch-204</tt></p>
<ul class="nomargin">
<li>Renamed package <tt>XML</tt> to <tt>CXML</tt>.</li>
<li>The unparse functions support non-canonical output now.</li>
</ul>
<p class="nomargin"><tt>patch-191</tt> (2004-03-18)</p>
<ul class="nomargin">
<li>Initial release.</li>
</ul>
</documentation>
--- /project/cxml/cvsroot/cxml/doc/installation.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/installation.xml 2007/02/18 12:35:50 1.1
<documentation title="CXML Installation">
<h1>Installation of Closure XML</h1>
<a name="download"/>
<h2>Download</h2>
<ul>
<li>
<div><a href="http://common-lisp.net/project/cxml/download/">tarballs</a></div>
</li>
<li>
<div>
Anoncvs (<a href="http://common-lisp.net/cgi-bin/viewcvs.cgi/cxml/?cvsroot=cxml">browse</a>):
<pre>$ export CVSROOT=:pserver:anonymous at common-lisp.net:/project/cxml/cvsroot
$ cvs login
Logging in to :pserver:anonymous at common-lisp.net:2401/project/cxml/cvsroot
CVS password: anonymous
$ cvs co cxml</pre>
</div>
</li>
</ul>
<a name="implementations"/>
<h2>Implementation-specific notes</h2>
<p>
CXML should be portable to all Common Lisp implementations
supported by <a
href="http://common-lisp.net/project/cl-plus-ssl/#trivial-gray-streams">trivial-gray-streams</a>.
</p>
<ul>
<li>
The SBCL port uses 16 bit surrogate characters instead of taking
advantage of SBCL's full 21 bit character support.
</li>
</ul>
<a name="compilation"/>
<h2>Compilation</h2>
<p>
<a href="http://www.cliki.net/asdf">ASDF</a> is used for
compilation. The following instructions assume that ASDF has
already been loaded.
</p>
<p>
<b>Prerequisites.</b>
CXML needs the <a href="http://www.cliki.net/Puri">puri</a> library
[58 lines skipped]
--- /project/cxml/cvsroot/cxml/doc/klacks.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/klacks.xml 2007/02/18 12:35:50 1.1
[276 lines skipped]
--- /project/cxml/cvsroot/cxml/doc/quickstart.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/quickstart.xml 2007/02/18 12:35:50 1.1
[332 lines skipped]
--- /project/cxml/cvsroot/cxml/doc/sax.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/sax.xml 2007/02/18 12:35:50 1.1
[944 lines skipped]
--- /project/cxml/cvsroot/cxml/doc/xmls-compat.xml 2007/02/18 12:35:50 NONE
+++ /project/cxml/cvsroot/cxml/doc/xmls-compat.xml 2007/02/18 12:35:50 1.1
[1018 lines skipped]
More information about the Cxml-cvs
mailing list