Source

xslt-process / README

Diff from to

File README

    The _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, which allows you to quickly
+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
 
      <?xml-stylesheet href="URL/to/XSLT/file" type="text/xsl"?>
 
+   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 (*note 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 `page-html.xsl' in the same
 directory as the XML file you can simply have inside the XML file the
      <?xml-stylesheet href="page-html.xsl" type="text/xsl"?>
 
    The _XSLT-process_ mode was designed to work with any XSLT processor
-written in the Java language. Support for processors written in other
-languages should be trivial to add.
+written in the Java language. Support for processors written in
+programming languages other than Java may require some work.
+
+
+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
+     (*note 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://sunsite.dk/jde/>)
+
+   * *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, *note 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::
-* Supported XSLT processors::
 * Customization::
 * Temporarily changing the XSLT processor::
 * Additional parameters passed to Cocoon::
 
 
-
-Key binding
-===========
-
-   To invoke the XSLT processor on a file, position the point inside the
-buffer and type `C-M-x'. 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 actual Emacs-Lisp function that gets invoked when you enter the
-keystrokes is `xslt-process-invoke'.
-
-   The first time you invoke the above function, it will start-up the
-Java Bean Shell (http://www.beanshell.org/) 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 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.
-
-
 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 (http://users.iclway.co.uk/mhkay/saxon/)
 
-     Both Saxon version 5.5.1 and 6.0.1 have been tested and work fine.
-     The 6.0.1 version however prints some annoying messages to stdout
-     which show up in the additional messages buffer.
+     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 (http://xml.apache.org/xalan/)
 
-     This works fine.
+     Xalan 1.2 is supported using the Xalan1 interface.
 
    * Cocoon 1.8.x (http://xml.apache.org/cocoon/)
 
      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 started
+     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, because
-     of some weird caching problems in Cocoon.
+     was doing a change in either an XML file or an XSLT sheet.
 
 
 
+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 *note 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.
+
+
+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
+(http://www.beanshell.org/), 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.
+
+
 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 -> Languages -> Sgml -> 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.
 Temporarily changing the XSLT processor
 =======================================
 
-   If you want to experiment the results of your stylesheets using
-different XSLT processors, going through the customization page and
-changing the processor can be quite an involved process.
+   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
      End:
      -->
 
-   In this release, the acceptable values for `processor' are `Saxon',
-`Xalan1' and `Cocoon1'. By replacing the value of `processor', you can
-run any of the supported processors on your file.
+   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).
+
+* Menu:
+
+* Additional parameters passed to Cocoon::
 
 
 Additional parameters passed to Cocoon
 transforming the output to HTML.
 
 
-Installation
-************
-
-   The _XSLT-process_ mode has been developed under XEmacs 21.1 under
-Linux, but all the precautions have been taken to make sure it works
-with GNU Emacs as well. Also, as the _XSLT-process_ mode does not have
-any operating system dependencies by itself, it should work on any
-operating system JDE has been ported to, including Windows.
-
-   However since I'm not a user of neither GNU Emacs nor Windows, if you
-find any problems on these platforms, I would appreciate any feedback
-that helps improving this package.
-
-   This mode depends on a few other packages:
-
-   * *JDE*: This package 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://sunsite.dk/jde/>)
-
-   * *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.
-
-
-   Make sure you have these packages installed in your Emacs-Lisp path.
-
-   You can now add the following line in your `.emacs' file:
-
-     (autoload 'xslt-process-mode "xslt-process"
-               "Run XSLT processor on buffer" t)
-
-   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 *Note Setting up PSGML with XSLT-process:: for an
-example on how you can do it.
-
-* Menu:
-
-* Setting up PSGML with XSLT-process::
-
-
-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 when
-you visit an XML file under PSGML, add the following lines in your
-`.emacs' (I assume all the packages are installed under `~/emacs'):
-
-     (setq load-path
-           (append (list "~/emacs/xslt-process-1.0/lisp"
-     		    "~/emacs/jde-2.2.2/lisp"
-     		    "~/emacs/semantic-1.2.1"
-     		    "~/emacs/speedbar-0.12"
-     		    ) load-path))
-     
-     (setq auto-mode-alist
-           (append '(("\\.xml$" . xml-mode)) auto-mode-alist))
-     
-     (add-hook 'xml-mode-hook 'xslt-process-mode)
-     
-     (autoload 'xslt-process-mode "xslt-process"
-               "Run XSLT processor on buffer" t)
-
-   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.
-
-
 Changes
 *******
 
-   This is a list of changes since the 1.0 release.
+   These are the changes since the 1.2 release:
 
-  1. The `xslt-process-additional-classpath' customization variable has
+   * Fixed problem in accessing stylesheets referred by `file:' URIs on
+     Windows. Reported by Nicolas Kessler (mailto:kessler@balcab.ch).
+
+
+   This is the list of changes since the 1.1 release.
+
+   * Added support for the TrAX interface, thanks to Allan Erskine
+     (mailto:a.erskine@cs.ucl.ac.uk). 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.
+
+   * The mode is now running with GNU Emacs on Windows NT/2000, thanks
+     to Allan Erskine (mailto:a.erskine@cs.ucl.ac.uk) for figuring out
+     the issues.
+
+   * Changed again the keyboard binding to `C-c C-x C-v', as `C-M-x'
+     doesn't work on Windows systems.
+
+   * The documentation has been reorganized a little bit to be more
+     logical.
+
+
+
+   This is the list of changes since the 1.0 release.
+
+   * The `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
      invoking _XSLT-process_ on a buffer. (Suggestion from T. V. Raman
      (mailto:tvraman@almaden.ibm.com).)
 
-  2. Allow for passing the user agent to the Cocoon processor so that
+   * 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.
 
-  3. The way the error messages are displayed has changed, now error
+   * The way the error messages are displayed has changed, now error
      messages messages encountered during the JVM startup process also
      go in the `*xslt-output*' buffer.
 
-  4. The default keybinding has been changed to `C-M-x' instead of `C-c
+   * The default keybinding has been changed to `C-M-x' instead of `C-c
      x', to conform to the (X)Emacs keybinding standards.
 
 
    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.
 
-  1. Add an additional buffer local variable to specify additional
+   * Add check to observe changes in the Java additional classpath and
+     restart BSH if such changes occur while it's running.
+
+   * 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 `xsl:param' element.
 
-  2. Add additional buffer local variable to support specifying HTTP
-     header values. This would require additional changes in the Cocoon
-     1.x code to support them.
+   * Introduce the ability to process an XML document with an XSLT
+     stylesheet, without using the `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.
+
+   * 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.
 
 
 
 ********
 
    I would appreciate any feedback on the _XSLT-process_ mode; please
-send it to Ovidiu Predescu (mailto:ovidiup@altavista.net).
+send it to Ovidiu Predescu (mailto:ovidiu@xemacs.org).
 
    The home page of the _XSLT-process_ package is: