README.xml
1<!DOCTYPE article [
2 <!ENTITY version "2.6">
3]>
4<article>
5 <articleinfo>
6 <title>XSLT For Tcl</title>
7 <subtitle>A Tcl wrapper for the Gnome libxslt library</subtitle>
8
9 <releaseinfo>$Id: README.xml,v 1.1 2003/03/09 11:30:42 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 Tcl interface to the <ulink url='http://xmlsoft.org/XSLT/'>Gnome libxslt library</ulink>. The libxslt library is loaded into the Tcl interpeter process. XSL stylesheets are compiled and managed by a Tcl object, so reusing a stylesheet is very fast.</para>
32
33 <para>TclXSLT also allows XSLT extensions elements and functions to be implemented as a callback into the application's Tcl code.</para>
34
35 <para>See <ulink url='http://xmlsoft.org/XSLT/'>xmlsoft.org/XSLT</ulink> for more information on the Gnome libxslt library.</para>
36
37 <para>See <ulink url='http://tclxml.sourceforge.net/'>tclxml.sf.net</ulink> for more information on XML support for Tcl.</para>
38
39 <section>
40 <title>Installation</title>
41
42 <para>Follow these steps:</para>
43
44 <orderedlist>
45 <listitem>
46 <para>Install libxml2 and libxslt.</para>
47 </listitem>
48 <listitem>
49 <para>Install TclXML v&version;.</para>
50 </listitem>
51 <listitem>
52 <para>Install TclDOM v&version; with libxml2 support.</para>
53 </listitem>
54 <listitem>
55 <para>Run the <filename>configure</filename> script. Various switches may need to be included, namely <arg>--prefix</arg>, <arg>--exec_prefix</arg>, <arg>--enable-threads</arg>, <arg>--with-xml2-include</arg>, <arg>--with-xml2-lib</arg>, <arg>--with-libxslt-include</arg>, <arg>--with-libxslt-lib</arg>, <arg>--with-libexslt-include</arg>, <arg>--with-libexslt-lib</arg></para>
56
57 <para>For example, on my Linux system I have Tcl 8.4 installed (with threads) in <filename>/usr/local/tcl8.4</filename> and libxml2 and libxslt installed in <filename>/usr/local</filename> so I would use the command:</para>
58
59 <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 --with-libxslt-include=/usr/local/include --with-libxslt-include=/usr/local/lib --with-libexslt-include=/usr/local/include --with-libexslt-include=/usr/local/lib</programlisting>
60 </listitem>
61 <listitem>
62 <programlisting>make</programlisting>
63 </listitem>
64 <listitem>
65 <programlisting>make install</programlisting>
66 <para>You may have to do this as root.</para>
67 </listitem>
68 </orderedlist>
69 </section>
70
71 <section>
72 <title>Usage</title>
73
74 <para>Here's a quick start:</para>
75 <programlisting>
76package require dom &version;
77package require xslt &version;
78
79# First use the TclDOM package to parse the
80# source and stylesheet documents.
81
82set source [dom::libxml2::parse $sourcexml]
83
84# NB. Specifying -baseuri is a good idea
85set styledoc [dom::libxml2::parse $stylexml]
86
87# Now create the stylesheet
88
89set stylesheet [xslt::compile $styledoc]
90
91# Now apply the transformation.
92# The return result is a TclDOM document.
93# Parameters may be supplied as additional arguments.
94
95set result [$stylesheet transform $source name 'value']
96
97# Use TclDOM to serialize the result document.
98
99set resultxml [dom::libxml2::serialize $result]
100</programlisting>
101 </section>
102
103 <section>
104 <title>Extensions</title>
105
106 <para>See <para>test/extension.test</para> for a demonstration of how to implement an extension function as a Tcl callback.</para>
107 </section>
108</article>
109