1<!DOCTYPE article [
2  <!ENTITY version "2.6">
3]>
4<article>
5  <articleinfo>
6    <title>DOM Binding For Tcl</title>
7    <subtitle>TclDOM</subtitle>
8
9    <releaseinfo>$Id: README.xml,v 1.1 2003/03/09 11:14:56 balls Exp $</releaseinfo>
10
11    <revhistory>
12      <revision>
13	<revnumber>&version;</revnumber>
14      </revision>
15    </revhistory>
16
17    <author>
18      <firstname>Steve</firstname>
19      <surname>Ball</surname>
20      <affiliation>
21	<orgname>Zveno Pty Ltd</orgname>
22	<address>
23	  <otheraddr>
24	    <ulink url='http://www.zveno.com/'>www.zveno.com</ulink>
25	  </otheraddr>
26	</address>
27      </affiliation>
28    </author>
29  </articleinfo>
30
31  <para>This package provides a DOM binding for Tcl.  It provides the following implementations:</para>
32
33  <itemizedlist>
34    <listitem>
35      <para>A Tcl-only implementation (slow, but no compilation required),</para>
36    </listitem>
37    <listitem>
38      <para>A C-based implementation based on TclDOMPro (fast),</para>
39    </listitem>
40    <listitem>
41      <para>A wrapper for the <ulink url='http://xmlsoft.org/'>Gnome libxml2 library</ulink> (also fast and compatiable with <ulink url='http://tclxml.sourceforge.net/tclxslt.html'>TclXSLT/libxslt</ulink>).</para>
42    </listitem>
43  </itemizedlist>
44
45  <para>See <ulink url='http://tclxml.sourceforge.net/'>the TclXML website</ulink> for more information on XML support for Tcl.</para>
46
47  <para>Contact <ulink url='mailto:Steve.Ball@zveno.com'>Steve Ball</ulink> for information about this release.</para>
48
49  <section>
50    <title>Installation</title>
51
52    <para>How you install the package depends on which components you require.</para>
53
54    <section>
55      <title>Dependencies</title>
56
57      <para>All in cases, the following packages must be installed before attempting to install TclDOM.</para>
58
59      <variablelist>
60	<varlistentry>
61	  <term>Tcllib</term>
62	  <listitem>
63	    <para><ulink url='http://dev.scriptics.com/software/tcllib/'>http://dev.scriptics.com/software/tcllib/</ulink></para>
64
65	    <para>In order for the Tcl-only parser to resolve external entities, the tcllib package must be installed.</para>
66
67	    <para>Be sure to get a version which includes the <tclpackage>uri</tclpackage> package.  Version 1.2 or better is recommended.</para>
68	    <itemizedlist>
69	      <listitem>
70		<para><ulink url='ftp://prdownloads.sf.net/tcllib/tcllib-1.3.tar.gz'>GZip'd tarball</ulink></para>
71	      </listitem>
72	      <listitem>
73		<para><ulink url='ftp://prdownloads.sf.net/tcllib/tcllib-1.3.zip'>ZIP file</ulink></para>
74	      </listitem>
75	    </itemizedlist>
76	    <para>The latest CVS snapshot may be found at <ulink url='http://sourceforge.net/projects/tcllib'>the SourceForge project page</ulink>.</para>
77	  </listitem>
78	</varlistentry>
79
80	<varlistentry>
81	  <term>TclXML</term>
82	  <listitem>
83	    <para>First install <ulink url='http://tclxml.sourceforge.net/tclxml.html'>TclXML version &version;</ulink>.</para>
84
85	    <note>You must install the same numbered version as this package, ie. &version;.</note>
86	  </listitem>
87	</varlistentry>
88      </variablelist>
89    </section>
90
91    <section>
92      <title>Pure-Tcl Installation</title>
93      <subtitle>no compilation required</subtitle>
94
95      <para>The <filename>install.tcl</filename> script will install the pure-Tcl DOM implementation.  Run it using <application>wish</application>, eg.</para>
96
97      <programlisting>wish install.tcl</programlisting>
98
99      <note>If Tcl/Tk has been configured correctly on your system, you should be able to simply double-click the script</note>
100
101      <para>If the pure-Tcl parser is good enough for you, then read no further.</para>
102    </section>
103
104    <section>
105      <title>Compiled Installation</title>
106
107      <para>If you need the speed of a compiled DOM implementation, then you have three options:</para>
108
109      <itemizedlist>
110	<listitem>
111	  <para>TclDOM/C (a.k.a. TclDOMPro)</para>
112	</listitem>
113	<listitem>
114	  <para>TclDOM/libxml2</para>
115	</listitem>
116	<listitem>
117	  <para>tDOM (different API to TclDOM, but similar functionality)</para>
118	</listitem>
119      </itemizedlist>
120
121      <section>
122	<title>Compiling TclDOM/libxml2</title>
123
124	<section>
125	  <title>Additional Dependencies</title>
126
127	  <para>In order to build TclDOM/libxml2, first install the libxml2 library itself.  Download libxml2 from <ulink url='http://xmlsoft.org/'>the libxml2 website</ulink>.  There are binary distributions available for some platforms.</para>
128	</section>
129
130	<section>
131	  <title>Unix/Linux</title>
132
133	  <para>You must have Tcl/Tk version 8.2 or better installed on your system.  Tcl/Tk 8.3 or better is recommended.</para>
134
135	  <orderedlist>
136	    <listitem>
137	      <para>Unpack the TclDOM distribution and <command>cd</command> into the <filename>tcldom-&version;</filename> directory.</para>
138	    </listitem>
139	    <listitem>
140	      <para>Run the <filename>configure</filename> script, with the <arg>--prefix</arg>, <arg>--exec_prefix</arg> and <arg>--enable-threads</arg> switches (the latter only if Tcl has been built with threads enabled).</para>
141
142	      <para>For example, on my system I have Tcl 8.4 installed in <filename>/usr/local/tcl8.4</filename> so I would use the command:</para>
143
144	      <programlisting>/configure --prefix=/usr/local/tcl8.4 --exec-prefix=/usr/local/tcl8.4 --enable-threads</programlisting>
145	    </listitem>
146	    <listitem>
147	      <programlisting>make</programlisting>
148	    </listitem>
149	    <listitem>
150	      <programlisting>make install</programlisting>
151
152	      <para>You may have to do this as root</para>
153	    </listitem>
154	    <listitem>
155	      <programlisting>cd src-libxml2</programlisting>
156	    </listitem>
157	    <listitem>
158	      <para>Run the <filename>configure</filename> script, with the same values as above for the <arg>--prefix</arg>, <arg>--exec_prefix</arg> and <arg>--enable-threads</arg> switches.</para>
159
160	      <note>If libxml2 was installed in a non-standard location you might have to add the <arg>--with-xml2-include</arg> and <arg>--with-xml-lib</arg> switches.</note>
161
162	      <note>On Windows the iconv library is required too. See <ulink url='http://www.fh-frankfurt.de/~igor/projects/libxml/'>www.fh-frankfurt.de/~igor/projects/libxml/</ulink> for either precompiled binaries, or a link to the sources.  The relevant options are <arg>--with-iconv-include</arg> and <arg>--with-iconv-lib</arg>.</note>
163
164	      <para>For example, on my Linux system I have Tcl 8.4 installed in <filename>/usr/local/tcl8.4</filename> and libxml2 installed in <filename>/usr/local</filename> so I would use the command:</para>
165
166	      <programlisting>/configure --prefix=/usr/local/tcl8.4 --exec-prefix=/usr/local/tcl8.4 --enable-threads --with-xml2-include=/usr/local/include --with-xml2-lib=/usr/local/lib</programlisting>
167	    </listitem>
168	    <listitem>
169	      <programlisting>make</programlisting>
170	    </listitem>
171	    <listitem>
172	      <programlisting>make install</programlisting>
173
174	      <para>You may have to do this as root</para>
175	    </listitem>
176	  </orderedlist>
177	</section>
178      </section>
179    </section>
180  </section>
181
182  <section>
183    <title>Usage</title>
184
185    <para>See reference documentation.</para>
186</section>
187</article>
188