Chapter 10. Transforming documents

Table of Contents

XSLT Transformations
Output formats
Transformation scenario
Batch transformation
Built-in transformation scenarios
Defining a new transformation scenario
XSLT Stylesheet Parameters
Additional XSLT Stylesheets
XSLT/XQuery Extensions
Creating a Transformation Scenario
Transformation Scenarios view
XSL-FO processors
Add a font to the built-in FOP
Locate font
Generate font metrics file
Register font to FOP configuration
Set FOP configuration file in Oxygen
Add new font to FO output
DocBook Stylesheets
TEI Stylesheets
DITA-OT Stylesheets
Common transformations
PDF Output
PS Output
TXT Output
HTML Output
HTML Help Output
Java Help Output
XHTML Output
Supported XSLT processors
Configuring custom XSLT processors
Configuring the XSLT processor extensions paths
XProc Transformations
XProc transformation scenario
Integration of an external XProc engine - the XProc API

XML is designed to store, carry, and exchange data, not to display data. When you want to view the data you must either have an XML compliant user agent or transform it to a format that can be read by other user agents. This process is known as transformation.

Status messages generated during transformation are displayed in the Console view.

XSLT Transformations

Output formats

Within the current version of <oXygen/> you can transform your XML documents to the following formats without having to exit from the application. For transformation to formats not listed simply install the tool chain required to perform the transformation and process the xml files created with <oXygen/> in accordance with the processor instructions.

PDF

Adobe Portable Document Format (PDF) is a compact binary file format that can be viewed and printed by anyone, anywhere across a broad range of hardware and software using the free PDF Viewer from Adobe.

PS

PostScript is the leading printing technology from Adobe for high-quality, best-in-class printing solutions ranging from desktop devices to the most advanced digital presses, platemakers, and large format image setters in the world. Postscript files can be viewed using viewers such as GhostScript, but are more commonly created as a prepress format.

TXT

Text files are Plain ASCII Text and can be opened in any text editor or word processor.

XML

XML stands for eXtensible Markup Language and is a W3C standard markup language, much like HTML, which was designed to describe data. XML tags are not predefined in XML. You must define your own tags. XML uses a Document Type Definition (DTD), an XML Schema or a Relax NG schema to describe the data. XML with a DTD, XML Schema or Relax NG schema is designed to be self-descriptive. XML is not a replacement for HTML. XML and HTML were designed with different goals:

  • XML was designed to describe data and to focus on what data is.

  • HTML was designed to display data and to focus on how data looks.

  • HTML is about displaying information, XML is about describing information.

XHTML

XHTML stands for eXtensible HyperText Markup Language, a W3C standard. XHTML is aimed to replace HTML. While almost identical to HTML 4.01, XHTML is a stricter and cleaner version of HTML. XHTML is HTML defined as an XML application.

All formatting during a transformation is provided under the control of an Extensible Stylesheet (XSLT). Specifying the appropriate XSLT enables transformation to the above formats and preparation of output files for specific user agent viewing applications, including:

HTML

HTML stands for Hyper Text Markup Language and is a W3C Standard for the World Wide Web. HTML is a text file containing small markup tags. The markup tags tell the Web browser how to display the page. An HTML file must have an htm or html file extension. An HTML file can be created using a simple text editor.

HTML Help

Microsoft HTML Help is the standard help system for the Windows platform. Authors can use HTML Help to create online help for a software application or to create content for a multimedia title or Web site. Developers can use the HTML Help API to program a host application or hook up context-sensitive help to an application.

JavaHelp

JavaHelp software is a full-featured, platform-independent, extensible help system from Sun Microsystems that enables developers and authors to incorporate online help in applets, components, applications, operating systems, and devices. JavaHelp is a free product and the binaries for JavaHelp can be redistributed.

Eclipse Help

Eclipse Help is the help system incorporated in the Eclipse platform that enables Eclipse plugin developers to incorporate online help in their plugins.

Many other target formats are possible, these are the most popular. The basic condition for transformation to any format is that your source document is well-formed. Always, make sure that the XSL used for the transformation is the right one according to the desired output format and with the input source definition. For example, if you want to transform to HTML format using a DocBook html stylesheet, your source xml document should respect the DocBook DTD.

An XSL stylesheet specifies the presentation of a class of XML documents by describing how an instance of the class is transformed into an output document by using special formatting vocabulary.

XSL consists of three parts:

XSL Transformations (XSLT)

XSLT is a language for transforming XML documents.

XML Path (XPath) Language

XPath is an expression language used by XSLT to access or refer parts of an XML document. (XPath is also used by the XML Linking specification).

XSL Formatting Objects (XSL:FO)

XSL:FO is an XML vocabulary for specifying formatting semantics.

<oXygen/> supports XSLT/XPath version 1.0 using Saxon 6.5.5, Xalan, Xsltproc, MSXML (3.0, 4.0, .NET) and XSLT/XPath 2.0 by using Saxon 9.2.0.6 B, Saxon 9.2.0.6 EE and Saxon.NET. Also the validation is done in function of the stylesheet version.

Transformation scenario

Before transforming the current edited XML document in <oXygen/> you must define a transformation scenario to apply to that document. A scenario is a set of values for various parameters defining a transformation. It is not related to any particular document but to a document type:

Scenarios that apply to XML files

Such a scenario contains the location of an XSLT stylesheet that is applied on the edited XML document and other transform parameters.

Scenarios that apply to XSLT files

Such a scenario contains the location of an XML document that the edited XSLT stylesheet is applied on and other transform parameters.

Scenarios that apply to XQuery files

