		XML Support For Tcl

		TclXML Version 2.4

		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::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.4 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.3.tar.gz
  ftp://prdownloads.sf.net/tcllib/tcllib-1.3.zip

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


Expat

Expat is only required for the compiled version of the package.

TclXML/expat 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
SourceForge project (volunteer needed!).

Pure-Tcl Installation (no compilation required)
===============================================

The install.tcl script will install the pure-Tcl parser.
Run it using wish, eg.

wish install.tcl

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.

0. Make sure you have Tcllib 1.2 (or better) installed.
   Tcllib is still required, even for the compiled parser.

1. Run the configure script, with the --prefix, --exec_prefix and
   --enable-threads switches (the latter only if Tcl has been built
   with threads enabled).  For example, on my system I have Tcl 8.4
   installed in /usr/local/tcl8.4 so I would use the command:

   ./configure --prefix=/usr/local/tcl8.4 --exec_prefix=/usr/local/tcl8.4 --enable-threads

2. "make"

3. "make install"

   You may need to do this as root.  This installs the pure-Tcl parser class,
   as well as support files required for the next step.

4. "cd expat"

   Now TclXML/expat is about to be built.

5. Use the same configure command from step (1) above.

6. "make"

7. "make install"

   You may need to do this as root.  This installs the expat parser class.



WINDOWS (MS VC++) 
-----------------

[Warning: these instructions may not be up-to-date.]
[Advice:  ActiveTcl includes binaries for TclXML.]

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 doesn't 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.4 .

   - 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
--------------

There are two ways to build TclXML under Mac OS X:
(a) The usual Unix way, see above.
(b) As a Framework using ProjectBuilder.

The 'macosx' directory contains the Project Builder files
for building under OS X.  TclXML has been tested on 10.2.1.

Start-up the project, select the 'expat' target and build.
This builds everything.  The result is a Mac OS X Framework.
Copy tclxml.framework and expat.framework to any of the
usual places for frameworks (~/Library/Frameworks, 
/Library/Frameworks, etc).

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 'tclxml2.4'.  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.4

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.4

or

	package require tclparser 2.4

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