3. Installation

This mode depends on a few other packages:

• an XSLT processor: You definitely need an XSLT processor for this (X)Emacs mode to work! This package doesn't come with an XSLT processor integrated, so you need to download and install one (see section 3.1 Supported XSLT processors for supported XSLT processors). Installing an XSLT processor is nothing else than placing the jar file in the Java CLASSPATH.

  You can either put the jar file in the system's CLASSPATH environment variable or use XSLT-process's customization to setup the additional classpath. The supporting Java code expects the Java XSLT processor to be in the classpath, so make sure you define it one way or the other.

• JDE: XSLT-process was tested with JDE version 2.2.2, but it should work with newer versions as well. Please make sure you follow all the installation instructions on JDE's Web site (http://jdee.sunsite.dk/)

• Elib: This package is a package JDE depends on, but I list it here to insure it's installed. If this package is missing, you'll get an error about the `avltree' package not found. This is a frequently asked question on the JDE's mailing list, so please make sure you don't ask it one more time.

If the above packages are not already installed on your system, you can install them in an `emacs' directory in your home directory. Then add the following lines in your `.emacs' configuration file:

(setq load-path
      (append (list "~/emacs/xslt-process-1.2.1/lisp"
		    "~/emacs/jde/lisp"
		    "~/emacs/semantic"
		    "~/emacs/speedbar"
		    ) load-path))

(autoload 'xslt-process-mode "xslt-process"
          "Run XSLT processor on buffer" t)

These lines add the needed packages in your emacs `load-path' variable, and make known the XSLT-process minor mode to your (X)Emacs.

After the XSLT-process mode has been made available to (X)Emacs, you can enable the minor mode on a per-buffer basis by running `M-x xslt-process-mode'. Or you can invoke `xslt-process-mode' from the mode's hook, see section 3.2 Setting up PSGML with XSLT-process for an example on how you can do it.

3.1 Supported XSLT processors

In this version the XSLT-process minor mode supports the following XSLT processors:

• generic TrAX processor

  Any XSLT processor that implements the TrAX interface as defined in the JAXP 1.1 should work. The currently tested XSLT processors are Saxon 6.2 and Xalan 2.0.

• Saxon

  Both Saxon version 5.5.1, 6.0 and 6.1 are supported through the Saxon interface. If you have a version equal or newer than 6.2, the TrAX interface should be used instead. If you use the 6.0.1 version, beware that it prints some annoying messages to stdout which show up in the buffer of additional messages.

• Xalan 1.2

  Xalan 1.2 is supported using the Xalan1 interface.

• Cocoon 1.8.x

  Although Cocoon is not an XSLT processor, but rather an XML publishing framework, I added support for it as I'm using it quite extensively. This was in fact the primary reason I started XSLT-process: I got really tired of restarting Apache each time I was doing a change in either an XML file or an XSLT sheet.

3.2 Setting up PSGML with XSLT-process

The XSLT-process minor mode works really nice in conjuction with the PSGML major mode for SGML and XML editing.

To setup the XSLT-process minor mode to be automatically enabled whenever you edit an XML file under PSGML, add the below lines in your `.emacs'. I assume you have already added the configuration lines mentioned in see section 3. Installation.

(setq auto-mode-alist
      (append '(("\\.xml$" . xml-mode)) auto-mode-alist))

(add-hook 'xml-mode-hook 'xslt-process-mode)

If you're using a different major mode for editing XML documents, you can setup the mode's hook in a similar way as above to automatically enable the XSLT-process minor mode.

3.3 Key binding

To invoke the XSLT processor on a file, position the point inside the buffer and type `C-c C-x C-v'. You can customize the key binding by invoking `M-x customize-group RET xslt-process' and updating the key binding in the appropriate customization option.

The first time you invoke the XSLT processor on a buffer, the XSLT-process mode will start-up the Java Bean Shell, a Java helper program as a separate process running in the background. This operation may take some time, however further invocations of the processor are very fast as the JVM is started and all the classes are already loaded.

The XSLT processor will look into your XML file for an `xml-stylesheet' processing instruction specifying the XSLT file to be used to process the file.

3.4 Customization

There are several things you might want to customize. You can get to the customization page by typing `M-x customize-group RET xslt-process' or by choosing the following menu path in XEmacs: `Options -> Emacs -> Programming -> Tools -> Xslt Process'.

To choose the XSLT processor of your choice update the Default Processor option.

If you're using Cocoon as the processor, you should also specify the location of the properties file, otherwise you'll get an error at runtime.

3.5 Temporarily changing the XSLT processor

If you want to experiment what are the results of your stylesheets using different XSLT processors, going through the customization page and changing the processor can be quite an involved process.

You can specify the processor you want to be applied to your file right inside the file. Just add a Local Variables section at the end of your XML file and specify within it what should be the XSLT processor to be invoked using the `processor' variable. For example, by adding the following section at the end of your file, you specify Saxon to be used as the XSLT processor, no matter what is the global setting in the customization page:

<!--
Local Variables:
processor: Saxon
End:
-->

In this release, the acceptable values for `processor' are `TrAX', `Saxon', `Xalan1', and `Cocoon1'. By replacing the value of `processor', you can run any of the supported processors on your file.

Note however that in this release the TrAX processor which is chosen is the first processor that appears in the `CLASSPATH'. If you want to experiment with multiple TrAX processors, you will need to change the order of the processors in the `CLASSPATH' and restart the BSH process (just kill the `*bsh*' buffer, the next time you invoke the XSLT processor, XSLT-process will automatically restart BSH).

3.5.1 Additional parameters passed to Cocoon

It is possible to pass additional parameters to a Cocoon processor using `user-agent' local variable in an Emacs buffer:

<!--
Local Variables:
processor: Cocoon1
user-agent: UP.Browser
End:
-->

In this example the user agent of the requesting browser appears to Cocoon as being UP.Browser. If no user agent is specified, by default Cocoon will consider the requesting browser as being HTML capable, thus transforming the output to HTML.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.