<!DOCTYPE chapter [
  <!ENTITY current "3.1">
]>
<chapter fileref='tclxml.xml'>
  <title>TclXML</title>
  <subtitle>XML Parsing For Tcl</subtitle>

  <chapterinfo>
    <revhistory>
      <revision>
	<revnumber>1.9</revnumber>
	<date>2005-11-04</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 3.1 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.8</revnumber>
	<date>20040711</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 3.0 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.7</revnumber>
	<date>20040226</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 3.0b2 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.6</revnumber>
	<date>20031215</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 3.0b1 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.5</revnumber>
	<date>20030819</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 3.0rc1 release.</para>
	  <para>Added additional information about TclXML; SAX compliance (lack thereof), etc.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.4</revnumber>
	<date>20020310</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 2.6 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.3.1</revnumber>
	<date>20021210</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Fix link to manual page.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.3</revnumber>
	<date>20021210</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 2.5 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.2</revnumber>
	<date>20021030</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 2.4 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.1</revnumber>
	<date>20020914</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Version 2.3 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.0</revnumber>
	<date>20011206</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Initial version</para>
	</revremark>
      </revision>
    </revhistory>
    <highlights>
      <formalpara>
	<title>Instant Download:</title>
	<para>TclXML v&current; <ulink url="http://prdownloads.sourceforge.net/tclxml/tclxml-&current;.tar.gz">(tarball)</ulink> <ulink url="http://prdownloads.sourceforge.net/tclxml/tclxml-&current;.zip">(zip)</ulink></para>
      </formalpara>
    </highlights>
  </chapterinfo>

  <para>TclXML is an API for parsing XML documents using the Tcl scripting language.  It is also a package with several parser implementations.  The goal of the TclXML package is to provide an API for Tcl scripts that allows "Plug-and-Play" parser implementations; ie. an application will be able to use different parser implementations without change to the application code.</para>

  <section>
    <title>About TclXML</title>

    <para>The TclXML package provides a streaming, or "event-based", interface to an XML document.  An application using TclXML creates a parser "object", sets a number of callback scripts and then instructs the parser to parse an XML document.  The parser scans the XML document's text and as it finds certain constructs, such as the start/end of elements, character data, and so on, it invokes the appropriate callback script.</para>

    <para>This processing model is very similar to SAX.  However, TclXML does not use exactly the same method names, etc, as SAX and so it is not 100% SAX compliant.  Functionally, TclXML is <emphasis>equivalent</emphasis> to SAX2.</para>
  </section>

  <section>
    <title>Parser Implementations</title>

    <para>TclXML v2.X's architecture separates the application interface from the parser implementation, in the same fashion as SAX.  Currently there are two parser implementations available: tcl-parser and expat.  Version 3.0 of TclXML has the same architecture and introduces a new parser class: libxml2.</para>

    <section>
      <title>Pure-Tcl Implementation</title>

      <para>The TclXML package provides a parser implementation written purely as a Tcl script.  When no other parser is available, this one can always be used.</para>

      <para>Having a pure-Tcl parser has some advantages, apart from the obvious advantages in not having to compile any code.  This parser implementation is more configurable, can provide better error reporting and recovery and can also be modified at run-time to achieve various special features.</para>
    </section>

    <section>
      <title>expat</title>

      <para>expat is a C-based XML parser, originally written by James Clark.  It has the advantage of having very high performance.</para>
    </section>

    <section>
      <title>libxml2</title>

      <para><emphasis>Now available!</emphasis></para>

      <para>The Gnome libxml2 library is also a C-based XML parser.  It has the advantage of having high performance, as well as being able to (DTD) validate documents.  The latest version of libxml2 can also perform WXS (W3C XML Schema) schema-validation and Relax-NG validation, but that functionality will be provided by the TclDOM package.</para>

      <para>A wrapper for this library is available as part of version 3.0 of the TclXML package.</para>
    </section>

    <section>
      <title>xerces-c</title>

      <para>Q: I heard that there has been work on a Tcl wrapper for the Apache Xerces-C parser.  What's happening with that?</para>

      <para>A: (SRB) I started writing a module to wrap the Xerces-C++ parser, but got bogged-down, side-tracked and eventually abandoned the effort :-(  However, now that Xerces-C++ supports both DTD and WXS validation, it's probably worth trying to resurrect this subproject - a volunteer is needed!</para>
    </section>
  </section>

  <section>
    <title>Download and Installation</title>

    <para>TclXML v&current; is the current release.  This version is known to work with Tcl v8.1 and above<footnote><para>This package has some support for Tcl v8.0 and earlier, but such usage is untested.  Also, Tcl v8.1 introduced support for Unicode; earlier versions of Tcl will not be able to handle 8-bit and multi-byte characters.</para></footnote>.  Download from SourceForge:</para>
    <itemizedlist>
      <listitem>
	<para><ulink url="http://prdownloads.sourceforge.net/tclxml/tclxml-&current;.tar.gz">Gzip'd tarball</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url="http://prdownloads.sourceforge.net/tclxml/tclxml-&current;.zip">Zip archive</ulink></para>
      </listitem>
    </itemizedlist>

    <para><ulink url="http://sourceforge.net/cvs/?group_id=13178">Pull the CVS tree</ulink> to get the latest-and-greatest code.  The module name is "tclxml".  There are no guarantees that the code is in any particular state (or even working at all).</para>

    <section>
      <title>Installation</title>

      <para>Download the package in one of the forms above and unpack the downloaded file.</para>

      <para>Detailed instructions on how to <ulink url='tclxml/&current;/README.html#installation'>build and install</ulink> TclXML may be found in the <ulink url='tclxml/&current;/README.html'><filename>README</filename></ulink> file.</para>
    </section>
  </section>

  <section>
    <title>Documentation</title>

    <para>You can never have enough...</para>
    <itemizedlist>
      <listitem>
	<para><ulink url="tclxml/&current;/tclxml.html">Reference Manual</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url="tclxml/&current;/README.html">README</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url="tclxml/&current;/RELNOTES.txt">Release notes</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url="tclxml/&current;/ChangeLog.txt">Change log</ulink></para>
      </listitem>
      <listitem>
	<para>Papers</para>
	<itemizedlist>
	  <listitem>
	    <para><ulink url='http://www.zveno.com/papers/Tcl2K2/paper.html'>TclXML: The Next Generation</ulink>.  Presented at the 9th Tcl Workshop, 16-19 September 2002, Vancouver Canada.</para>
	  </listitem>
	  <listitem>
	    <para>XML Support For Tcl.  Tcl Workshop...</para>
	  </listitem>
	</itemizedlist>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Contributing</title>

    <para>Contributions of any kind to the project are welcome.</para>

    <section>
      <title>Reporting Bugs</title>

      <para>An important contribution you can make is to test the package and report any bugs.  Use <ulink url="http://sourceforge.net/tracker/?func=add&amp;group_id=13178&amp;atid=113178">SourceForge bug tracking</ulink> to report problems or request features.  Please make sure you set the category to "TclXML".</para>
    </section>

    <section>
      <title>Sponsorship</title>

      <para>We are very grateful to Invisible Worlds, who sponsored the TclXML project for most of 2000.  Their contribution resulted in the development of XML Namespace support, the xmlswitch command and other features.</para>
    </section>
  </section>

  <section>
    <title>Discussion</title>

    <para>There are three mailing lists for the TclXML project:</para>

    <itemizedlist>
      <listitem>
        <para><ulink url='mailto:tclxml-announce@lists.sourceforge.net'>tclxml-announce</ulink> is a low-volume mailing list for announcements.</para>
      </listitem>
      <listitem>
        <para><ulink url='mailto:tclxml-devel@lists.sourceforge.net'>tclxml-devel</ulink> is for discussion on the development of any of the packages within the TclXML project.</para>
      </listitem>
      <listitem>
        <para><ulink url='mailto:tclxml-users@lists.sourceforge.net'>tclxml-users</ulink> is for discussion on the use of any of the packages within the TclXML project.</para>
      </listitem>
    </itemizedlist>

    <para>There are instructions on SourceForge for subscribing or unsubscribing to any of these mailing lists.</para>

    <para>You might like to view, and contribute to, the <ulink url='http://wiki.tcl.tk/TclXML'>TclXML page</ulink> on the <ulink url='http://wiki.tcl.tk/'>Tcl/Tk Wiki</ulink>.  There are many other pages on the Wiki <ulink url='http://wiki.tcl.tk/XML'>discussing XML</ulink> and its use with Tcl.</para>

    <para>Discussion also takes place on the <ulink url='news:comp.lang.tcl'>comp.lang.tcl</ulink> USENET newsgroup.</para>
  </section>
</chapter>
