Ubuntu Manpage: xslt-process.texi

input texinfo @c -*-Texinfo-*- @setfilename xslt-process.info @settitle XSLT-process minor mode

@set version 1.2.1 @set update-month February 2001

@ifinfo @dircategory Miscellaneous @direntry * XSLT-process:: Apply XSLT processor on an Emacs buffer. @end direntry

This file documents the features of the XSLT-process minor mode.

Distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

@sp 2

The XSLT-process minor mode manual may be reproduced and distributed in whole or in part, in any medium, physical or electronic, so long as this copyright notice remains intact and unchanged on all copies. @end ifinfo

@titlepage @title XSLT-process minor mode @subtitle for version @value{version} @subtitle @value{update-month} @author by Ovidiu Predescu @page @vskip 0pt plus 1filll Copyright @copyright{} 2000, 2001 Ovidiu Predescu.

@sp 1

Distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

@sp 1

@node Top, What is it and how to use it?, ,(dir)

@ifinfo This document describes the XSLT-process, a minor mode for (X)Emacs which allows running an XSLT processor on a buffer. @end ifinfo

@menu * What is it and how to use it?:: * Installation:: * Changes:: * Future enhancements:: * Feedback:: @end menu

@ifhtml

@chapter Current version

[Here are different versions of this document: @uref{xslt-process.pdf, PDF}, @uref{xslt-process.ps, PS}]

The current version of @emph{XSLT-process} is @value{version}. You can download it from @uref{xslt-process-@value{version}.tar.gz, here}.

For a list of changes between since the last version, please @pxref{Changes}.

@end ifhtml

@node What is it and how to use it?, Installation, Top, Top @chapter What is it and how to use it?

Have you ever developed XML applications using XSLT? If so you probably felt the need of viewing the result of applying the XSLT processor on the XML file using an XSLT sheet you have been working on right inside your (X)Emacs, without having to go to a terminal or to the Web browser. This minor mode allows you to do it!

The @emph{XSLT-process} minor mode allows you, while you're inside a buffer for which this minor mode is enabled, to enter a few keystrokes that will invoke the XSLT processor of choice on the buffer. The result is displayed in another (X)Emacs buffer, that allows you to quickly view and inspect the results.

The XSLT file that's used to process the file should be specified inside the XML file using the XML processing instruction @samp{xml-stylesheet}, like this:

@example <?xml-stylesheet href="URL/to/XSLT/file" type="text/xsl"?> @end example

You can use any URI understood by your Java system, e.g. file, HTTP or FTP, to refer to a stylesheet. The XSLT engine will download the stylesheet from the remote location and make use of it locally. With the TrAX interface (@pxref{Supported XSLT processors}), the stylesheet is cached in the processor, so further invocations of the XSLT processor won't process the stylesheet again, unless the stylesheet is modified.

You can use URLs which are relative to the location of your XML file. For example if you have an XSLT file @file{page-html.xsl} in the same directory as the XML file you can simply have inside the XML file the following processing instruction:

@example <?xml-stylesheet href="page-html.xsl" type="text/xsl"?> @end example

The @emph{XSLT-process} mode was designed to work with any XSLT processor written in the Java language. Support for processors written in programming languages other than Java may require some work.

@ifhtml

Here is a @uref{xslt-process.gif, screenshot} of the @emph{XSLT-process} mode in action.

@end ifhtml

@node Installation, Changes, What is it and how to use it?, Top @chapter Installation

This mode depends on a few other packages:

@itemize @bullet

@item @strong{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 (@pxref{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 @emph{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.

@item @strong{JDE}: @emph{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 (@url{http://jdee.sunsite.dk/})

@item @strong{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 @samp{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.

@end itemize

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

@example (setq load-path
(append (list "~/emacs/xslt-process-@value{version}/lisp" "~/emacs/jde/lisp" "~/emacs/semantic" "~/emacs/speedbar" ) load-path))

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

These lines add the needed packages in your emacs @samp{load-path} variable, and make known the @emph{XSLT-process} minor mode to your (X)Emacs.

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

@menu * Supported XSLT processors:: * Setting up PSGML with XSLT-process:: * Key binding:: * Customization:: * Temporarily changing the XSLT processor:: * Additional parameters passed to Cocoon:: @end menu

@node Supported XSLT processors, Setting up PSGML with XSLT-process, Installation, Installation @section Supported XSLT processors

In this version the @emph{XSLT-process} minor mode supports the following XSLT processors:

@itemize @bullet

@item 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.

@item @uref{http://users.iclway.co.uk/mhkay/saxon/, 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.

@item @uref{http://xml.apache.org/xalan/, Xalan 1.2}

Xalan 1.2 is supported using the Xalan1 interface.

@item @uref{http://cocoon.apache.org/, 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 @emph{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.

@end itemize

@node Setting up PSGML with XSLT-process, Key binding, Supported XSLT processors, Installation @section 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 @file{.emacs}. I assume you have already added the configuration lines mentioned in @pxref{Installation}.

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

(add-hook 'xml-mode-hook 'xslt-process-mode) @end example

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 @emph{XSLT-process} minor mode.

@node Key binding, Customization, Setting up PSGML with XSLT-process, Installation @section Key binding

To invoke the XSLT processor on a file, position the point inside the buffer and type @samp{C-c C-x C-v}. You can customize the key binding by invoking @samp{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 @emph{XSLT-process} mode will start-up the @uref{http://www.beanshell.org/, 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 @samp{xml-stylesheet} processing instruction specifying the XSLT file to be used to process the file.

@node Customization, Temporarily changing the XSLT processor, Key binding, Installation @section Customization

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

To choose the XSLT processor of your choice update the @emph{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.

@node Temporarily changing the XSLT processor, , Customization, Installation @section 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 @emph{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 @samp{processor} variable. For example, by adding the following section at the end of your file, you specify @emph{Saxon} to be used as the XSLT processor, no matter what is the global setting in the customization page:

@example  @end example

In this release, the acceptable values for @samp{processor} are @samp{TrAX}, @samp{Saxon}, @samp{Xalan1}, and @samp{Cocoon1}. By replacing the value of @samp{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 @samp{CLASSPATH}. If you want to experiment with multiple TrAX processors, you will need to change the order of the processors in the @samp{CLASSPATH} and restart the BSH process (just kill the @samp{*bsh*} buffer, the next time you invoke the XSLT processor, @emph{XSLT-process} will automatically restart BSH).

@menu * Additional parameters passed to Cocoon:: @end menu

@node Additional parameters passed to Cocoon, , Temporarily changing the XSLT processor, Temporarily changing the XSLT processor @subsection Additional parameters passed to Cocoon

It is possible to pass additional parameters to a Cocoon processor using @samp{user-agent} local variable in an Emacs buffer:

@example  @end example

In this example the user agent of the requesting browser appears to Cocoon as being @emph{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.

@node Changes, Future enhancements, Installation, Top @chapter Changes

These are the changes since the 1.2 release:

@itemize @bullet

@item Fixed problem in accessing stylesheets referred by @kbd{file:} URIs on Windows. Reported by @uref{mailto:kessler@@balcab.ch, Nicolas Kessler}.

@end itemize

This is the list of changes since the 1.1 release.

@itemize @bullet

@item Added support for the TrAX interface, thanks to @uref{mailto:a.erskine@@cs.ucl.ac.uk, Allan Erskine}. Currently Saxon 6.2 and Xalan2 have been tested. The TrAX interface caches the XSLT stylesheets in the processor driver in a compiled form, so the speed of the processing is increased.

@item The mode is now running with GNU Emacs on Windows NT/2000, thanks to @uref{mailto:a.erskine@@cs.ucl.ac.uk, Allan Erskine} for figuring out the issues.

@item Changed again the keyboard binding to @kbd{C-c C-x C-v}, as @kbd{C-M-x} doesn't work on Windows systems.

@item The documentation has been reorganized a little bit to be more logical.

@end itemize

@sp 1

This is the list of changes since the 1.0 release.

@itemize @bullet

@item The @samp{xslt-process-additional-classpath} customization variable has been introduced. Setup this variable with any additional Java classpath components you want to be passed to the BeanShell when is first invoked. If you already started a BeanShell, you need to kill the corresponding buffer (named @samp{*bsh*}) and restart it by invoking @emph{XSLT-process} on a buffer. (Suggestion from @uref{mailto:tvraman@@almaden.ibm.com, T. V. Raman}.)

@item Allow for passing the user agent to the Cocoon processor so that multiple browser types can be simulated. This works with a patch I submitted against Cocoon 1.8-dev; it was incorporated and should be available in the 1.8.1 release. If you need the patch before this release, feel free to contact me, I'll gladly send it to you.

@item The way the error messages are displayed has changed, now error messages messages encountered during the JVM startup process also go in the @samp{*xslt-output*} buffer.

@item The default keybinding has been changed to @kbd{C-M-x} instead of @kbd{C-c x}, to conform to the (X)Emacs keybinding standards.

@end itemize

@node Future enhancements, Feedback, Changes, Top @comment node-name, next, previous, up @chapter Future enhancements

I have few ideas on how this mode could be improved, however they may or may not appear in the next version of this package.

@itemize @bullet

@item Add check to observe changes in the Java additional classpath and restart BSH if such changes occur while it's running.

@item Add an additional buffer local variable to specify additional arguments to the XSLT processor. These arguments could then be read in the XSLT stylesheet using the @samp{xsl:param} element.

@item Introduce the ability to process an XML document with an XSLT stylesheet, without using the @samp{xml-stylesheet} processing instruction inside the XML document. Define user customizable menu entries for the XSLT stylesheets.

This would be really handy for people doing DocBook editing for example, as the DocBook stylesheets live somewhere on the disk and you don't want to put references to them in the XML documents.

@item Provide the ability to view the result of processing in a browser, in addition to viewing them in (X)Emacs. This again would be handy for people doing HTML or WML authoring.

@end itemize

@node Feedback, , Future enhancements, Top @chapter Feedback

I would appreciate any feedback on the @emph{XSLT-process} mode; please send it to @uref{mailto:ovidiu@@xemacs.org,Ovidiu Predescu}.

The home page of the @emph{XSLT-process} package is:

@url{http://www.geocities.com/SiliconValley/Monitor/7464/emacs/xslt-process/}.

@bye

Ubuntu Manpages

xslt-process.texi