Such a scenario contains the location of an XML source that the edited XQuery file is applied on and other transform parameters. When the XML source is a native XML database the XML source field of the scenario is empty because the XML data is read with XQuery functions like document(). When the XML source is a local XML file the URL of the file is specified in the XML input field of the scenario.

A scenario can be created at document type level or at global level. The scenarios defined at document type level are available only for the documents that match that document type. The global scenarios are available for any document.

In order to apply a transformation scenario one has to press the Apply Transformation Scenario button from the Transformation toolbar.

Batch transformation

Alternatively, a transform action can be applied on a batch of files from the Project view's contextual menu without having to open the files:

  • Apply Transformation Scenario - applies to each selected file the transformation scenario associated to that file. If the currently processed file does not have an associated transformation scenario then a warning is displayed in the Warnings view to let the user know about it.

  • Transform with... - allows the user to select one transformation scenario to be applied to each one of the currently selected files.

Built-in transformation scenarios

If the Apply Transformation Scenario button from the Transformation toolbar is pressed, currently there is no scenario associated with the edited document and the edited document contains a "xml-stylesheet" processing instruction referring to a XSLT stylesheet (commonly used for display in Internet browsers), then <oXygen/> will prompt the user and offer the option to associate the document with a default scenario containing in the XSL URL field the URL from the href attribute of the processing instruction. This scenario will have the "Use xml-stylesheet declaration" checkbox set by default, will use Saxon as transformation engine, will perform no FO processing and will store the result in a file with the same URL as the edited document except the extension which will be changed to html. The name and path will be preserved because the output file name is specified with the help of two editor variables: ${cfd} and ${cfn}.

<oXygen/> comes with preconfigured built-in scenarios for usual transformations that enable the user to obtain quickly the desired output: associate one of the built-in scenarios with the current edited document and then apply the scenario with just one click.

Defining a new transformation scenario

The Configure Transformation Scenario dialog is used to associate a scenario from the list of all scenarios with the edited document by selecting an entry from the list. The dialog is opened by pressing the Configure Transformation Scenario button on the Transformation toolbar of the document view. Once selected the scenario will be applied with only one click on the Apply Transformation Scenario on the same toolbar. Pressing the Apply Transformation button before associating a scenario with the edited document will invoke first the Configure Transformation Scenario dialog and then apply the selected scenario.

Open the Configure Transformation Scenario dialog using one of the methods previously presented or by selecting XMLConfigure transformation scenario. (Alt+Shift+T C (Cmd+Alt+T C on Mac OS)).

Figure 10.1. Configure Transformation Scenario Dialog

Configure Transformation Scenario Dialog

The Scenario type controls which scenarios are presented to the user. The available scenario types are:

XML transformation with XSLT

Represents a transformation that consists in applying an XSLT stylesheet over an XML.

XML transformation with XQuery

Represents a transformation that consists in applying an XQuery over an XML. More about executing XQuery statements can be found here.

DITA OT transformation

Scenarios that use the DITA Open Toolkit (DITA-OT) to transform XML content into an output format. More information about configuring an DITA OT transformation scenario can be found here.

XSLT transformation

Represents a transformation that consists in applying an XSLT stylesheet over an XML file.

XQuery transformation

Represents a transformation that consists in applying an XQuery over an XML. More about executing XQuery statements can be found here.

SQL transformation

Executes an SQL over a database. More about executing SQL statements can be found here.

If you want an XSLT scenario select as Scenario type either XML transformation with XSLT or XSLT transformation then complete the dialog as follows:

Figure 10.2. The Configure Transformation Dialog - XSLT Tab

The Configure Transformation Dialog - XSLT Tab

XML URL

Specifies an input XML file to be used for the transformation. Please note that this URL is resolved through the catalog resolver. If the catalog does not have a mapping for the URL, then the editor will try to use the file directly.

Note

If the transformation engine is Saxon 9 and a custom URI resolver is configured for Saxon 9 in Preferences then the XML input of the transformation is passed to that URI resolver.

The following buttons are shown immediately after the input field:

Insert Editor Variables

Opens a pop-up menu allowing to introduce special <oXygen/> editor variables or custom editor variables in the XML URL field.

Browse for local file

Opens a local file browser dialog allowing to select a local file name for the text field.

Browse for remote file

Opens a URL browser dialog allowing to select a remote file name for the text field.

Browse for archived file

Opens a zip archive browser dialog allowing to select a file name from a zip archive that will be inserted in the text field.

Open in editor

Opens the file with the path specified in the text field in an editor panel.

XSL URL

Specifies an input XSL file to be used for the transformation. Please note that this URL is resolved through the catalog resolver. If the catalog does not have a mapping for the URL, then the editor will try to use the file directly.

The above set of browsing buttons are available also for this input.

Use "xml-stylesheet" declaration

Use the stylesheet declared with an "xml-stylesheet" declaration instead of the stylesheet specified in the XSL URL field. By default this checkbox is not selected and the transformation applies the XSLT stylesheet specified in the XSL URL field. If it is checked the scenario applies the stylesheet specified explicitly in the XML document with the xml-stylesheet processing instruction.

Transformer

This combo box contains all the transformer engines available for applying the stylesheet. These are the built-in engines and the external engines defined in the user preferences. If you want to change the default selected engine just select other engine from the drop down list of the combo box. For XQuery/XSLT files only, if no validation scenario is associated, the transformer engine will be used in validation process, if has validation support.

Parameters

Opens the dialog for configuring the XSLT parameters. In this dialog you set any global XSLT parameters of the main stylesheet set in the XSL URL field or of the additional stylesheets set with the button Additional XSLT stylesheets.

Append header and footer

Opens a dialog for specifying a URL for a header HTML file added at the beginning of the result of an HTML transformation and a URL for a footer HTML file added at the end of the HTML result of the transformation.

