[cxml-cvs] CVS cxml/doc

18 Feb 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@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@common-lisp.net">cxml-devel@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@common-lisp.net:/project/cxml/cvsroot
$ cvs login
Logging in to :pserver:anonymous@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]

[cxml-cvs] CVS cxml/doc

dlichteblau