=======================================================================
         README FILE FOR THE SUN XSLT COMPILER
                 Preview Version 6 
                    April, 2001
           Copyright (c) Sun Microsystems, 2001
=======================================================================

The Sun XSLT Compiler (XSLTC) is a Java-based tool for compiling XSL 
stylesheets into extremely lightweight and portable Java byte code. 
The Sun XSLTC Java Runtime environment can then process XML files 
against these compiled stylesheets (Translets) to generate any manner 
of output per the style-sheet instructions.

This preview version of the XSLT Compiler can be run on any 
platform -- including UNIX, Windows, NT, Mac -- that supports 
Java2 or later. The Translets (compiled stylesheets) can be run on any 
Java platform including a Palm Pilot with J2ME CLDC 
(Java 2 Micro Edition, Connected Limited Device Configuration). 
While the compiler itself requires Java2,translets are designed to run 
anywhere Java is available.

Almost all functions of the XLST 1.0 language are implemented; 
more than enough to show you how this new approach to XSLT works 
and its advantages! Using the samples provided, you will be able 
to see for yourself. Also, demos for the Palm Pilot, Applets, and 
Servlets are provided.

-----------------------------------------------------------------------
ATTRIBUTIONS
-----------------------------------------------------------------------
The XSLT Compiler program uses the CUP Parser Generator
for Java, Copyright 1996-1999 by Scott Hudson, Frank Flannery,
C. Scott Ananian.  For more details, please see:
http://www.cs.princeton.edu/~appel/modern/java/CUP/

The XSLT Compiler program also uses a modified version of the
Byte Code Engineering Library (BCEL), formerly known as 
(JavaClass API), Copyright 2000 Markus Dahm.

** Please note that this additional package, BCEL, is
** needed in order to generate the class files from the compiler.
** Without the BCEL package, this preview version of the
** compiler WILL NOT WORK.  BCEL is freely available for
** download as described below.

-----------------------------------------------------------------------
REQUIRED PACKAGE
-----------------------------------------------------------------------
BCEL (formerly JavaClass) by Markus Dahm has been 
used to automatically create class files from the XSLT compiler output.  
You must obtain the BCEL.jar file and install it before using the 
XSLT compiler.

The simplest way to download the BCEL.jar file from 

    http://bcel.sourceforge.net/downloads.html

is to use the "JAR file (without docs)" link.

You may want to obtain the precompiled class files and documentation.
To download them to a Unix system:

    1) Choose the "latest version (Precompiled + docs)" 
       Gzipped Tar-File or ZIP-File link.

    2) Unpack and expand the downloaded BCEL files in your 
       download directory (e.g., /usr/local).

    3) Change directory to BCEL.

    4) Create the jar file BCEL.jar.
    
       From within the BCEL directory, you can either use the 
       included GNUmakefile or create the jar yourself.
       
       To use the GNUmakefile, type the command 'make jar'.
       
       To create the jar yourself, type the command:
       
         jar cvf BCEL.jar `find de gnu -name \*.class` listclass.class

To download the precompiled class files and documentation 
to a Windows system:

    1) Choose the "latest version (Precompiled + docs)" 
       ZIP-File link.

    2) Unzip the downloaded BCEL files in your 
       download directory.

    3) Change directory to BCEL and from a DOS command line,
       type the command:

         jar -cvf BCEL.jar de\fub\bytecode\classfile\*.class
           gnu\regexp\*.class listclass.class

To complete the BCEL setup:

    1) Install XSLTC, as described in the section below,
       "HOW TO INSTALL XSLTC AND RUN THE SAMPLES."

    2) Copy the BCEL.jar file into the "lib" directory
       under your "xsltc" directory.

       You are now set to run the XSLT compiler.

------------------------------------------------------------
ADDITIONS FROM VERSION 5 (of the PREVIEW COMPILER)
------------------------------------------------------------

Support for 

	- Simplified Stylesheets
	- id() and key() in match patterns

------------------------------------------------------------
XSLT 1.0 Features Not Suported in PREVIEW VERSION 6
------------------------------------------------------------

