Merge commit '55c7ed6e4d159cebe06999bf61e668284a89cd69' as 'tclxml'

1 files changed, 356 insertions, 0 deletions

diff --git a/tclxml/README.md b/tclxml/README.md
new file mode 100644
index 0000000..7419da1
--- /dev/null
+++ b/tclxml/README.md
@@ -0,0 +1,356 @@
+### TclXML, TclDOM and TclXSLT
+
+Contents
+--------
+
+-   [TclXML](#id18498)
+-   [TclDOM](#id18546)
+-   [TclXSLT](#id18594)
+-   [Installation](#id18619)
+    -   [Dependencies](#id18633)
+    -   [Pure-Tcl Installation](#id18747)
+    -   [Compiled Installation](#id18776)
+        -   [Unix/Linux](#id18786)
+        -   [Windows (MSYS/MINGW)](#id18948)
+        -   [Windows (NMAKE/VC++ 6.0)](#id18987)
+        -   [Macintosh OS X](#id19109)
+-   [Usage](#id19193)
+    -   [Parsing XML, Streaming](#id19216)
+    -   [Parsing XML with DOM](#id19244)
+    -   [Transforming XML with XSLT](#id19268)
+-   [XPath](#id19306)
+
+### TclXML, TclDOM and TclXSLT
+
+This package provides XML parsers, DOM scripting and XSL Transformations
+for [Tcl](http://www.tcl.tk). In previous distributions, these features
+were supplied as separate packages. Now they have been combined into a
+single package to make installation easier.
+
+Contact [Steve Ball](mailto:Steve.Ball@explain.com.au) for information
+about this release.
+
+### TclXML
+
+TclXML provides a streaming parser for XML documents. This is the
+lowest-level interface for processing XML documents in Tcl. The package
+has a generic front-end interface with plugin parser implementations. A
+number of parser implementations or wrappers are provided:
+
+-   Gnome libxml2 library. This package is known as TclXML/libxml2.
+
+-   A generic Tcl implementation (which does not require compilation).
+    This package is known as TclXML/tcl.
+
+Both of these implementations may be installed at the same time. See
+[the manual page](doc/tclxml.html) for more information.
+
+### TclDOM
+
+TclDOM provides a tree view for XML documents. This is usually the best
+interface for scripting XML documents using Tcl. The package has two
+implementations:
+
+-   Gnome libxml2 library. This package is known as TclDOM/libxml2.
+
+-   A generic Tcl implementation (which does not require compilation).
+    This package is known as TclDOM/tcl.
+
+Only one of these will be installed.
+
+See [the manual page](doc/tcldom.html) for more information.
+
+### TclXSLT
+
+TclXSLT provides a method to invoke XSL Transformations upon XML
+documents. This package is a wrapper for the libxslt library.
+
+See [the manual page](doc/tclxslt.html) for more information.
+
+### Installation
+
+#### Dependencies
+
+Tcllib
+
+[http://www.tcl.tk/software/tcllib/](http://www.tcl.tk/software/tcllib/)
+
+In order for the Tcl-only parser to resolve external entities, the
+tcllib package must be installed.
+
+Be sure to get a version which includes the `uri` package. Version 1.11
+or better is recommended.
+
+-   [GZip'd tarball](ftp://prdownloads.sf.net/tcllib/tcllib-1.11.tar.gz)
+
+-   [ZIP file](ftp://prdownloads.sf.net/tcllib/tcllib-1.11.zip)
+
+The latest CVS snapshot may be found at [the SourceForge project
+page](http://sourceforge.net/projects/tcllib).
+
+libxml2
+
+libxml2 is required for the compiled version of the TclXML/libxml2
+package. libiconv may also be required.
+
+The source code for libxml2 and libiconv is *not* supplied with this
+package. Download libxml2 from [xmlsoft.org](http://xmlsoft.org/)
+separately. libiconv may also be required; download from a GNU mirror
+site.
+
+Version 2.7.2 (or better) is recommended.
+
+#### Pure-Tcl Installation
+
+### no compilation required
+
+Run the configure script and invoke the command:
+
+    make install
+
+If the pure-Tcl parser is good enough for you, then read no further.
+
+#### Compiled Installation
+
+##### Unix/Linux
+
+You must have Tcl/Tk version 8.2 or better installed on your system.
+Tcl/Tk 8.3 or better is recommended.
+
+1.  Make sure you have Tcllib 1.11 (or better) installed. Tcllib is
+    still required, even for the compiled parser.
+
+2.  If you wish to use TclXML/libxml2, make sure libxml2-2.7.2 (or
+    better) is installed.
+
+3.  Unpack the TclXML distribution and **cd** into the `tclxml-3.2`
+    directory.
+
+4.  Run the `configure` script, with the --prefix and --enable-threads
+    switches (the latter only if Tcl has been built with threads
+    enabled). Use the --with-xml2-config switch to specify the location
+    of the libxml2 configuration script, `xml2Conf.sh`. Similarly, use
+    the --with-xslt-config if necessary.
+
+    TclXML/libxml2 may be configured to statically link the libxml2 and
+    libxslt libraries to the libtclxml.so shared library. This is
+    advantageous when using TclXML/libxml2 in a StarKit. To statically
+    link the libraries use the --with-xml-static switch.
+
+    For example, on my system I have Tcl 8.5 installed in
+    `/usr/local/tcl8.5` and libxm2 installed in `/usr/local/gnome`. I
+    also need to statically link the libraries. Therefore I would use
+    the command:
+
+        ./configure --prefix=/usr/local/tcl8.5 --enable-threads --with-xml2-config=/usr/local/gnome/bin/xml2Conf.sh --with-xml-static=1
+
+5.  make
+
+6.  Don't test the package using make test until all of the packages are
+    installed (it is a current deficiency of the build system that the
+    package cannot be tested before installation - we hope to fix this
+    soon!).
+7.  make install
+
+    You may need to do this as root, depending on your installation.
+
+8.  make test
+
+9.  make doc
+
+10. make install-doc
+
+##### Windows (MSYS/MINGW)
+
+[Advice: ActiveTcl includes binaries for TclXML.]
+
+You must have Tcl/Tk version 8.2 or better installed on your system.
+Tcl/Tk 8.5.5 or better is recommended.
+
+Before starting, download the binaries for libxml2 (or build them from
+source). [xmlsoft](http://xmlsoft.org/) has a link to the MS Windows
+binary distribution.
+
+If you have a TEA build environment setup, just use the normal
+configure/make/make install pattern.
+
+##### Windows (NMAKE/VC++ 6.0)
+
+TclXML/libxml2 is built with MSYS/MINGW, see above, so this build system
+is untested.
+
+Alternatively, the `win` subdirectory contains a `makefile.vc` file for
+Visual Studio C++ v6.0. In a Command Prompt window set up your
+environment so that `nmake` is on the path (by running `VCVARS32.BAT`),
+then type the following:
+
+    nmake -f makefile.vc TCLDIR=C:\Path\To\Tcl INSTALLDIR=C:\Path\To\Tcl LIBZDIR=C:\Path\To\libz LIBICONVDIR=C:\Path\To\libiconv LIBXML2DIR=C:\Path\To\libxml2 LIBXSLTDIR=C:\Path\To\libxslt
+
+As an example, on my system I have Tcl installed in `C:\Tcl` and the
+libxml2 and libxslt binaries unpacked in the directory `C:\gnome`.
+Accordingly, I would use the following command line:
+
+    nmake -f makefile.vc TCLDIR=C:\Tcl INSTALLDIR=C:\Tcl LIBZDIR=C:\gnome\zlib-1.1.4.win32 LIBICONVDIR=C:\gnome\libiconv-1.9.1.win32 LIBXML2DIR=C:\gnome\libxml2-2.7.2.win32 LIBXSLTDIR=C:\gnome\libxslt-1.1.24.win32
+
+Install the package by appending 'install' to the command line used
+above, for example:
+
+    nmake -f makefile.vc TCLDIR=C:\Path\To\Tcl INSTALLDIR=C:\Path\To\Tcl LIBZDIR=C:\Path\To\libz LIBICONVDIR=C:\Path\To\libiconv LIBXML2DIR=C:\Path\To\libxml2 LIBXSLTDIR=C:\Path\To\libxslt install
+
+##### Macintosh OS X
+
+Binary distributions of libxml2, libxslt and TclXML as frameworks are
+provided by [Explain](http://www.explain.com.au/oss/).
+
+There are two ways to build TclXML under Mac OS X:
+
+1.  The usual Unix way, see above.
+
+2.  As an embedded Framework using Xcode.
+
+The `macosx` directory contains the Xcode files for building under OS X
+(Leopard/Panther). TclXML/libxml2 has been tested on OS X 10.5 (or is
+that X.5?).
+
+Start-up the project. Make sure that the references to the libxml2 and
+Tcl external frameworks are correct. Select the 'Make' target and build.
+This builds everything. The result is two Mac OS X Frameworks; a
+"normal" and an "embedded". The embedded framework will be in the
+`embedded` subdirectory of the Build Products directory. Copy
+`tclxml.framework` to any of the usual places for frameworks
+(`~/Library/Frameworks`, `/Library/Frameworks`, etc).
+
+For earlier version of OS X using Project Builder, you will have to
+retrieve a previous version of the Project Builder files from the CVS
+repository.
+
+### Usage
+
+See [the website](http://tclxml.sourceforge.net/) for links to tutorials
+and the reference manual.
+
+In the meantime, here's a quick tutorial:
+
+#### Parsing XML, Streaming
+
+This is the lowest-level access to an XML document; use SAX-like events
+to stream through the document. The simple program below counts the
+number of characters in the content of an XML document.
+
+    package require xml 3.2
+
+    set parser [xml::parser]
+    $parser configure -elementstartcommand EStart \
+        -characterdatacommand PCData
+
+    proc EStart {tag attlist args} {
+        array set attr $attlist
+        puts "Element \"$tag\" started with [array size attr] attributes"
+    }
+
+    proc PCData text {
+        incr ::count [string length $text]
+    }
+
+    set count 0
+    $parser parse [read stdin]
+
+    puts "The document contains $count characters"
+    exit 0
+
+#### Parsing XML with DOM
+
+This is the next level up in accessing an XML document; use the Document
+Object Model (DOM) to view the XML document as a tree. The simple
+program below counts the number of characters in the content of an XML
+document.
+
+    package require xml 3.2
+
+    set doc [dom::parse [read stdin]]
+    set count 0
+    foreach textNode [dom::selectNode $doc //text()] {
+        incr count [string length [$textNode cget -nodeValue]]
+    }
+
+    puts "The document contains $count characters"
+          
+
+#### Transforming XML with XSLT
+
+This is the highest level in processing an XML document; use a XSL
+stylesheet to transform a XML document. The simple program below reads
+two XML documents, compiles one into a XSL stylesheet and performs the
+transformation.
+
+    package require xml 3.2
+
+    set chan [open "count.xsl"]
+    set styleDoc [dom::parse [read $chan]]
+    close $chan
+    set sourceDoc [dom::parse [read stdin]]
+
+    set style [xslt::compile $styleDoc]
+    set resultDoc [$style transform $sourceDoc]
+
+    puts [dom::serialize $resultDoc]
+          
+
+The XSL stylesheet `count.xsl`, which counts the number of characters in
+the source document, looks like this:
+
+    <xsl:stylesheet version='1.0'
+      xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
+
+      <xsl:template match='/'>
+        <xsl:text>The document contains </xsl:text>
+        <xsl:call-template name='add'>
+          <xsl:with-param name='nodes' select='//text()'/>
+        </xsl:call-template>
+        <xsl:text> characters.
+    </xsl:text>
+      </xsl:template>
+
+      <xsl:template name='add'>
+        <xsl:param name='sum' select='0'/>
+        <xsl:param name='nodes' select='/..'/>
+
+        <xsl:choose>
+          <xsl:when test='not($nodes)'>
+            <xsl:value-of select='$sum'/>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:call-template name='add'>
+              <xsl:with-param name='sum'
+                select='$sum + string-length($nodes[1])'/>
+              <xsl:with-param name='nodes'
+                select='$nodes[position() != 1]'/>
+            </xsl:call-template>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:template>
+    </xsl:stylesheet>
+
+### XPath
+
+In addition to XML parsing packages, TclXML also provides a package for
+parsing XPath location paths. The XPath package only parsing the path's
+syntax, it does interpret the path. See
+[TclDOM](http://tclxml.sourceforge.net/tcldom.html) for a package that
+will interpret XPath location paths.
+
+This package is in its infancy, and does not support the full range of
+XPath features. Only a very limited subset of location paths are
+supported, of the form "/simple/example[2]". Paths within predicates
+will definitely fail.
+
+To use the XPath package:
+
+    package require xpath
+
+To parse a location path:
+
+    xpath::split {/simple/example}
+
+This returns a Tcl list, each element of which is a three element
+sublist: {axis node-test {?predicate ...?}}.