Additional XSLT stylesheets

Opens the dialog for adding XSLT stylesheets which are applied on the result of the main stylesheet specified in the XSL URL field. This is useful when a chain of XSLT stylesheets must be applied to the input XML document.

Extensions

Opens the dialog for configuring the XSLT/XQuery extension jars or classes which define extension Java functions or extension XSLT elements used in the XSLT/XQuery transformation.

Advanced options

Configure advanced options specific for the Saxon HE / PE / EE engine. They are the same options as the ones set in the user preferences but they are configured as a specific set of transformation options for each transformation scenario. By default if you do not set a specific value in the transformation scenario each advanced option has the same value as the global option with the same name set in the user preferences.

The advanced options include two options that are not available globally in the user preferences: the initial XSLT template and the initial XSLT mode of the transformation. They are Saxon specific options that allow imposing the name of the first XSLT template that starts the XSLT transformation or the initial mode of transformation.

Figure 10.3. The advanced options of Saxon HE / PE / EE

The advanced options of Saxon HE / PE / EE

The advanced options specific for Saxon PE / EE are:

Initial mode

Specifies to the transformer the initial template mode

Initial template

Specifies the name of the initial template to the transformer. When specified, the XML input URL for the transformation scenario is optional.

Use a configuration file

If checked, the specified Saxon configuration file will be used to specify the Saxon advanced options.

Disable calls on extension functions

If checked the stylesheet is disallowed to call external Java functions.

Version warnings

If checked display a warning when it is applied to an XSLT 1.0 stylesheet.

DTD based validation of the source file

If checked the source XML file is validated against the declared DTD

Line numbering

Include the line number in errors for the

Handling of recoverable stylesheet errors

Policy for handling recoverable errors in the stylesheet: Allows the user to choose how dynamic errors will be handled. Either one of the following options can be selected: recover silently, recover with warnings or signal the error and do not attempt recovery.

Strip whitespaces

Strip whitespaces feature can be one of the three options: All, Ignorable, None.

All

strips all whitespace text nodes from source documents before any further processing, regardless of any xsl:strip-space declarations in the stylesheet, or any xml:space attributes in the source document.

Ignorable

strips all ignorable whitespace text nodes from source documents before any further processing, regardless of any xsl:strip-space declarations in the stylesheet, or any xml:space attributes in the source document. Whitespace text nodes are ignorable if they appear in elements defined in the DTD or schema as having element-only content.

None

strips no whitespace before further processing. (However, whitespace will still be stripped if this is specified in the stylesheet using xsl:strip-space).

Validation of the source file

Available only for Saxon SA.

Schema validation

This mode requires an XML Schema and determines whether source documents should be parsed with schema-validation enabled.

Lax schema validation

This mode determines whether source documents should be parsed with schema-validation enabled if an XML Schema is provided.

Disable schema validation

This determines whether source documents should be parsed with schema-validation disabled.

Validation errors in the results tree treated as warnings

Available only for Saxon SA. If checked, all validation errors are treated as warnings, otherwise they are treated as fatal.

When creating a scenario that applies to an XML file, <oXygen/> fills the XML URL with the default variable "${currentFile}". This means the input for the transformation is taken from the currently edited file. You can modify this value to other file path. This is the case of currently editing a section from a large document, and you want the transformation to be performed on the main document, not the section. You can specify in this case either a full absolute path: file:/c:/project/docbook/test.xml or a path relative to one of the editor variables, like the current file directory: ${cfdu}/test.xml .

When the scenario applies to XSL files, the field XSL URL is containing ${currentFile}. Just like in the XML case, you can specify here the path to a master stylesheet. The path can be configured using the editor variables or the custom editor variable .

Figure 10.4. The Configure Transformation Dialog - FO Processor Tab

The Configure Transformation Dialog - FO Processor Tab

Checkbox Perform FO Processing

Enable or disable applying an FO processor (either the built-in Apache FOP engine or an external engine defined in Preferences) during the transformation.

Radio button XSLT result as input

The FO processor is applied to the result of the XSLT transformation defined on the XSLT tab of the dialog.

Radio button Edited document as input

The FO processor is applied directly to the current edited document.

Combo box Method

The output format of the FO processing: PDF, PostScript or plain text.

Combo box Processor

The FO processor, which can be the built-in Apache FOP processor or an external processor.

Figure 10.5. The Configure Transformation Dialog - Output Tab

The Configure Transformation Dialog - Output Tab

Radio button Prompt for file

At the end of the transformation a file browser dialog will be displayed for specifying the path and name of the file which will store the transformation result.

Text field Save As

The path of the file where it will be stored the transformation result. The path can include special <oXygen/> editor variables or custom editor variables.

Check box Open in browser

If this is checked <oXygen/> will open automatically the transformation result in a browser application specific for the type of that result (HTML/XHTML, PDF, text).

Radio button Saved file

When Open in browser is selected this button can be selected to specify that <oXygen/> should open automatically at the end of the transformation the file specified in the Save As text field.

Radio button Other location

When Open in browser is selected this button can be used to specify that <oXygen/> should not open the file specified in the Save As text field, it should open the file specified in the text field of the Other location radio button. The file path can include special <oXygen/> editor variables or custom editor variable.

Check box Open in editor

When this is checked the transformation result set in the Save As field is opened in a new editor panel in <oXygen/> with the appropriate built-in editor type: if the result is an XML file it is opened with the built-in XML editor, if it is an XSL-FO file it is opened with the built-in FO editor, etc.

Check box Show As XHTML

It is enabled only when Open in browser is disabled. If this is checked <oXygen/> will display the transformation result in a built-in XHTML browser panel at the bottom of the <oXygen/> window.

