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 Information view.
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.
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.
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.
Text files are Plain ASCII Text and can be opened in any text editor or word processor.
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 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 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.
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 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 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:
XSLT is a language for transforming XML documents.
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: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.
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:
Such a scenario contains the location of an XSLT stylesheet that is applied on the edited XML document and other transform parameters.
Such a scenario contains the location of an XML document that the edited XSLT stylesheet is applied on and other transform parameters.
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.
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:
Warnings view to let the user know about it.
- 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 theTransform with... - allows the user to select one transformation scenario to be applied to each one of the currently selected files.
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.
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 button on the Transformation toolbar of the document view. Once selected the scenario will be applied with only one click on the 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 + → (Ctrl+Shift+C).
The Scenario type controls which scenarios are presented to the user. The available scenario types are:
Represents a transformation that consists in applying an XSLT stylesheet over an XML.
Represents a transformation that consists in applying an XQuery over an XML. More about executing XQuery statements can be found here.
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.
Represents a transformation that consists in applying an XSLT stylesheet over an XML file.
Represents a transformation that consists in applying an XQuery over an XML. More about executing XQuery statements can be found here.
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:
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:
Opens a pop-up menu allowing to introduce special <oXygen/> editor variables or custom editor variables in the XML URL field.
Opens a local file browser dialog allowing to select a local file name for the text field.
Opens a URL browser dialog allowing to select a remote file name for the text field.
Opens a zip archive browser dialog allowing to select a file name from a zip archive that will be inserted in the text field.
Opens the file with the path specified in the text field in an editor panel.
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 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.
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.
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.
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.
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.
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.
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.
The advanced options specific for Saxon PE / EE are:
Specifies to the transformer the initial template mode
Specifies the name of the initial template to the transformer. When specified, the XML input URL for the transformation scenario is optional.
If checked, the specified Saxon configuration file will be used to specify the Saxon advanced options.
If checked the stylesheet is disallowed to call external Java functions.
If checked display a warning when it is applied to an XSLT 1.0 stylesheet.
If checked the source XML file is validated against the declared DTD
Include the line number in errors for the
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 feature can be one of the three options: All, Ignorable, None.
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.
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.
strips no whitespace before further processing. (However, whitespace will still be stripped if this is specified in the stylesheet using xsl:strip-space).
Available only for Saxon SA.
This mode requires an XML Schema and determines whether source documents should be parsed with schema-validation enabled.
This mode determines whether source documents should be parsed with schema-validation enabled if an XML Schema is provided.
This determines whether source documents should be parsed with schema-validation disabled.
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
project file: ${pdu}/docbook/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 .
![]() | Note |
---|---|
If you are sharing the scenarios by saving them into the project file (see Transformation Scenario Sharing)
it is recommended that the URL fields to have path values relative to the project
editor variable
|
Enable or disable applying an FO processor (either the built-in Apache FOP engine or an external engine defined in Preferences) during the transformation.
The FO processor is applied to the result of the XSLT transformation defined on the XSLT tab of the dialog.
The FO processor is applied directly to the current edited document.
The output format of the FO processing: PDF, PostScript or plain text.
The FO processor, which can be the built-in Apache FOP processor or an external processor.
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.
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.
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).
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.
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.
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.
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. |
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.
If this is checked <oXygen/> will display the transformation result in a SVG viewer panel at the bottom of the <oXygen/> window by rendering the result as a SVG image.
If Show As XHTML is checked this text field specifies the path for resolving image paths contained in the transformation result.
The global parameters of the XSLT stylesheet used in the transformation scenario are configured from the dialog available from the Parameters button:
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 a new parameter to the list.
Edit the value of the selected parameter.
Reset the selected parameter to the default value. This button is enabled only for parameters with edited values, that is values set in this dialog with the Edit button.
Remove the selected parameter from the list. It is enabled only for parameters added to the list with the Add button.
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'
The list of additional XSLT stylesheets can be edited in the dialog opened by the button Additional XSLT Stylesheets.
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.
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.
Deletes the selected stylesheet from the "Additional XSLT stylesheets" list.
Opens the selected stylesheet in a separate view .
Move the selected stylesheet up in the list.
Move the selected stylesheet down in the list.
This dialog allows the user to add additional XSLT stylesheets to the transformation.
The path specified in the URL text field can include special <oXygen/> editor variables.
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.In the upper part of the dialog showing the list of scenarios you will find two radio buttons controlling where the scenarios are stored.
Selecting "Global Scenarios" ensures that the scenarios are saved in the user home directory.
After changing the selection to "Project Scenarios", the scenario list will be stored in the project file. If your project is saved on a source versioning/sharing system (CVS, SVN, Source Safe, etc..) then your team can use the scenarios you defined.
Predefined scenarios are presented according to the current document's detected type. The screenshot above shows all default scenarios for a DocBook 4 document and one custom transformation scenario. The key symbol before the scenario name indicates that the scenario can only be modified from the Document Type Association options page.
Other preferences can also be stored at the project level. For more information, see the Preference Sharing section.
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.
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.
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.
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.
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 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.
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.
Go to menu
→ → → →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.
You can do this by changing the stylesheet parameters.
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:
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:
Run the transformation again. The characters are now displayed correctly.
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>
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 |
The following steps are common to all the example procedures below.
Set the editor focus to the document to be transformed.
Select Ctrl+Shift+C) to open the Configure Transformation dialog.
+ → (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.
Select the XSLT tab.
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. |
Change directory to [oxygen]/frameworks/docbook/xsl/fo/.
Select docbook.xsl
, click . The
dialog closes.
Select the FOP tab.
Check the
option. The remaining options are enabled.Select the following options:
XSLT result as input.
PDF as method.
Built-in(Apache FOP) as processor.
Select the Output tab.
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
).
Optionally, uncheck the XHTML and XML check boxes in the Show As group.
Click
. The transformation is started.Change directory to [oxygen]/frameworks/docbook/xsl/fo/.
Select docbook.xsl
, click . The
dialog closes.
Select the FOP tab.
Check the
option. The remaining options are enabled.Select the following options:
XSLT result as input.
PS as method.
Built-in(Apache FOP) as processor.
Select the Output tab.
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
).
Optionally, uncheck the XHTML and XML check boxes in the Show As group.
Click
. The transformation is started.Change directory to [oxygen]/frameworks/docbook/xsl/fo/.
Select docbook.xsl
, click . The
dialog closes.
Select the FOP tab.
Check the
option. The remaining options are enabled.Select the following options:
XSLT result as input.
TXT as method.
Built-in(Apache FOP) as processor.
Select the Output tab.
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
).
Optionally, uncheck the XHTML and XML check boxes in the Show As group.
Click
. The transformation is started.Change directory to [oxygen]/frameworks/docbook/xsl/html/.
Select docbook.xsl
, click . The
dialog closes.
Select the FOP tab.
Uncheck the
option. The FOP options are disabled.Select the Output tab.
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
).
If your pictures are not located relative to the out location, check the XHTML check box in the Show As group.
Specify the path to the folder or URL where the pictures are located
Click
. The transformation is started.Change directory to [oxygen]/frameworks/docbook/xsl/htmlhelp/.
Select htmlhelp.xsl
, click . The
dialog closes.
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.
Select the FOP tab.
Uncheck the
option. The FOP options are disabled.Click
. The transformation is started.At the end of the transformation you should find the html, hhp and hhc files in the base.dir directory.
Download Microsoft's HTML Help Workshop and install it.
Integrate HTML Help Workshop as an external tool. Go to External Tools → +
Create a new external tool entry named HTMLHelp with Working directory being the
same with the base.dir parameter defined above and Configure command set to [path to
installed HTML Help Workshop]\hhc.exe <filename>, where <filename> is
the name of the html help project file (for example
htmlhelp.hhp
).
Run the tool from → → .
Change directory to [oxygen]/frameworks/docbook/xsl/javahelp/.
Select javahelp.xsl
, click . The
dialog closes.
Set the XSLT parameter base.dir, it identifies the output directory. (If not specified, the output directory is system dependent.)
Select the FOP tab.
Uncheck the
option. The FOP options are disabled.Click
. The transformation is started.Change directory to [oxygen]/frameworks/docbook/xsl/xhtml/.
Select docbook.xsl
, click . The
dialog closes.
Select the FOP tab.
Uncheck the
option. The FOP options are disabled.Select the Output tab.
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
).
If your pictures are not located relative to the out location, check the XHTML check box in the Show As group.
Specify the path to the folder or URL where the pictures are located
Click
. The transformation is started.The <oXygen/> distribution comes with the following XSLT processors:
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 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-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 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:
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.
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 http://msdn.microsoft.com/xml/ is available only on Windows 2000, Windows NT and Windows XP platforms. It can be used for transformation and 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 http://msdn.microsoft.com/xml/ is available only on Windows NT4, Windows 2000 and Windows XP platforms. It can be used for transformation and 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
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
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 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. |
The button Transformation toolbar allows quick access to the XSLT options in the <oXygen/> user preferences.
available on theOne 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.
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.
Extensions for Xalan and Saxon are included in [<oXygen/> install directory] \frameworks\docbook\xsl\extensions. If you want to use the extensions group for Xalan, you have to rename the file "xalan27.jar.ext" to "xalan27.jar". Same specifications for Saxon: rename "saxon65.jar.ext" to "saxon65.jar". You can only use one group of extensions at a time.
Samples on how to use extensions can be found at:
for Xalan - http://xml.apache.org/xalan-j/extensions.html
for Saxon 6.5.5 - http://saxon.sourceforge.net/saxon6.5.5/extensions.html
for Saxon 9.2.0.6 - http://www.saxonica.com/documentation/extensions/intro.html
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.