Chapter 4. Specifying how to convert an XML document to another format Previous topic Parent topic Child topic Next topic

What is a conversion specification?

How to convert an XML document to another format is specified in XML configuration files called xslutil.conversions. Excerpts of xslsrv/addon/config/xhtml/xslutil.conversions (xslsrv/ being the unpacked xslsrv.war):
<conversions xmlns="http://www.xmlmind.com/xslutil/schema/conversion">  
  <conversion name="xhtmlToPDF"
    description="Convert to PDF using Apache FOP"
    icon="icon:acroread"
    category="XHTML"
    categoryIcon="icon:xhtml_file"
    outputExtension="pdf">
    <transform styleSheet="xsl/fo.xsl">
      <parameter name="paper.type">A4</parameter>

      <!-- Needed to convert a remote URL rather than a local file. -->
      <parameter name="img-src-path">%~pi</parameter>
    </transform>

    <processFO processor="FOP">
      <parameter name="renderer">pdf</parameter>
      <parameter name="strict-validation">false</parameter>
    </processFO>
  </conversion>
</conversions>
A conversion specification is always referred to by its name, which is unique. In the above example, the conversion specification is called "xhtmlToPDF" and allows to convert an XHTML document to PDF using Apache FOP.
The format of xslutil.conversions is not yet documented. Fortunately, XMLmind XSL Utility Opens in new window, a user-friendly desktop application allows to create and edit conversion specifications quickly and easily.

Where does XMLmind XSL Server find all its conversion specifications?

During its initialization, that is, the first time the XMLmind XSL Server WebApp is invoked after its Servlet Container has been started, XMLmind XSL Server searches the following directories
  1. xslsrv/addon/, where xslsrv/ is the unpacked xslsrv.war,
  2. customize_dir/addon/, where customize_dir is the directory pointed to by the customizeDir server parameter, if any.
for files called xslutil.conversions, which contain conversion specifications and also for files whose basename ends with "atalog.xml", which are XML catalogs Opens in new window (1). The conversion specifications collected during these stage are immutable. Moreover their number is fixed, that is, adding or removing xslutil.conversions files to/from any of the two addon/ directories will not be detected by XMLmind XSL Server. We'll call this set the stock conversion specifications.
During its initialization, XMLmind XSL Server also attempts to load customize_dir/xslutil.conversions, which may contain redefinitions of some of the stock conversion specifications and/or custom conversion specifications.

Specifying the customization directory of XMLmind XSL Server

If you carefully read the above section, you'll understand that, unless you properly define the customizeDir server parameter, you'll be limited to using the stock conversion specifications, as is.
Procedure:
  1. Download and install XMLmind XSL Utility Opens in new window.
  2. Stop the Servlet Container.
    If you are using the bundled Jetty Servlet Container, start install_dir/server/bin/controlapp and click the Stop button.
    mainWin_started.png
  3. Specify the customizeDir server parameter in xslsrv/WEB-INF/web.xml (xslsrv/ being the unpacked xslsrv.war) . In the following examples, we'll suppose that customizeDir points to /opt/xslsrv/.
    • If you are using controlapp, click the Configure button.
      mainWin_configured.png
      Then, specify a customization directory in the first screen of the configuration wizard.
      configure_customize_dir.png
    • Otherwise, use a text editor and edit xslsrv/WEB-INF/web.xml. Give a value to the customizeDir init-param. Example:
      <init-param>
      <param-name>customizeDir</param-name><param-value>/opt/xslsrv</param-value>
      </init-param>
  4. Open a terminal or a command prompt and start XMLmind XSL Utility as follows:
    $ xslutil -p /opt/xslsrv &
  5. Quit XMLmind XSL Utility by clicking its Quit button. This is sufficient to create and properly initialize /opt/xslsrv/.
    $ ls /opt/xslsrv
    addon
    xslutil.conversions
    xslutil.properties
  6. Restart the Servlet Container.
    If you are using controlapp, click the Start button (see screenshot above).
Important
Important
Make sure that the user account used to run the Servlet Container (e.g. user: tomcat, group: tomcat) has sufficient privileges to read the contents of the directory pointed to by the customizeDir server parameter.
Tip
Tip
XMLmind XSL Server can directly use the user preferences directory of XMLmind XSL Utility. In other words, no need to create a special purpose directory (/opt/xslsrv/ in the above examples) for that.
The user preferences directory of XMLmind XSL Utility is:
  • $HOME/.xfc/ on Linux.
  • $HOME/Library/Application Support/XMLmind/FOConverter/ on the Mac.
  • %APPDATA%\XMLmind\FOConverter\ on Windows XP, Vista, 7, 8, 10.
    Examples: C:\Documents and Settings\joe\Application Data\XMLmind\FOConverter\ on Windows XP. C:\Users\joe\AppData\Roaming\XMLmind\FOConverter\ on Windows Vista, 7, 8, 10.
Example (user: joe on Linux):
<init-param>
<param-name>customizeDir</param-name><param-value>/home/joe/.xfc</param-value>
</init-param>

 (1)
Let's suppose you want to convert an XHTML document to RTF. The XHTML file starts with:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
...
Without an XML catalog, xhtml1-transitional.dtd will be downloaded from http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd in order to be parsed, which will make the conversion really slow.
With the following XML catalog, xslsrv/addon/config/catalog.xml:
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
         prefer="public">
  ...
  <public publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"
          uri="xhtml/dtd/1.0/xhtml1-transitional.dtd"/>    
  ...
</catalog>
It's the local copy of the DTD, xslsrv/addon/config/xhtml/dtd/1.0/xhtml1-strict.dtd, which is going to be parsed.