Important

When transforming very large documents you should be aware that enabling this feature will result in a very long time necessary for rendering the transformation result in the XHTML result viewer panel. This drawback appears due to the built-in Java XHTML browser implementation. In this situations if you wish to see the XHTML result of the transformation you should use an external browser by checking the Open in browser checkbox.

Check box Show As XML

If this is checked <oXygen/> will display the transformation result in an XML viewer panel at the bottom of the <oXygen/> window with syntax highlight specific for XML documents.

Text field Image URLs are relative to

If Show As XHTML is checked this text field specifies the path for resolving image paths contained in the transformation result.

XSLT Stylesheet Parameters

The global parameters of the XSLT stylesheet used in the transformation scenario are configured from the dialog available from the Parameters button:

Figure 10.6. Configure parameters dialog

Configure parameters dialog

The table presents all the parameters of the XSLT stylesheet and all imported and included stylesheets with their current values. If a parameter value was not edited then the table presents its default value. The bottom panel presents the default value of the parameter selected in the table, a description of the parameter if it is available and the system ID of the stylesheet that declares it.

For setting the value of a parameter declared in the stylesheet in a namespace, for example:

<xsl:param name="p:param" xmlns:p="namespace">default</xsl:param>

use the following expression in the Name column of the Parameters dialog:

{namespace}param

The buttons of the dialog have the following functions:

Add

Add a new parameter to the list.

The editor variables displayed at the bottom of the dialog (${frameworks}, ${home}, ${cfd}, etc) can be used in the values of the parameters to make the value independent of the location of the XSLT stylesheet or the XML document.

The value of a parameter can be entered at runtime if a value ask('user-message', param-type, 'default-value' ?) is used as value of parameter in the Configure parameters dialog:

  • ${ask('message')} - only the message displayed for the user is specified

  • ${ask('message', generic, 'default')} - 'message' will be displayed for the user, the type is not specified (the default is string), the default value will be 'default'

  • ${ask('message', password)} - 'message' will be displayed for the user, the characters typed will be replaced with a circle character

  • ${ask('message', password, 'default')} - same as above, default value will be 'default'

  • ${ask('message', url)} - 'message' will be displayed for the user, the type of parameter will be URL

  • ${ask('message', url, 'default')} - same as above, default value will be 'default'

Additional XSLT Stylesheets

The list of additional XSLT stylesheets can be edited in the dialog opened by the button Additional XSLT Stylesheets.

Add

Adds a stylesheet in the "Additional XSLT stylesheets" list using a file browser dialog , also you can type an editor variable in the file name field of the browser dialog. The name of the stylesheet will be added in the list after the current selection.

New

Opens a dialog in which you can type the name of a stylesheet. The name is considered relative to the URL of the current edited XML document. You can use editor variables in the name of the stylesheet. The name of the stylesheet will be added in the list after the current selection.

Remove

Deletes the selected stylesheet from the "Additional XSLT stylesheets" list.

Up

Move the selected stylesheet up in the list.

Down

Move the selected stylesheet down in the list.

The path specified in the URL text field can include special <oXygen/> editor variables.

XSLT/XQuery Extensions

The Edit Extensions dialog is used to specify the jars and classes containing extension functions called from the XSLT/XQuery file of the current transformation scenario.

An extension function called from the XSLT or XQuery file of the current transformation scenario will be searched in the specified extensions in the order of the list displayed in the dialog. For changing the order of the items the user must select the item that must be moved to other position in the list and press the up and down buttons.

Creating a Transformation Scenario

Use the following procedure to create a scenario.

  1. Select XMLConfigure transformation scenario (Alt+Shift+T C (Cmd+Alt+T C on Mac OS)) to open the Configure Transformation dialog.

  2. Click the Duplicate Scenario button of the dialog to create a copy of the current scenario.

  3. Click in the Name field and type a new name.

  4. Click OK or Transform Now to save the scenario.

Transformation Scenarios view

The list of transformation scenarios may be easier to manage for some users as a list presented in a dockable and floating view called Transformation Scenarios.

Figure 10.7. The Scenarios view

The Scenarios view

The actions available on the right click menu allow the same operations as in the dialog Configure Transformation Scenario: creating, editing, executing, duplicating and removing a transformation scenario.

XSL-FO processors

The <oXygen/> installation package is distributed with the Apache FOP (Formatting Objects Processor) for rendering your XML documents to PDF. FOP is a print and output independent formatter driven by XSL Formatting Objects. FOP is implemented as a Java application that reads a formatting object tree and renders the resulting pages to a specified output.

Tip

