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

Copyright (C) 2000--2001 Ovidiu Predescu
All rights reserved.

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.
@par All rights reserved.

@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

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 titlepage

@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://sunsite.dk/jde/})

@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://xml.apache.org/cocoon/, 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
<!--
Local Variables:
processor: Saxon
End:
-->
@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
<!--
Local Variables:
processor: Cocoon1
user-agent: UP.Browser
End:
-->
@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
