<!DOCTYPE chapter [
  <!ENTITY current "3.1">
]>
<chapter fileref='tcldom.xml'>
  <title>TclDOM</title>
  <subtitle>Document Object Model For Tcl</subtitle>

  <chapterinfo>
    <revhistory>
      <revision>
	<revnumber>1.11</revnumber>
	<date>2005-11-04</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 3.1.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.10</revnumber>
	<date>20040711</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 3.0.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.10</revnumber>
	<date>20040226</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 3.0b2.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.9</revnumber>
	<date>20031215</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 3.0b1.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.8</revnumber>
	<date>20020310</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 2.6.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.7.1</revnumber>
	<date>20021210</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Added brief description of example scripts.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.7</revnumber>
	<date>20021210</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 2.5.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.6</revnumber>
	<date>20021110</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 2.4.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.5</revnumber>
	<date>20020914</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Release 2.3.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.4</revnumber>
	<date>20020812</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Point current documentation to v2.2 release man page.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.3</revnumber>
	<date>20020528</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Point current documentation to v2.1 release man page.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.2</revnumber>
	<date>20020301</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Added details on v2.1a1 release.</para>
	</revremark>
      </revision>
      <revision>
	<revnumber>1.1</revnumber>
	<date>20020115</date>
	<authorinitials>SRB</authorinitials>
	<revremark>
	  <para>Added details on v2.0theta 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>TclDOM v&current; <ulink url="http://prdownloads.sourceforge.net/tclxml/tcldom-&current;.tar.gz">(tarball)</ulink> <ulink url="http://prdownloads.sourceforge.net/tclxml/tcldom-&current;.zip">(zip)</ulink></para>
      </formalpara>
    </highlights>
  </chapterinfo>

  <para>TclDOM is a Tcl language binding for the W3C's DOM standard.  DOM provides a tree view of an XML document.  TclDOM is also a package with several implementations, including one written in pure Tcl (TclDOM/tcl), one written in C based on tcldompro (TclDOM/c) and another that wraps the Gnome libxml2 library (TclDOM/libxml2).</para>

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

    <note>To install TclDOM you'll need to first install <ulink url='tclxml.html'>the TclXML package</ulink>.</note>

    <para>TclDOM v&current; is the current release.  Check the release notes for details on what's working and what's not.  Download from SourceForge:</para>
    <itemizedlist>
      <listitem>
	<para><ulink url="http://prdownloads.sourceforge.net/tclxml/tcldom-&current;.tar.gz">Gzip'd tarball</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url="http://prdownloads.sourceforge.net/tclxml/tcldom-&current;.zip">Zip archive</ulink></para>
      </listitem>
    </itemizedlist>

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

    <section>
      <title>Installation</title>

      <para>See the detailed instructions in the <ulink url='tcldom/&current;/README.html'>README</ulink> file.</para>
    </section>
  </section>

  <section>
    <title>Examples</title>

    <para>The TclDOM package distribution includes a number of useful example scripts.  These are as follows:</para>

    <itemizedlist>
      <listitem>
	<para><filename>tkxmllint.tcl</filename></para>
	<para>This application provides a graphical interface for the <application>xmllint</application> command-line tool that is part of Gnome libxml2 library.</para>
      </listitem>
      <listitem>
	<para><filename>cgi2dom.tcl</filename></para>
	<para>The <literal>cgi2dom</literal> package turns a HTTP query string into a DOM tree.</para>
      </listitem>
      <listitem>
	<para><filename>domtext.tcl</filename></para>

	<para>The <literal>domtext</literal> package provides a Tk megawidget.  It makes the Text widget DOM-aware.  Instead of inserting characters into a Text widget, a <literal>domtext</literal> widget is associated with a DOM tree.  The widget displays a text representation of the DOM document.</para>

	<para>A <literal>domtext</literal> widget responds to certain DOM events that occur on its associated DOM tree.  The widget also posts DOM events.  A <literal>domtext</literal> widget allows character data to be edited, and updates the corresponding DOM text node with the new character data.</para>
      </listitem>
      <listitem>
	<para><filename>domtree.tcl</filename></para>

	<para>The <literal>domtree</literal> package provides a BWidget megawidget.  It makes the BWidget Tree widget DOM-aware.  A <literal>domtree</literal> widget may be configured to display a DOM tree, which is represented as a tree of nodes.</para>

	<para>A <literal>domtree</literal> widget responds to certain DOM events that occur on its associated DOM tree.  The widget also posts DOM events.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Documentation</title>

    <para>The more the merrier...</para>

    <itemizedlist>
      <listitem>
	<para><ulink url='tcldom/&current;/tcldom.html'>Reference Manual</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url='tcldom/&current;/README.txt'>README</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url='tcldom/&current;/RELNOTES.txt'>Release notes</ulink></para>
      </listitem>
      <listitem>
	<para><ulink url='tcldom/&current;/ChangeLog.txt'>Change log</ulink></para>
      </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 "TclDOM".</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 XPath support, the xmlswitch command and other features.</para>
    </section>
  </section>

  <section>
    <title>Discussion</title>

    <para>Discussion takes place on the TclXML mailing lists and on comp.lang.tcl.</para>
  </section>
</chapter>