To include PNG images in the final PDF document you need the JIMI or JAI libraries. For TIFF images you need the JAI library. For PDF images you need the fop-pdf-images library. These libraries are not bundled with <oXygen/> (JIMI and JAI due to Sun's licensing). Using them is as easy as downloading them and creating a external FO processor based on the built-in FOP libraries and the extension library. The external FO processor created in Preferences will have a command line like:

java -cp "${oxygenInstallDir}/lib/xercesImpl.jar:
${oxygenInstallDir}/lib/fop.jar:${oxygenInstallDir}/lib/
avalon-framework-4.2.0.jar:
${oxygenInstallDir}/lib/batik-all-1.7.jar:${oxygenInstallDir}/lib/
commons-io-1.3.1.jar:
${oxygenInstallDir}/lib/xmlgraphics-commons-1.3.1.jar:
${oxygenInstallDir}/lib/commons-logging-1.0.4.jar:
${oxygenInstallDir}/lib/saxon9ee.jar:${oxygenInstallDir}/lib/
saxon9-dom.jar:
${oxygenInstallDir}/lib/xalan.jar:${oxygenInstallDir}/lib/
serializer.jar:
${oxygenInstallDir}/lib/resolver.jar:${oxygenInstallDir}/lib/
fop-pdf-images-1.3.jar:
${oxygenInstallDir}/lib/PDFBox-0.7.3.jar" 
org.apache.fop.cli.Main -fo ${fo} -${method} ${out}

You need to add to the classpath JimiProClasses.zip for JIMI and jai_core.jar, jai_codec.jar and mlibwrapper_jai.jar for JAI. For the JAI package you also need to include the directory containing the native libraries (mlib_jai.dll and mlib_jai_mmx.dll on Windows) in the PATH system variable.

The MacOS X version of the JAI library can be downloaded from http://www.apple.com/downloads/macosx/apple/java3dandjavaadvancedimagingupdate.html. In order to use it, install the downloaded package.

Other FO processors can be configured in the Preferences -> FO Processors panel.

Add a font to the built-in FOP

If an XML document is transformed to PDF using the built-in Apache FOP processor but it contains some Unicode characters that cannot be rendered by the default PDF fonts then a font that is capable to render these characters must be configured and embedded in the PDF result.

Locate font

First, you have to find out the name of a font that has the glyphs for the special characters you used. One font that covers the majority of characters, including Japanese, Cyrillic and Greek, is Arial Unicode MS. In the following is described how to embed the true type fonts in the output PDF. Embedding the fonts is necessary to ensure your document is portable.

On Windows the fonts are located into the C:\Windows\Fonts directory. On Mac they are placed in /Library/Fonts. To install a new font on your system is enough to copy it in the Fonts directory.

Generate font metrics file

Generate a FOP font metrics file from the TrueType font file. This example reads the Windows Arial Unicode MS file and generates an arialuni.xml font metrics file in the current directory. FOP includes an utility application for this task.

I assume you have opened a terminal or command line console and changed the working directory to the oxygen install directory. The FOP files are stored in the lib subdirectory of the Oxygen install directory.

Create the following script file in the Oxygen installation directory. The relative paths specified in the following script file are relative to the Oxygen installation directory so if you decide to create it in other directory you have to adapt the file paths.

For the Mac OS X: ttfConvert.sh

#!/bin/sh 
export LIB=lib
export CMD=java -cp "$LIB/fop.jar:$LIB/avalon-framework-4.2.0.jar:$LIB/xercesImpl.jar"
export CMD=$CMD org.apache.fop.fonts.apps.TTFReader 
export FONT_DIR='/Library/Fonts' 
$CMD $FONT_DIR/Arialuni.ttf Arialuni.xml

For Linux: ttfConvert.sh

#!/bin/sh 
export LIB=lib
export CMD=java -cp "$LIB/fop.jar:$LIB/avalon-framework-4.2.0.jar:$LIB/xercesImpl.jar"
export CMD=$CMD org.apache.fop.fonts.apps.TTFReader
export FONT_DIR='/Library/Fonts' 
$CMD $FONT_DIR/Arialuni.ttf Arialuni.xml

For Windows: ttfConvert.bat

set LIB=lib
set CMD=java -cp "%LIB%\fop.jar;%LIB%\avalon-framework-4.2.0.jar;%LIB%\xercesImpl.jar"
set CMD=%CMD% org.apache.fop.fonts.apps.TTFReader
set FONT_DIR=C:\Windows\Fonts
%CMD% %FONT_DIR%\Arialuni.ttf Arialuni.xml

The FONT_DIR can be different on your system. Make sure it points to the correct font directory. If java executable is not in the PATH you will have to specify the full path for java.

Execute the script. On Linux and Mac OS X you have to use sh ttfConvert.sh from the command line.

Note

If Oxygen was installed by an administrator user and now it is used by a standard user who does not have write permission in the Oxygen installation folder (for example on Windows Vista or Linux) then the output location of the font metrics file should be a directory where the user has write permission, for example:

%CMD% %FONT_DIR%\Arialuni.ttf C:\temp_dir\Arialuni.xml

If the font has bold and italic variants, you will have to convert those also. For this you can modify the script, by adding two more lines:

$CMD $FONT_DIR/Arialuni-Bold.ttf Arialuni-Bold.xml
                      $CMD $FONT_DIR/Arialuni-Italic.ttf Arialuni-Italic.xml

In our case the font Arial Unicode MS is not having a Bold and Italic variant, so you will leave the script unchanged.

Register font to FOP configuration

Create a file and name it for example fopConfiguration.xml.

<fop version="1.0">
  <base>file:/C:/path/to/FOP/font/metrics/files/</base>
  <source-resolution>72</source-resolution>
  <target-resolution>72</target-resolution>
  <default-page-settings height="11in" width="8.26in"/>































































































































































































































































































































































































































































































































  <renderers>
    <renderer mime="application/pdf">
      <filterList>
        <value>flate</value>
      </filterList>
      <fonts>
          <font metrics-url="Arialuni.xml" kerning="yes" 
                embed-url="file:/Library/Fonts/Arialuni.ttf">
              <font-triplet name="Arialuni" style="normal" 
                    weight="normal"/>
          </font>
      </fonts>
    </renderer>
  </renderers>
</fop>
                       

The embed-url attribute points to the TTF file to be embedded. You have to specify it using the URL convention. The metrics-url attribute points to the font metrics file with a path relative to the base element. The triplet refers to the unique combination of name, weight, and style (italic) for each variation of the font. In our case is just one triplet, but if the font had variants, you would have to specify one for each variant. Here is an hypothetic example for the Arial Unicode if it had italic and bold variants:

<fop version="1.0">
  ...
    <fonts>
        <font metrics-url="Arialuni.xml" kerning="yes" 
              embed-url="file:/Library/Fonts/Arialuni.ttf">
            <font-triplet name="Arialuni" style="normal" 
                  weight="normal"/>
        </font>
        <font metrics-url="Arialuni-Bold.xml" kerning="yes" 
              embed-url="file:/Library/Fonts/Arialuni-Bold.ttf">
            <font-triplet name="Arialuni" style="normal" 
































































































































































































































































                  weight="bold"/>
        </font>
        <font metrics-url="Arialuni-Italic.xml" kerning="yes" 
              embed-url="file:/Library/Fonts/Arialuni-Italic.ttf">
            <font-triplet name="Arialuni" style="italic" 
                  weight="normal"/>
        </font>
    </fonts>
  ...
</fop>
                       

More details about the FOP configuration file are available on http://xmlgraphics.apache.org/fop/0.93/configuration.htmlthe FOP website.

Set FOP configuration file in Oxygen

Go to menu OptionsPreferencesXMLXSLT / FO / XQueryFO Processors

Click the browse button near Configuration file for the built-in FOP text field and locate the fopConfiguration.xml file.

Click on the OK button to accept the changes.

Add new font to FO output

You can do this by changing the stylesheet parameters.

DocBook Stylesheets

Create a transformation scenario that makes use of the docbook.xsl file from the [oXygen-install-dir]/frameworks/docbook/xsl/fo directory. You must do this in the Configure Transformation Scenario dialog.

Also you can use the predefined Docbook PDF scenario which is based on this Docbook stylesheet. Run a test transformation to make sure the PDF is generated. The Unicode characters are not yet displayed correctly. You have to specify to the stylesheet to generate FO output that uses the font Arialuni.

Click on the Parameters button in the transformation scenario edit dialog and enter the following parameters indicating the font for the body text and for the titles:

Table 10.1. XSL FO Parameters

NameValue
body.font.familyArialuni
title.font.familyArialuni


TEI Stylesheets

Create a transformation scenario that makes use of the tei.xsl file from the [oXygen-install-dir]/frameworks/tei/xsl/fo directory. Also you can use the predefined TEI PDF scenario which is based on this XSLT stylesheet. Run a test transformation to make sure the PDF is generated. Just like for the Docbook, you have to specify to the stylesheet to generate FO output that uses the font Arialuni.

Click on the Parameters button of the transformation scenario edit dialog and enter the following parameters indicating the font for the body text and for other sections:

Table 10.2. XSL FO Parameters

NameValue
bodyFontArialuni
sansFontArialuni


Run the transformation again. The characters are now displayed correctly.

DITA-OT Stylesheets

For setting a font to the Apache FOP processor in the transformation of a DITA map with an IDIOM FOP transformation there are two files that must be modified :

  • font-mappings.xml - available in folder ${frameworks}/dita/DITA-OT/demo/fo/cfg/fo: the font-face element included in each element physical-font having the attribute char-set="default" must contain the name of the font (Arialuni in our example) instead of the default value

  • fop.xconf - available in folder ${frameworks}/dita/DITA-OT/demo/fo/fop/conf: an element font must be inserted in the element fonts which is inside the element renderer having the attribute mime="application/pdf" as in the above fopConfiguration.xml file, for example:

    <renderer mime="application/pdf">
      . . .
       <fonts>
           <font metrics-url="Arialuni.xml" kerning="yes" 
               embed-url="file:/Library/Fonts/Arialuni.ttf">
               <font-triplet name="Arialuni" style="normal" 
                   weight="normal"/>
           </font>
       </fonts>
      . . .
    </renderer>

Common transformations

The following examples use the DocBook XSL Stylesheets to illustrate how to configure <oXygen/> for transformation to the various target formats.

Note

<oXygen/> comes with the latest versions of the DocBook and TEI frameworks including special XSLT stylesheets for DocBook and TEI documents. DocBook XSL extensions for the Saxon and Xalan processors are included in the frameworks/docbook/xsl/extensions directory.

The following steps are common to all the example procedures below.

  1. Set the editor focus to the document to be transformed.

  2. Select XMLConfigure transformation scenario (Alt+Shift+T C (Cmd+Alt+T C on Mac OS)) to open the Configure Transformation dialog.

  3. If you want to edit an existing scenario select that scenario in the list and press the Edit button. If you want to create a new scenario press the New button. If you want to create a new scenario based on an existing scenario select the scenario in the list and press the Duplicate button.

  4. Select the XSLT tab.

  5. Click the Browse for an input XSL file button. The Open dialog is displayed.

Note

During transformations the Editor Status Bar will show "Transformation - in progress". The transformation is successfully complete when the message "XSL transformation successful" displays. If the transform fails the message "XSL transformation failed" is displayed as an error message in the Messages Panel. The user can stop the transformation process, if the transformer offers such support, by pressing the "Stop transformation" button. In this case the message displayed in the status bar will be "Transformation stopped by user". For the specific case of an XQuery transformation, if you chose an NXD transformer, pressing the "Stop transformation" button will have no effect, as NXD transformers offer no such support.

PDF Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/fo/.

  2. Select docbook.xsl, click Open. The dialog closes.

  3. Select the FOP tab.

  4. Check the Perform FOP option. The remaining options are enabled.

  5. Select the following options:

    1. XSLT result as input.

    2. PDF as method.

    3. Built-in(Apache FOP) as processor.

  6. Select the Output tab.

  7. In the Save As field enter the output file name relative to the current directory (YourFileName.pdf ) or the path and output file name (C:\FileDirectory\YourFileName.pdf).

  8. Optionally, uncheck the XHTML and XML check boxes in the Show As group.

  9. Click Transform Now. The transformation is started.

PS Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/fo/.

  2. Select docbook.xsl, click Open. The dialog closes.

  3. Select the FOP tab.

  4. Check the Perform FOP option. The remaining options are enabled.

  5. Select the following options:

    1. XSLT result as input.

    2. PS as method.

    3. Built-in(Apache FOP) as processor.

  6. Select the Output tab.

  7. In the Save As field enter the output file name relative to the current directory (YourFileName.ps ) or the path and output file name (C:\FileDirectory\YourFileName.ps).

  8. Optionally, uncheck the XHTML and XML check boxes in the Show As group.

  9. Click Transform Now. The transformation is started.

TXT Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/fo/.

  2. Select docbook.xsl, click Open. The dialog closes.

  3. Select the FOP tab.

  4. Check the Perform FOP option. The remaining options are enabled.

  5. Select the following options:

    1. XSLT result as input.

    2. TXT as method.

    3. Built-in(Apache FOP) as processor.

  6. Select the Output tab.

  7. In the Save As field enter the output file name relative to the current directory (YourFileName.txt ) or the path and output file name (C:\FileDirectory\YourFileName.txt).

  8. Optionally, uncheck the XHTML and XML check boxes in the Show As group.

  9. Click Transform Now. The transformation is started.

HTML Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/html/.

  2. Select docbook.xsl, click Open. The dialog closes.

  3. Select the FOP tab.

  4. Uncheck the Perform FOP option. The FOP options are disabled.

  5. Select the Output tab.

  6. In the Save As field enter the output file name relative to the current directory (YourFileName.html ) or the path and output file name (C:\FileDirectory\YourFileName.html).

    1. If your pictures are not located relative to the out location, check the XHTML check box in the Show As group.

    2. Specify the path to the folder or URL where the pictures are located

  7. Click Transform Now. The transformation is started.

HTML Help Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/htmlhelp/.

  2. Select htmlhelp.xsl, click Open. The dialog closes.

  3. Set the XSLT parameter base.dir, it identifies the output directory. (If not specified, the output directory is system dependent.) Also set the manifest.in.base.dir to 1 in order to have the project files copied in output as well.

  4. Select the FOP tab.

  5. Uncheck the Perform FOP option. The FOP options are disabled.

  6. Click Transform Now. The transformation is started.

  7. At the end of the transformation you should find the html, hhp and hhc files in the base.dir directory.

  8. Download Microsoft's HTML Help Workshop and install it.

  9. Apply the HTML Help compiler called hhc.exe on the html, hhp and hhc files in the base.dir directory.

Java Help Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/javahelp/.

  2. Select javahelp.xsl, click Open. The dialog closes.

  3. Set the XSLT parameter base.dir, it identifies the output directory. (If not specified, the output directory is system dependent.)

  4. Select the FOP tab.

  5. Uncheck the Perform FOP option. The FOP options are disabled.

  6. Click Transform Now. The transformation is started.

XHTML Output

  1. Change directory to [oxygen]/frameworks/docbook/xsl/xhtml/.

  2. Select docbook.xsl, click Open. The dialog closes.

  3. Select the FOP tab.

  4. Uncheck the Perform FOP option. The FOP options are disabled.

  5. Select the Output tab.

  6. In the Save As field enter the output file name relative to the current directory (YourFileName.html ) or the path and output file name (C:\FileDirectory\YourFileName.html).

    1. If your pictures are not located relative to the out location, check the XHTML check box in the Show As group.

    2. Specify the path to the folder or URL where the pictures are located

  7. Click Transform Now. The transformation is started.

Supported XSLT processors

The <oXygen/> distribution comes with the following XSLT processors:

Xalan 2.7.1

Xalan-Java http://xml.apache.org/xalan-j/ is an XSLT processor for transforming XML documents into HTML, text, or other XML document types. It implements XSL Transformations (XSLT) Version 1.0 and XML Path Language (XPath) Version 1.0.

Saxon 6.5.5

Saxon 6.5.5 is an XSLT processor, which implements the Version 1.0 XSLT and XPath with a number of powerful extensions. This version of Saxon also includes many of the new features that were first defined in the XSLT 1.1 working draft, but for conformance and portability reasons these are not available if the stylesheet header specifies version="1.0".

Saxon 9.2.0.6 Home Edition (HE), Professional Edition (PE)

Saxon-HE/PE http://saxon.sf.net/ implements the "basic" conformance level for XSLT 2.0 and XQuery. The term basic XSLT 2.0 processor is defined in the draft XSLT 2.0 specifications: it is a conformance level that requires support for all features of the language other than those that involve schema processing. The HE product remains open source, but removes some of the more advanced features that were present in Saxon-PE.

Saxon 9.2.0.6 Enterprise Edition (EE)

Saxon EE http://www.saxonica.com/ is the schema-aware edition of Saxon 9 and it is one of the built-in processors of <oXygen/>. Saxon EE includes an XML Schema processor, and schema-aware XSLT, XQuery, and XPath processors.

The validation in schema aware transformations is done according to the W3C XML Schema 1.0 specification or according to the W3C XML Schema 1.1 one. This can be configured in Preferences.

Besides the above list <oXygen/> supports the following processors:

Xsltproc (libxslt)

Libxslt http://xmlsoft.org/XSLT/ is the XSLT C library developed for the Gnome project. Libxslt is based on libxml2 the XML C library developed for the Gnome project. It also implements most of the EXSLT set of processor-portable extensions functions and some of Saxon's evaluate and expressions extensions. The libxml2 version included in <oXygen/> is 2.7.6 and the libxslt version is 1.1.26

<oXygen/> uses Libxslt through its command line tool (Xsltproc). The XSLT processor is included into the distribution kit of the stand-alone version for Windows and Mac OS X. Because there are differences between different Linux distributions, on Linux you must install Libxslt on your machine as a separate application and set the PATH variable to contain the Xsltproc executable.

If you do not have the Libxslt library already installed, you should copy the following files from <oXygen/> stand-alone installation directory to root of the com.oxygenxml.editor_11.1.0 plugin

  • Windows: xsltproc.exe; zlib1.dll,libxslt.dll,libxml2.dll, libexslt.dll,iconv.dll

  • Linux: xsltproc,libexslt.so.0, libxslt.so.1,libxsml2.so.2

  • Mac OSX: xsltproc.mac, libexslt, libxslt, libxml

The Xsltproc processor can be configured from the XSLTPROC options page.

Note

Known problem: file paths containing spaces are not handled correctly in the LIBXML processor. For example the built-in XML catalog files of the predefined document types (DocBook, TEI, DITA, etc) are not handled by LIBXML if <oXygen/> is installed in the default location on Windows (C:\Program Files) because the built-in XML catalog files are stored in the frameworks subdirectory of the installation directory which in this case contains at least a space character.

MSXML 3.0/4.0

MSXML 3.0/4.0 http://msdn.microsoft.com/xml/ is available only on Windows 2000, Windows NT and Windows XP platforms. It can be used for transformationand validation of XSLT stylesheets .

<oXygen/> use the Microsoft XML parser through its command line tool msxsl.exe

Because msxsl.exe is only a wrapper, Microsoft Core XML Services (MSXML) must be installed on the computer otherwise you get an corresponding warning. You can get the latest Microsoft XML parser from Microsoft web-site http://www.microsoft.com/downloads/details.aspx?FamilyId=3144B72B-B4F2-46DA-B4B6-C5D7485F2B42&displaylang=en

MSXML .NET

MSXML .NET http://msdn.microsoft.com/xml/ is available only on Windows NT4, Windows 2000 and Windows XP platforms. It can be used for transformationand validation of XSLT stylesheets .

<oXygen/> performs XSLT transformations and validations using .NET Framework's XSLT implementation (System.Xml.Xsl.XslTransform class) through the nxslt command line utility. The nxslt version included in <oXygen/> is 1.6.

You should have the .NET Framework version 1.0 already installed on your system otherwise you get this warning: MSXML.NET requires .NET Framework version 1.0 to be installed. Exit code: 128

You can get the .NET Framework version 1.0 from Microsoft web-site http://www.microsoft.com/downloads/details.aspx?FamilyID=d7158dee-a83f-4e21-b05a-009d06457787&displaylang=en

.NET 1.0

A transformer based on the System.Xml 1.0 library available in the .NET 1.0 and .NET 1.1 frameworks from Microsoft (http://msdn.microsoft.com/xml/). It is available only on Windows.

You should have the .NET Framework version 1.0 or 1.1 already installed on your system otherwise you get this warning: MSXML.NET requires .NET Framework version 1.0 to be installed. Exit code: 128

You can get the .NET Framework version 1.0 from Microsoft web-site http://www.microsoft.com/downloads/details.aspx?FamilyID=d7158dee-a83f-4e21-b05a-009d06457787&displaylang=en

.NET 2.0

A transformer based on the System.Xml 2.0 library available in the .NET 2.0 framework from Microsoft (http://msdn.microsoft.com/xml/). It is available only on Windows.

You should have the .NET Framework version 2.0 already installed on your system otherwise you get this warning: MSXML.NET requires .NET Framework version 2.0 to be installed. Exit code: 128

You can get the .NET Framework version 2.0 from Microsoft web-site http://www.microsoft.com/downloads/details.aspx?FamilyID=9655156b-356b-4a2c-857c-e62f50ae9a55&DisplayLang=en

Saxon.NET

Saxon.NET http://weblog.saxondotnet.org/ is the port of Saxon 9B XSLT processor to the .NET platform and it is available on a Mozilla Public License 1.0 (MPL) from the Mozilla site.

In order to use it you have to unzip in the <oXygen/> install folder the Saxon.NET distribution which you can download from http://saxon.sourceforge.net/.

You should have the .NET Framework version 1.1 already installed on your system otherwise you get this warning: Saxon.NET requires .NET Framework 1.1 to be installed.

You can get the .NET Framework version 1.1 from Microsoft web-site http://www.microsoft.com/downloads/ThankYou.aspx?familyId=262d25e3-f589-4842-8157-034d1e7cf3a3&displayLang=en

Note

There is no integrated XML Catalog support for MSXML 3.0/4.0 and .NET processors.

Configuring custom XSLT processors

One can configure other XSLT transformation engines than the ones which come with the <oXygen/> distribution. Such an external engine can be used for XSLT transformations within <oXygen/>, in the Editor perspective, and is available in the list of engines in the dialog for editing transformation scenarios.However it cannot be used in the XSLT Debugger perspective.

The output messages of a custom processor are displayed in an output view at the bottom of the <oXygen/> window. If an output message follows the format of an <oXygen/> linked message then a click on the message in the output view highlights the location of the message in an editor panel containing the file referred in the message.

Configuring the XSLT processor extensions paths

The Xalan and Saxon processors support the use of extension elements and extension functions. Unlike a literal result element, which the stylesheet simply transfers to the result tree, an extension element performs an action. The extension is usually used because the xslt stylesheet fails in providing adequate functions to the user for accomplishing a more complex task.

Samples on how to use extensions can be found at:

In order to set an XSLT processor extension (a directory or a jar file), you have to use the Extensions button of the scenario edit dialog. The old way of setting an extension (using the parameter -Dcom.oxygenxml.additional.classpath) was deprecated and you should use the extension mechanism of the XSLT transformation scenario.