		XML Support For Tcl

		TclXML Version 2.3

		Steve Ball, Zveno Pty Ltd.

This package provides XML parsers for Tcl scripts.  There is a
generic front-end interface with plugin parser implementations.
A number of parser implementations or wrappers are provided:

* James Clark's expat library
* A generic Tcl implementation, 
  if you can't be bothered compiling an extension

The packages define commands in the ::xml Tcl namespace,
xml::parserclass, xml::parser, xml::configure

xml::parserclass info names
	lists the registered parser implementations

xml::parser
	creates a parser instance object

Other packages are also provided to provide support for related
standards.  In particular, work has commenced on the 'xpath'
package for parsing XPath location paths.

See <URL:http://tclxml.sourceforge.net/> for more information
on XML support for Tcl.

Contact Steve Ball <Steve.Ball@zveno.com> for information about 
this release.

INSTALLATION
============

TclXML v2.3 features a pure-Tcl installer.
Future work on the installer will include an 'uninstall' capability,
as well as the capability to build the binary libraries in the 
package from the source.


Dependencies
------------

Tcllib 
< http://dev.scriptics.com/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.2 or better is recommended.
  ftp://prdownloads.sf.net/tcllib/tcllib-1.2.tar.gz
  ftp://prdownloads.sf.net/tcllib/tcllib-1.2.zip

Latest CVS snapshost from http://sourceforge.net/projects/tcllib


Expat

TclExpat requires expat v0.2, with modifications by Ajuba Solutions.
This is now supplied in the expat subdirectory of this distribution
and will maintained until tclxml has been resynchronised with the Expat
project.

Unix/Linux
----------

You must have Tcl/Tk version 8.2 or better installed on your system.
Tcl/Tk 8.3 or better is recommended.

0. You can skip this step if you only want to use the Tcl-only parser.

   Use the expat package included in the distribution, unless you want
   to tackle porting the latest expat code yourself 8-). Follow the 
   instructions in the expat directory and take note of the location of the 
   library and header files. The expat build has been modified to use TEA
   based configuration and needs to find the tclConfig.sh script so the 
   usual approach will to _BUILD_ the expat library will be :

      cd expat
      make distclean            # if Makefile already exists
      ./configure  --with-tcl=/path/to/tcl/libraries
      make 


1. Run the configure script.  With no switches, only the Tcl-only
   parser will be installed.

   To build TclExpat use "--enable-expat".  The expat library will
   be searched for.  If it is not found then TclExpat will not be
   built.  The switch "--with-expat=dir" can be used to give an explicit 
   path for the library. Configure will attempt to discover the location
   of the expat header files based on this directory. The switch 
   "--with-expat-inc=dir" can be used to give an explicit path. 

2. "make"

3a. "make install"

3b. Alternatively, use the tcl/tk based installer install.tcl to install
    the package. Either cd to the build directory and just invoke the installer 
    or use command line options to designate the build directory.
    For the simplest build (i.e. built in src dir) :
	wish installer.tcl
    For multiple builds (e.g. Linux target dir in 'build' subdir)
        wish ./installer.tcl -builddir build/Linux
    or
	cd build/Linux
        wish ../../installer.tcl

   Various screens will appear allowing you to select where the
   package is installed, what optional files can be installed
   and showing a log of the installation process.

   Currently both methods install all of the configured parser implementations.
   The Tcl-only parser is always installed.

        
 

WINDOWS (MS VC++) 
-----------------
You must have Tcl/Tk version 8.2 or better installed on your system.
Tcl/Tk 8.3 or better is recommended. 
 

1. Run MS Visual C++ and load the tclxml workspace in the win subdirectory.
   There are project files for tclxml, tclexpat & expat. The active project
   will be the Release version of tclexpat. 
   
2. To build tclxml w/o tclexpat, select the tclxml project and just build that.
 
3. Installation
 
   Since you must have tcl/tk installed already (!) you might like to use the 
   new installer that we have been working on.

   You can install one of multiple builds (Release/Debug etc) by invoking the 
   install.tcl script  and specifying the directory path to the build , or 
   by invoking the installer from the build directory directly :

   cd win
   wish ../install.tcl -builddir Release

   or

   cd win/Release
   wish ../../install.tcl

   Various screens will appear allowing you to select where the
   package is installed, what optional components can be installed
   and showing a log of the installation process.

   If that doesnt do the deed you need to do some hard yards :

   - Copy the DLL's in the target build subdirectory (win/Release or win/Debug)
   to a directory which is in your execution PATH (the same directory as your
   TCL/TK binaries is an obvious one).

   - Copy the top level library subdirectory and its contents into a directory
   which will be part of the autoexec_path in any TCL/TK apps that will 
   need to load the tclxml modules (the lib subdirectory of your TCL/TK
   installation is one) . Rename the directory to tclxml2.0 .

   - Rename the file pkgIndex.tcl.in in this directory to pkgIndex.tcl, and edit the
   file, replacing any macros (strings with leading and trailing '@''s) 
   with approriate directory/lib/paths. 

   @RELPATH@              = relative path between the library directory 
                            & the dll's directory
   @TCLXML_LIB_FILE@      = tclxml.dll
   @expat_TCL_LIB_FILE@   = tclexpat.dll


MACINTOSH OS X
--------------

The 'macosx' directory contains the Project Builder files
for building under OS X.  TclXML has been tested on 10.1.5.
[instructions not yet complete]

MACINTOSH OS 9 (or earlier)
---------------------------

The installer script doesn't work properly on Macintosh yet, 
and the binary parsers have not been ported yet (sorry).

Since the distribution has an all-Tcl parser, you can get a working parser 
fairly easily.

Copy the 'library' folder to the Tcl library folder in the 
Extensions folder of the System folder.

Rename the 'library' folder to 'tclxml-2.3'.  This isn't strictly
necessary, but it helps keep things organised.

You're on your own as far as the demos, programs and documentation go.


USAGE
=====

To use the package, a Tcl script can either load the generic
package or choose a specific package.  If it loads the generic
package then the package will automatically choose the best
parser available as the default parser (what's really going on
is that the last parser registered becomes the default).

The generic package is loaded using:

	package require xml 2.3

This package defines the "xml::parser" command which is used to create a 
parser object.  It also defines the command "::xml::parserclass" which
is used to manipulate and query parser implementations.

A specific package is loaded using:

	package require expat 2.3

or

	package require tclparser 2.3

The parser implementations register themselves with the generic module.
The last parser class to be registered becomes the default parser class.
Registered parsers can be listed with the command "::xml::parserclass info names"

A parser instance object is created with the command:

	::xml::parser ?name? ?options ...?

If no "name" argument is given then a unique name is chosen.
The name of the newly created parser object is returned and a new Tcl command
of the same name is created to manipulate the parser object.

The "-parser" option gives the name of the parser class to
instantiate for this parser object.  For example:

	::xml::parser myParser -parser tcl

See the man page for details on the methods and options available
for the parser object command.  To get you started, some of the methods
the parser object command accepts are:

	$parser cget -option
		Returns the current value of an option.

	$parser configure -option value ?-option value...?
		Sets configuration options.

	$parser parse xml
		Parses the XML data given by "xml".  This will
		cause Tcl callback scripts to be invoked, if they
		have been configured.

		If the document is not well-formed then the command 
		returns an error.  Callbacks may cause other return
		codes, see the man page.

	$parser reset
		Resets the parser.  Call this method before parsing
		a new document.

XPATH
=====

NB.  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 ...?}}.