The following XSLT 1.0 features are not yet supported:

    * Nonstatic external Java methods. 
      You may call static Java functions
      using a namespace prefix matching the class name that is 
      associated with the following URL:
      
        http://www.sun.com/xsltc/java/YourJavaClass
      
    * Namespace axis

------------------------------------------------------------
LIST OF FILES
------------------------------------------------------------

The files included in this preview package are as follows:

xsltc-1_0-alpha5-bin.zip
   <install dir>/xsltc
      LICENSE.txt           (license file)
      XSLTCprn_lg.txt       (copyright notice)
      README                (this file)
      README.api            (describes Translet API)
      README.xslt           (describes runtime command line interface)
      README.xsltc          (describes compiler command line interface)
      bin 
         xslt               (runtime for Unix)
         xsltc              (compiler for Unix)

         xslt.bat           (runtime for DOS)
         xsltc.bat          (compiler for DOS)
      demo
         README
         TransletDemo.prc (Palm Pilot install file)
      lib
         xml.jar
         xsltc.jar
         xsltcrt.jar               ('rt' = runtime)
         [BCEL.jar goes here] (see REQUIRED PACKAGE above)
      samples
         set of xml and xsl files for you to try
      src
         subset of the runtime package to complement README.api
         plus an Applet demo and a servlet demo
         com/sun/xslt/demo/servlet
             README.servlet        (describes Servlet demo)
         com/sun/xslt/demo/applet
             README.applet         (describes Applet demo)

------------------------------------------------------------
HOW TO INSTALL XSLTC AND RUN THE SAMPLES
------------------------------------------------------------

1. Unzip the files in a directory of your choice, for example
   from the user directory '/home/user1', the distribution
   zip file can be unzipped using the jar command as:

   jar xvf xsltc-1_0-alpha5-bin.zip 

   The subdirectory 'xslt' will be created in '/home/user1'.

2. Set the XSLT environment variable to point to your installation
   directory. Set your PATH environment variable to include
   the bin directory of XSLT. 

   For example, in the bash shell:
 
      export XSLT=/home/user1/xslt
      export PATH=$XSLT/bin:$PATH

3. Compile the stylesheet to produce a Java class file.

   For example, on the Unix platform, to compile the play1.xsl
   stylesheet for the play.xml document:

      cd /home/user1/xsltc/samples
      xsltc play1.xsl

   The compiled stylesheet will be in the main Java class file 
   'play1.class'

   NOTE: The 'xlstc' shell script adds the required jars to your CLASSPATH

   For example, on the Windows platform, to compile the play1.xsl
   stylesheet for the play.xml document:
   
      set classpath=c:\xsltc\samples;c:\xsltc\lib\xsltc.jar;
      c:\xsltc\lib\xsltcrt.jar;c:\xsltc\lib\xml.jar;
      c:\xsltc\lib\BCEL.jar;.
      cd c:\xsltc\samples
      java com.sun.xslt.compiler.XSLTC play1.xsl

4. Use the compiled Java class file (play1.class) to transform 
   the example XML document.

   For example, on the Unix platform:

      xslt play.xml play1

   For example, on the Windows platform:

      java com.sun.xslt.runtime.DefaultRun play.xml play1

   The result is sent to standard output.

   NOTE: When running the compiled stylesheet, you 
         just specify the name of its Java class, not its
         file name (e.g., play1, not play1.class).
         You do not include the ".class" extension, nor
         the path to the class. The class is found by means 
         of the Java CLASSPATH variable. If you run
         the translet from a directory other
         than the directory in which the compiled
         stylesheet class is located, you need to add 
         that directory to your Java CLASSPATH. Also, you
         need to remove directories from your CLASSPATH 
         for prior installations of XSLTC and any references 
         to Sun's project X parser (com.sun.xml.tree)
         installed from some other XML application/tool.
 
   NOTE: The javadocToHtml sample calls external Java methods
         from the JavadocFormatter class. Before compiling the
         javadocToHtml.xsl stylesheet, compile the 
         JavadocFormatter class using 'javac'.

------------------------------------------------------------
END OF README