0% found this document useful (0 votes)

170 views

Technical Documentation

Uploaded by

P.Prabu Dass

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

170 views

Technical Documentation

Uploaded by

P.Prabu Dass

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 392

Oxygen XML Author 12.

2
Oxygen XML Author | TOC | 3

Contents

Chapter 1: Introduction................................................................................11
Key Features and Benefits of Oxygen XML Author .............................................................................12

Chapter 2: Installation..................................................................................13
Installation Requirements.......................................................................................................................14
Platform Requirements...............................................................................................................14
Operating System.......................................................................................................................14
Environment Requirements........................................................................................................14
Installation Instructions..........................................................................................................................14
Eclipse Plugin.............................................................................................................................15
Obtaining and Registering a License Key..............................................................................................16
Named User License Registration..............................................................................................16
Named User License Registration with Text File.......................................................................17
How Floating (Concurrent) Licenses Work................................................................................17
License Registration with an Activation Code...........................................................................22
Unregistering the License Key...............................................................................................................22
Upgrading the Oxygen XML Author Application..................................................................................22
Upgrading the Eclipse Plugin.....................................................................................................22
Checking for New Versions....................................................................................................................23
Uninstalling the Application...................................................................................................................23
Uninstalling the Eclipse plugin..................................................................................................23

Chapter 3: Getting Started...........................................................................25

Getting Help...........................................................................................................................................26
Supported Types of Documents..............................................................................................................26
Perspectives............................................................................................................................................26
Oxygen XML Perspective .........................................................................................................27
Oxygen Database Perspective ...................................................................................................30

Chapter 4: Editing Documents.....................................................................33

Working with Unicode...........................................................................................................................34
Opening and Saving Unicode Documents..................................................................................34
Opening and Closing Documents...........................................................................................................34
Creating New Documents..........................................................................................................34
Saving Documents......................................................................................................................38
Opening and Saving Remote Documents via FTP/SFTP ..........................................................38
Opening the Current Document in a Web Browser....................................................................42
4 | Oxygen XML Author | TOC

Closing Documents....................................................................................................................42
Viewing File Properties..............................................................................................................42
Editing XML Documents.......................................................................................................................42
Associate a Schema to a Document...........................................................................................43
Streamline with Content Completion.........................................................................................46
Validating XML Documents......................................................................................................53
Document Navigation.................................................................................................................61
Grouping Documents in XML Projects.....................................................................................64
Working with XML Catalogs.....................................................................................................67
Formatting and Indenting Documents (Pretty Print)..................................................................68
Viewing Status Information........................................................................................................69
XML Editor Specific Actions.....................................................................................................69
Handling Read-Only Files......................................................................................................................72

Chapter 5: Authoring in the Tagless Editor................................................73

Authoring XML Documents Without the XML Tags............................................................................74
General Author Presentation..................................................................................................................75
Author Views..............................................................................................................................76
The Author Editor.......................................................................................................................81
Review........................................................................................................................................93
Profiling / Conditional Text........................................................................................................95

Chapter 6: Author for DITA.......................................................................101

Creating DITA Maps and Topics..........................................................................................................102
Editing DITA Maps..............................................................................................................................102
Editing Actions.........................................................................................................................104
Creating a Map.........................................................................................................................105
Validating DITA Maps.............................................................................................................105
Create a Topic in a Map............................................................................................................106
Organize Topics in a Map.........................................................................................................106
Create a Bookmap....................................................................................................................106
Create a Subject Scheme..........................................................................................................107
Create Relationships Between Topics......................................................................................107
Advanced Operations...............................................................................................................108
Transforming DITA Maps and Topics..................................................................................................111
Available Output Formats.........................................................................................................111
Configuring a DITA Transformation........................................................................................113
Running a DITA Map ANT Transformation............................................................................114
Customizing a DITA Scenario..................................................................................................114
Set a Font for PDF Output Generated with Apache FOP.........................................................120
DITA-OT Customization......................................................................................................................120
Support for Transformation Customizations............................................................................120
Using Your Custom Build File.................................................................................................120
Oxygen XML Author | TOC | 5

Customizing the Oxygen Ant Tool...........................................................................................120

Upgrading to a New Version of DITA OT................................................................................120
Increasing the Memory for the Ant Process.............................................................................121
Resolving Topic References Through an XML Catalog..........................................................121
DITA Specialization Support...............................................................................................................121
Integration of a DITA Specialization.......................................................................................121
Editing DITA Map Specializations..........................................................................................121
Editing DITA Topic Specializations.........................................................................................122
Use a New DITA Open Toolkit in Oxygen..........................................................................................122
Reusing Content...................................................................................................................................122
Working with Content References...........................................................................................123
How to Work with Reusable Components...............................................................................123
Insert a Direct Content Reference............................................................................................124
DITA Profiling / Conditional Text........................................................................................................124
Profiling / Conditional Text Markers.......................................................................................125
Publish Profiled Text................................................................................................................125
Working with MathML........................................................................................................................126

Chapter 7: Predefined Document Types....................................................127

Document Type....................................................................................................................................128
The DocBook 4 Document Type..........................................................................................................128
Author Extensions....................................................................................................................129
Transformation Scenarios.........................................................................................................131
Templates..................................................................................................................................131
The DocBook 5 Document Type..........................................................................................................131
Author Extensions....................................................................................................................132
Transformation Scenarios.........................................................................................................132
Templates..................................................................................................................................132
The DocBook Targetset Document Type.............................................................................................132
Templates..................................................................................................................................133
The DITA Topics Document Type........................................................................................................133
Author Extensions....................................................................................................................133
Transformation Scenarios.........................................................................................................139
Templates..................................................................................................................................139
The DITA Map Document Type...........................................................................................................139
Author Extensions....................................................................................................................140
Transformation Scenarios.........................................................................................................140
Templates..................................................................................................................................140
The XHTML Document Type..............................................................................................................140
Author Extensions....................................................................................................................141
Transformation Scenarios.........................................................................................................142
Templates..................................................................................................................................142
The TEI P4 Document Type.................................................................................................................143
Author Extensions....................................................................................................................143
6 | Oxygen XML Author | TOC

Transformation Scenarios.........................................................................................................144
Templates..................................................................................................................................144
The TEI P5 Document Type.................................................................................................................145
Transformation Scenarios.........................................................................................................145
Templates..................................................................................................................................145
The MathML Document Type..............................................................................................................145
Templates..................................................................................................................................145
The Microsoft Office OOXML Document Type..................................................................................146
The Open Office ODF Document Type...............................................................................................147
The OASIS XML Catalog Document Type.........................................................................................148
The XML Schema Document Type......................................................................................................148
The Relax NG Document Type............................................................................................................148
The NVDL Document Type.................................................................................................................148
The Schematron Document Type.........................................................................................................149
The Schematron 1.5 Document Type...................................................................................................149
The XSLT Document Type...................................................................................................................149
The XMLSpec Document Type............................................................................................................149
Transformation Scenarios.........................................................................................................150
Templates..................................................................................................................................150
The FO Document Type.......................................................................................................................150
Transformation Scenarios.........................................................................................................150
The EAD Document Type....................................................................................................................150
Templates..................................................................................................................................150
The EPUB Document Type..................................................................................................................151

Chapter 8: Author Developer Guide..........................................................153

Simple Customization Tutorial.............................................................................................................155
XML Schema...........................................................................................................................155
CSS Stylesheet.........................................................................................................................156
The XML Instance Template....................................................................................................158
Advanced Customization Tutorial - Document Type Associations......................................................159
Author Settings.........................................................................................................................160
Configuring New File Templates.............................................................................................177
Configuring XML Catalogs.....................................................................................................179
Configuring Transformation Scenarios....................................................................................179
Configuring Validation Scenarios.............................................................................................181
Configuring Extensions............................................................................................................183
Customizing the Default CSS of a Document Type.................................................................206
Document Type Sharing...........................................................................................................207
CSS Support in Oxygen Author...........................................................................................................208
CSS 2.1 Features......................................................................................................................208
CSS 3 Features.........................................................................................................................213
Additional Custom Selectors....................................................................................................216
Oxygen CSS Extensions...........................................................................................................217
Oxygen XML Author | TOC | 7

Example Files Listings - The Simple Documentation Framework Files.............................................223

XML Schema files...................................................................................................................223
CSS Files..................................................................................................................................225
XML Files................................................................................................................................227
XSL Files..................................................................................................................................229
Oxygen XML Author Component........................................................................................................230
Licensing..................................................................................................................................230
Installation Requirements.........................................................................................................231
Customization...........................................................................................................................232
Deployment..............................................................................................................................233

Chapter 9: Grid Editor................................................................................237

Layouts: Grid and Tree.........................................................................................................................239
Navigating the Grid..............................................................................................................................239
Specific Grid Actions...........................................................................................................................240
Sorting a Table Column............................................................................................................240
Inserting a Row in a Table........................................................................................................240
Inserting a Column in a Table..................................................................................................240
Clearing the Content of a Column............................................................................................240
Adding Nodes...........................................................................................................................240
Duplicating Nodes....................................................................................................................241
Refresh Layout.........................................................................................................................241
Start Editing a Cell Value.........................................................................................................241
Stop Editing a Cell Value.........................................................................................................241
Drag and Drop in the Grid Editor.........................................................................................................241
Copy and Paste in the Grid Editor........................................................................................................241
Bidirectional Text Support in the Grid Editor......................................................................................243

Chapter 10: Transforming Documents......................................................245

Output Formats.....................................................................................................................................246
Transformation Scenario......................................................................................................................247
Batch Transformation...............................................................................................................247
Built-in Transformation Scenarios...........................................................................................247
Defining a New Transformation Scenario................................................................................248
Transformation Scenarios View...............................................................................................257
XSLT Processors..................................................................................................................................258
Supported XSLT Processors.....................................................................................................258
Configuring Custom XSLT Processors....................................................................................259
Configuring the XSLT Processor Extensions Paths.................................................................260
XSL-FO Processors..............................................................................................................................260
The Built-in XSL-FO Processor...............................................................................................260
Add a Font to the Built-in FOP - The Simple Version.............................................................261
Add a Font to the Built-in FOP................................................................................................261
8 | Oxygen XML Author | TOC

XProc Transformations........................................................................................................................264
XProc Transformation Scenario...............................................................................................264
Integration of an External XProc Engine.................................................................................265

Chapter 11: Querying Documents..............................................................267

Running XPath Expressions.................................................................................................................268
What is XPath...........................................................................................................................268
Oxygen's XPath Console..........................................................................................................268
Working with XQuery..........................................................................................................................271
What is XQuery........................................................................................................................271
Syntax Highlight and Content Completion..............................................................................272
XQuery Outline View...............................................................................................................272
The XQuery Input View...........................................................................................................273
XQuery Validation....................................................................................................................274
Other XQuery Editing Actions.................................................................................................274
Transforming XML Documents Using XQuery.......................................................................274

Chapter 12: Working with Archives...........................................................277

Browsing and Modifying Archive Structure........................................................................................278
Working with EPUB.............................................................................................................................279
Create an EPUB.......................................................................................................................280
Publish to EPUB.......................................................................................................................280
Editing Files From Archives.................................................................................................................280

Chapter 13: Working with Databases........................................................281

Relational Database Support................................................................................................................282
Configuring Database Data Sources........................................................................................282
Configuring Database Connections..........................................................................................288
Resource Management.............................................................................................................293
Native XML Database (NXD) Support................................................................................................298
Configuring Database Data Sources........................................................................................298
Configuring Database Connections..........................................................................................300
Data Source Explorer View......................................................................................................303
WebDAV Connection...........................................................................................................................310
How to Configure a WebDAV Connection...............................................................................310
WebDAV Connection Actions..................................................................................................310

Chapter 14: Content Management System (CMS) Integration...............313

Integration with Documentum (CMS).................................................................................................314
Configure Connection to Documentum Server........................................................................314
Documentum (CMS) Actions in the Data Source Explorer View............................................315
Transformations on DITA Content from Documentum (CMS)...............................................319
Oxygen XML Author | TOC | 9

Chapter 15: Digital Signatures...................................................................321

Overview..............................................................................................................................................322
Canonicalizing Files.............................................................................................................................323
Certificates...........................................................................................................................................324
Signing Files.........................................................................................................................................324
Verifying the Signature.........................................................................................................................325

Chapter 16: Text Editor Specific Actions..................................................327

Finding and Replacing Text in the Current File...................................................................................328
The Find All Elements / Attributes Dialog...............................................................................328
Spell Checking.....................................................................................................................................329
Spell Checking Dictionaries.....................................................................................................330
Learned Words..........................................................................................................................331
Ignored Words..........................................................................................................................331
Automatic Spell Check.............................................................................................................331
Spell Checking in Multiple Files..............................................................................................331

Chapter 17: Configuring the Application..................................................333

Importing / Exporting Global Options.................................................................................................334
Preferences...........................................................................................................................................334
Oxygen License........................................................................................................................335
Global.......................................................................................................................................335
Fonts.........................................................................................................................................335
Document Type Association.....................................................................................................336
Editor........................................................................................................................................338
CSS Validator...........................................................................................................................360
XML.........................................................................................................................................360
Data Sources.............................................................................................................................376
Archive.....................................................................................................................................380
Custom Editor Variables...........................................................................................................382
Network Connections ..............................................................................................................382
Certificates...............................................................................................................................383
XML Structure Outline............................................................................................................384
Scenarios Management............................................................................................................385
View..........................................................................................................................................385
Automatically Importing the Preferences from the Other Distribution...............................................386
Reset Global Options...........................................................................................................................386
Scenarios Management........................................................................................................................386
Editor Variables....................................................................................................................................387
Custom Editor Variables...........................................................................................................387
10 | Oxygen XML Author | TOC

Chapter 18: Common Problems.................................................................389

The Scroll Function of my Notebook's Trackpad is Not Working.......................................................390
Syntax Highlight Not Available in Eclipse Plugin...............................................................................390
Problem Report Submitted on the Technical Support Form................................................................390
Chapter
1
Introduction
Topics: Welcome to the Oxygen XML Author 12.2.0 plugin for Eclipse User Manual.

• Key Features and Benefits of Oxygen XML Author plugin for Eclipse is a cross-platform application designed
Oxygen XML Author for authors who want to edit XML documents visually without extensive
knowledge about XML and XML related technologies. The WYSIWYG-like
editor is driven by CSS stylesheets associated with the XML documents and
offers the option to switch off XML tags completely when editing an XML
document.
This user guide is focused mainly at describing features, functionality and
application interface to help you get started in no time.
12 | Oxygen XML Author | Introduction

Key Features and Benefits of Oxygen XML Author

Multiplatform availability: Windows, Mac OS X, Linux, Non blocking operations, you can perform validation and
Solaris transformation operations in background
Visual WYSIWYG XML editing mode based on W3C Visual DITA Map editor
CSS stylesheets.
Closely integration of the DITA Open Toolkit for Support for latest versions of document frameworks:
generating DITA output DocBook and TEI.
Support for XML, XML Schema, Relax NG , Schematron, Support for XML, CSS, XSLT, XSL-FO.
DTD, NVDL schemas, XSLT, XSL:FO, WSDL, XQuery,
HTML, CSS
Multiple built-in validation engines (Xerces, libxml, Multiple built-in XSLT transformers (Saxon 6.5, Saxon 9
MSXML 4.0, MSXML.NET) and support for custom Enterprise (schema aware), Xalan, libxslt, MSXML 3.0 /
validation engines (Saxon SA, XSV, SQC). 4.0, Microsoft .NET 1.0, Microsoft .NET 2.0), support for
custom JAXP transformers.
Ready to use FOP support to generate PDF or PS XInclude support
documents
Context sensitive content assistant driven by XML Schema, New XML document wizards to easily create documents
Relax NG, DTD, NVDL or by the edited document specifying a schema or a DTD
structure enhanced with schema annotation presenter
XML Catalog support Unicode support
Easy error tracking - locate the error source by clicking on Easy configuration for external FO Processors
it
Apply XSLT and FOP transformations XPath search, evaluation and debugging support
Preview transformation results as XHTML or XML or in Support for document templates to easily create and share
your browser documents
Batch validate selected files in project Canonicalize and sign documents
Configurable actions key bindings Associate extensions with editors provided by the Oxygen
plugin.
Model View Attributes View
XSLT 2.0 full support XPath 2.0 execution and debugging support
Document folding Spell checking supporting English, German and French
including locals
Pretty-printing of XML files Drag&drop support
Outline view in sync with a non well-formed document
Chapter
2
Installation
Topics: This section explains platform requirements and installation procedures. It also
provides instructions on how to obtain and register a license key, how to perform
• Installation Requirements upgrades and uninstall the application.
• Installation Instructions
If you need help at any point during these procedures please send email to
• Obtaining and Registering a [email protected]
License Key
• Unregistering the License Key
• Upgrading the Oxygen XML
Author Application
• Checking for New Versions
• Uninstalling the Application
14 | Oxygen XML Author | Installation

Installation Requirements
This section contains details about the platform and environment requirements necessary for installing and running the
application.

Platform Requirements
The run-time requirements of the application are:
• CPU (processor): minimum - Intel Pentium III™/AMD Athlon™ class processor, 500 Mhz; recommended - Dual Core
class processor.
• Computer memory: minimum - 512 MB of RAM (1 GB on Windows Vista™ and Windows 7) ; recommended - 2
GB of RAM.
• Hard disk space: minimum - 300 MB free disk space ; recommended - 500 MB free disk space.

Operating System
Windows
Windows XP, Windows Vista, Windows 7, Windows 2003, Windows Server 2008

Mac OS
Mac OS X version 10.4 or later

Unix/Linux
Any Unix/Linux distribution with an available Java SE Runtime Environment version
1.5 or 1.6 from Oracle (formerly from Sun).

Environment Requirements
This section specifies the Java platform requirements and other tools that may be needed for installing the application.

Tools
Installation packages are supplied in compressed archives. Ensure you have installed a suitable archive extraction utility
with which to extract the archive. The MD5 sum is available on the Download page for every archive. You should check
the MD5 sum of the downloaded archive with a MD5 checking tool available on your platform.

Java Virtual Machine Prerequisites

Prior to installation ensure that the latest stable Eclipse version (available at the release date of Oxygen XML Author)
is installed on your computer. The current Eclipse version number is 3.6.
Oxygen XML Author supports only official and stable Java virtual machine versions 1.5.0 and later from Sun/Oracle
(available at http://java.sun.com) and from Apple Computer. The Java Virtual Machine from Apple is pre-installed on
Mac OS X computers. For Mac OS X, Java Virtual Machine updates are available at the Apple website. Oxygen XML
Author may work very well with JVM implementations from other vendors but the eventual incompatibilities will not
be solved in further Oxygen XML Author releases. Oxygen XML Author does not work with the GNU libgcj Java
virtual machine.

Installation Instructions
Before proceeding with the following instructions, please ensure that your system complies with the prerequisites detailed
in the installation requirements.
Oxygen XML Author | Installation | 15

Eclipse Plugin
This section contains the following installation procedures:
• Eclipse 3.3 Plugin Installation - The Update Site Method
• Eclipse 3.3 Plugin Installation - The Zip Archive Method
• Eclipse 3.4 - 3.7 Plugin Installation - The Update Site Method
• Eclipse 3.4 - 3.7 Plugin Installation - The Zip Archive Method

Eclipse 3.3 Plugin Installation - The Update Site Method

Installation procedure for the Eclipse plugin in Eclipse 3.3 with the Update Site method.

1. Start Eclipse.
2. Choose the Help > Software Update > Find and Install menu option.
3. Select Search for new features to install checkbox.
4. Press Next.
5. In the Update sites to visit dialog press the button Add Update Site or New Remote Site.
6. Enter the value http://www.oxygenxml.com/InstData/Eclipse/site.xml into the URL field of
the New Update Site dialog.
7. Press OK.
8. Select the oXygen XML Author checkbox.
9. Press Next.
10. Select the new feature to install oXygen XML Editor and XSLT debugger.
11. Press the Next button in the following install pages.
12. You must accept the Eclipse restart confirmation.
13. When prompted for a license key, paste the license information received in the registration email.
This will happen when you use one of the wizards to create an XML project or document, when you open or create
a document associated with Oxygen or when accessing the Oxygen Preferences.

The "oXygen XML Author plugin is installed correctly if you can create an XML project with the New Project wizard
of the "oXygen XML Author plugin started from menu File -> New -> Other -> oXygen -> XML Project.

Eclipse 3.3 Plugin Installation - The Zip Archive Method

Installation procedure for the Eclipse plugin in Eclipse 3.3 with the Zip Archive method.

1. Download the Eclipse Plugin zip distribution archive.

2. Unzip the downloaded zip archive in the plugins subfolder of the Eclipse install directory.
3. Restart Eclipse.

Eclipse should display an entry com.oxygenxml.author (12.2.0) in the list available from Window - Preferences - Plug-in
Development - Target Platform.

Eclipse 3.4 - 3.7 Plugin Installation - The Update Site Method

Installation procedure for the Eclipse plugin in Eclipse 3.4 - 3.7 with the Update Site method.

1. Start Eclipse.
2. Choose the Help > Software Updates > Available Software menu option.
3. Press Add Site in the Available Software tab of the Software Updates dialog.
4. Enter http://www.oxygenxml.com/InstData/Author/Eclipse/site.xml into the Location field
of the Add Site dialog.
5. Press OK.
16 | Oxygen XML Author | Installation

6. Select the oXygen XML Author checkbox.

7. Press Install.
8. Press the Next button in the following install pages.
9. You must accept the Eclipse restart confirmation.
10. When prompted for a license key, paste the license information received in the registration email.
This will happen when you use one of the wizards to create an XML project or document, when you open or create
a document associated with Oxygen or when accessing the Oxygen Preferences.

The "oXygen XML Author plugin is installed correctly if you can create an XML project with the New Project wizard
of the oXygen XML Author plugin started from menu File -> New -> Other -> oXygen -> XML Project.

Eclipse 3.4 - 3.7 Plugin Installation - The Zip Archive Method

The steps for installing the Eclipse plugin in Eclipse 3.4 - 3.7 with the Zip Archive method.

1. Download the zip archive with the plugin.

2. Unzip the downloaded zip archive in the dropins subdirectory of the Eclipse install directory.
3. Restart Eclipse.

Eclipse should display an entry com.oxygenxml.author (12.2.0) in the list available from Window - Preferences - Plug-in
Development - Target Platform.

Obtaining and Registering a License Key

The Oxygen XML Author is not free software and requires a license in order to enable the application.
For demonstration and evaluation purposes a time limited license is available upon request from the Oxygen web site.
This license is supplied at no cost for a period of 30 days from date of issue. During this period the Oxygen XML Author
is fully functional enabling you to test all aspects of the application. Thereafter, the application is disabled and a permanent
license must be purchased in order to use the application. For special circumstances, if a trial period of greater than 30
days is required, please contact [email protected] . All licenses are obtained from the Oxygen web site .
For definitions and legal details of the license types available for Oxygen XML Author you should consult the End User
License Agreement received with the license key and available also on the Oxygen XML Author website at
http://www.oxygenxml.com/eula_author.html

Named User License Registration

1. Save a backup copy of the message containing the new license key.
2. Start the application.
3. Copy to the clipboard the license text as explained in the message.
4. If this is a new install of the application then it will display automatically the registration dialog when it is started.
In the case you already used the application and obtained a new license, go to Window > Preferences > oXygen ,
Register button.
Oxygen XML Author | Installation | 17

Figure 1: Registration Dialog

5. Select Use a license key as licensing method.

6. Paste the license text in the registration dialog.
7. Press the OK button.

Named User License Registration with Text File

1. Save the license key in a file named licensekey.txt.
2. Copy the file in the lib subfolder of the install folder.
3. Start Eclipse.

How Floating (Concurrent) Licenses Work

Floating licenses are “pooled” licenses that can be shared across a group of users. They are most often deployed when
an organization has a group of users that will only consume a license for a minority of their working hours. The licenses
are returned back into the license pool as soon as they are released. Other users can then immediately reuse them.
The license management is done either by the application itself or by the Oxygen license server:
• if you plan to use the application on machines running in the same local network, Oxygen can manage the licenses
usage by itself. Different running instances of the application communicate between them. The registration procedure
requires you to paste the license key in the license registration dialog. See Named User License Registration procedure
for more details.
• if you plan to use the application on machines running in different network segments, then you must use a Oxygen
floating license server. A floating license server can be installed either as a Java servlet or as a standalone process.
18 | Oxygen XML Author | Installation

Setting up a Floating License Server Running as a Java Servlet

Setting up the floating license servlet.
Apache Tomcat 5.5 or higher is necessary. You can get it from: http://tomcat.apache.org/

1. Download the license servlet Web ARchive (.war) from one of the download URLs included in the registration
email message.
2. Go to the Tomcat Web Application Manager page. In the WAR file to deploy section choose the WAR file and then
press the Deploy button. The oXygen License Servlet should be up and running, but there is no licensing information
set.
3. To set the license key, log on the deployment machine, and go to the Tomcat installation folder (usually
/usr/local/tomcat). Then go to the webapps/oXygenLicenseServlet/WEB-INF/license/ folder
and create a new file called license.txt. Copy the license text that was sent to you via e-mail into this file and
save it.
4. It is recommended to password protect your pages using a Tomcat Realm. Please refer to the Tomcat Documentation
for detailed info, like the Realm Configuration HOW-TO - Memory Based Realm section.
5. Once you have defined a realm resource, you have to edit
webapps/oXygenLicenseServlet/WEB-INF/web.xml file to configure user access rights on the license
server. Note that Tomcat's standard security roles are used, i.e.: standard for licensing and admin or manager for
the license usage report page.
6. Restart oXygen License Servlet from the Tomcat Web Application Manager page.

Contact the Oxygen XML support staff at [email protected] and ask for a new license key if:
• you have multiple license keys for the same Oxygen version and you want to have all of them managed by the same
server;
• you have a multiple-user floating license and you want to split it between two or more license servers.
Report Page
You can access an activity report at
http://hostName:port/oXygenLicenseServlet/license-servlet/report.
It displays in real time the following information:
• License load - a graphical indicator that shows how many licenses are available. When the indicator turns red, there
are no more licenses available.
• Floating license server status - general information about the license server status like:
• server start time
• license count
• rejected and acknowledged requests
• average usage time
• license refresh and timeout intervals
• location of the license key
• server version

• License key information - license key data:

• licensed product
• registration name
• company name
• license category
• number of floating users
• Maintenance Pack validity

• Current license usage - lists all currently acknowledged users:

Oxygen XML Author | Installation | 19

• user name
• date and time when the license was granted
• name and IP address of the computer where Oxygen runs
• MAC address of the computer where Oxygen runs

Note: The report is available also in XML format at

http://hostName:port/oXygenLicenseServlet/license-servlet/report-xml.

Setting up a Floating License Server Running as a Standalone Process

Setting up the floating license server.

1. Download the license server installation kit for your platform from one of the download URLs included in the
registration email message with your floating license key.
2. Unzip the install kit in a new folder.
The Windows installer installs the license server as a Windows service. It provides the following optional features
that are not available in the other license server installers:
• Start the Windows service automatically at Windows startup
• Create shortcuts on the Start menu for starting and stopping the Windows service manually.
If you use the zip archive on Windows you have to run the scripts provided in the archive for installing, starting,
stopping and uninstalling the server as a Windows service.
The zip archive can be used for running the license server on any platform where a Java virtual machine can run
(Windows, Mac OS X, Linux / Unix, etc).
3. Start the server using the startup script.
The startup script is called licenseServer.bat for Windows and licenseServer.sh for Mac OS X and
Unix / Linux. It has 2 parameters:
• licenseDir - the path of the directory where the license files will be placed. Default value: license.
• port - the port number used to communicate with Oxygen XML Author instances. Default value: 12346.
The following is an example command line for starting the license server on Unix/Linux and Mac OS X:

sh licenseServer.sh myLicenseDir 54321

The following is an example command line for starting the license server on Windows:

licenseServer.bat myLicenseDir 54321

The license folder must contain a text file called license.txt which must contain a single floating license key
corresponding to the set of purchased floating licenses. If you have more than one floating license key for the same
Oxygen version obtained from different purchases or you want to split a set of license keys between 2 different servers
please contact us at [email protected] to merge / split your license keys.
Install the License Server as a Windows Service

1. Download the Windows installer of the license server from the URL provided in the registration email message
containing your floating license key.
2. Run the downloaded installer.
3. Enable the Windows service on the machine that hosts the license server.
If you want to install, start, stop and uninstall manually the server as a Windows service you must run the following
scripts from command line. On Windows Vista and Windows 7 you have to run the commands as Administrator.
20 | Oxygen XML Author | Installation

• installWindowsService.bat - install the server as Windows service with the name

"oXygenLicenseServer". The parameters for the license key folder and the server port can be set in the
oXygenLicenseServer.vmoptions file.
• startWindowsService.bat - start the Windows service.
• stopWindowsService.bat - stop the Windows service.
• uninstallWindowsService.bat - uninstall the Windows service created by the
installWindowsService.bat script.

When the license server is used as a Windows service the output and error messages are redirected automatically to the
following log files created in the install folder:
• outLicenseServer.log - server's standard output stream
• errLicenseServer.log - server's standard error stream
Note: Before starting the server, the JAVA_HOME variable must point to the home folder of a Java runtime
environment installed on your Windows system.

Note:
On Windows Vista and Windows 7 if you want to start or stop the Windows service with the Start menu shortcut
called Start Windows service / Stop Windows service you have to run the shortcut as Administrator.

Request a Floating License from a License Server Running as a Standalone Process

Figure 2: Floating License Server Running as a Standalone Process

1. Start the Eclipse platform.

2. Go to menu Window > Preferences > oXygen > Register .
The license dialog is displayed.
3. Choose Use a license server as licensing method.
4. Select Standalone server as server type.
5. Fill-in the Host text field with the host name or IP address of the license server.
6. Fill-in the Port text field with the port number used to communicate with the license server.
7. Click the OK button.

If the maximum number of available licenses was not exceeded a license key is received from the floating license server
and registered in Oxygen XML Author. The license details are displayed in the About dialog opened from the Help
menu. If the maximum number of licenses was exceeded a warning dialog pops up letting you know about the problem.
The message contains information about the users who requested and successfully received the floating licenses before
exceeding the maximum number of licenses.
Oxygen XML Author | Installation | 21

Request a Floating License from a License Server Running as a Java Servlet

Starting with Oxygen version 12.1, Oxygen can use a license server running as a Java Servlet to manage floating licenses.

Figure 3: Floating License Server Running as a Servlet

1. Start the Eclipse platform.

2. Go to menu Window > Preferences > oXygen > Register .
The license dialog is displayed.
3. Choose Use a license server as licensing method.
4. Select HTTP Server as server type.
5. Fill-in the URL text field with the address of the license server.
The URL address has the following format:
http://hostName:port/oXygenLicenseServlet/license-servlet/.
6. Fill-in the User and Password text fields. Contact your server administrator to supply you this information.
7. Click the OK button.

Release a Floating License

To manually release a floating license key to be returned to the server's pool of available license keys:

1. Go to the main Oxygen XML Author preferences panel .

2. Select Register.
3. Select Use a license key as licensing method.
4. Paste a Named User license key in the registration dialog. Leave the text area empty to return to the previously used
license key, if any.
5. Press the OK button of the dialog.
22 | Oxygen XML Author | Installation

License Registration with an Activation Code

If you have only an activation code and you want to register the associated license key you must request this license key
by filling the registration code and other details associated with your license in a request form on the Oxygen XML
Author website. The button Request license for registration code in the registration dialog available from menu
Window > Preferences > oXygen > Register opens this request form in the default Web browser on your computer.

Unregistering the License Key

Sometimes you need to unregister your license key, for example to release a floating license to be used by other user
and still use the current Oxygen XML Author instance with a Named User license, or to transfer your license key to
other computer before other user starts using your current computer.

1. Go to menu Windows > Preferences > oXygen > Register

This displays the license registration dialog.
2. Make sure the text area for the license key is empty.
3. Make sure the checkbox Use a license server is unchecked.
4. Press the OK button of the dialog.
This displays a confirmation dialog.
5. Select between falling back to the license key entered previously (for the case of releasing a floating license and
reverting to Named User license) and removing your license key from your user account of the computer.

Upgrading the Oxygen XML Author Application

From time to time, upgrade and patch versions of Oxygen XML Author are released to provide enhancements that rectify
problems, improve functionality and the general efficiency of the application.
Any personal configuration settings and customizations are preserved by installing an upgrade or a patch.

Upgrading the Eclipse Plugin

1. Uninstall the Oxygen XML Author plugin (see Uninstall procedure).
2. Follow the Installation instructions.
3. Restart the Eclipse platform.
4. Start the Oxygen XML Author plugin to ensure that the application can start and that your license is recognized by
the upgrade installation.
5. If you are upgrading to a major version, for example from 11.2 to 12.0, and you did not purchase a Maintenance
Pack that covers the new major version (12.0) you will need to enter a new license for version 12 into the registration
dialog that is shown when the plugin is started.
6. Go to menu Window > Preferences > Plug-In Development > Target Platform
7. The list entry contains the version number of the installed plugin. If the previous version was 11.2.0 the list entry
should now contain 12.0.0.
Oxygen XML Author | Installation | 23

Checking for New Versions

Oxygen XML Author offers the option of checking for new versions at the http://www.oxygenxml.com site when the
application is started.
You can check for new versions manually at any time by going to menu Help > Check for New Versions

Uninstalling the Application

This section contains uninstallation procedures.

Uninstalling the Eclipse plugin

Caution:
The following procedure will remove the Oxygen XML Author plugin from your system. It will not remove the
Eclipse platform. If you wish to uninstall Eclipse please see its uninstall instructions.

1. Choose the menu option Help > Software Update > Manage Configuration
2. Select Oxygen XML Author and XSLT Debugger from the list of plugins.
3. Select Disable
4. Accept to restart the Eclipse platform.
5. Choose the menu option Help Software Update Manage Configuration
6. Enable Show Disabled Features from the dialog toolbar.
7. Select Oxygen XML Author from the list of plugins.
8. Choose Uninstall in the right section of the displayed window
9. Accept the Eclipse restart.
10. If you want to remove also the user preferences that were configured in the Preferences dialog you must remove
the folder %APPDATA%\com.oxygenxml.author on Windows (usually %APPDATA% has the value
[user-home-dir]\Application Data) / the subfolder .com.oxygenxml.author of the user home directory on
Linux / the subfolder Library/Preferences/com.oxygenxml.author of the user home folder on Mac
OS X.
Chapter
3
Getting Started
Topics: This section will get you started with the editing perspectives of the application.

• Getting Help
• Supported Types of Documents
• Perspectives
26 | Oxygen XML Author | Getting Started

Getting Help
Online help is available at any time while working in Oxygen XML Author by going to Help > Help Contents >
oXygen User Manual for Eclipse

Supported Types of Documents

Oxygen XML Author provides a rich set of features for working with:
• XML documents and applications
• CSS documents

Perspectives
The interface uses standard interface conventions and components to provide a familiar and intuitive editing environment
across all operating systems.
In you can work with documents in one of the perspectives:

Editor perspective
Documents editing is supported by specialized and synchronized editors and views.

Oxygen Database perspective

Multiple connections to relational databases, native XML databases, WebDAV
sources and FTP sources can be managed at the same time in this perspective:
database browsing, SQL execution, XQuery execution and data export to XML.
Oxygen XML Author | Getting Started | 27

Oxygen XML Perspective

The Oxygen XML perspective is used for editing the content of your documents.
Figure 4: Oxygen XML perspective

As majority of the work process centers around the Editor panel, other panels can be hidden from view using the expand
and collapse controls located on the divider bars.
This perspective organizes the workspace in the following panels:

The Oxygen Custom Menu

When the current editor window contains a document associated with Oxygen a custom menu is added to the Eclipse
menu bar named after the document type: XML, XSL, XSD, RNG, RNC, Schematron, DTD, FO, WSDL, XQuery,
HTML, CSS.

The Oxygen Toolbar Buttons

The toolbar buttons added by the Oxygen plugin provide easy access to common and frequently used functions. Each
icon is a button that acts as a shortcut to a related function.
28 | Oxygen XML Author | Getting Started

The Editor Pane

The editor pane is where you edit your documents opened or created by the Oxygen Eclipse plugin. You know the
document is associated with Oxygen from the special icon displayed in the editor's title bar which has the same graphic
pattern painted with different colors for different types of documents.
This pane has three different modes of displaying and editing the content of a document available as different tabs at
the bottom left margin of the editor panel: Text mode, Grid Mode, Author mode (CSS based tagless editor).

The Outline View

Figure 5: The Outline View

The Oxygen Text View

The Oxygen Text view is automatically showed in the views pane of the Eclipse window to display text output from
XSLT transformations, FO processor's info, warning and error messages. It contains a tab for each file with text results
displayed in the view.
Oxygen XML Author | Getting Started | 29

Figure 6: The Text View

The Oxygen Browser View

The Oxygen Browser view is automatically showed in the views pane of the Eclipse window to display HTML output
from XSLT transformations. It contains a tab for each file with HTML results displayed in the view.

Figure 7: The Browser View

The Oxygen XPath Results View

The Oxygen XPath Results view is automatically showed in the views pane of the Eclipse window to display XPath
results.

Figure 8: The XPath Results View

Supported Editor Types

The Oxygen Eclipse plugin provides special Eclipse editors identified by the following icons:
30 | Oxygen XML Author | Getting Started

• - The XML documents icon

• - The JavaScript documents icon
• - The CSS documents icon

Oxygen Database Perspective

The Database perspective is similar to the Editor perspective. It allows you to manage a database, offering support for
browsing multiple connections at the same time, both relational and native XML databases, SQL execution, XQuery
execution and data export to XML.
This perspective offers database specific support for:
• Oracle Berkeley DB XML Database
• eXist XML Database
• IBM DB2 (Enterprise edition only)
• JDBC-ODBC Bridge (Enterprise edition only)
• MarkLogic (Enterprise edition only, XQuery support only)
• Microsoft SQL Server 2005 and Microsoft SQL Server 2008 (Enterprise edition only)
• MySQL
• Oracle 11g (Enterprise edition only)
• PostgreSQL 8.3 (Enterprise edition only)
• Software AG Tamino (Enterprise edition only)
• TigerLogic (Enterprise edition only, XQuery support only)
• Documentum xDb (X-Hive/DB) 10 XML Database (Enterprise edition only)
• Documentum (CMS) 6.5 (Enterprise edition only)
The XML capabilities of the databases marked in this list with "Enterprise edition only" are available only in the Enterprise
edition of Oxygen. The non-XML capabilities of any database listed here are available also in the Academic and
Professional editions of Oxygen by registering the database driver as a generic JDBC driver (the Generic JDBC type in
the list of driver types) when defining the data source for accessing the database in Oxygen.
The non-XML capabilities are:
• browsing the structure of the database instance;
• opening a database table in the Table Explorer view;
• handling the values from XML Type columns as String values.
The XML capabilities are:
• displaying an XML Schema node in the tree of the database structure (for databases with such an XML specific
structure) with actions for opening/editing/validating the schemas in an Oxygen editor panel;
• handling the values from columns of type XML Type as XML instance documents that can be opened and edited in
an Oxygen editor panel;
• validating an XML instance document added to an XML Type column of a table, etc.
For a detailed feature matrix that compares the Academic, Professional and Enterprise editions of Oxygen please go to
the Oxygen website.
Note: Only connections configured on relational data sources can be used to import data to XML or to generate
XML schemas.
Oxygen XML Author | Getting Started | 31

Figure 9: Database perspective

• Main menu - provides menu driven access to all the features and functions available within Oxygen.
• Main toolbar - provides easy access to common and frequently used functions. Each icon is a button that acts as a
shortcut to a related function.
• Editor panel - the place where you spend most of your time, reading, editing, applying markup and validating your
documents.
• Data Source explorer - provides browsing support for the configured connections.
• Table explorer - provides table content editing support: insert a new row, delete a table row, cell value editing, export
to XML file.
Chapter
4
Editing Documents
Topics: This chapter explains the editor types available in the Oxygen application and
how to work with them for editing different types of documents.
• Working with Unicode
• Opening and Closing Documents
• Editing XML Documents
• Handling Read-Only Files
34 | Oxygen XML Author | Editing Documents

Working with Unicode

Unicode provides a unique number for every character, independent of the platform and language. Unicode is an
internationally recognized standard, adopted by industry leaders. The Unicode is required by modern standards such as
XML, Java, ECMAScript (JavaScript), LDAP, CORBA 3.0, WML, etc., and is the official way to implement ISO/IEC
10646.
It is supported in many operating systems, all modern browsers, and many other products. The emergence of the Unicode
Standard, and the availability of tools supporting it, are among the most significant recent global software technology
trends. Incorporating Unicode into client-server or multi-tiered applications and websites offers significant cost savings
over the use of legacy character sets.
As a modern XML Editor, Oxygen provides support for the Unicode standard enabling your XML application to be
targeted across multiple platforms, languages, and countries without re-engineering. Internally, the Oxygen XML Editor
uses 16bit characters covering the Unicode Character set.
Note: Oxygen may not be able to display characters that are not supported by the operating system (either not
installed or unavailable).

Tip: Windows XP/2003: You can enable support for CJK (Chinese, Japanese, Korean) languages from Control
Panel / Regional and Language Options / Languages / Install files for East Asian languages.

Opening and Saving Unicode Documents

On loading documents Oxygen receives the encoding of the document from the Eclipse platform. This encoding is then
used to instruct the Java Encoder to load support for and to save the document using the specified code chart.
While in most cases you are using UTF-8, simply changing the encoding name causes the application to save the file
using the new encoding.
To edit documents written in Japanese or Chinese, change the font to one that supports the specific characters (a Unicode
font). For the Windows platform, Arial Unicode MS or MS Gothic is recommended. Do not expect Wordpad or Notepad
to handle these encodings. Use Internet Explorer or Word to examine XML documents.
When a document with a UTF-16 encoding is edited and saved in Oxygen, the saved document has a byte order mark
(BOM) which specifies the byte order of the document content. The default byte order is platform-dependent. That
means that a UTF-16 document created on a Windows platform (where the default byte order mark is UnicodeLittle)
has a different BOM than a UTF-16 document created on a Mac OS platform (where the byte order mark is UnicodeBig).
The byte order and the BOM of an existing document are preserved Oxygen when the document is edited and saved.

Opening and Closing Documents

This section explains the actions and wizards available for creating new files, opening existing files, and closing files.

Creating New Documents

This section details the procedures available for creating new documents.

Oxygen Plugin Wizard for New Document

The New wizard only creates a skeleton document containing the document prolog, a root element and possibly other
child elements depending on the options specific for each schema type.
Oxygen XML Author | Editing Documents | 35

The Oxygen plugin installs a series of Eclipse wizards for easy creation of new documents. Using these wizards you let
Oxygen complete details like the system ID or schema location of a new XML document, the minimal markup of a
DocBook article or the namespace declarations of a Relax NG schema.

1. Select File > New > -> Other (Ctrl+N) > oXygen or press the New toolbar button.
The New wizard is displayed.
2. Select a document type.
3. Click the Next button.
For example if XML was selected the Create an XML Document wizard is started.
The Create an XML Document dialog enables definition of an XML Document Prolog using the system identifier
of an XML Schema, DTD, Relax NG (full or compact syntax) schema, or NVDL (Namespace-based Validation
Dispatching Language) schema. As not all XML documents are required to have a Prolog, you may choose to skip
this step by clicking OK. If the prolog is required, complete the fields as described in the next step.
4. Type a name for the new document and press the Next button.
5. If Customize was clicked, the following dialog is opened. Depending on the selected document type, different
properties can be set:
•

Figure 10: New XML Document Dialog

• Schema URL - Path to the schema file. When a file is selected, Oxygen analyzes its content and tries to fill-in
the rest of the dialog;
• Schema type - The following options are available: XML Schema, DTD, RelaxNG XML syntax, RelaxNG
compact syntax, and NVDL;
• Public ID - Specifies the PUBLIC identifier declared in the document prolog;
• Namespace - The document namespace;
• Prefix - The prefix for the namespace of the document root;
• Root Element - Populated with elements defined in the specified schema, enables selection of the element
to be used as document root;
36 | Oxygen XML Author | Editing Documents

• Description - Shows a small description of the selected document root;

• Add optional content - When selected, the elements and attributes that are defined in the XML Schema as
optional, are generated in the skeleton XML document;
• Add first Choice particle - When selected, the first element of an xs:choice schema element is generated in
the skeleton XML document created in a new editor panel when the OK button is pressed.

Figure 11: New XSL Document Dialog

• Stylesheet version - Stylesheet version number. Possible options: 1.0 and 2.0;
• Generate stylesheet documentation - Generates the stylesheet documentation.
Oxygen XML Author | Editing Documents | 37

Figure 12: New XML Schema Document Dialog

• Target namespace - Specifies the schema target namespace;

• Namespace prefix declaration table - Contains namespace prefix declarations. Table information can be
managed using the New and Delete buttons.

Figure 13: New Schematron Document Dialog

• Schematron version - Specifies the Schematron version. Possible options: 1.5 and ISO.
38 | Oxygen XML Author | Editing Documents

Creating Documents Based on Templates

The New wizard enables you to select predefined templates or templates that have already been created in previous
sessions or by other users.
The list of templates presented in the dialog includes:
• Document Types templates - Templates supplied with the defined document types.
• User defined templates - The user can add template files in the templates folder of the Oxygen install directory.
Also in the option page Window > Preferences > oXygen > Editor > Templates > Document Templates can
be specified a custom templates folder to be scanned.

1. Go to menu File > New > Other > oXygen > New From Templates .
2. Select a document type.
3. Type a name for the new document and press the Next button.
4. Press the Finish button.

The newly created document already contains the structure and content provided in the template.
Document Templates
Templates are documents containing a predefined structure. They provide starting points on which one can rapidly build
new documents that repeat the same basic characteristics: file type, prolog, root element, existing content. Oxygen
installs a rich set of templates for a number of XML applications. You may also create your own templates from Options
> Windows > Preferences > oXygen > Editor > Templates > Document Templates and share them with other users.
You can also use editor variables in the template files' content and they will be expanded when the files are opened.

Saving Documents
The edited document can be saved with one of the following actions:
• File > Save > (Ctrl+S) .
• File > Save As : displays the Save As dialog, used either to name and save an open document to a file or to save an
existing file with a new name.
• File > Save All : Saves all open documents.

Opening and Saving Remote Documents via FTP/SFTP

Oxygen supports editing remote files, using the FTP, SFTP protocols. The remote files can be edited exactly as the local
ones, for example they can be added to a project, and can be subject to XSL and FO transformations.
You can open one or more remote files in the dialog Open using FTP/SFTP.
To improve the transfer speed, the content exchanged between Oxygen XML Author and the HTTP / WebDAV server
is compressed using the GZIP algorithm.
The current WebDAV Connection details can be saved using the button and then used in the Data Source Explorer
view.

The Dialog Open Using FTP/SFTP

The dialog Open using FTP/SFTP is displayed from the menu File > Open URL ... or from the toolbar button
Open URL ....
Oxygen XML Author | Editing Documents | 39

Figure 14: Open URL dialog

The displayed dialog is composed of several parts:

• The editable combo box, in which it can be specified directly the URL to be opened or saved.
Tip:
You can type in here an URL like ftp://[email protected]/home/test.xml if the file is accessible through
anonymous FTP.

This combo box is also displaying the current selection when the user changes selection by browsing the tree of
folders and files on the server.
• The Identification section contains the access credentials. If you want to browse for a file on a server, you have to
specify the user and password. This information is bound to the selected URL displayed in the File URL combo
box, and used further in opening/saving the file. If the check box Save is selected, then the user and password are
saved between editing sessions. The password is kept encrypted into the options file.
Note:
Your password is well protected. In the case the options file is used on other machine by a user with a different
username the password will become unreadable, since the encryption is username dependent. This is also true
if you add URLs having user and password to your project.

• The Browse for remote file section contains the server combo and the Autoconnect check box. Into the server combo
it may be specified the protocol , the name or IP of the server .
40 | Oxygen XML Author | Editing Documents

Tip:
Server URLs
When accessing a FTP server, you need to specify only the protocol and the host, like: ftp://server.com, or if
using a nonstandard port: ftp://server.com:7800/.

By pressing the Browse button the directory listing will be shown in the component below. When Autoconnect is
selected then at every time the dialog is shown, the browse action will be performed.
• The tree view of the documents stored on the server. You can browse the directories, and make multiple selections.
Additionally, you may use the Rename, Delete, and New Folder to manage the file repository.
The file names are sorted in a case-insensitive way.

Changing File Permissions on a Remote FTP Server

Some FTP servers allow the modification of permissions of the files served over the FTP protocol. This protocol feature
is accessible directly in the FTP file browser dialog by right-clicking on a tree node and selecting the Change permissions
menu item.
The usual Unix file permissions Read, Write and Execute are granted or denied in this dialog for the file owner, owner
group and the rest of the users. The permission's aggregate number is updated in the Permissions text field when it is
modified with one of the check boxes.

WebDAV over HTTPS

If you want to access a WebDAV repository across an insecure network, Oxygen allows you to load and save the
documents over the HTTPS protocol (if the server understands this protocol) so that any data exchange with the WebDAV
server is encrypted.
When a WebDAV repository is first accessed over HTTPS, the server hosting the repository will present a security
certificate as part of the HTTPS protocol, without any user intervention. Oxygen XML Author will use this certificate
to decrypt any data stream received from the server. For the authentication to succeed you should make sure the security
certificate of the server hosting the repository can be read by Oxygen XML Author . This means that Oxygen XML
Author can find the certificate in the key store of the Java Runtime Environment in which it runs. You know the server
certificate is not in the JRE key store if you get the error No trusted certificate found when trying to access the WebDAV
repository.
How to Add a HTTPS Server Certificate to Oxygen
You add a HTTPS server certificate to the Java key store by exporting it to a local file using any HTTPS-capable Web
browser (for example Internet Explorer) and then importing this file into the JRE using the keytool executable bundled
with the JRE. The steps are the following using Internet Explorer (if you use other browser the procedure is similar):

1. Export the certificate into a local file

a) Point your HTTPS-aware Web browser to the repository URL.
If this is your first visit to the repository it will be displayed a security alert stating that the security certificate
presented by the server is not trusted.
Oxygen XML Author | Editing Documents | 41

Figure 15: Security alert - untrusted certificate

b) Go to menu Tools > Internet Options .

Internet Options dialog is opened.
c) Select Security tab.
d) Select Trusted sites icon.
e) Press Sites button.
This will open Trusted sites dialog.
f) Add repository URL to Websites list.
g) Close Trusted sites dialog and Internet Options dialog.
h) Try again to connect to the same repository URL in Internet Explorer.
The same error page as above will be displayed.
i) Select Continue to this website option.
A clickable area with a red icon and text Certificate Error is added to Internet Explorer address bar.
j) Click on Certificate Error area.
A dialog containing View certificates link is displayed.
k) Click on View certificates link.
Certificate dialog is displayed.
l) Select Details tab of Certificate dialog.
m) Press Copy to File button.
Certificate Export Wizard is started.
n) Follow indications of wizard for DER encoded binary X.509 certificate. Save certificate to local file server.cer.
2. Import the local file into the JRE running Oxygen Eclipse plugin.
a) Open a text-mode console.
b) Go to the lib/security subfolder of your JRE directory, that is of the directory where it is installed the JRE
running Oxygen Eclipse plugin. You find the home folder of the JRE in the java.home property that is displayed
in the About dialog tab.
c) Run the following command:

..\..\bin\keytool.exe -import -trustcacerts -file server.cer -keystore

cacerts
42 | Oxygen XML Author | Editing Documents

The local-file.cer file contains the server certificate, created during the previous step. keytool requires
a password before adding the certificate to the JRE keystore. The default password is changeit. If somebody
changed the default password then he is the only one who can perform the import. As a workaround you can
delete the cacerts file, re-type the command and enter as password any combination of at least 6 characters.
This will set the password for future operations with the key store.

3. Restart Eclipse.

Opening the Current Document in a Web Browser

To open the current document in your computer's default Web browser, use the Open in browser action available on
the XML > File menu and also on the Document toolbar. This is useful to see the effect of applying an XSLT stylesheet
or a CSS stylesheet on a document which specifies the stylesheet using an xml-stylesheet processing instruction.

Closing Documents
To close documents use one of the following methods:
• Go to menu File > Close (Ctrl+F4) : Closes only the selected tab. All other tab instances remain opened.
• Go to menu File > Close All (Ctrl+Shift+F4) : Closes all open documents. If a document is modified or has no
file, a prompt to save, not to save, or cancel the save operation is displayed.
• Select the item Close from the contextual menu of an editor tab: Closes the selected editor.
• Select the item Close Other Files from the contextual menu of an editor tab: Closes the other files except the selected
tab.
• Select the item Close All from the contextual menu of an editor tab: Closes all open editors within the panel.

Viewing File Properties

In the Properties view you can quickly access information about the current edited document like:
• character encoding
• full path on the file system
• schema used for content completion and document validation
• document type name and path
• associated transformation scenario
• file's read-only state
• bidirectional text (left to right and right to left) state
• document's total number of characters
• line width
• indent with tabs state
• indent size
The view can be accessed from Window > Show View > Other ... > oXygen > Editor properties
To copy a value from the Properties view in the clipboard, for example the full file path, use the Copy action available
on the contextual menu of the view.

Editing XML Documents

This section explains the XML editing features of the application. All the user interface components and actions available
to users are described in detail with appropriate procedures for various tasks.
Oxygen XML Author | Editing Documents | 43

Associate a Schema to a Document

This section explains the methods of associating a schema to a document for validation and content completion purposes.

Setting a Schema for Content Completion

This section explains the available methods of setting a schema for content completion in an XML document edited in
the Oxygen application.
Supported Schema Types for XML Documents
The supported schema types are:
• W3C XML Schema (with and without embedded Schematron rules)
• DTD
• Relax NG - XML syntax (with and without embedded Schematron rules)
• Relax NG - compact syntax
• NVDL
• Schematron (both ISO Schematron and Schematron 1.5)
Setting a Default Schema
The default schema used by content completion is the schema of the document type that matches the edited document.
The list of document types available at Options > Preferences > Document Type Association contains a set of rules
for associating a schema with the current document when no schema is explicitly specified within the document. The
schema has one of following the types: XML Schema, XML Schema with embedded Schematron rules, Relax NG (XML
syntax or compact syntax), Relax NG (XML syntax) with embedded Schematron rules, Schematron, DTD, NVDL.
The rules are applied in the order they appear in the table and take into account the local name of the root element, the
default namespace and the file name of the document.
Important:
The editor is creating the content completion lists by analysing the specified schema and the current context (the
position in the editor). If you change the schema you can observe that the list of tags to be inserted is changing.

Figure 16: Content Completion Driven by DocBook DTD

Making the Schema Association Explicit in the XML Instance Document

The schema used by the content completion assistant and document validation engine can be associated with the document
using the Associate Schema action. For most of the schema types, it uses the xml-model processing instruction, the
exceptions being:
44 | Oxygen XML Author | Editing Documents

• W3C XML Schema - the xsi:schemaLocation attribute is used;

• DTD - the DOCTYPE declaration is used.
The association can specify a relative file path or a URL of the schema. The advantage of relative file path is that you
can configure the schema at file level instead of document type level.

Go to menu Document > Schema > Associate schema... or click the Associate schema toolbar button to select
the schema that will be associated with the XML document. The following dialog is displayed:

Figure 17: The Associate Schema Dialog

The following options are available:

• URL - contains a predefined set of schemas that are used more often and it also keeps a history of the last used
schemas. The URL must point to the schema file which can be loaded from the local disk or from a remote server
through HTTP(S), FTP(S).
• Schema type - selected automatically from the list of possible types in the Schema type combo box (XML Schema,
DTD, Relax NG, Relax NG Compact, Schematron, NVDL) based on the extension of the schema file that was entered
in the URL field.
• Public ID - Specify a public ID if you have selected a DTD.
• Embedded schematron rules - if you have selected XML Schema or Relax NG schemas with embedded Schematron
rules, enable this option.
• Use relative paths - enable this option if the XML instance document and the associated schema contain relative
paths. The location of the schema file is inserted in the XML instance document as a relative file path. This practice
allows you, for example, to share these documents with other users, without running into problems caused by different
project locations on physical disk.
The association with an XML Schema is added as an attribute of the root element. The Associate schema action adds
a:
• xsi:schemaLocation attribute, if the root element of the document sets a default namespace with an xmlns
attribute;
• or a xsi:noNamespaceSchemaLocation attribute, if the root element does not set a default namespace.
The association with a DTD is added as a DOCTYPE declaration. The association with a Relax NG , Schematron or
NVDL schema is added as xml-model processing instruction.
Associating a Schema With the Namespace of the Root Element
The namespace of the root element of an XML document can be associated with an XML Schema using an XML catalog.
If there is no xsi:schemaLocation attribute on the root element and the XML document is not matched with a
document type, the namespace of the root element is searched in the XML catalogs set in Preferences.
If the XML catalog contains an uri or rewriteUri or delegateUri element, its schema will be used by the
application to drive the content completion and document validation.
Oxygen XML Author | Editing Documents | 45

The xml-model Processing Instruction

The xml-model processing instruction associates a schema with the XML document that contains the processing
instruction. It must be added at the beginning of the document, just after the XML prologue. The following code snippet
contains an xml-model processing instruction declaration:
<?xml-model href="../schema.sch" type="application/xml"
schematypens="http://purl.oclc.org/dsdl/schematron" phase="ALL" title="Main
schema"?>
It is available in the content completion assistant, before XML document root element and has the following attributes:
• href - schema file location. Mandatory attribute.
• type - content type of schema. Optional attribute with the following possible values:
• for DTD the recommended value is application/xml-dtd;
• for W3C XML Schema the recommended value is application/xml or can be left unspecified;
• for RELAX NG the recommended value is application/xml or can be left unspecified;
• for RELAX NG - compact syntax the recommended value is application/relax-ng-compact-syntax;
• for Schematron the recommended value is application/xml or can be left unspecified;
• for NVDL the recommended value is application/xml or can be left unspecified.

• schematypens - namespace of schema language of referenced schema with the following possible values:
• for DTD - not specified;
• for W3C XML Schema the recommended value is http://www.w3.org/2001/XMLSchema;
• for RELAX NG the recommended value is http://relaxng.org/ns/structure/1.0;
• for RELAX NG - not specified;
• for Schematron the recommended value is http://purl.oclc.org/dsdl/schematron;
• for NVDL the recommended value is http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0.

• phase - phase name of validation function in Schematron schema. Optional attribute.

• title - title for associated schema optional attribute
Older versions of Oxygen used the oxygen processing instruction with the following attributes:
• RNGSchema - specifies the path to the Relax NG schema associated with the current document;
• type - specifies the type of Relax NG schema. It is used together with the RNGSchema attribute and can have the
value "xml" or "compact";
• NVDLSchema - specifies the path to the NVDL schema associated with the current document;
• SCHSchema - specifies the path to the SCH schema associated with the current document.
Note: Documents that use the oxygen processing instruction are compatible with newer versions of Oxygen.

Learning Document Structure

When working with documents that do not specify a schema, or for which the schema is not known or does not exist,
Oxygen is able to learn and translate the document structure to a DTD. You can choose to save the learned structure to
a file in order to provide a DTD as an initialization source for content completion and document validation. This feature
is also useful for producing DTD's for documents containing personal or custom element types.
When you open a document that is not associated with a schema, Oxygen automatically learns the document structure
and uses it for content completion. To disable this feature you have to uncheck the checkbox Learn on open document
in the user preferences.
Create a DTD from Learned Document Structure
When there is no schema associated with an XML document, Oxygen can learn the document structure by parsing the
document internally. This feature is enabled with the option Learn on open document that is available in the user
preferences.
46 | Oxygen XML Author | Editing Documents

To create a DTD from the learned structure:

1. Open the XML document for which a DTD will be created.

2. Go to menu XML > Learn Structure (Ctrl+Shift+L) .
The Learn Structure action reads the mark-up structure of the current document. The Learn completed message
is displayed in the application's status bar when the action is finished.
3. Go to menu XML > Save Structure (Ctrl+Shift+S) . Enter the DTD file path.
4. Press the Save button.

Streamline with Content Completion

Oxygen's intelligent Content Completion feature enables rapid, in-line identification and insertion of structured language
elements, attributes and in some cases their parameter options.

Figure 18: Content Completion Assistant

Oxygen logs the URL of the detected schema in the Status view.
If the Content Completion assistant is enabled in user preferences (the option Use Content Completion), then it is
displayed:
• automatically, after a configurable delay from the last key press of the < character. The delay is configurable in
Preferences as a number of milliseconds from last key press.
• on demand, by pressing CTRL+Space on a partial element or attribute name.
Elements are highlighted in the list using the Up and Down cursor keys. Here are the options to insert the selected
content:
• press the Enter key or the Tab key to insert both the start and end tags.
• press CTRL + Enter. The application inserts both the start and end tags, separated by an empty line. The cursor is
positioned on the empty line on an indented position with regard to the start tag.
Note: When the DTD, XML Schema or RELAX NG schema specifies required child elements for the newly added
element, they will be inserted automatically only if the Add Element Content option (found in Preferences >
Editor > Content Completion options page) is enabled. The Content Completion assistant can also add optional
content and first choice particle, as specified in the DTD or XML Schema or RELAX NG schema, for the element
if these two options are enabled.

After inserting the element, the cursor will be positioned:

• before the > character of the start tag, if the element allows attributes, in order to enable rapid insertion of any of the
attributes supported by the element. Pressing the space bar will display the Content Completion list once again. This
time it will contain the list of allowed attribute names. If the attribute supports a fixed set of parameters, the assistant
list will display the list of valid parameters. If the parameter setting is user-defined and therefore variable, the assistant
Oxygen XML Author | Editing Documents | 47

will be closed to enable manual insertion. The values of the attributes can be learned from the same elements in the
current document.
• after the > char of the start tag if the element has no attributes.
The content assistant can be started at any time by pressing CTRL+Space The effect is that the context-sensitive list of
proposals will be shown in the caret's current position if element, attribute or attribute value insertion makes sense. The
Content Completion assistant is displayed:
• anywhere within a tag name or at the beginning of a tag name in an XML document, XML Schema, DTD or Relax
NG (full or compact syntax) schema;
• anywhere within an attribute name or at the beginning of an attribute name in any XML document with an associated
schema;
• within attribute values or at the beginning of attribute values in XML documents where lists of possible values have
been defined for that element in the schema associated with the document
The items that populate the Content Completion assistant are dependent on the element structure specified in the DTD,
XML Schema, Relax NG (full or compact syntax) schema, or NVDL schema associated to the edited document.
The number and type of elements displayed by the assistant is dependent on the cursor's current position in the structured
document. The child elements displayed within a given element are defined by the structure of the specified DTD, XML
Schema, Relax NG (full or compact syntax) schema, or NVDL schema. All elements that can't be child elements of the
current element according to the specified schema are not displayed.
If only one element name must be displayed by the content assistant then the assistant is not displayed anymore but this
only option is automatically inserted in the document at the current cursor position.
If the schema for the edited document defines attributes of type ID and IDREF the content assistant will display for
IDREF attributes a list of all the ID values already present in the document for an easy insertion of a valid ID value at
the cursor position in the document. This is available for documents that use DTD, XML Schema and Relax NG schema.
Also values of all the xml:id attributes are treated as ID attributes and collected and displayed by the Content Completion
assistant as possible values for anyURI attributes defined in the schema of the edited document. This works only for
XML Schema and Relax NG schemas.
For documents that use an XML Schema or Relax NG schema the content assistant offers proposals for attributes and
elements values that have as type an enumeration of tokens. Also if a default value or a fixed value is defined in the
XML Schema used in validation for an attribute or element then that value is offered in the content completion window.
The operation of the Content Completion assistant is configured by the options available in the options group called
Content Completion.

Set Schema for Content Completion

The DTD, XML Schema, Relax NG, or NVDL schema used to populate the Content Completion assistant is specified
in the following methods, in order of precedence:
• the schema specified explicitly in the document. In this case Oxygen reads the beginning of the document and resolves
the location of the DTD, XML Schema, Relax NG schema, or NVDL schema;
Note:
Limitation: In case of XML Schema, the content completion takes into account only the schema declarations
from the document's root element. If a schema declaration is attached to other element of the XML document,
then it will be ignored.

• the default schema rule declared in the Document Type Association preferences panel which matches the edited
document;

Content Completion in Documents with Relax NG Schemas

Inside the documents that use a Relax NG schema the Content Completion assistant is able to present element values if
such values are specified in the Relax NG schema. Also in Relax NG documents the Content Completion assistant
48 | Oxygen XML Author | Editing Documents

presents additional values of type ID for an anyURI data type. It presents also pattern names defined in the Relax NG
schema as possible values for pattern references. For example if the schema defines an enumValuesElem element like:

<element name="enumValuesElem">
<choice>
<value>value1</value>
<value>value2</value>
<value>value3</value>
</choice>
</element>
In documents based on this schema, the Content Completion assistant offers the following list of values:

Figure 19: Content Completion assistant - element values in Relax NG documents

Schema Annotations
If the document's schema is an XML Schema, Relax NG (full syntax), NVDL or DTD and it contains element, attributes
or attributes values annotations, these will be presented when the content completion window is displayed, only if the
option Show annotations is enabled. Also the annotation is presented in a small tooltip window displayed automatically
when the mouse hovers over an element or attribute annotated in the associated schema of the edited document.
In an XML Schema the annotations are specified in an <xs:annotation> element like this:
<xs:annotation>
<xs:documentation>
Description of the element.
</xs:documentation>
</xs:annotation>
If the current element / attribute in the edited document does not have an annotation in the schema and that schema is
an XML Schema, Oxygen seeks an annotation in the type definition of the element / attribute or, if no annotation is
found there, in the parent type definition of that definition, etc.
When editing a Schematron schema the content completion assistant displays XSLT 1.0 functions and optionally XSLT
2.0 functions in the attributes path, select, context, subject, test depending on the Schematron options that are set in
Preferences. If the Saxon 6.5.5namespace (xmlns:saxon="http://icl.com/saxon") or the Saxon 9.3.0.5
namespace is declared in the Schematron schema (xmlns:saxon="http://saxon.sf.net/") the content
completion displays also the XSLT Saxon extension functions as in the following figure:

Figure 20: XSLT extension functions in Schematron schemas documents

Oxygen XML Author | Editing Documents | 49

In a Relax NG schema any element outside the Relax NG namespace (http://relaxng.org/ns/structure/1.0) is handled as
annotation and the text content is displayed in the annotation window together with the content completion window:
For NVDL schemas annotations for the elements / attributes in the referred schemas (XML Schema, RNG, etc) are
presented

Figure 21: Schema annotations displayed at Content Completion

The following HTML tags are recognized inside the text content of an XML Schema annotation: p, br, ul, li. They
are rendered as in an HTML document loaded in a web browser: p begins a new paragraph, br breaks the current line,
ul encloses a list of items, li encloses an item of the list.
For DTD Oxygen defines a custom mechanism for annotation using comments enabled from the option Use DTD
comments as annotations . The text of a comment with the following format will be presented on content completion:

Content Completion Helper Panels

Information about the current element being edited is also available in the Model panel and Attributes panel, located on
the left-hand side of the main window. The Model panel and the Attributes panel combined with the powerful Outline
view provide spatial and insight information on the edited document.
The Model Panel
The Model panel presents the structure of the current edited tag and tag documentation defined as annotation in the
schema of the current document. Open the Model panel from Window > Show View > Other > oXygen > Model view
50 | Oxygen XML Author | Editing Documents

Figure 22: The Model View

The Element Structure Panel

The element structure panel shows the structure of the current edited or selected tag in a tree-like format.
The information includes the name, model and attributes the currently edited tag may have. The allowed attributes are
shown along with imposed restrictions, if any.

Figure 23: The Element Structure Panel

The Annotation Panel

The Annotation panel displays the annotations that are present in the used schema for the currently edited or selected
tag. This information can be very useful to developers learning XML because it has small available definitions for each
used tag.
Oxygen XML Author | Editing Documents | 51

Figure 24: The Annotation panel

The Attributes Panel

The Attributes panel presents all possible attributes of the current element and allows to insert attributes in the current
element or change the value of the attributes already used in the element. The attributes already present in the document
are painted with a bold font. Clicking on the Value column of a table row will start editing the value of the attribute
from the selected row. If the possible values of the attribute are specified as list in the schema associated with the edited
document, the Value column works as a combo box where you can select one of the possible values to be inserted in
the document.
The Attributes table is sortable, three sorting orders being available by clicking on the columns' names. Thus the table's
contents can be sorted in ascending order, in descending order or in a custom order, where the already used attributes
are placed at the beginning of the table as they appear in the element followed by the rest of the allowed elements as
they are declared in the associated schema.

Figure 25: The Attributes Panel

The Elements View

The Elements view presents a list of all defined elements that you can insert at the current caret position according to
the document's schema. Double-clicking any of the listed elements will insert that element in the edited document. All
elements from a sequence are presented but the invalid proposals (which cannot be inserted in the current context) are
grayed-out.
52 | Oxygen XML Author | Editing Documents

Figure 26: The Elements View

The Entities View

This view displays a list with all entities declared in the current document as well as built-in ones. Double clicking one
of the entities will insert it at the current cursor position. You can also sort entities by name and value.

Figure 27: The Entities View

Code Templates
You can define short names for predefined blocks of code called code templates. The short names are displayed in the
Content Completion window if the word at cursor position is a prefix of such a short name. If there is no prefix at cursor
position, that is the character at the left of cursor is a whitespace, all the code templates are listed.
Oxygen comes with a lot of predefined code templates but you can define your own code templates for any type of
editor.
To obtain the template list you can use the Content Completion on request shortcut key (usually CTRL-SPACE) or the
Code Templates on request shortcut key (CTRL-SHIFT-SPACE). The first shortcut displays the code templates in the
same content completion list with elements from the schema of the document. The second shortcut displays only the
code templates and is the default shortcut of the action Document > Content Completion > Show Code Templates
.
The following variables can appear in a code template:
• ${caret} - The caret position after inserting the code template.
Oxygen XML Author | Editing Documents | 53

• ${selection} - The position of the current selection in the inserted template.

• ${env(ENV_VAR_NAME)} - The value of the environment variable ENV_VAR_NAME.
• ${system(var.name)} - The value of the system variable var.name.
• ${date(yyyy-MM-dd)} - A date in the format: 4 digits for year, 2 digits for month, 2 digits for day.

Validating XML Documents

The W3C XML specification states that a program should not continue to process an XML document if it finds a
validation error. The reason is that XML software should be easy to write, and that all XML documents should be
compatible. With HTML it was possible to create documents with lots of errors (like when you forget an end tag). One
of the main reasons that HTML browsers are so big and incompatible, is that they have their own ways to figure out
what a document should look like when they encounter an HTML error. With XML this should not be possible.
However, when creating an XML document, errors are very easily introduced. When working with large projects or
many files, the probability that errors will occur is even greater. Determining that your project is error-free can be time
consuming and even frustrating. For this reason Oxygen provides functions that enable easy error identification and
rapid error location.

Checking XML Well-Formedness

A Well-Formed XML document is a document that conforms to the XML syntax rules. A Namespace Well-Formed XML
document is a document that is XML Well-Formed and is also namespace-wellformed and namespace-valid.
The XML Syntax rules for Well-Formed XML are:
• All XML elements must have a closing tag.
• XML tags are case sensitive.
• All XML elements must be properly nested.
• All XML documents must have a root element.
• Attribute values must always be quoted.
• With XML, white space is preserved.
The namespace-wellformed rules are:
• All element and attribute names contain either zero or one colon.
• No entity names, processing instruction targets, or notation names contain any colons.
The namespace-valid rules are:
• The prefix xml is by definition bound to the namespace name http://www.w3.org/XML/1998/namespace. It MAY,
but need not, be declared, and MUST NOT be undeclared or bound to any other namespace name. Other prefixes
MUST NOT be bound to this namespace name.
• The prefix xmlns is used only to declare namespace bindings and is by definition bound to the namespace name
http://www.w3.org/2000/xmlns/. It MUST NOT be declared or undeclared. Other prefixes MUST NOT be bound to
this namespace name.
• All other prefixes beginning with the three-letter sequence x, m, l, in any case combination, are reserved. This means
that users SHOULD NOT use them except as defined by later specifications and processors MUST NOT treat them
as fatal errors.
• The namespace prefix, unless it is xml or xmlns, MUST have been declared in a namespace declaration attribute in
either the start-tag of the element where the prefix is used or in an ancestor element (i.e. an element in whose content
the prefixed markup occurs). Furthermore, the attribute value in the innermost such declaration MUST NOT be an
empty string.
If you select menu Document > Validate > Check Well-Formedness (Alt+Shift+V W (Cmd+Alt+V W on Mac))
or click the toolbar button Check Well-FormednessOxygen checks if your document is Namespace Well-Formed
XML. If any error is found the result is returned to the message panel. Each error is one record in the result list and is
accompanied by an error message. Clicking the record will open the document containing the error and highlight its
approximate location.
54 | Oxygen XML Author | Editing Documents

A not Well-Formed XML Document

<root><tag></root>
When Check Well-Formedness is performed the following error is raised:
The element type "tag" must be terminated by the matching end-tag
"</tag>"
To resolve the error, click in the result list record which will locate and highlight the errors
approximate position. Identify which start tag is missing an end tag and insert </tag>.

A not namespace-wellformed document

<x::y></x::y>
When Check document form is performed the following error is raised:

Element or attribute do not match QName production:

QName::=(NCName':')?NCName.

A not namespace-valid document

<x:y></x:y>
When Check document form is performed the following error is raised:

The prefix "x" for element "x:y" is not bound.

Also the files contained in the current project and selected with the mouse in the Project view can be checked for
well-formedness with one action available on the popup menu of the Project view : Check Well-Formedness.

Validating XML Documents Against a Schema

A Valid XML document is a Well Formed XML document, which also conforms to the rules of a schema which defines
the legal elements of an XML document. The schema type can be: XML Schema, Relax NG (full or compact syntax),
Schematron, Document Type Definition (DTD), or Namespace-based Validation Dispatching Language (NVDL).
The purpose of the schema is to define the legal building blocks of an XML document. It defines the document structure
with a list of legal elements.

The Oxygen Validate document function ensures that your document is compliant with the rules defined by an
associated DTD, XML Schema, Relax NG, or Schematron schema. XML Schema or Relax NG Schema can embed
Schematron rules. For Schematron validations, it is possible to select the validation phase.
Marking Validation Errors and Warnings
A line with a validation error or warning will be marked in the editor panel by underlining the error region with a red
color. Also a red sign will mark the position in the document of that line on the right side ruler of the editor panel. The
same will happen for a validation warning, only the color will be yellow instead of red.
The ruler on the right side of the document is designed to display the errors and warnings found during the validation
process and also to help the user to locate them more easily. The ruler contains the following areas:
• Top area containing a success validation indicator that will turn green in case the validation succeeded or red otherwise.
• Middle area where the error markers are depicted in red . The number of markers shown can be limited by modifying
the setting Window > Preferences > oXygen > Editor > Document checking > Maximum number of problems
reported per document .
Clicking on a marker will highlight the corresponding text area in the editor. The error message is displayed both in
the tool tip and in the error area on the bottom of the editor panel.
Oxygen XML Author | Editing Documents | 55

Status messages from every validation action are logged into the Console view.
Validation Example - A DocBook Validation Error
In the following DocBook 4 document the content of the listitem element does not match the rules of the DocBook
4 schema, that is docbookx.dtd.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<article>
<title>Article Title</title>
<sect1>
<title>Section1 Title</title>
<itemizedlist>
<listitem>
<link>a link here</link>
</listitem>
</itemizedlist>
</sect1>
</article>
The Validate Document action will return the following error:
Unexpected element "link". The content of the parent element type must match
"(calloutlist|glosslist|bibliolist|itemizedlist|orderedlist|segmentedlist|simplelist
|variablelist|caution|important|note|tip|warning|literallayout|programlisting
|programlistingco|screen|screenco|screenshot|synopsis|cmdsynopsis|funcsynopsis
|classsynopsis|fieldsynopsis|constructorsynopsis|destructorsynopsis|methodsynopsis
|formalpara|para|simpara|address|blockquote|graphic|graphicco|mediaobject|mediaobjectco
|informalequation|informalexample|informalfigure|informaltable|equation|example|figure
|table|msgset|procedure|sidebar|qandaset|task|anchor|bridgehead|remark|highlights
|abstract|authorblurb|epigraph|indexterm|beginpage)+".
This error message is a little more difficult to understand, so understanding of the syntax or processing rules for the
DocBook XML DTD's listitem element is recommended. However, the error message does give us a clue as to the
source of the problem, indicating that “The content of element type c must match”.
Luckily most standards based DTD's, XML Schema's and Relax NG schemas are supplied with reference documentation.
This enables us to lookup the element and read about it. In this case you should learn about the child elements of
listitem and their nesting rules. Once you have correctly inserted the required child element and nested it in accordance
with the XML rules, the document will become valid on the next validation test.
Caching the Schema Used for Validation
If you don't change the active editor and you don't switch to other application, the schema associated to the current
document is parsed and cached by the first Validate Document action and is reused by the next actions without re-parsing
it. This increases the speed of the validate actions if the schema is large or is located on a remote server on the Web. To
reset the cache and re-parse the schema you have to use the Reset Cache and Validate action. This action will
also re-parse the catalogs and reset the schema used for content completion.
Automatic Validation
Oxygen can be configured to mark validation errors in the document as you are editing. If you enable the Automatic
validation option any validation errors and warnings will be highlighted automatically in the editor panel. The automatic
validation starts parsing the document and marking the errors after a configurable delay from the last key typed. Errors
are highlighted with underline markers in the main editor panel and small rectangles on the right side ruler of the editor
panel, in the same way as for manual validation invoked by the user.
56 | Oxygen XML Author | Editing Documents

Figure 28: Automatic Validation on the Edited Document

Custom Validators
If you need to validate the edited document with other validation engine than the built-in one you have the possibility
to configure external validators in the Oxygen user preferences. After such a custom validator is properly configured it
can be applied on the current document with just one click on the Custom Validation Engines toolbar. The document
is validated against the schema declared in the document.
Some validators are configured by default but they are third party processors which do not support the output message
format of Oxygen for linked messages:
• LIBXML - Included in Oxygen (Windows edition only). It is associated to XML Editor. It is able to validate the
edited document against XML Schema, Relax NG schema full syntax, internal DTD (included in the XML document)
or a custom schema type. XML catalogs support (the --catalogs parameter) and XInclude processing (--xinclude)
are enabled by default in the preconfigured LIBXML validator. The --postvalid parameter is also set by default which
allows LIBXML to validate correctly the main document even if the XInclude fragments contain IDREFS to ID's
located in other fragments.
For validation against an external DTD specified by URI in the XML document, the parameter --dtdvalid ${ds} must
be added manually to the DTD validation command line. ${ds} represents the detected DTD declaration in the XML
document.
Caution: 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 subfolder of the installation folder which in this
case contains at least one space character in the file path.

Attention:
On Mac OS X if the full path to the LIBXML executable file is not specified in the Executable path text field,
some errors may occur on validation against a W3C XML Schema like:
Unimplemented block at ... xmlschema.c
These errors can be avoided by specifying the full path to the LIBXML executable file.

• Saxon SA - Included in Oxygen. It is associated to XML Editor and XSD Editor. It is able to validate XML Schema
schemas and XML documents against XML Schema schemas. The validation is done according to the W3C XML
Oxygen XML Author | Editing Documents | 57

Schema 1.0 specification or according to the W3C XML Schema 1.1 specification. This can be configured in
Preferences.
• MSXML 4.0 - Included in Oxygen (Windows edition only). It is associated to XML Editor, XSD Editor and XSL
Editor. It is able to validate the edited document against XML Schema, internal DTD (included in the XML document),
external DTD or a custom schema type.
• MSXML.NET - Included in Oxygen (Windows edition only). It is associated to XML Editor, XSD Editor and XSL
Editor. It is able to validate the edited document against XML Schema, internal DTD (included in the XML document),
external DTD or a custom schema type.
• XSV - Not included in Oxygen. Windows and Linux distributions of XSV can be downloaded from
http://www.cogsci.ed.ac.uk/~ht/xsv-status.html. The executable path is already configured in Oxygen for the
[Oxygen-install-folder]/xsv installation folder. If it is installed in a different folder the predefined
executable path must be corrected in Preferences. It is associated to XML Editor and XSD Editor. It is able to validate
the edited document against XML Schema or a custom schema type.
• SQC (Schema Quality Checker from IBM) - Not included in Oxygen. It can be downloaded from here (it comes
as a .zip file, at the time of this writing SQC2.2.1.zip is about 3 megabytes). The executable path and working
directory are already configured for the SQC installation directory [Oxygen-install-folder]/sqc. If it is
installed in a different folder the predefined executable path and working directory must be corrected in the Preferences
page. It is associated to XSD Editor.
Linked Output Messages of an External Engine
Validation engines display messages in an output view at the bottom of the Oxygen window. If such an output message
(warning, error, fatal error, etc) spans between three to five lines of text and has the following format then the message
is linked to a location in the validated document so that 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. This behavior is similar to the linked
messages generated by the default built-in validator. The format for linked messages is:
• Type:[F|E|W] (the string Type: followed by a letter for the type of the message: fatal error, error, warning) - this line
is optional in a linked message.
• SystemID: a system ID of a file (the string SystemID: followed by the system ID of the file that will be opened for
highlighting when the message is clicked in the output message - usually the validated file, the schema file or an
included file).
• Line: a line number (the string Line: followed by the number of the line that will be highlighted).
• Column: a column number (the string Column: followed by the number of the column where the highlight will start
on the highlighted line) - this line is optional in a linked message.
• Description: message content (the string Description: followed by the content of the message that will be displayed
in the output view).
Validation Scenario
A complex XML document is usually split in smaller interrelated modules which do not make much sense individually
and which cannot be validated in isolation due to interdependencies with the other modules. A mechanism is needed to
set the main module of the document which in fact must be validated when an imported module needs to be checked
for errors.
A typical example is the chunking DocBook XSL stylesheet which has chunk.xsl as the main module and param.xsl,
chunk-common.xsl and chunk-code.xsl as imported modules. param.xsl only defines XSLT parameters.
The module chunk-common.xsl defines a XSLT template with the name chunk which is called by
chunk-code.xsl. The parameters defined in param.xsl are used in the other modules without being redefined.
Validation of chunk-code.xsl as an individual XSLT stylesheet issues a lot of misleading errors referring to
parameters and templates used but undefined which are only caused by ignoring the context in which this module is
used in real XSLT transformations and in which it should be validated. To properly validate such a module, a validation
scenario must be defined to set the main module of the stylesheet and also the validation engine used to find the errors.
Usually this is the engine which applies the transformation in order to detect in validation the same errors that would
be issued by transformation.
58 | Oxygen XML Author | Editing Documents

A second benefit of a validation scenario is that the stylesheet can be validated with several engines to make sure that
it can be used in different environments with the same results. For example an XSLT stylesheet needs to be applied with
Saxon 6.5, Xalan and MSXML 4.0 in different production systems.
Other examples of documents which can benefit of a validation scenario are:
• A complex XQuery with a main module which imports modules developed independently but validated in the context
of the main module of the query. In an XQuery validation scenario the default validator of Oxygen (Saxon 9) or any
connection to a database that supports validation (Berkeley DB XML Database, eXist XML Database, Software AG
Tamino, Documentum xDb (X-Hive/DB) 10 XML Database) can be set as validation engine.
• An XML document in which the master file includes smaller fragment files using XML entity references.
How to Create a Validation Scenario
Follow these steps for creating a validation scenario:

1. Open the Configure Validation Scenario dialog from menu XML or from the toolbar of the Oxygen plugin.
The following dialog is displayed. It contains the following types of scenarios:
• Default validation scenario validates the input using Oxygen default validation options that apply to the type of
the current document;
• Predefined scenarios are organized in categories depending on the type of file they apply to and can be easily
identified by a yellow key icon that marks them as read-only. If the predefined scenario is the framework's default
scenario its name is written in bold font. If you try to edit one of these scenarios, Oxygen creates a customizable
duplicate;
• User defined scenarios are organized under a single category, but you can use the drop-down option box to filter
them by the type of file they validate.

Figure 29: Configure Validation Scenario

2. Press the New button to add a new scenario.

3. Press the Add button to add a new validation unit with default settings.
The dialog that lists all validation units of the scenario is opened.
Oxygen XML Author | Editing Documents | 59

Figure 30: Add / Edit a Validation Unit

The table holds the following information:

• URL of the file to validate - The URL of the main module which includes the current module. It is also the entry
module of the validation process when the current one is validated.
• File type - The type of the document validated in the current validation unit. Oxygen automatically selects the
file type depending on the value of the URL of the file to validate field.
• Validation engine - One of the engines available in Oxygen for validation of the type of document to which the
current module belongs. Default engine is the default setting and means that the validation is done by the default
engine set in Preferences pages for the type of the current document (XML document, XML Schema, XSLT
stylesheet, XQuery file, etc) instead of a validation scenario.
• Automatic validation - If this option is checked, then the validation operation defined by this row of the table
is applied also by the automatic validation feature. If the Automatic validation feature is disabled in Preferences
then this option does not take effect as the Preference setting has higher priority.
• Schema - Active when you set the File type to XML Document.
• Settings - Contains an action that allows you to set a schema, when validating XML documents, or a list of
extensions when validating XSL or XQuery documents.

4. Edit the URL of the main validation module.

Specify the URL of the main module:
• browsing for a local, remote or archived file;
• using an editor variable or a custom editor variable, available in the following pop-up menu, opened after pressing
the button:

Figure 31: Insert an Editor Variable

60 | Oxygen XML Author | Editing Documents

5. Select the type of the validated document.

Note that it determines the list of possible validation engines.
6. Select the validation engine.
7. Select the Automatic validation option if you want to validate the current unit when automatic validation feature
is turned on.
8. Choose what schema is used during validation: the one detected after parsing the document or a custom one.

Validation Actions in the User Interface

Use one of the actions for validating the current document:
• Select menu XML > Validate Document (Alt+Shift+V V) ( (Cmd+Alt+V V on Mac OS)) or click the button
Validate Document available in the Validate toolbar. This action returns an error list in the message panel.
Mark-up of current document is checked to conform with the specified DTD, XML Schema or Relax NG schema
rules. It caches the schema and the next execution of the action uses the cached schema.
• Select menu XML > Reset Cache and Validate or click the button Reset Cache and Validate available in
the Validate toolbar to reset the cache with the schema and validate the document. This action also parses again the
XML catalogs and reset the schema used for content completion. It returns an error list in the message panel. Mark-up
of current document is checked to conform with the specified DTD, XML Schema or Relax NG schema rules.
• Select menu XML > Validate with (Alt+Shift+V E) ( (Cmd+Alt+V E on Mac OS)) or click the button
Validate with available in the Validate toolbar. This action can be used to validate the current document using a
selectable schema (XML Schema, DTD, Relax NG, NVDL, Schematron schema). It returns an error list in the
message panel. Mark-up of current document is checked to conform with the specified schema rules.
• Select submenu Batch Validation > Validate in the contextual menu of Navigator or Package Explorer view,
to validate all selected files with their declared schemas.
• Select submenu Batch Validation > Validate With ... of the contextual menu of Navigator or Package Explorer
view, to select a schema and validate all selected files with that schema.
• Select menu XML > Clear Validation Markers (Alt+Shift+V X) ( (Cmd+Alt+V X on Mac OS)) or click the
toolbar button Clear Validation Markers to clear the error markers added to the Problems view at the last
validation of the current edited document.
• Select the submenu Batch Validation > Configure Validation Scenario ... of the contextual menu of Navigator
or Package Explorer view, to configure and apply a validation scenario in one action to all the selected files in the
Navigator or Package Explorer view.
Also you can select several files in the views Package Explorer or Navigator and validate them with one click by
selecting the action Validate selection, the action Validate selection with Schema ... or the action Configure Validation
Scenario ... available from the contextual menu of that view, the submenu Batch Validate.
If there are too many validation errors and the validation process takes too long, you can limit the maximum number of
reported errors in Preferences.
Resolving References to Remote Schemas with an XML Catalog
When a reference to a remote schema must be used in the validated XML document for interoperability purposes, but
a local copy of the schema should be actually used for validation for performance reasons, the reference can be resolved
to the local copy of the schema with an XML catalog. For example, if the XML document contains a reference to a
remote schema docbook.rng like this:
<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng"
type="xml"?>
it can be resolved to a local copy with a catalog entry:
<system systemId="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng"
uri="rng/docbook.rng"/>
Oxygen XML Author | Editing Documents | 61

An XML catalog can be used also to map a W3C XML Schema specified with an URN in the xsi:schemaLocation
attribute of an XML document to a local copy of the schema. For example, if the XML document specifies the schema
with:
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1">
the URN can be resolved to a local schema file with a catalog entry like:
<system systemId="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1"
uri="topic.xsd"/>

Document Navigation
This section explains various methods for navigating the edited XML document.

Folding of the XML Elements

An XML document is organized as a tree of elements. When working on a large document you can collapse some
elements leaving in the focus only the ones you need to edit. Expanding and collapsing works on individual elements:
expanding an element leaves the child elements unchanged.

Figure 32: Folding of the XML Elements

To toggle the folded state of an element click on the special mark displayed in the left part of the document editor next
to the start tag of that element or click on the action Toggle fold (Ctrl+Alt+Y) available from the contextual menu
Other menu actions related to folding of XML elements are available from the contextual menu of the current editor:
• (Ctrl+NumPad+/) > Document > Folding > Close Other Folds (Ctrl+NumPad+/) - Folds all the elements
except the current element.
• Document > Folding > Collapse Child Folds (Ctrl+Decimal) (Ctrl+NumPad+-) ( (Cmd+NumPad+- on
Mac OS)) - Folds the elements indented with one level inside the current element.
• Document > Folding > Expand Child Folds (Ctrl+NumPad++) ( (Cmd+NumPad++)) - Unfolds all child
elements of the currently selected element.
• Document > Folding > Expand All (Ctrl+NumPad+*) ( (Cmd+NumPad+* on Mac OS)) - Unfolds all
elements in the current document.
• Document > Folding > Toggle Fold (Alt+Shift+Y) ( (Cmd+Alt+Y on Mac OS)) - Toggles the state of the
current fold.
You can use folding by clicking on the special marks displayed in the left part of the document editor.
62 | Oxygen XML Author | Editing Documents

Outline View
The Outline view offers the following functionality:
• XML Document Overview on page 62
• Outline Specific Actions on page 62
• Modification Follow-up on page 63
• Document Structure Change on page 63
• Document Tag Selection on page 63

Figure 33: The Outline View

XML Document Overview

• Show text - show/hide additional text content for the displayed elements.
• Show attributes - show/hide attribute values for the displayed elements. The displayed attribute values can be
changed from the Outline preferences panel.
• Configure displayed attributes - displays the XML Structured Outline preferences page.
The upper part of the view contains a filter box which allows you to focus on the relevant components. Type a text
fragment in the filter box and only the components that match it are presented. For advanced usage you can use wildcard
characters (*, ?) and separate multiple patterns with commas.
Modification Follow-up
When editing, the Outline view dynamically follows the modifications introduced by the user, showing in the middle
of the panel the node which is currently being modified. This gives the user better insight on location where in the
document one is positioned and how the structure of the document is affected by one's modifications.
Document Structure Change
Entire XML elements can be moved or copied in the edited document using only the mouse in the Outline view in
drag-and-drop operations. Several drag and drop actions are possible:
• If you drag an XML element in the Outline view and drop it on another one in the same panel then the dragged
element will be moved after the drop target element.
• If you hold the mouse pointer over the drop target for a short time before the drop then the drop target element will
be expanded first and the dragged element will be moved inside the drop target element after its opening tag.
• You can also drop an element before or after another element if you hold the mouse pointer towards the upper or
lower part of the targeted element. A marker will indicate whether the drop will be performed before or after the
target element.
• If you hold down the (Ctrl) key after dragging, there will be performed a copy operation instead of a move one.
The drag and drop action in the Outline view can be disabled and enabled from the Preferences dialog.
Tip: You can select and drag multiple nodes in the Author Outline tree.

The Popup Menu of the Outline Tree

The Append Child, Insert Before and Insert After submenus of the outline tree popup menu allow to quickly insert new
tags in the document at the place of the element currently selected in the Outline tree. The Append Child submenu lists
the names of all the elements which are allowed by the schema associated with the current document as child of the
current element. The Insert Before and Insert After submenus of the Outline tree popup menu list the elements which
are allowed by the schema associated with the current document as siblings of the current element inserted immediately
before respectively after the current element.
Edit attributes for the selected node. A dialog is presented allowing the user to see and edit the attributes of the selected
node.
The Toggle comment item of the outline tree popup menu is the same item as in the editor popup menu with the same
name. It encloses the currently selected element of the outline tree in an XML comment, if the element is not commented,
or uncomments it, if it is commented.
The Cut, Copy and Delete items of the popup menu execute the same actions as the Edit menu items with the same name
on the elements currently selected in the outline tree (Cut, Copy, Paste).
Document Tag Selection
The Outline view can also be used to search for a specific tag's location and contents in the edited document. Intuitively,
by selecting with the left mouse button the desired tag in the Outline view, the document is scrolled to the position of
the selected tag. Moreover, the tag's contents are selected in the document, making it easy to notice the part of the
document contained by that specific tag and furthermore to easily copy and paste the tag's contents in other parts of the
document or in other documents.
You can also use key search to look for a particular tag name in the Outline tree.
64 | Oxygen XML Author | Editing Documents

Grouping Documents in XML Projects

This section explains how to create and work with projects in the Oxygen application.

Large Documents
Let's consider the case of documenting a large project. It is likely to be several people involved. The resulting document
can be few megabytes in size. How to deal with this amount of data in such a way the work parallelism would not be
affected ?
Fortunately, XML provides two solutions for this: DTD entities and XInclude. It can be created a master document,
with references to the other document parts, containing the document sections. The users can edit individually the
sections, then apply an XSLT stylesheet over the master and obtain the result files, let say PDF or HTML.
Including Document Parts with DTD Entities
There are two conditions for including a part using DTD entities:
• The master document should declare the DTD to be used, while the external entities should declare the XML sections
to be referred;
• The document containing the section must not define again the DTD.

A master document looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book SYSTEM "../xml/docbookx.dtd" [
<!ENTITY testing SYSTEM "testing.xml" > ]
>
<book>
<chapter> ...

The referred document looks like this:

<section> ... here comes the section content ... </section>
Note:
The indicated DTD and the element names (section, chapter) are used here only for illustrating the inclusion
mechanism. You can use any DTD and element names you need.

At a certain point in the master document there can be inserted the section testing.xml entity:
... &testing; ...
When splitting a large document and including the separate parts in the master file using external entities, only the master
file will contain the Document Type Definition (the DTD) or other type of schema. The included sections can't define
again the schema because the main document will not be valid. If you want to validate the parts separately you have to
use XInclude for assembling the parts together with the master file.
Including Document Parts with XInclude
XInclude is a standard for assembling XML instances into another XML document through inclusion. It enables larger
documents to be dynamically created from smaller XML documents without having to physically duplicate the content
of the smaller files in the main file. XInclude is targeted as the replacement for External Entities. The advantage of using
XInclude is that, unlike the entities method, each of the assembled documents is permitted to contain a Document Type
Declaration (DOCTYPE Decl.). This means that each file is a valid XML instance and can be independently validated.
It also means that the main document to which smaller instances are included can be validated without having to remove
or comment the DOCTYPE Decl. as is the case with External Entities. This makes XInclude a more convenient and
effective method for managing XML instances that need to be stand-alone documents and part of a much larger project.
Oxygen XML Author | Editing Documents | 65

The main application for XInclude is in the document-oriented content frameworks such as manuals and Web pages.
Employing XInclude enables authors and content managers to manage content in a modular fashion that is akin to Object
Oriented methods used in languages such as Java, C++ or C#.
The advantages of modular documentation include: reusable content units, smaller file units that are easier to be edited,
better version control and distributed authoring.

Include a chapter in an article using XInclude

Create a chapter file and an article file in the samples folder of the Oxygen install folder.
Chapter file (introduction.xml) looks like this:
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter>
<title>Getting started</title>
<section>
<title>Section title</title>
<para>Para text</para>
</section>
</chapter>
Main article file looks like this:
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.docbook.org/xml/4.3/docbookx.dtd"
[ <!ENTITY % xinclude SYSTEM
"../frameworks/docbook/dtd/xinclude.mod">
%xinclude;
]>
<article>
<title>Install guide</title>
<para>This is the install guide.</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="introduction.dita">
<xi:fallback>
<para>
<emphasis>FIXME: MISSING XINCLUDE CONTENT</emphasis>
</para>
</xi:fallback>
</xi:include>
</article>

In this example the following is of note:

• the DOCTYPE Decl. defines an entity that references a file containing the information to add the xi namespace to
certain elements defined by the DocBook DTD;
• the href attribute of the xi:include element specifies that the introduction.xml file will replace the xi:include
element when the document is parsed;
• if the introduction.xml file cannot be found, the parser will use the value of the xi:fallback element - a FIXME
message.

If you want to include only a fragment of a file in the master file, the fragment must be contained in a tag having an
xml:id attribute and you must use an XPointer expression pointing to the xml:id value. For example if the master file is:
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="test.rng" type="xml"?>
<test>
<xi:include href="a.xml" xpointer="a1"
66 | Oxygen XML Author | Editing Documents

xmlns:xi="http://www.w3.org/2001/XInclude"/>
</test>
and the a.xml file is:
<?xml version="1.0" encoding="UTF-8"?>
<test>
<a xml:id="a1">test</a>
</test>
after resolving the XPointer reference the document is:
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="test.rng" type="xml"?>
<test>
<a xml:id="a1" xml:base="a.xml">test</a>
</test>
The XInclude support in Oxygen is turned on by default. You can toggle it by going to the entry Enable XInclude
processing in the menu Window > Preferences ... > oXygen > XML > XML Parser . When enabled, Oxygen will
be able to validate and transform documents comprised of parts added using XInclude.

Creating a New Project

The tree structure occupies most of the view area. In the upper left side of the view, there is a drop-down list that holds
all recently used projects and project management actions:
• Open Project ... (Ctrl+F2) - Opens an existing project. An alternate way to open a project is to drop an Oxygen
XPR project file from the file explorer in the Project panel.
• New Project - Creates a new, empty project.
The files are organized in an XML project usually as a collection of folders. They are created and deleted with the usual
Eclipse actions.

Creating New Project Items

A series of actions are available in the contextual menu:
• New > File - Creates a new file and adds it to the project structure.
• Add Folder - Adds a link to a physical folder, whose name and content mirror a real folder existing in the file
system on disk. The icon of this action is different on Mac OS X ( ) as the standard folder icon on Mac OS X is
not the usual one from Windows and Unix/Linux systems.
• New > Logical Folder - Creates a logical folder in the tree structure (the icon is a magenta folder on Mac OS
X - ).
• New > Logical Folders from File System - Replicates the structure of physical folders on disk. The newly created
logical folder contains the file structure of the folder it points to.
• New > Logical Folders from Web - Replicates the structure of a remote folder accessible over FTP/SFTP/WebDAV,
as a structure of logical folders. The newly created logical folders contain the file structure of the folder it points to.
• New > Project - Creates a new project, after closing the current project and all open files.

Managing Project Content

Validate Files
The currently selected files associated to the Oxygen plugin in the Package Explorer view can be validated against a
schema of type Schematron, XML Schema, Relax NG, NVDL, or a combination of the later with Schematron with one
of the following contextual menu actions:
• Validate available on the Batch Validation submenu of the contextual menu of the Package Explorer view.
• Validate with ... available on the Batch Validation submenu of the contextual menu of the Package Explorer view.
Oxygen XML Author | Editing Documents | 67

Applying Transformation Scenarios

The currently selected files associated to the Oxygen plugin in the Package Explorer view can be transformed in one
step with one of the actions Apply Transformation, Configure Transformation ... and Transform with... available
on the Transformation sub-menu of the right-click menu of the Package Explorer view. This, together with the logical
folder support of the project allows you to group your files and transform them very easily.
If the resources from a linked folder in the project have been changed outside the view, you can refresh the content of
the folder by using the Refresh action from the contextual menu. The action is also performed when selecting the
linked resource and pressing F5 key
You can also use drag and drop to arrange the files in logical folders . Also, dragging and dropping files from the project
tree to the editor area results in the files being opened.

Other Context-Dependent Actions

Many of the actions available in the Project view are grouped in a contextual menu. This menu is displayed after selecting
a file or folder and then pressing right-click (or Ctrl+Click on Mac OS X)
• Show in Explorer (or Show in Finder on Mac OS X) - Opens an OS-specific finder/explorer window, with the file
or folder in question selected in the finder/explorer window.
• Open with - Open selected file with one of internal tools: SVG Viewer, Hex Viewer, Large File Viewer, MathML
Editor, WSDL/SOAP Analyzer, DITA Maps Manager, Archive Browser.
• Open All Files - Action available only when at least one folder is selected. Opens in the author view all files contained
by the selected resources.
Create an Oxygen XML Project

1. Go to menu File > New (Ctrl+N) > XML Project

The New XML Project wizard is displayed.
2. Type a name for the new project.
3. Click the Next button.
4. Select other Eclipse projects that you want to reference in the new project.
5. Click the Finish button.

Working with XML Catalogs

When Internet access is not available or the Internet connection is slow the OASIS XML catalogs present in the list
maintained in the XML Catalog Preferences panel will be scanned trying to map a remote system ID (at document
validation) or a URI reference (at document transformation) pointing to a resource on a remote Web server to a local
copy of the same resource. If a match is found then Oxygen will use the local copy of the resource instead of the remote
one. This enables the XML author to work on his/hers XML project without Internet access or when the connection is
slow and waiting until the remote resource is accessed and fetched becomes unacceptable. Also XML catalogs make
documents machine independent so that they can be shared by many developers by modifying only the XML catalog
mappings related to the shared documents.
Oxygen supports any XML catalog file that conforms to one of:
• the OASIS XML Catalogs Committee Specification v1.1
• the OASIS Technical Resolution 9401:1997 including the plain-text flavor described in that resolution

The version 1.1 of the OASIS XML Catalog specification introduces the possibility to map a system ID, a public ID or
a URI to a local copy using only a suffix of the ID or URI used in the actual document. This is done using the new
catalog elements systemSuffix and uriSuffix.
68 | Oxygen XML Author | Editing Documents

An XML catalog can be used also to map a W3C XML Schema specified with an URN in the xsi:schemaLocation
attribute of an XML document to a local copy of the schema. For example if the XML document specifies the schema
with:
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1">
Inside an XML Schema if an xs:import statement specifies only the namespace attribute, without the schemaLocation
attribute, Oxygen will try to resolve the specified namespace URI through one of the XML catalogs configured in
Preferences pages.
The URN can be resolved to a local schema file with a catalog entry like:
<system systemId="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1"
uri="topic.xsd"/>
An XML Catalog file can be created quickly in Oxygen starting from the two XML Catalog document templates called
OASIS XML Catalog 1.0 and OASIS XML Catalog 1.1 and available in the document templates dialog.
User preferences related to XML Catalogs can be configured from Window > Preferences ... > oXygen > XML >
XML Catalog

XML Catalog
An XML catalog helps the XML parser to check a document for errors if the schema or a part of the schema is not
available, for example when an Internet connection is not available.
Important:
Oxygen XML Editor collects all the catalog files listed in the installed frameworks. No matter what the Document
Type Association matches the edited file, all the catalog mappings are considered when resolving external references.

Important:
The catalog files settings are available for all editing modes, not only for the Author mode.

Formatting and Indenting Documents (Pretty Print)

In structured markup languages, the whitespace between elements that is created using the Space bar, Tab or multiple
line breaks is not recognized by the parsing tools. Often this means that when structured markup documents are opened,
they are arranged as one long, unbroken line, that seems to be a single paragraph.
While this is a perfectly acceptable practice, it makes editing difficult and increases the likelihood of errors being
introduced. It also makes the identification of exact error positions difficult. Formatting and Indenting, also called Pretty
Print, enables such documents to be neatly arranged, in a manner that is consistent and promotes easier reading on
screen and in print output.
Pretty print is in no way associated with the layout or formatting that will be used in the transformed document. This
layout and formatting is supplied by the XSL stylesheet specified at the time of transformation.
To change the indenting of the current selected text see the Indent selection action.
For user preferences related to formatting and indenting like Detect indent on open and Indent on paste see the
corresponding Preferences panel.
XML elements can be excepted from the reformatting performed by the pretty-print operation by including them in the
Preserve space elements (XPath) list. That means that when the Format and Indent (pretty-print) action encounters in
the document an element with the name contained in this list, the whitespace is preserved inside that element. This is
useful when most of the elements must be reformatted with the exception of a few ones which are listed here.
For the situation when whitespace should be preserved in most elements with the exception of a few elements, the names
of these elements must be added to the Strip space elements (XPath) list.
Oxygen XML Author | Editing Documents | 69

In addition to simple element names, both the Preserve space elements (XPath) list and the Strip space elements (XPath)
one accept a restricted set of XPath expressions to cover a pattern of XML elements with only one expression. The
allowed types of expressions are:

//xs:documentation
the XPath descendant axis can be used only at the beginning of the expression; the
namespace prefix can be attached to any namespace, no namespace binding check
is performed when applying the pretty-print operation

/chapter/abstract/title
note the use of the XPath child axis

//section/title
the descendant axis can be followed by the child axis

The value of an xml:space attribute present in the XML document on which the pretty-print operation is applied always
takes precedence over the Preserve space elements (XPath) and the Strip space elements (XPath) lists.

Viewing Status Information

Status information generated by the Schema Detection, Validation, Automatic validation and Transformation threads
are fed into the Console view allowing the user to monitor how the operation is being executed.

Figure 34: The Console view messages

Messages contain a timestamp, the name of the thread that generated it and the actual status information. The number
of displayed messages in the Console view can be controlled from the Options panel.

XML Editor Specific Actions

Oxygen offers groups of actions for working on single XML elements. They are available from the

Edit Actions
The following XML specific editing actions are available in Text mode:
• contextual menu of current editor > Toggle comment (Ctrl + /) - Comments the current selection of the current
editor. If the selection already contains a comment the action removes the comment from around the selection. If
there is no selection in the current editor and the cursor is not positioned inside a comment the current line is
commented. If the cursor is positioned inside a comment then the commented text is uncommented.

Select Actions
In Text mode of the XML editor these actions are enabled when the caret is positioned inside a tag name:
• contextual menu of current editor > Select > Element - Selects the entire current element.
• contextual menu of current editor > Select > Content - Selects the content of the current element, excluding the
start tag and end tag. If it is applied repeatedly, starts with selecting the XML element from the cursor position and
extends the selection to the ancestor XML elements. Each execution of the action extends the current selection to
the surrounding element.
70 | Oxygen XML Author | Editing Documents

• contextual menu of current editor > Select > Attributes - Selects all the attributes of the current element.
• contextual menu of current editor > Select > Parent - Selects the parent element of the current element.
• Double click on an element or processing instruction - If the double click is done before the start tag of an element
or after the end tag of an element then all the element is selected by the double click action. If it is done after the
start tag or before the end tag then only the element content without the start tag and end tag is selected.
• Double click after the opening quote or before the closing quote of an attribute value - Select the whole attribute
value.

Source Actions
The following actions can be applied on the text content of the XML editor:
• contextual menu of current editor > Source > Escape Selection ... - Escapes a range of characters by
replacing them with the corresponding character entities.
• contextual menu of current editor > Source > Unescape Selection ... - Replaces the character entities with
the corresponding characters.
• contextual menu of current editor > Source > Indent selection (Ctrl + I) ( (Cmd + I on Mac OS)) - Corrects
the indentation of the selected block of lines if it does not follow the current indenting preferences of the user.
• contextual menu of current editor > Source > Format and Indent Element (Ctrl + Shift + I) - Pretty prints
the element that surrounds the caret position.
• contextual menu of current editor > Source > Import entities list - Shows a dialog that allows you to select
a list of files as sources for external DTD entities. The internal subset of the DOCTYPE declaration of your document
will be updated with the chosen entities. For instance, if choosing the file chapter1.xml and chapter2.xml,
the following section is inserted in the DOCTYPE:
<!ENTITY chapter1 SYSTEM "chapter1.xml">
<!ENTITY chapter2 SYSTEM "chapter2.xml">

• contextual menu of current editor > Join and normalize - The action works on the selection. It joins the lines
by replacing the line separator with a single space character. It also normalizes the whitespaces by replacing a
sequence of such characters with a single space.

XML Document Actions

The Text mode of the XML editor provides the following document level actions:
• contextual menu of current editor > Show Definition - Moves the cursor to the definition of the current element
in the schema associated with the edited XML document (DTD, XML Schema, Relax NG schema).
• contextual menu of current editor > Copy XPath (Ctrl+Shift+.) - Copies the XPath expression of the current
element or attribute from the current editor to the clipboard.
• contextual menu of current editor > Go to Matching Tag - Moves the cursor to the end tag that matches the
start tag, or vice versa.
• contextual menu of current editor > Go after Next Tag (Ctrl+]) - Moves the cursor to the end of the next tag.
• contextual menu of current editor > Go after Previous Tag (Ctrl+[) - Moves the cursor to the end of the previous
tag.
• XML > Associate XSLT/CSS Stylesheet - Inserts an xml-stylesheet processing instruction at the
beginning of the document referencing either an XSLT or a CSS file depending on the user selection. Either reference
is useful for rendering the document in a Web browser when the action Open in browser is executed. Referencing
the XSLT file is also useful for automatic detection of the XSLT stylesheet when there is no scenario associated
with the current document.
When associating the CSS stylesheet, the user can also specify a title for it if it is an alternate one. Setting a Title for
the CSS makes it the author's preferred stylesheet. Selecting the Alternate checkbox makes the CSS an alternate
stylesheet.
Oxygen XML Author | Editing Documents | 71

Oxygen XML Author fully implements the W3C recommendation regarding Associating Style Sheets with XML
documents. See also Specifying external style sheets in HTML documents.

XML Refactoring Actions

The following refactoring actions are available while editing an XML document:
• context menu of current editor > XML Refactoring > Surround with tag... (Alt+Shift+E) ( (Cmd+Alt+E
on Mac OS)) - Selected text in the editor is marked with the specified start and end tags.
• context menu of current editor > XML Refactoring > Surround with last <tag> (Alt+Shift+/) ( (Cmd+Alt+/
on Mac OS)) - Selected Text in the editor is marked with start and end tags of the last 'Surround in' action.
• context menu of current editor > XML Refactoring > Rename element (Alt+Shift+R) ( (Cmd+Alt+R on
Mac OS)) - the element from the caret position and the elements that have the same name as the current element
can be renamed according with the options from the Rename dialog.

context menu of current editor > XML Refactoring > Rename prefix (Alt+Shift+P) ( (Cmd+Alt+P on Mac
OS)) - the prefix of the element from the caret position and the elements that have the same prefix as the current
element can be renamed according with the options from the Rename dialog.
Selecting the Rename current element prefix option, the application will recursively traverse the current element
and all its children.
For example, to change the xmlns:p1="ns1" association existing in the current element to xmlns:p5="ns1",
just select this option and press OK. If the association xmlns:p1="ns1" is applied on the parent of the current
element, then Oxygen will introduce a new declaration xmlns:p5="ns1" in the current element and will change
the prefix from p1 to p5. If p5 is already associated in the current element with another namespace, let's say ns5,
then a dialog showing the conflict will be displayed. Pressing the OK button, the prefix will be modified from p1
to p5 without inserting a new declaration xmlns:p5="ns1". On Cancel no modification is made.
Selecting the Rename current prefix in all document option, the application will apply the change on the entire
document.
To apply the action also inside attribute values one must check the Rename also attribute values that start with
the same prefix checkbox.
• context menu of current editor > XML Refactoring > Split element - Split the element from the caret
position in two identical elements. The caret must be inside the element.
• context menu of current editor > XML Refactoring > Join elements (Alt+Shift+F) ( (Cmd+Alt+F on Mac
OS)) - Joins the left and right elements relative to the current caret position. The elements must have the same name,
attributes and attributes values.
• context menu of current editor > XML Refactoring > Delete element tags (Alt+Shift+,) ( (Cmd+Alt+, on
Mac OS)) - Deletes the start and end tag of the current element.

Smart Editing
The following helper actions are available in the XML editor:
• Closing tag auto-expansion - If you want to insert content into an auto closing tag like <tag/> deleting the / character
saves some keystrokes by inserting a separate closing tag automatically and placing the cursor between the start and
end tags: <tag></tag>
• Auto-rename matching tag - When you edit the name of the start tag, Oxygen will mirror-edit the name of the
matching end tag. This feature can be controlled from the Content Completion option page.
• Auto-breaking the edited line - The Hard line wrap option breaks the edited line automatically when its length
exceeds the maximum line length defined for the pretty-print operation.
• Indent on Enter - The Indent on Enter option indents the new line inserted when Enter is pressed.
72 | Oxygen XML Author | Editing Documents

• Smart Enter - The Smart Enter option inserts an empty line between the start and end tags. If Enter is pressed between
a start and an end tag the action places the cursor in an indented position on the empty line between the lines that
contain the start and end tag.
• Triple click - A triple click with the left mouse button selects a different region of text of the current document
depending on the position of the click in the document:
• if the click position is inside a start tag or an end tag then the entire element enclosed by that tag is selected
• if the click position is immediately after a start tag or immediately before an end tag then the entire content of
the element enclosed by that tag is selected, including all the child elements but excluding the start tag and the
end tag of the element
• otherwise the triple click selects the entire current line of text

Syntax Highlight Depending on Namespace Prefix

The syntax highlight scheme of an XML file type allows the configuration of a color per each type of token which can
appear in an XML file. Distinguishing between the XML tag tokens based on the namespace prefix brings additional
visual help in editing some XML file types. For example in XSLT stylesheets elements from different namespaces like
XSLT, XHTML, XSL:FO or XForms are inserted in the same document and the editor panel can become cluttered.
Marking tags with different colors based on the namespace prefix allows easier identification of the tags.

Figure 35: Example of Coloring XML Tags by Prefix

Handling Read-Only Files

The default workbench behavior applies when editing read-only files in the Text page. For all other pages no modification
is allowed as long as the file remains read-only.
You can check out the read-only state of the file by looking in the Properties view. If you modify the file properties
from the operating system and the file becomes writable, you are able to modify it on the spot without having to reopen
it.
Chapter
5
Authoring in the Tagless Editor
Topics: This chapter presents the WYSIWYG like editor targeted for content authors,
also called Author editor.
• Authoring XML Documents
Without the XML Tags
• General Author Presentation
74 | Oxygen XML Author | Authoring in the Tagless Editor

Authoring XML Documents Without the XML Tags

Once the structure of the XML document and the required restrictions on the elements and attributes are fixed with an
XML schema the editing of the document is easier in a WYSIWYG (what-you-see-is-what-you-get) editor in which the
XML markup is not visible.
This tagless editor is available as the Author mode of the XML editor. The Author mode is activated by pressing the
Author button at the bottom of the editing area where the mode switches of the XML editor are available: Text, Grid,
and Author. The Author mode renders the content of the XML document visually based on a CSS stylesheet associated
with the document. Many of the actions and features available in Text mode are also available in Author mode.

Figure 36: oXygen Author Editor

The tagless rendering of the XML document in the Author mode is driven by a CSS stylesheet which conforms to the
version 2.1 of the CSS specification from the W3C consortium. Also some CSS 3 features like namespaces and custom
extensions of the CSS specification are supported.
The CSS specification is convenient for driving the tagless rendering of XML documents as it is an open standard
maintained by the W3C consortium. A stylesheet conforming to this specification is easy to develop and edit in Oxygen
as it is a plain text file with a simple syntax.
The association of such a stylesheet with an XML document is also straightforward: an xml-stylesheet XML
processing instruction with the attribute type="text/css" must be inserted at the beginning of the XML document.
If it is an XHTML document, that is the root element is an html element, there is a second method for the association
of a CSS stylesheet: an element link with the href and type attributes in the head child element of the html
element as specified in the CSS specification.
There are two main types of users of the Author mode: developers and content authors. A developer is a technical person
with advanced XML knowledge who defines the framework for authoring XML documents in the tagless editor. Once
the framework is created or edited by the developer it is distributed as a deliverable component ready to plug into the
application to the content authors. A content author does not need to have advanced knowledge about XML tags or
operations like validation of XML documents or applying an XPath expression to an XML document. The author just
Oxygen XML Author | Authoring in the Tagless Editor | 75

plugs the framework set-up by the developer into the application and starts editing the content of XML documents
without editing the XML tags directly.
The framework set-up by the developer is called document type and defines a type of XML documents by specifying
all the details needed for editing the content of XML documents in tagless mode:
• the CSS stylesheet which drives the tagless visual rendering of the document;
• the rules for associating an XML schema with the document which is needed for content completion and validation
of the document;
• transformation scenarios for the document;
• XML catalogs;
• custom actions available as buttons on the toolbar.
The tagless editor comes with some ready to use predefined document types for XML frameworks largely used today
like DocBook, DITA, TEI, XHTML.

General Author Presentation

A content author edits the content of XML documents in tagless mode disregarding the XML tags as they are not visible
in the editor. If he edits documents conforming to one of the predefined types he does not need to configure anything
as the predefined document types are already configured when the application is installed. Otherwise he must plug the
configuration of the document type into the application. This is as easy as unzipping an archive directly in the
[Oxygen-install-folder]/frameworks folder.
In case the edited XML document does not belong to one of the document types set up in Preferences you can specify
the CSS stylesheets to be used by inserting an xml-stylesheet processing instructions. You can insert the processing
instruction by editing the document or by using the Associate XSLT/CSS stylesheet action.
The syntax of such a processing instruction is:
<?xml-stylesheet type="text/css" media="media type" title="title"
href="URL" alternate="yes|no"?>
You can read more about associating a CSS to a document in the section about customizing the CSS of a document type.
When the document has no CSS association or the referred stylesheet files cannot be loaded, a default one is used. A
warning message is also displayed at the beginning of the document presenting the reason why the CSS cannot be loaded.
76 | Oxygen XML Author | Authoring in the Tagless Editor

Figure 37: Document with no CSS association default rendering

Author Views
The content author is supported by special views which are automatically synchronized with the current editing context
of the editor panel. The views present additional information about this context thus helping the author to see quickly
the current location in the overall document structure and the available editing options.

Outline View
The Outline view offers the following functionality:
• Document Overview
• Outline View Specific Actions
• Modification Follow-up
• Document Structure Change
• Document Tag Selection
Oxygen XML Author | Authoring in the Tagless Editor | 77

Figure 38: The Outline View

XML Document Overview

The Outline view displays a general tag overview of the current edited XML Document. It also shows the correct
hierarchical dependencies between the tag elements. That makes easier for the user to be aware of the document structure
and the way tags are nested. It allows fast navigation of the document by displaying the start of the content of the child
elements in the node of the parent element thus allowing to see quickly the content of an element without expanding it
in the Outline tree. It also allows the user to insert or delete nodes using pop-up menu actions.
The Expand all and Collapse all items of the popup menu available on the Outline tree enlarge or reduce the set of nodes
of the edited document currently visible in the view. The tree expansion action is a faster alternative to mouse clicks on
the plus signs of the tree when one wants to access quickly a node deeply nested in the hierarchy of document nodes.
When a large number of nodes become expanded and the document structure is not clear any more, the collapsing action
clears the view quickly by reducing the depth of the expanded nodes to only one child of the currently selected node.
Document errors (such as an element inserted in an invalid position, or a wrong attribute name, or a missing required
attribute value) are highlighted in the Outline tree. An easy-to-spot exclamation mark sign is used as element icon, a
red underline decorates the element name and value and a tooltip provides more information about the nature of the
error.
Modification Follow-up
When editing, the Outline view dynamically follows the modifications introduced by the user, showing in the middle
of the panel the node which is currently being modified. This gives the user better insight on location where in the
document one is positioned and how the structure of the document is affected by one's modifications.
Document Structure Change
Entire XML elements can be moved or copied in the edited document using only the mouse in the Outline view in
drag-and-drop operations. Several drag and drop actions are possible:
• If you drag an XML element in the Outline view and drop it on another one in the same panel then the dragged
element will be moved after the drop target element.
• If you hold the mouse pointer over the drop target for a short time before the drop then the drop target element will
be expanded first and the dragged element will be moved inside the drop target element after its opening tag.
• You can also drop an element before or after another element if you hold the mouse pointer towards the upper or
lower part of the targeted element. A marker will indicate whether the drop will be performed before or after the
target element.
78 | Oxygen XML Author | Authoring in the Tagless Editor

• If you hold down the (Ctrl) key after dragging, there will be performed a copy operation instead of a move one.
The drag and drop action in the Outline view can be disabled and enabled from the Preferences dialog.
Tip: You can select and drag multiple nodes in the Author Outline tree.

Outline Filters
The following actions are available in the View menu on the Outline view's action bar:
• Flat presentation mode of the filtered results - when active, the application flattens the filtered result elements
to a single level.
• Show comments and processing instructions - show/hide comments and processing instructions in the Outline
view.
• Show text - show/hide additional text content for the displayed elements.
• Show attributes - show/hide attribute values for the displayed elements. The displayed attribute values can be
changed from the Outline preferences panel.
• Configure displayed attributes - displays the XML Structured Outline preferences page.
The upper part of the view contains a filter box which allows you to focus on the relevant components. Type a text
fragment in the filter box and only the components that match it are presented. For advanced usage you can use wildcard
characters (*, ?) and separate multiple patterns with commas.
The Contextual Menu of the Outline Tree
The contextual menu of the Outline tree contains the following actions:
• Edit attributes - A dialog is presented allowing the user to see and edit the attributes of the selected node.
• The Append child, Insert before and Insert after submenus allow to quickly insert new tags in the document at
the place of the element selected in the Outline tree. The Append child submenu lists the names of all the elements
which are allowed by the schema associated with the current document as child of the current element. The effect
is the same as typing the '<' character and selecting an element name from the popup menu offered by the content
completion assistant. The Insert before and Insert after submenus list the elements which are allowed by the schema
associated with the current document as siblings of the current element inserted immediately before respectively
after the current element.
• The Cut, Copy and Delete actions execute the same actions as the Edit menu items with the same name on the
elements currently selected in the Outline tree (Cut, Copy, Paste).
• You can insert a well-formed element before, after or as a child of the currently selected element by accessing the
Paste before, Paste after or Paste as Child actions.
• The Toggle Comment item encloses the currently selected element of the Outline tree in an XML comment, if the
element is not commented, or removes the comment if it is commented.
• Using the Rename Element action the element from the caret position and the elements that have the same name
as the current element can be renamed according with the options from the Rename dialog.
• The Expand All / Collapse All actions expand / collapse the selection and all its children.
Tip: You can copy, cut or delete multiple nodes in the Outline by using the contextual menu after selecting multiple
nodes in the tree.

Elements View
The Elements view presents a list of all defined elements that you can insert in your document. All elements from a
sequence are presented but the invalid proposals (which cannot be inserted in the current context) are grayed-out. The
upper part of the view features a combo box that contains the current element's ordered ancestors. Selecting a new
element in this combo box will update the list of the allowed elements in Before and After tabs.
Oxygen XML Author | Authoring in the Tagless Editor | 79

Figure 39: The Elements View

Three tabs present information relative to the caret location:

• Caret - Shows a list of all the elements allowed at the current caret location. Double-clicking any of the listed
elements will insert that element at the caret position.
• Before - Shows a list of all elements that can be inserted before the element selected in the combo box. Double-clicking
any of the listed elements will insert that element before the element at the caret position.
• After - Shows a list of all elements that can be inserted after the element selected in the combo box. Double-clicking
any of the listed elements will insert that element after the element at the caret position.
Double clicking an element name in the list surrounds the current selection in the editor panel with the start tags and
end tags of the element. If there is no selection just an empty element is inserted in the editor panel at the cursor position.

Attributes View
The Attributes view presents all the possible attributes of the current element allowed by the schema of the document.
It allows you to insert attributes in the current element or change the value of the attributes already used in the element.
The already present attributes are painted with a bold font. Default values are painted with gray color. The Attributes
view uses a red color to highlight invalid attributes and values.
Clicking the Value column of a table row will start editing the value of the attribute from the selected row. If the possible
values of the attribute are specified as list in the schema associated with the edited document the Value column works
as a combo box where you can select one of the possible values to be inserted in the document. The attributes table is
sortable by clicking the column names. Thus the table's contents can be sorted in ascending order, in descending order
or in a custom order, where the used attributes are placed at the beginning of the table as they appear in the element
followed by the rest of the allowed elements as they are declared in the associated schema.
80 | Oxygen XML Author | Authoring in the Tagless Editor

Figure 40: The Attributes View

A combo box located in the upper part of the view allows you to edit the attributes of the ancestors of the current element.
The contextual menu of the view allows you to insert a new element (Add action) or delete an existing one (Delete
action). Delete action can be invoked on a selected table entry by pressing (Del) or (Backspace).
The attributes of an element can be edited also in place in the editor panel by pressing the shortcut (Alt + Enter) which
pops up a small window with the same content of the Attributes view. In the initial form of the popup, only the two
text fields Name and Value are displayed, the list of all the possible attributes is collapsed.

Figure 41: Edit attributes in place

The small right arrow button expands the list of possible attributes allowed by the schema of the document as in the
Attributes panel.
Oxygen XML Author | Authoring in the Tagless Editor | 81

Figure 42: Edit attributes in place - full version

The Name field auto-completes the name of the attribute: the complete name of the attribute is suggested based on the
prefix already typed in the field as the user types in the field.
Adding an attribute that is not in the list of all defined attributes is not possible when the Allow only insertion of valid
elements and attributes schema aware option is enabled.

Entities View
This view displays a list with all entities declared in the current document as well as built-in ones. Double clicking one
of the entities will insert it at the current cursor position.

Figure 43: The Entities View

The Author Editor

This section explains the features of the CSS-driven WYSIWYG-like editor for XML documents.

Navigating the Document Content

Fast navigating the document content can be done using the (Tab)/(Shift + Tab) for advancing forward / backwards.
The caret is moved to the next / previous editable position. To navigate one word forward or backwards, use Ctrl +
Right Arrow, and Ctrl + Left Arrow, respectively. Entities and hidden elements are skipped.
82 | Oxygen XML Author | Authoring in the Tagless Editor

A left-hand side stripe paints a vertical thin light blue bar indicating the vertical span of the element found at caret
position. Also a top stripe called breadcrumb indicates the path from document root to the current element.

Figure 44: The breadcrumb in Editor view

The last element is also highlighted by a thin light blue bar for easier identification. Clicking one element from the top
stripe selects the entire element in the editor view.
The tag names displayed in the breadcrumb can be customized with an Author extension class that implements
AuthorBreadCrumbCustomizer. See the Author SDK for details about using it.
The locations of selected text are stored in an internal list which allows navigating between them with the buttons
Ctrl+Alt+[ Back and Ctrl+Alt+] Forward that are available on the toolbar Navigation.
The Append child, Insert before and Insert after submenus of the top stripe popup menu allow you to insert new tags
in the document at the place of the selected element. The Append child submenu lists the names of all the elements
which are allowed by the schema associated with the current document as child of the current element. The effect is the
same as typing the '<' character and selecting an element name from the popup menu offered by the content completion
assistant. The Insert before and Insert after submenus list the elements which are allowed by the schema associated
with the current document as siblings of the current element inserted immediately before respectively after the current
element.
The Cut, Copy, Paste and Delete items of the popup menu execute the same actions as the Edit menu items with the
same name on the elements currently selected in the stripe (Cut, Copy, Paste, Delete). The Cut and Copy operations
(like the display:block property or the tabular format of the data from a set of table cells) preserve the styles of
the copied content. The Paste before, Paste after and Paste as Child actions allow the user to insert an well-formed
element before, after or as a child of the currently selected element.
The Toggle Comment item of the Outline tree popup menu encloses the currently selected element of the top stripe in
an XML comment, if the element is not commented, or removes the comment if it is commented.
Using the Rename Element action the selected element and the elements that have the same name as the current element
can be renamed according with the options from the Rename dialog.
When working on a large document, the folding support can be used to collapse some elements content leaving in focus
only the ones you need to edit. Foldable elements are marked with a small triangle painted in the upper left corner.
Hovering with the mouse pointer over that marker, the entire content of the element is highlighted by a dotted border
for quick identification of the foldable area.
When working on a suite of documents that refer to one another (references, external entities, XInclude, DITA conref,
etc), the linking support is useful for navigating between the documents. In the predefined customizations that are
bundled with Oxygen XML Author links are marked with an icon representing a chain link: . When hovering with
the mouse pointer over the marker, the mouse pointer changes its shape to indicate that the link can be followed and a
tooltip presents the destination location. Click a followable link to open the referred resource in an editor. The same
effect can be obtained by using the action Open file at caret when the caret is in a followable link element.
To position the cursor at the beginning or at the end of the document you can use (Ctrl+Home) and (Ctrl+End),
respectively.
Displaying the Markup
In Author view, the amount of displayed markup can be controlled using the following dedicated actions:
• Full Tags with Attributes - Displays full name tags with attributes for both block level as well as in-line level
elements.
• Full Tags - Displays full name tags without attributes for both block level as well as in-line level elements.
• Block Tags - Displays full name tags for block level elements and simple tags without names for in-line level
elements.
• Inline Tags - Displays full name tags for inline level elements, while block level elements are not displayed.
Oxygen XML Author | Authoring in the Tagless Editor | 83

• Partial Tags - Displays simple tags without names for in-line level elements, while block level elements are
not displayed.
• No Tags - None of the tags is displayed. This is the most compact mode.
The default tags display mode can be configured in the Author options page. However, if the document opened in Author
editor does not have an associated CSS stylesheet, then the Full Tags mode will be used.
Block-level elements are those elements of the source document that are formatted visually as blocks (e. g. paragraphs),
while the inline level elements are distributed in lines (e. g. emphasizing pieces of text within a paragraph, inline images,
etc). The graphical format of the elements is controlled from the CSS sources via the display property.
Bookmarks
A position in a document can be marked with a bookmark. Later the cursor can go quickly to the marked position with
a keyboard shortcut or with a menu item. This is useful to ease the navigation in a large document or to work on more
than one document when the cursor must move between several marked positions.
A bookmark can be placed with:
• one of the menu items available on the menu Edit > Bookmarks > Create
• the menu item Edit > Bookmarks > Bookmarks Quick Creation (F9)
• the keyboard shortcuts associated with these menu items and visible on the menu Edit > Bookmarks
A bookmark can be removed when a new bookmark is placed in the same position as an old one or with the action Edit
> Bookmarks > Remove All . The cursor can go to a bookmark with one of the actions available on the menu Edit >
Bookmarks > Go to .

Position Information Tooltip

When the caret is positioned inside a new context, a tooltip will be shown for a couple of seconds displaying the position
of the caret relative to the current element context.
Here are the common situations that can be encountered:
• The caret is positioned before the first block child of the current node.

Figure 45: Before first block

• The caret is positioned between two block elements.

Figure 46: Between two block elements

• The caret is positioned after the last block element child of the current node.

Figure 47: After last block

• The caret is positioned inside a node.

84 | Oxygen XML Author | Authoring in the Tagless Editor

Figure 48: Inside a node

• The caret is positioned inside an element, before an inline child element.

Figure 49: Before an inline element

• The caret is positioned between two inline elements.

Figure 50: Between two inline elements

• The caret is positioned inside an element, after an inline child element.

Figure 51: After an inline element

The nodes in the previous cases are displayed in the tooltip window using their names.
You can deactivate this feature by unchecking the Options > Preferences > Editor / Author > Show caret position
tooltip check box. Even if this option is disabled, you can trigger the display of the position tooltip by pressing Shift+F2.
Note: The position information tooltip is not displayed if one of the modes Full Tags with Attributes or Full Tags
is selected.

Displaying Referred Content

The references to entities, XInclude, and DITA conrefs are expanded by default in Author mode and the referred content
is displayed. You can control this behavior from the Author options page. The referred resources are loaded and displayed
inside the element or entity that refers them, however the displayed content cannot be modified directly.
When the referred resource cannot be resolved, an error will be presented inside the element that refers them instead of
the content.
If you want to make modifications to the referred content, you must open the referred resource in an editor. The referred
resource can be opened quickly by clicking on the link (marked with the icon ) which is displayed before the referred
content. The referred resource is resolved through the XML Catalog set in Preferences.
The referred content is refreshed:
• automatically, when it is modified and saved from Oxygen XML Author;
• on demand, by using the Refresh references action. Useful when the referred content is modified outside the Oxygen
XML Author scope.

Finding and Replacing Text

The Find / Replace dialog can be used in the Author page in the same way as in the Text page.
Oxygen XML Author | Authoring in the Tagless Editor | 85

Contextual Menu
More powerful support for editing the XML markup is offered via actions included in the contextual menu. Two types
of actions are available: generic actions (actions that not depends on a specific document type) and document type
actions (actions that are configured for a specific document type).

Figure 52: Contextual menu

The generic actions are:

• Edit Attributes - A pop-up window is displayed allowing you to manage the element attributes.
• Rename - The element from the caret position can be renamed quickly using the content completion window. If the
Allow only insertion of valid elements and attributes schema aware option is enabled only the proposals from the
content completion list are allowed, otherwise a custom element name can also be provided.
• Cut, Copy, Paste - Common edit actions with the same functionality as those found in the text editor.
• Paste As XML - Similar to Paste operation, except that the clipboard's content is considered to be XML.
• Edit Profiling Attributes - Allows you to select the profiling attributes.
• Select - Contains the following actions:
• Select > Select Element - Selects the entire element at the current caret position.
• Select > Select Content - Selects the entire content of the element at the current caret position, excluding the
start and end tag. Performing this action repeatedly will result in the selection of the content of the ancestor of
the currently selected element content.
• Select > Select Parent - Selects the parent of the element at the current caret position.
Note: You can select an element by triple clicking inside its content. If the element is empty you can select it
by double clicking it.

• Refactoring - Contains a series of actions designed to alter the document's structure:

• Toggle Comment - Encloses the currently selected text in an XML comment, or removes the comment if it is
commented.
• Split Element - Splits the content of the closest element that contains the caret's position. Thus, if the caret is
positioned at the beginning or at the end of the element, the newly created sibling will be empty.
• Join Elements - Joins two adjacent elements that have the same name. The action is available only when the
caret position is between the two adjacent elements. Also, joining two elements can be done by pressing the
Delete or Backspace keys and the caret is positioned between the boundaries of these two elements.
• Surround with Tag... - Selected text in the editor is marked with the specified tag.
• Surround with '<Tag name>' - Selected text in the editor is marked with start and end tags of the last 'Surround
with Tag...' action.
86 | Oxygen XML Author | Authoring in the Tagless Editor

• Rename Element - The element from the caret position and the elements that have the same name as the current
element can be renamed according with the options from the Rename dialog.
• Delete Element Tags - Deletes the tags of the closest element that contains the caret's position. This operation
is also executed if the start or end tags of an element are deleted by pressing the (Delete) or (Backspace) keys.

• Review - Provides access to Track Changes and Manage Comments actions.

• Insert Entity - Allows the user to insert a predefined entity or a character entity. Surrogate character entities (range
#x10000 to #x10FFFF) are also accepted. Character entities can be entered in one of the following forms:
• #<decimal value> - e. g. #65
• &#<decimal value>; - e. g. A
• #x<hexadecimal value> - e. g. #x41
• &#x<hexadecimal value>; - e. g. A

• Open File at Caret - Opens in a new editor panel the file with the name under the current position of the caret in
the current document. If the file does not exist at the specified location the error dialog that is displayed contains a
Create new file action which displays the New file dialog. This allows you to choose the type or the template for
the file. If the action succeeds, the file is created with the referred location and name and is opened in a new editor
panel. This is useful when you decide first on the file name and after that you want to create it in the exact location
specified at the current cursor position.
• Options - Opens the Author options page.
Document type actions are specific to some document type. Examples of such actions can be found in section Predefined
document types.

Editing XML Documents in Author

This section details how to edit the text content and the markup of XML documents in Author mode. It explains also
how to edit tables and MathML content in Author mode.
Editing the XML Markup
One of the most useful feature in Author editor is the content completion support. The fastest way to invoke it is to press
(Enter) or (Ctrl + Space) (on Mac OS X the shortcut is (Meta + Space)) in the editor panel.
Content completion window offers the following types of actions:
• inserting allowed elements for the current context according to the associated schema, if any;
• inserting element values if such values are specified in the schema for the current context;
• inserting new undeclared elements by entering their name in the text field;
• inserting CDATA sections, comments, processing instructions;
• inserting code templates.

Figure 53: Content completion window

If you press (Enter) the displayed content completion window will contain as first entries the Split <Element name>
items. Usually you can only split the closest block element to the caret position but if it is inside a list item, the list item
will also be proposed for split. Selecting Split <Element name> splits the content of the specified element around the
caret position. Thus, if the caret is positioned at the beginning or at the end of the element, the newly created sibling
will be empty.
If the caret is positioned inside a space preserve element the first choice in the content completion window is Enter
which inserts a new line in the content of the element. If there is a selection in the editor and you invoke content
Oxygen XML Author | Authoring in the Tagless Editor | 87

completion, a Surround with operation can be performed. The tag used will be the selected item from the content
completion window.
By default you are not allowed to insert element names which are not considered by the associated schema as valid
proposals in the current context. This can be changed by unchecking the Allow only insertion of valid elements and
attributes check box from the Schema aware preferences page.
Joining two elements - You can choose to join the content of two sibling elements with the same name by using the
contextual menu > Join elements action.
The same action can be triggered also in the next situations:
• The caret is located before the end position of the first element and (Delete) key is pressed.
• The caret is located after the end position of the first element and (Backspace) key is pressed.
• The caret is located before the start position of the second element and (Delete) key is pressed.
• The caret is located after the start position of the second element and (Backspace) key is pressed.
In either of the described cases, if the element has no sibling or the sibling element has a different name, Unwrap
operation will be performed automatically.
Unwrapping the content of an element - You can unwrap the content of an element by deleting its tags using the
Delete element tags action from the editor contextual menu.
The same action can be triggered in the next situations:
• The caret is located before the start position of the element and (Delete) key is pressed.
• The caret is located after the start position of the element and (Backspace) key is pressed.
• The caret is located before the end position of the element and (Delete) key is pressed.
• The caret is located after the end position of the element and (Backspace) key is pressed.
Removing all the markup of an element - You can remove the markup of the current element and keep only the text
content with the action Remove All Markup available on the submenu Refactoring of the contextual menu and
on the toolbar XML Refactoring.
When you press (Delete) or (Backspace) in the presented cases the element is unwrapped or it is joined with its sibling.
If the current element is empty, the element tags will be deleted.
When you click on a marker representing the start or end tag of an element, the entire element will be selected. The
contextual menu displayed when you right-click on the marker representing the start or end tag of an element contains
Append child, Insert Before and Insert After submenus as first entries.
Code Templates
You can define short names for predefined blocks of code called code templates. The short names are displayed in the
Content Completion window if the word at cursor position is a prefix of such a short name. If there is no prefix at cursor
position, that is the character at the left of cursor is a whitespace, all the code templates are listed.
Oxygen comes with a lot of predefined code templates but you can define your own code templates for any type of
editor.
To obtain the template list you can use the Content Completion on request shortcut key (usually CTRL-SPACE) or the
Code Templates on request shortcut key (CTRL-SHIFT-SPACE). The first shortcut displays the code templates in the
same content completion list with elements from the schema of the document. The second shortcut displays only the
code templates and is the default shortcut of the action Document > Content Completion > Show Code Templates
.
The following variables can appear in a code template:
• ${caret} - The caret position after inserting the code template.
• ${selection} - The position of the current selection in the inserted template.
• ${env(ENV_VAR_NAME)} - The value of the environment variable ENV_VAR_NAME.
• ${system(var.name)} - The value of the system variable var.name.
• ${date(yyyy-MM-dd)} - A date in the format: 4 digits for year, 2 digits for month, 2 digits for day.
88 | Oxygen XML Author | Authoring in the Tagless Editor

Editing the XML Content

By default you can type only in elements which accept text content. So if the element is declared as empty or element
only in the associated schema you are not allowed to insert text in it. This is also available if you try to insert CDATA
inside an element. Instead a warning message is shown:

Figure 54: Editing in empty element warning

You can disable this behavior by checking the Allow Text in empty or element only content check box in the Author
preferences page.
Entire sections or chunks of data can be moved or copied by using the drag and drop support. The following situations
can be encountered:
• when both the drag and drop sources are Author pages, an well-formed XML fragment is transferred. The section
is balanced before dropping it by adding matching tags when needed.
• when the drag source is the Author page but the drop target is a text-based editor only the text inside the selection
is transferred as it is.
• the text dropped from another text editor or another application into the Author page is inserted without changes.
Styled content can be inserted in the Author editor by copying or dragging it from:
• Office-type applications (Microsoft Word and Microsoft Excel, OpenOffice.org Writer and OpenOffice.org
Calc);
• Web browsers (like Mozilla Firefox or Microsoft Internet Explorer);
• the Data Source Explorer view (where resources are available from WebDAV or CMS servers).
The styles and general layout of the copied content like: sections with headings, tables, list items, bold and italic text,
hyperlinks, etc. are preserved by the paste operation by transforming them to the equivalent XML markup of the target
document type. This is available by default in the following predefined document types: DITA, DocBook 4, DocBook
5, TEI 4, TEI 5, XHTML.
More details about setting up a custom copy/paste handler are available in the Author Developer Guide.
The font size of the current WYSIWYG-like editor can be increased and decreased on the fly with the same actions as
in the Text editor:
• (Ctrl - NumPad+) or (Ctrl - +) or (Ctrl - mouse wheel) - Increases font size.
• (Ctrl - NumPad-) or (Ctrl - -) or (Ctrl - mouse wheel) - Decreases font size.
• (Ctrl - NumPad0) or (Ctrl - 0) - Restores font size to the size specified in Preferences.
Removing the Text Content of the Current Element

You can remove the text content of the current element and keep only the markup with the action Remove Text
available on the submenu Refactoring of the contextual menu and on the toolbar XML Refactoring. This is useful
when the markup of an element must be preserved, for example a table structure but the text content must be replaced.
Duplicating Elements with Existing IDs
If the Auto generate IDs for elements option is turned off and you duplicate elements with existing IDs, the duplicates
lose these IDs. If the previously mentioned option is active, when you duplicate content, Oxygen makes sure that if there
is an ID attribute set in the XML markup, the newly created duplicate has a new, unique ID attribute value. If you cut
and paste content, the moved element retains its ID.
Table Layout and Resizing
The support for editing data in tabular form can manage table width and column width specifications from the source
document. The specified widths will be considered when rendering the tables and when visually resizing them using
mouse drag gestures. These specifications are supported both in fixed and proportional dimensions. The predefined
Oxygen XML Author | Authoring in the Tagless Editor | 89

frameworks (DITA, DocBook and XHTML) already implement support for this feature. The layout of the tables from
these types of documents takes into account the table width and the column width specifications particular to them. The
tables and columns widths can be visually adjusted by dragging with the mouse their edges and the modifications will
be committed back into the source document.

Figure 55: Resizing a column in Oxygen Author editor

DocBook Table Layout

The DocBook table layout supports two models: CALS and HTML.
In the CALS model column widths can be specified by using the colwidth attribute of the associated colspec
element. The values can be fixed or proportional.

Figure 56: CALS table

XHTML Table Layout

The HTML table model accepts both table and column widths by using the width attribute of the table element and the
col element associated with each column. The values can be represented in fixed units, proportional units or percentages.

Figure 57: HTML table

DITA Table Layout

The DITA table layout accepts CALS tables and simple tables.
90 | Oxygen XML Author | Authoring in the Tagless Editor

The simple tables accept only relative column width specifications by using the relcolwidth attribute of the
simpletable element.

Figure 58: DITA simple table

Image Rendering
The Author editor and the output transformation process might render differently the images referenced in the XML
document, since they use different rendering engines. The following image formats are supported by default: GIF, JPEG,
PNG, SVG, BMP. To extend this support for other formats (like TIFF, JPEG 2000 or WBMP, for example) install the
Java Advanced Imaging (JAI) Image I/O Tools plug-in.
When an image cannot be rendered, Oxygen XML Author displays a warning message that contains the reason why this
is happening. Possible causes:
• the image is very large and you need to enable Show very large images option;
• the image format is not supported by default. It is recommended to install the Java Advanced Imaging Image I/O
Tools plug-in.

Scaling Images
Image dimension and scaling attributes are taken into account when an image is rendered. The following rules apply:
• if you specify only the width attribute of an image, the height of the image is proportionally applied;
• if you specify only the height attribute of an image, the width of the image is proportionally applied;
• if you specify width and height attributes of an image, both of them controls the rendered image;
• if you want to scale proportionally both the width and height of an image, use the scale attribute.
Installing Java Advanced Imaging Image I/O Tools plug-in
Follow this procedure:

1. Start Oxygen and open the Help > About dialog. Open the System properties tab and look for java.runtime.name
and java.home properties. Keep their values for later use.
2. Go to Java Advanced Imaging Image I/O page and download the kit corresponding to your operating system and
Java distribution (found in the java.runtime.name property).
3. Execute the installer. When the installation wizard displays the Choose Destination Location page, fill-in the
Destination Folder field with the value of the java.home property. Continue with the installation procedure and
follow the on-screen instructions.

Adding an Image
An image can be inserted in an XML document edited in Author mode with the following methods:
• The insert image actions from the predefined document types. The following document types have an insert image
action: DocBook 4, DocBook 5, DITA, TEI P4, TEI P5, XHTML.
• Drag an image from other application and drop it in the Author editor. If it is an image file, it is inserted as a reference
to the image file. For example, in a DITA topic the path of the image file is inserted as the value of the href attribute
in an image element:

<image href="../images/image_file.png"/>
If it is only an image part, first it is saved as a file using the file save dialog which is displayed automatically. After
saving the image to a file the file path is inserted at the drop position as specified above.
• Copy the image from other application and paste it in your document. The content inserted in the document is similar
with that added after dragging and dropping an image.
Oxygen XML Author | Authoring in the Tagless Editor | 91

Refreshing the Content

On occasion you may need to reload the content of the document from the disk or reapply the CSS. This can be performed
by using the Reload action.
For refreshing the content of the referred resources you can use the action Refresh references. However, this action
will not refresh the expanded external entities, to refresh those you will need to use the Reload action.

Validation and Error Presenting

Automatic validation as well as validate on request operations are available while editing documents in the Author
editor. A detailed description of the document validation process and its configuration is described in section Validating
Documents.

Figure 59: Error presenting in Oxygen Author editor

A fragment with a validation error or warning will be marked by underlining the error region with a red color. The same
will happen for a validation warning, only the color will be yellow instead of red.
• The top area - a success validation indicator that will turn green in case the validation succeeded or red otherwise.
• The middle area - the errors markers are depicted in red. The number of markers shown can be limited by modifying
the setting Window > Preferences > oXygen > Editor > Document checking > Maximum number of errors
reported per document .
Status messages from every validation action are logged into the Console view.

Whitespace Handling
There are several major aspects of white-space handling in the Oxygen Author editor which are important in the following
cases:
• when opening documents
• when switching from other editing mode to Author mode
• when saving documents in Author mode
• when switching from Author mode to another one
• Open documents - When deciding if the white-spaces from a text node are to be preserved, normalized or stripped,
the following rules apply:
• If the text node is inside an element context where the xml:space="preserve" is set then the white-spaces
are preserved.
92 | Oxygen XML Author | Authoring in the Tagless Editor

• If the CSS property white-space is set to pre for the node style then the white-spaces are preserved.
• If the text node contains other non-white-space characters then the white-spaces are normalized.
• If the text node contains only white-spaces:
• If the node has a parent element with the CSS display property set to inline then the white-spaces are
normalized.
• If the left or right sibling is an element with the CSS display property set to inline then the white-spaces
are normalized.
• If one of its ancestors is an element with the CSS display property set to table then the white-spaces
are striped.
• Otherwise the white-spaces are ignored.

• Save documents - The Author editor will try to format and indent the document while following the white-space
handling rules:
• If text nodes are inside an element context where the xml:space="preserve" is set then the white-spaces
are written without modifications.
• If the CSS property white-space is set to pre for the node style then the white-spaces are written without
any changes.
• In other cases the text nodes are wrapped.
Also, when formatting and indenting an element that is not in a space-preserve context, additional line separators
and white-spaces are added as follows:
• Before a text node that starts with a white-space.
• After a text node that ends with a white-space.
• Before and after CSS block nodes.
• If the current node has an ancestor that is a CSS table element.

• Editing documents - You can insert space characters in any text nodes. Line breaks are permitted only in
space-preserve elements. Tabs are marked in the space-preserve elements with a little marker.
Minimize Differences Between Versions Saved on Different Computers
The number of differences between versions of the same file saved by different content authors on different computers
can be minimized by imposing the same set of formatting options when saving the file, for all the content authors. An
example for a procedure that minimizes the differences is the following.

1. Create an Oxygen project file that will be shared by all content authors.
2. Set your own preferences in the following panels of the Preferences dialog: Editor / Format and Editor / Format
/ XML.
3. Save the preferences of these two panels in the Oxygen project by selecting the button Project Options in these two
panels.
4. Save the project and commit the project file to your versioning system so all the content authors can use it.
5. Make sure the project is opened in the Project view.
6. Open and save your XML files in the Author mode.
7. Commit the saved XML files to your versioning system.

When other content authors will change the files only the changed lines will be displayed in your diff tool instead of
one big change that does not allow to see the changes between two versions of the file.
Oxygen XML Author | Authoring in the Tagless Editor | 93

Review

Tracking Document Changes

Track Changes is a way to keep track of the changes you make to a document. You can activate change tracking for the
current document by choosing Edit > Review > Track Changes or by clicking the Track Changes button located on
the Author toolbar. When Track Changes is enabled your modifications will be highlighted using a distinctive color.
The name of the author who is currently making changes and the colors can be customized from the Review preferences
page.

Figure 60: Change Tracking in Oxygen Author

When hovering a change the tooltip will display information about the author and modification time.
If the selection in the Author contains track changes and you copy it the clipboard will contain the selection with all the
changes accepted. This filtering will happen only if the selection is not entirely inside a tracked change.
Tip: For each change the author name and the modification time are preserved. The changes are stored in the
document as processing instructions and they do not interfere with validating and transforming it.

Adding Comments into a Document

You can associate a note or a comment to a selected area of text content. Comments can highlight virtually any content
from your document, except read-only text. The difference between such comments and change tracking is that a
comment can be associated to an area of text without modifying or deleting the text.
The actions for managing comments are Add Comment..., Edit Comment..., Delete Comment... and Manage
Comments... and are available on the Author Comments toolbar and on the Review submenu of the contextual menu
of Author editor.
Comments are persistent highlights with a colored background. The background color is customizable or can be assigned
automatically by the application. This behaviour can be controlled from the Review options page.
94 | Oxygen XML Author | Authoring in the Tagless Editor

Managing Changes
You can review the changes made by you or other authors and then accept or reject them using the Track Changes

toolbar buttons or the similar actions from the Edit > Review menu.
• Track Changes - Enables or disables track changes support for the current document.
• Accept Change(s) - Accepts the change located at the caret position. If you select a part of a delete or insert change,
then only the selected content is accepted. If you select multiple changes, all of them are accepted. For an insert
change, it means keeping the inserted text and for a delete change it means removing the content from the document.
• Reject Change(s) - Rejects the change located at the caret position. If you select a part of a delete or insert change,
then only the selected content is rejected. If you select multiple changes, all of them are rejected. For an insert change,
it means removing the inserted text and for a delete change it means preserving the original content from the document.
• Comment Change - You can decide to add additional comments to an already existing change. The additional
description appears in the tooltip when hovering over the change and in the Manage Tracked Changes dialog when
navigating changes.
• Manage Tracked Changes - Action designed to find and manage all changes in the current document.

Figure 61: Manage Tracked Changes

The dialog offers the following actions:

• Next - Finds the next change in the document.
• Previous - Finds the previous change in the document.
• Accept - Accepts the current change. This action is also available on the contextual menu.
• Reject - Rejects the current change. This action is also available on the contextual menu.
• Accept All - Accepts all changes in the document.
• Reject All - Rejects all changes in the document.
The dialog is not modal and it is reconfigured after switching between the dialog and one of the opened editors.

Track Changes Visualization Modes

Three specialized actions allow you to switch between the following visualization modes:
• View All Changes - default visualization mode, all tracked changes are represented in the Author mode;
• View Final - previews the document as if all tracked changes (both inserted and deleted) were accepted;
• View Original - previews the document as if all tracked changes (both inserted and deleted) were rejected. You
cannot edit the document in this mode. Attempting to do so switches the view mode to View All Changes.
Oxygen XML Author | Authoring in the Tagless Editor | 95

Note: All three actions are available only in a drop-down list in the Track Changes toolbar.

Managing Comments
A comment is marked in Author editor with a background color which can be configured for each user name.

Figure 62: Manage Comments in Author Editor

You can manage comments using the following actions:

• Add Comment... - Allows you to insert a comment at the cursor position or on a specific selection of content.
The action is available on the Author page toolbar.
• Edit Comment... - Allows you to change an existing content. The action is available both on the Author page
toolbar and the contextual menu.
• Manage Comments... - Opens a dialog that allows you to manage all comments contained in the current
document. You can cycle through comments, edit, and remove individual comments or all comments. The action is
available on the Author page toolbar.
• Remove Comment(s)... - Removes the comment at the cursor position or all comments found in the selected
content. The action is available on the Author page contextual menu, Review sub-menu.

Profiling / Conditional Text

Create Profiling Attributes

Note: To ensure the validity of the document, the attribute must be already defined in the document DTD or schema
before referring it here.

To create custom profiling attributes for a specific document type, follow these steps:

1. Open the Profiling/Conditional Text preferences page from Window > Preferences > oXygen > Editor > Pages
> Author > Profiling / Conditional Text .
2. In the Profiling Attributes area, press the New button.
The following dialog is opened:

3. Fill-in the dialog as follows:

a) Choose the document type on which the profiling attribute is applied. * and ? are used as wildcards, while ,(comma
character) can be used to specify more patterns. For example use DITA* to match any document type name that
starts with DITA.
b) Set the attribute name.
c) Set a display name. This field is optional, being used only as a more descriptive rendering in application's profiling
dialogs.
d) Use the New, Edit, Delete buttons to add, edit and delete possible values of the attribute. Each attribute value
can have a description.
e) Choose whether the attribute accepts a single value (Single value option checked) or multiple values. Multiple
values can be separated by a default delimiter (space, comma, semicolon), or a custom one.
4. Click OK.
5. Click Apply to save the profiling attribute.

Create Profiling Condition Sets

Several profiling attributes can be aggregated into a profiling condition set that allow apply more complex filters on the
document content. A Profiling Condition Set is a very powerful and convenient tool used to preview the content that
goes into the published output. For example, an installation manual available both in Windows and Linux variants can
be profiled to highlight only the Linux procedures for more advanced users.
To create a new profiling condition set:
Oxygen XML Author | Authoring in the Tagless Editor | 97

1. Open the Profiling/Conditional Text preferences page from Window > Preferences > oXygen > Editor > Pages
> Author > Profiling / Conditional Text .
2. In the Profiling Condition Sets area, press the New button.
The following dialog is opened:

3. Fill-in the dialog as follows:

a) Type the condition set's name.
b) Choose the document type for which you have previously defined profiling attributes.
After choosing a document type, all profiling attributes and their possible values are listed in the central area of
the dialog.
c) Define the combination of attribute values by ticking the appropriate checkboxes.
4. Click OK.
5. Click Apply to save the condition set. All saved profiling condition sets are available in the Profiling / Conditional
Text toolbar menu.

Apply Profiling Condition Sets

All defined Profiling Condition Sets are available as shortcuts in the Profiling / Conditional Text menu. Just click on a
menu entry to apply the condition set. The filtered content is grayed-out.
An element is filtered-out when one of its attributes is part of the condition set and its value does not match any of the
value covered by the condition set.
As an example, let us suppose that you have the following document:
98 | Oxygen XML Author | Authoring in the Tagless Editor

If you apply the following condition set it means that you want to filter-out the content written for non-expert audience
and having the Other attribute value different than prop1.

And this is how the document looks like after you apply the Expert user condition set:
Oxygen XML Author | Authoring in the Tagless Editor | 99

Apply Profiling Attributes

Profiling attributes are applied on element nodes.
To set a profiling attribute:

1. Invoke the application's contextual menu. Click the Edit Profiling Attributes... action.
The displayed dialog shows all profiling attributes and their values, defined on the document type of the edited
content.
2. In the Edit Profiling Attributes dialog, tick the checkboxes corresponding to attribute values you want to apply on
the current element.
3. If Show Profiling Attributes option (available in the Profiling / Conditional Text toolbar menu) is set, a light
green border is painted around profiled text, in the Author page. Also, all profiling attributes set on the current
element are listed at the end of the highlighted block and in its tooltip message.

Profiling / Conditional Text Menu

The Profiling / Conditional Text toolbar menu groups the following actions:
• Show Profiling Attributes - Enable this option to turn on conditional text markers. They are displayed at the end
of conditional text block, as a list of attribute name and their currently set values.
• The list of all profiling condition sets that match the current document type. Click on a condition set entry to activate
it.
• Configure Profiling Condition Sets... - Link to the Profiling / Conditional Text preference page, where you
can manage profiling attributes and profiling condition sets.
Chapter
6
Author for DITA
Topics: This chapter presents the Author features that are specific for editing DITA
XML documents.
• Creating DITA Maps and Topics
• Editing DITA Maps
• Transforming DITA Maps and
Topics
• DITA-OT Customization
• DITA Specialization Support
• Use a New DITA Open Toolkit in
Oxygen
• Reusing Content
• DITA Profiling / Conditional Text
• Working with MathML
102 | Oxygen XML Author | Author for DITA

Creating DITA Maps and Topics

The basic building block for DITA information is the DITA topic. DITA provides the following topic types:
• Concept - For general, conceptual information such as a description of a product or feature.
• Task - For procedural information such as how to use a dialog.
• Reference - For reference information.
You can organize topics into a DITA map or bookmap. A map is a hierarchy of topics. A bookmap supports also book
divisions such as chapters and book lists such as indexes. Maps do not contain the content of topics, but only references
to them. These are known as topic references. Usually the maps and bookmaps are saved on disk or in a CMS with the
extension '.ditamap'.
Maps can also contain relationship tables that establish relationships between the topics contained within the map.
Relationship tables are also used to generate links in your published document.
You can use your map or bookmap to generate a deliverable using an output type such as XHTML, PDF, HTML Help
or Eclipse Help.

Editing DITA Maps

Oxygen provides a special view for editing DITA maps. The DITA Maps Manager view presents a map in a simplified
table-of-contents manner allowing the user to navigate easily to the referred topics and maps, make changes and perform
transformations to various output formats using the DITA-OT framework bundled with Oxygen.

Figure 63: The DITA Maps Manager View

You can open a map file from Project in the DITA Maps Manager view by right clicking it and choosing Open in
DITA Maps Manager. The titles of the referenced resources are resolved and displayed in the view dynamically when
Oxygen XML Author | Author for DITA | 103

navigating the tree. After the map is opened in the view, you can open it in the main editor for further customization
using the Open map in editor toolbar action.
The toolbar includes the actions which are also available on menu DITA Maps:
•
Open - Allows opening the map in the DITA Maps Manager view. You can also open a map by dragging it
in the DITA Maps Manager view from the file system explorer.
• Open URL - Allows opening remote maps in the DITA Maps Manager view. See Open URL for details.
• Save (Ctrl+S) - Saves the current DITA map.
• Validate and Check for Completeness - Checks the validity and integrity of the map.
• Apply Transformation Scenario - Applies the DITA map transformation scenario that is associated with the
current map from the view.
• Configure Transformation Scenario - Allows associating a DITA map transformation scenario with the current
map.
• Refresh References - You can use this action to manually trigger a refresh and update of all titles of referred
topics. This action is useful when the referred topics are modified externally. When they are modified and saved
from the Oxygen Author, the DITA Map is updated automatically.
• Open Map in Editor with Resolved Topics - Opens the result of expanding all topic references in Author editor.
• Open Map in Editor - For complex operations which cannot be performed in the simplified DITA maps view
(like editing a relationship table) you can open the map in the main editing area.
• Link with Editor - Disables/Enables the synchronization between the file path of the current editor and the
selected topic reference in the DITA Maps Manager view.
• Profiling/Conditional Text menu with the following actions:
• Show Profiling Attributes - Enables/Disables displaying the values of the profiling attributes at the end of the
titles of topic references. When enabled, the values of the profiling attributes are displayed both in the DITA
Maps Manager view and in the Author editor.
• Configure Profiling Condition Sets ... - Opens the preferences panel for adding and editing the profiling
conditions that can be applied in the DITA Maps Manager view and the Author editor.

Tip: If your map references other DITA maps they will be shown expanded in the DITA Maps tree and you will
also be able to navigate their content. For editing you will have to open each referenced map in a separate editor.
You can choose not to expand referenced maps in the DITA Maps Manager view or referenced content in the
opened editors by unchecking the Display referred content checkbox available in the Author preferences page.

Tip: The additional edit toolbar can be shown by clicking the "Show/Hide additional toolbar" expand button located
on the general toolbar.

The following edit actions can be performed on an opened DITA Map:

• Insert Reference - Inserts a reference to a topic file. You can find more details about this action in the Inserting
a Reference, a Key Definition, a Topic Set topic.
• Insert Topic Heading - Inserts a topic heading. You can find more details about this action in the Inserting a
Topic Heading topic.
• Insert Topic Group - Inserts a topic group. You can find more details about this action in the Inserting a Topic
Group on page 110 topic.
• Edit Properties - Edit the properties of a selected node. You can find more details about this action in the Edit
Properties on page 111 topic.
• Edit Profiling Attributes - Allows you to select the profiling attributes.
• Edit Attributes - Allows you to edit all the attributes of a selected node. You can find more details about this
action in the Attributes View on page 79 topic.
104 | Oxygen XML Author | Author for DITA

• Delete - Deletes the selected node.

• Move Up (Alt + Up) - Moves the selected nodes in front of their respective previous siblings.
• Move Down (Alt + Down) - Moves the selected nodes after their next respective siblings.
• Promote (Alt + Left) - Moves the selected nodes after their respective parents as a siblings.
• Demote (Alt + Right) - Moves the selected nodes as children to their respective previous siblings.

Editing Actions
Important: References can be made either by using the href attribute or by using the new keyref attribute to
point to a key defined in the map. Oxygen tries to resolve both cases. keyrefs are solved relative to the current
map.

The contextual menu contains, in addition to the edit actions described above, the following actions:
• Open in Editor - Opens in the editor the resources referred by the selected nodes.
• Append Child/Insert After - Sub-menus containing the following actions:
• Reference - Appends/Inserts a topic reference as a child/sibling of the selected node.
• Reference to the current edited file - Appends/Inserts a topic reference to the current edited file as a child/sibling
of the selected node.
• New topic - Create a new topic from templates, saves it on disk and adds it into the DITA map.
• Anchor Reference, Key Definition, Map Reference, Topic Reference, Topic Set, Topic Set Reference -
Allows you to insert a reference to a topic file, a map file, a topic set, or a key definition.
• Topic heading - Appends/Inserts a topic heading as a child/sibling of the selected node.
• Topic group - Appends/Inserts a topic group as a child/sibling of the selected node.

• Check Spelling in Files - Checks the spelling of the files in the scope of the current edited map.
• Open Map in Editor with resolved topics - Opens the map in the main editing area with all the topic references
expanded in the map content.
• Cut, Copy, Paste, Undo, Redo - Common edit actions with the same functionality as those found in the text editor.
• Paste Before, Paste After - Pastes the content of the clipboard before, respectively after, the selected node.
You can also arrange the nodes by dragging and dropping one or more nodes at a time. Drop operations can be performed
before, after or as child of the targeted node. The relative location of the drop is indicated while hovering the mouse
over a node before releasing the mouse button for the drop.
Drag and drop operations allow you to:
• Copy - Select the nodes you want to copy and start dragging them. Before dropping them in the appropriate place,
press and hold the (Ctrl) key ( (Meta) key on Mac). The mouse pointer changes to indicate that a copy operation
is performed.
• Move - Select the nodes you want to move and drag and drop them in the appropriate place.
• Promote Alt+Left Arrow / Demote Alt+Right Arrow - You can move nodes between child and parent nodes which
ensures both PromoteAlt+Left Arrow and DemoteAlt+Right Arrow operations.
Tip:
You can open and edit linked topics easily by double clicking the references or by right-clicking and choosing
Open in editor. If the referenced file does not exist you are allowed to create it.
By right clicking the map root element you can open and edit it in the main editor area for more complex operations.
You can decide to open the reference directly in the Author page and keep this setting as a default.
Oxygen XML Author | Author for DITA | 105

Creating a Map
Here are the steps to create a DITA map are the following:

1. Go to menu File > New or click on the New toolbar button.

2. Select one of the DITA Map templates on the tab From templates of the New dialog.
3. Click the OK button.
A new tab is added in the DITA Maps Manager view.
4.
Press the Save button on the toolbar of the DITA Maps Manager view.
5. Select a location and a file name for the map in the Save As dialog.

Validating DITA Maps

The validation of DITA maps is done with the action Validate and Check for Completeness that is available on
the DITA Maps Manager view toolbar and on the DITA Maps menu.

Figure 64: DITA Map Completeness Check

The validation process does the following:

• Checks the file paths of the topic references. If a href attribute points to an invalid file path it is reported as a
separate error in the Errors view.
• Validate each referred topic and map. Each topic file is opened and validated against the appropriate DITA DTD. If
other map is referred in the main map, it is checked recursively applying the same algorithm as for the main map.
You can customize the operation setting the following options:
• Check the existence of non-DITA references resources - extends the validation of referred resources to non-DITA
files. You can also choose to include in the validation also the remote resources;
• Use DITAVAL file - profiling conditions are applied. First the content of the map is filtered by applying a profiling
condition set. The condition set can be either the one applied currently in the DITA Maps Manager view (the radio
button From the current condition set) or the one specified explicitly as a DITAVAL file in the current transformation
106 | Oxygen XML Author | Author for DITA

scenario associated with the DITA map (the radio button From the associated transformation scenario). If a link
is invalid in the content that resulted from the filtering process then it is reported as error.
• Check for duplicate element IDs within a topic - if an ID is duplicated after assembling all topics referred in the
map, it is reported as error.
• Report links to topics not referenced in DITA Maps - checks that all referred topics are linked in the DITA map.
• Identify possible conflicts in profile attribute values - when a topic's profiling attributes contain values that are
not found in parent topics profiling attributes, the content of the topic is overshadowed when generating profiled
output. This option reports such possible conflicts.
• Report attributes and values that conflict with profiling preferences - looks for profiling attributes and values
not defined in the Profiling / Conditional Text preferences page. It also checks if profiling attributes defined as
single-value have multiple values set in the searched topics.

Create a Topic in a Map

You add a new topic to a DITA map with the following steps:

1. Run the action Insert Topic Reference in the view DITA Maps Manager.
The action Insert Topic Reference is available on the toolbar and on the contextual menu of the view. The action
is available both on the submenu Append Child (when you want to insert a topic reference in a map as a child of
the current topic reference) and on the submenu Insert After (when you want to insert it as a sibling of the current
topic reference). The toolbar action is the same as the action from the submenu Insert After.
2. Select a topic file in the file system dialog called Insert Topic Reference.
3. Press the Insert button or the Insert and close button in the dialog.
A reference to the selected topic is added to the current map in the view.
4. If you clicked the Insert button you can continue inserting new topic references using the Insert button repeatedly
in the same file system dialog.
5. Close the dialog using the Close button.

Organize Topics in a Map

You can understand better how to organize topics in a DITA map by working with a populated map. You should open
the sample map called flowers.ditamap, located in the samples/dita folder.

1. Open the file flowers.ditamap.

2. Select the topic reference Summer Flowers and press the Move Down button to change the order of the topic
references Summer Flowers and Autumn Flowers.
3. Make sure that Summer Flowers is selected and press the Demote button. This topic reference and all the nested
ones are moved as a unit inside the Autumn Flowers topic reference.
4. Close the map without saving.

Create a Bookmap
The procedure for creating a bookmap is similar with that for creating a map.

1. Go to menu File > New or click on the New toolbar button.

This action will open the New wizard.
2. Select the DITA Map - Bookmap template.
3. Click the OK button.
A new tab with the new bookmap is added in the DITA Maps Manager view.
4.
Press the Save button on the toolbar of the DITA Maps Manager view.
Oxygen XML Author | Author for DITA | 107

5. In the Save As dialog select a location and a file name for the map.

Create a Subject Scheme

The procedure for creating a DITA subject scheme is similar with that for creating a map.

1. Go to menu File > New or click on the New toolbar button.

This action will open the New wizard.
2. Select the DITA Map - Subject Scheme template.
3. Click the OK button.
A new tab with the new subject scheme document is added in the DITA Maps Manager view.
4.
Press the Save button on the toolbar of the DITA Maps Manager view.
5. In the Save As dialog select a location and a file name for the map.

Create Relationships Between Topics

The DITA map offers the possibility of grouping different types of links between topics in a relationship table instead
of specifying the links of each topic in that topic.

1. Open the DITA map file where you want to create the relationship table.

Use the action Open that is available on the toolbar of the DITA Maps Manager view.
2. Place the cursor at the location of the relationship table.
3. Run the action Insert a DITA reltable.
The action is available on the Author toolbar, on the menu DITA > Table and on the Table submenu of the
contextual menu of the DITA map editor.
This action displays the Insert Relationship Table dialog.
4. Set the parameters of the relationship table that will be created: the number of rows, the number of columns, a table
title (optional), a table header (optional).
5. Press OK in the Insert Table dialog.
6. Set the type of the topics in the header of each column.
The header of the table (the relheader element) already contains a relcolspec element for each table column.
You should set the value of the attribute type of each relcolspec element to a value like concept, task, reference.
When you click in the header cell of a column (that is a relcolspec element) you can see all the attributes of that
relcolspec element including the type attribute in the Attributes view. You can edit the attribute type in this
view.
7. Place the cursor in a table cell and run the action Insert Topic Reference for inserting a topic reference in that
cell.
The action is available on the Author toolbar, on the menu DITA > Insert and on the Insert submenu of the
contextual menu.
8. Optionally for adding a new row to the table / removing an existing row you should run the action Insert Row/
Delete Row.
The actions are available on the Author toolbar, on the menu DITA > Table and on the Table submenu of the
contextual menu.
9. Optionally for adding a new column to the table / removing an existing column you should run the action Insert
Column/ Delete Column.
108 | Oxygen XML Author | Author for DITA

The actions are available on the Author toolbar, on the menu DITA > Table and on the Table submenu of the
contextual menu.

Advanced Operations
This section explains how to insert references like chapter, topic reference, topic group or topic heading in a DITA map.

Inserting a Reference, a Key Definition, a Topic Set

A DITA map can contain various types of references. The targets of the references can be:
• an anchor
• a map
• a topic
• a topic set
The topicref element is a reference to a topic (such as a concept, task, or reference) or other resource. A topicref
can contain other topicref elements, and allows you to express navigation or table-of-contents hierarchies, as well
as implying relationships between the containing topicref and its children. You can set the collection type of a
container topicref to determine how its children are related to each other. You can also express relationships among
topicref's using group and table structures (using topicgroup and reltable). Relationships end up expressed
as links in the output (with each participant in a relationship having links to the other participants by default).
A reference to a topic file, a map file, a topic set, or a key definition may be inserted with the following dialog box which
is opened from the actions of the Append child and Insert after submenus of the DITA Maps Manager view's contextual
menu. The content of the Append child and Insert after submenus depend on the selected node of the DITA map tree
on which the contextual menu was invoked. For example if the selected node is the bookmap root node the possible
child nodes are:
• chapter (the chapter element),
• part (the part element),
• appendix (the appendix element),
• appendices (the appendices element)
If the selected node is a topicref the possible child nodes are:
• anchor reference (the anchorref element),
• topic reference (the topicref element),
• map reference (the mapref element),
• topic set reference (the topicsetref element),
• topic set (the topicset element),
• key definition (the keydef element),
• topic head (the topichead element),
• topic group (the topicgroup element)
The same dialog box can be used to insert a non-DITA file like a PDF document.
Oxygen XML Author | Author for DITA | 109

Figure 65: Insert Topic Reference Dialog

By using the Insert Topic Reference dialog you can easily browse for and select the source topic file. The Target
combo box shows all available topics that can be targeted in the file. Selecting a target modifies the Href value to point
to it which corresponds to the href attribute of the inserted topicref element. The Format and Scope combos are
automatically filled based on the selected file and correspond to the format and scope attributes of the inserted
topicref element. You can specify and enforce a custom navigation title by checking the Navigation title checkbox
and entering the desired title.
The file chooser located in the dialog allows you to easily select the desired topic. The selected topic file will be added
as a child or sibling of the current selected topic reference, depending on the insert action selected from the contextual
menu of the DITA Maps view, that is an insert action from the Append child submenu or from the Insert after one.
You can easily insert multiple topic references by keeping the dialog opened and changing the selection in the DITA
Maps Manager tree. You can also select multiple resources in the file explorer and then insert them all as topic references.
Another easy way to insert a topic reference is to drag files from the Project view, file system explorer or Data Source
Explorer view and drop them into the map tree.
You can also define keys using the Keys text field on the inserted topicref or keydef element. Instead of using
the Href combo box to point to a location you can reference a key definition using the Keyref text field.
The Processing Role combo box allows setting the processing-role attribute to one of the allowed values for
DITA reference elements: resource-only, normal, -dita-use-conref-target.

Inserting a Topic Heading

The topichead element provides a title-only entry in a navigation map, as an alternative to the fully-linked title
provided by the topicref element.
110 | Oxygen XML Author | Author for DITA

A topic heading can be inserted both from the toolbar action and the contextual node actions.

Figure 66: Insert Topic Heading Dialog

By using the Insert Topic Heading dialog you can easily insert a topichead element. The Navigation title is required
but other attributes can be specified as well from the dialog.

Inserting a Topic Group

The topicgroup element identifies a group of topics (such as a concepts, tasks, or references) or other resources. A
topicgroup can contain other topicgroup elements, allowing you to express navigation or table-of-contents hierarchies,
as well as implying relationships between the containing topicgroup and its children. You can set the collection-type of
a container topicgroup to determine how its children are related to each other. Relationships end up expressed as links
in the output (with each participant in a relationship having links to the other participants by default).
A topic group may be inserted both from the toolbar action and the contextual node actions.

Figure 67: Insert Topic Group Dialog

By using the Insert Topic Group dialog you can easily insert a topicgroup element. The Type, Format, Scope and
Collection type attributes can be specified from the dialog.
Oxygen XML Author | Author for DITA | 111

Edit Properties
The Edit properties action, available both on the toolbar and on the contextual menu, is used to edit the properties of
the selected node. Depending on the selected node, the action will perform the following tasks:
• If a topicref or chapter element is selected, the action will show a dialog similar with the Insert Topic Reference
dialog allowing the editing of some important attributes.
• If a topichead element is selected, the action will show a dialog similar with the Insert Topic Heading dialog allowing
the editing of some important attributes.
• If a topicgroup element is selected, the action will show a dialog similar with the Insert Topic Group dialog allowing
the editing of some important attributes.
• If the map's root element is selected then the user will be able to easily edit the map's title using the Edit Map title
dialog. By using this dialog you can also specify whether the title will be specified as the title attribute to the map
or as a title element (for DITA-OT 1.1 and 1.2) or specified in both locations.

Transforming DITA Maps and Topics

Oxygen uses the DITA Open Toolkit (DITA-OT) to transform DITA maps and topics into an output format. For this
purpose both the DITA Open Toolkit 1.5.2 and ANT 1.7 come bundled in Oxygen.
More information about the DITA Open Toolkit are available at http://dita-ot.sourceforge.net/.

Available Output Formats

You can publish DITA-based documents in any of the following formats:
• PDF - DITA to PDF using the DITA OT IDIOM PDF plugin.
• WebHelp - DITA to XHTML.
• XHTML - DITA to XHTML.
• Compiled HTML Help (CHM) - DITA Map to HTML Help. If HTML Help Workshop is installed on your computer,
then Oxygen detects it and uses it to perform the transformation. When the transformation fails, the hhp (HTML
Help Project) file is already generated and it must be compiled to obtain the .chm file. Note that HTML Help Workshop
fails when the files used for transformation contain diacritics in their names, due to different encodings used when
writing the .hhp and .hhc files.
• JavaHelp - DITA Map to JavaHelp.
• Eclipse Help - DITA Map to Eclipse Help.
• Eclipse Content - DITA Map to Eclipse Content.
• TocJS - A JavaScript file that can be included in an HTML file to display in a tree-like manner the table of contents
of the transformed DITA map.
• Open Document Format - DITA Map to ODF.
• Docbook - DITA Map to Docbook.
• RTF - DITA Map to Rich Text Format.
• troff - DITA Map to Text Processor for Typesetters.
• Legacy PDF - DITA Map to PDF using the DITA OT deprecated PDF implementation.

The TocJS Transformation

The TocJS transformation of a DITA map does not generate all the files needed to display the tree-like table of contents.
To get a complete working set of output files you should follow these steps:

1. Run the XHTML transformation on the same DITA map. Make sure the output gets generated in the same output
folder as for the TocJS transformation.
112 | Oxygen XML Author | Author for DITA

2. Copy the content of ${frameworks}/dita/DITA-OT/demo/tocjs/basefiles folder in the transformation's

output folder.
3. Copy the ${frameworks}/dita/DITA-OT/demo/tocjs/sample/basefiles/frameset.html file
in the transformation's output folder.
4. Edit frameset.html file.
5. Locate element <frame name="contentwin" src="concepts/about.html">.
6. Replace "concepts/about.html" with "index.html".

WebHelp Output Format

WebHelp is a form of online help consisting of a series of web pages (XHTML format). Its advantages include continuous
content update and platform independence, since it can be viewed using a regular web browser.
Oxygen allows you to publish a DITA Map into a WebHelp format that provides both Table of Contents and advanced
search capabilities.

Figure 68: WebHelp Output

The layout is composed of two frames:

• left frame, containing separate tabs for Table of Contents and Search;
• central frame where help pages are displayed.
To publish the DITA map to WebHelp, you can use the DITA Map WebHelp transformation. You can further customize
the out-of-the-box transformation, by editing some of its parameters:
• args.xhtml.toc - name of the table of contents file. Default setting is toc.html;
• use.stemming - controls whether or not you want to include stemming search algorithms into the published
output. Stemming is the process for reducing inflected (or sometimes derived) words to their stem, base or root
form – generally a written word form. Default setting is false.
• clean.output - deletes all files from the output folder before the transformation is performed. Default setting is
no.
The Search tab is enhanced with a rating mechanism that computes scores for every page that matches the search criteria.
These scores are then translated into a 5-star rating scheme. The search results are sorted depending on:
• number of keywords found in a single page. The higher the number, the better.
Oxygen XML Author | Author for DITA | 113

• context - if a word is found in a title or emphasised section of text it scores better than a word found in a unformatted
text.

Figure 69: WebHelp Search with Stemming Enabled

Rules applied during search:

• keywords are separated by the space character. An expression like spray painting counts as two separate keywords:
spray and painting.
• do not use quotes to perform exact search for multiple-word expressions. An expression like "spray painting", returns
no results in our case, because it searches for two separate words: "spray and painting" (note the quote signs attached
to each word).

Configuring a DITA Transformation

Creating map transformation scenarios is similar to creating scenarios in the main editing area.

The Configure Transformation Scenario dialog is opened from the toolbar action Configure Transformation
Scenario of the DITA Maps Manager view. Select as scenario type DITA OT transformation then press the New
button. Next step involves choosing the type of output the DITA-OT ANT scenario will generate:
114 | Oxygen XML Author | Author for DITA

Figure 70: Select DITA Transformation type

Depending on the chosen type of output Oxygen generates values for the default ANT parameters so that you can execute
the scenario right away without further customization.

Running a DITA Map ANT Transformation

The transformation is run as an external ANT process so you can continue using the application as the transformation
unfolds. All output from the process appears in the DITA Transformation tab.
Tip: The HTTP proxy settings from Oxygen are also used for the ANT transformation so if the transformation
fails because it cannot connect to an external location you can check the HTTP/Proxy Configuration.

Customizing a DITA Scenario

This section explains how to edit the parameters of a DITA transformation in the dialog box for configuring such a
transformation.

The Parameters Tab

In the scenario Parameters tab you can customize all the parameters which will be sent to the DITA-OT build file.
Oxygen XML Author | Author for DITA | 115

Figure 71: Edit DITA Ant transformation parameters

All the parameters that the DITA-OT documentation specifies as available for each chosen type of transformation (eg:
XHTML) are listed along with their description. The values for some important parameters are already filled in. You
can find more information about each parameter in the DITA OT Documentation. You can also add additional parameters
to the list.
Using the toolbar buttons you can add, edit or remove a parameter.
Depending on the parameter type the parameter value will be:
• a simple text field for simple parameter values
• a combo box with some predefined values
• a file chooser and an editor variables selector to simplify setting a file path as value to a parameter
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 Filters Tab

In the scenario Filters tab you can add filters to remove certain content elements from the generated output.
116 | Oxygen XML Author | Author for DITA

Figure 72: Edit Filters tab

You have two ways in which to define filters:

• Use DITAVAL file - If you already have a DITAVAL file associated with the transformed map you can specify the
path to it and it will be used when filtering content. You can find out more about constructing a DITAVAL file in
the DITA OT Documentation.
• Exclude from output all elements with any of the following attributes - You can configure a simple list of attribute
(name, value) pairs which when present on an element in the input will remove it from output.

The Advanced Tab

In the Advanced tab, you can specify advanced options for the transformation.
Oxygen XML Author | Author for DITA | 117

Figure 73: Advanced settings tab

You have several parameters that you can specify here:

• Custom build file - If you use a custom DITA-OT build file you can specify the path to the customized build file.
If empty, the build.xml file from the dita.dir directory configured in the Parameters tab is used.
• Build target - You can specify a build target to the build file. By default no target is necessary and the default init
target is used.
• Additional arguments - You can specify additional command-line arguments to be passed to the ANT transformation
like -verbose.
• Ant Home - You can specify a custom ANT installation to run the DITA Map transformation. By default it is the
ANT installation bundled with Oxygen.
• Java Home - You can specify a custom Java Virtual Machine to run the ANT transformation. By default it is the
Java Virtual Machine used by Oxygen.
• JVM Arguments - This parameter allows you to set specific parameters to the Java Virtual Machine used by ANT.
By default it is set to -Xmx256m which means the transformation process is allowed to use 256 megabytes of memory.
Sometimes, when performing a large DITA map transformation you may want to increase the memory allocated to
the Java Virtual Machine from the default value (256 MB) to a higher value, like 512 MB. In this way, you can avoid
the Out of Memory error messages received from the ANT process.
Note: If you are publishing DITA to PDF and still experience problems, you should also increase the amount
of memory allocated to the FO transformer. To do this, open the Parameters tab and increase the value of
maxJavaMemory parameter (default value is 500).

• Libraries - Oxygen adds by default as high priority libraries which are not transformation-dependent and also patches
for certain DITA Open Toolkit bugs. You can specify all the additional libraries (jar files or additional class paths)
which are used by the ANT transformer. You can also decide to control all libraries added to the classpath.
118 | Oxygen XML Author | Author for DITA

The Output Tab

In the Output tab you can configure options related to the place where the output will be generated.

Figure 74: Output settings tab

You have several parameters that you can specify here:

• Base directory - All the relative paths which appear as values in parameters are considered relative to the base
directory. The default value is the directory where the transformed map is located.
• Temporary files directory - This directory will be used to store pre-processed temporary files until the final output
is obtained.
• Output folder - The folder where the final output content will be copied.
• Output file options - The transformation output can then be opened in a browser or even in the editor if specified.

The FO Processor Tab

This tab appears only when selecting to generate PDF output using the IDIOM FO Plugin and allows you to choose the
FO Processor.
Oxygen XML Author | Author for DITA | 119

Figure 75: FO Processor configuration tab

You can choose between three processors:

• Apache FOP - This processor comes bundled with Oxygen.
• XEP - The RenderX XEP processor.
If you select XEP in the combo and XEP was already installed in Oxygen you can see the detected installation path
appear under the combo.
XEP is considered as installed if it was detected from one of the following sources:
• XEP was added as an external FO Processor in the Oxygen preferences.
• The system property com.oxygenxml.xep.location was set to point to the XEP executable file for the platform
(eg: xep.bat on Windows).
• XEP was installed in the frameworks/dita/DITA-OT/demo/fo/lib directory of the Oxygen installation
directory.

• Antenna House - The Antenna House AH (v5) or XSL (v4) Formatter processor.
If you select Antenna House in the combo and Antenna House was already installed in Oxygen you can see the
detected installation path appear under the combo.
Antenna House is considered as installed if it was detected from one of the following sources:
• Environment variable set by Antenna House installation (the newest installation version will be used, v5 being
preferred over v4).
• Antenna House was added as an external FO Processor in the Oxygen preferences.

Tip: The DITA-OT contributors recommend the use of the IDIOM FO Plugin to transform DITA Maps to PDF
as opposed to using the standard PDF target in the DITA-OT framework. As IDIOM is also bundled with Oxygen
the PDF2 - IDIOM FO Plugin output format should be your first choice in transforming your map to PDF. If you
do not have a commercial license for XEP or Antenna House you can transform using the Apache FO Processor.
120 | Oxygen XML Author | Author for DITA

Set a Font for PDF Output Generated with Apache FOP

When a DITA map is transformed to PDF using the Apache FOP processor and 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.
The settings that must be modified for configuring a font for the Apache FOP processor are detailed in this section.

DITA-OT Customization
This section explains how to customize specific parameters of a DITA transformation scenario like setting a custom
DITA Open Toolkit, a custom build file or a separate installation of the Ant tool.

Support for Transformation Customizations

You can change all DITA transformation parameters to customize your needs. In addition, you can specify a custom
build file, parameters to the JVM and many more for the transformation.

Using Your Custom Build File

You can specify a custom build file to be used in DITA-OT transformations by editing the transformation scenario that
you are using. In the Advanced tab you should change the Custom build file path to point to the custom build file.

Customizing the Oxygen Ant Tool

The Ant 1.7 tool which comes with Oxygen is located in the [Oxygen-install-folder]/tools/ant directory.
Any additional libraries for Ant must be copied to the Oxygen Ant lib directory.
If you are using Java 1.6 to run Oxygen the Ant tool should need no additional libraries to process JavaScript in build
files.
If you are using Java 1.5 you have to copy the bsf.jar and js.jar libraries in the
[Oxygen-install-folder]/tools/ant directory.

Upgrading to a New Version of DITA OT

The DITA OT framework bundled in Oxygen is located in the
[Oxygen-install-folder]/frameworks/dita/DITA-OT folder.
Important: There are a couple of modifications made to the DITA OT framework which will be overwritten if
you choose to copy the new DITA-OT version over the bundled one:
• The DTD's in the framework have been enriched with documentation for each element. If you overwrite you
will lose the documentation which is usually shown when hovering an element or in the Model view.
• Several build files from the IDIOM plugin have been modified to allow transformation using the Oxygen Apache
built-in FOP libraries and usage of the Oxygen classpath while transforming.
• Oxygen provides Java patches for some DITA OT problems. These patches are located in the
[Oxygen-install-folder]/frameworks/dita/DITA-OT/lib/dost-patches.jar library.
If the patches library conflicts with the new DITA OT libraries it either has to be removed from disk or removed
from the libraries list available in the DITA Map transformation scenario.
Oxygen XML Author | Author for DITA | 121

Increasing the Memory for the Ant Process

For details about setting custom JVM arguments to the ANT process please see this section.

Resolving Topic References Through an XML Catalog

There are situations where you want to resolve URIs with an XML catalog:
• you customized your DITA map to refer topics using URI's instead of local paths
• you have URI content references in your DITA topic files and you want to map them to local files when the map is
transformed
In such situations you have to add the catalog to Oxygen. The DITA Maps Manager view will solve the displayed
topic refs through the added XML catalog and also the DITA map transformations (for PDF output, for XHTML output,
etc) will solve the URI references through the added XML catalog.

DITA Specialization Support

This section explains how you can integrate and edit a DITA specialization in Oxygen XML Author.

Integration of a DITA Specialization

A DITA specialization includes:
• DTD definitions for new elements as extensions of existing DITA elements
• optionally specialized processing, that is new XSLT template rules that match the extension part of the class
attribute values of the new elements and thus extend the default processing available in DITA Open Toolkit
A specialization can be integrated in Oxygen XML Author with minimum effort.
If the DTD's that define the extension elements are located in a folder outside the DITA Open Toolkit folder you should
add new rules to the DITA OT catalog file for resolving the DTD references from the DITA files that use the specialized
elements to that folder. This allows correct resolution of DTD references to your local DTD files and is needed for both
validation and transformation of the DITA maps or topics. The DITA OT catalog file is called catalog-dita.xml
and is located in the root folder of the DITA Open Toolkit.
If there is specialized processing provided by XSLT stylesheets that override the default stylesheets from DITA OT
these new stylesheets must be called from the Ant build scripts of DITA OT.
Important: If you are using DITA specialization elements in your DITA files it is recommended that you activate
the Enable DTD processing in document type detection checkbox in the Document Type Association page.

Editing DITA Map Specializations

In addition to recognizing the default DITA map formats: map and bookmap the DITA Maps Manager view can also
be used to open and edit specializations of DITA Maps.
All advanced edit actions available for the map like insertion of topic refs, heads, properties editing, allow the user to
specify the element in an editable combo box. Moreover the elements which appear initially in the combo are all the
elements which are allowed to appear at the insert position for the given specialization.
The topic titles rendered in the DITA Maps Manager view are collected from the target files by matching the class
attribute and not a specific element name.
When editing DITA specializations of maps in the main editor the insertions of topic reference, topic heading, topic
group and conref actions should work without modification. For the table actions you have to modify each action by
122 | Oxygen XML Author | Author for DITA

hand to insert the correct element name at caret position. You can go to the DITA Map document type from the Document
Type Association page and edit the table actions to insert the element names as specified in your specialization. See this
section for more details.

Editing DITA Topic Specializations

In addition to recognizing the default DITA topic formats: topic, task, concept, reference and composite,
topic specializations can also be edited in the Author page.
The content completion should work without additional modifications and you can choose the tags which are allowed
at the caret position.
The CSS styles in which the elements are rendered should also work on the specialized topics without additional
modifications.
The toolbar/menu actions should be customized to insert the correct element names if this is the case. You can go to the
DITA document type from the Document Type Association page and edit the actions to insert the element names as
specified in your specialization. See this section for more details.

Use a New DITA Open Toolkit in Oxygen

Oxygen comes bundled with a DITA Open Toolkit, located in the
[Oxygen-install-folder]/frameworks/dita/DITA-OT directory. To use a new DITA Open Toolkit,
follow these steps:

1. Edit your transformation scenarios and in the Parameters tab change the value for the dita.dir directory to point
to the new directory.
2. If you want to use exclusively the libraries that come with the new DITA Open Toolkit you have to go to the Advanced
tab, click the Libraries button, uncheck the checkbox Allow Oxygen to add high priority libraries to classpath
and configure all libraries that will be used by the ANT process.
3. If there are also changes in the DTD's and you want to use the new versions for content completion and validation,
go to the Oxygen preferences in the Document Type Association page, edit the DITA and DITA Map document
types and modify the catalog entry in the Catalogs tab to point to the custom catalog file catalog-dita.xml.

If the transformation fails after completing these steps please also take a look at this note about upgrading the DITA OT
which comes bundled with Oxygen.

Reusing Content
The DITA framework allows reusing content from other DITA files with a content reference in the following ways:
• You can select content in a topic, create a reusable component from it and reference the component in other locations
using the actions Create Reusable Component and Insert Reusable Component. A reusable component is a file,
usually shorter than a topic. You also have the option of replacing the selection with the component that you are in
the process of creating.
• You can add, edit, and remove a content reference (conref) attribute to/from an existing element. The actions
Add/Edit Content Reference and Remove Content Reference are available on the contextual menu of the Author
editor and on the DITA menu. When a content reference is added or an existing content reference is edited, you can
select any topic ID or interval of topic IDs (set also the conrefend field in the dialog for adding/editing the content
reference) from a target DITA topic file.
Oxygen XML Author | Author for DITA | 123

• You can insert an element with a content reference (conref or conkeyref ) attribute using one of the actions
Insert Content Reference and Insert Content Key Reference that are available on the DITA menu, the Author
custom actions toolbar and the contextual menu of the Author editor.
DITA makes the distinction between local content, that is the text and graphics that are actually present in the element,
and referenced content that is referred by the element but is located in a different file. You have the option of displaying
referenced content by setting the option Display referred content that is available from menu Options > Preferences
> Editor > Pages > Author .

Working with Content References

The DITA feature called conref (short for content reference) enables a piece of content to be included by reference
in multiple contexts. When you need to update that content, you do it in only one place. Typical uses of content references
are for product names, warnings, definitions or process steps.
You can use either or both of the following strategies for managing content references:
• Reusable components - With this strategy, you create a new file for each piece of content that you want to reuse.
• Arbitrary content references - You may prefer to keep many pieces of reusable content in one file. For example, you
might want one file to consist of a list of product names, with each product name in a phrase (<ph> element)
within the file. Then, wherever you need to display a product name, you can insert a content reference that points to
the appropriate <ph> element in this file.
This strategy requires more setup than reusable components, but makes easier centrally managing the reused content.

Oxygen XML Author creates a reference to the external content by adding a conref attribute to an element in the local
document. The conref attribute defines a link to the referenced content, made up of a path to the file and the topic ID
within the file. The path may also reference a specific element ID within the topic. Referenced content is not physically
copied to the referencing file, but Oxygen XML Author displays it as if it is there in the referencing file. You can also
choose to view local content instead of referenced content, to edit the attributes or contents of the referencing element.

How to Work with Reusable Components

When you need to reuse a part of a DITA topic in different places (in the same topic or in different topics) it is
recommended to create a separate component and insert only a reference to the new component in all places. Below are
the steps for extracting a reusable component, inserting a reference to the component and quickly editing the content
inside the component.

1. Select with the mouse the content that you want to reuse in the DITA file opened in Author mode.
2. Start the action Create Reusable Component that is available on the DITA menu, the Author framework actions
toolbar and the contextual menu of the Author editor.
3. In the combo box Reuse Content select the DITA element with the content that you want to extract in a separate
component. The combo box contains the current DITA element where the cursor is located (for example a p element
- a paragraph - or a step or a taskbody or a conbody etc.) and also all the ancestor elements of the current
element.
4. In the Description area enter a textual description for quick identification by other users of the component.
5. If you want to replace the extracted content with a reference to the new component you should leave the checkbox
Replace selection with content reference with the default value (selected).
6. Press the Save button which will open a file system dialog where you have to select the folder and enter the name
of the file that will store the reusable component.
7. Press the Save button in the file system dialog to save the reusable component in a file. If the checkbox was selected
in the Create Reusable Component dialog the conref attribute will be added to the element that was extracted
as a separate component. In Author mode the content that is referenced by the conref attribute is displayed with
grey background and is read-only because it is stored in other file.
8. Optionally, to insert a reference to the same component in other location just place the cursor at the insert location
and run the action Insert Reusable Component that is available on the DITA menu, the Author framework actions
124 | Oxygen XML Author | Author for DITA

toolbar and the contextual menu of the Author editor. Just select in the file system dialog the file that stores the
component and press the OK button. The action will add a conref attribute to the DITA element at the insert
location. The referenced content will be displayed in Author mode with grey background to indicate that it is not
editable.
9. Optionally, to edit the content inside the component just click on the open icon at the start of the grey background
area which will open the component in a separate editor.

Insert a Direct Content Reference

You should follow these steps for inserting an element with a content reference (conref) attribute:

1. Start one of the actions Insert a DITA Content Reference and Insert a DITA Content Key Reference.
2. In the dialog Insert Content Reference select the file with the referenced content in the URL field.
3. In the tree that presents the DITA elements of the specified file that have an id attribute you have to select the
element or the interval of elements that you want to reference. The conref field will be filled automatically with
the id value of the selected element. If you select an interval of elements the conrefend field will be filled with
the id value of the element that ends the selected interval.
4. Press the OK button to insert in the current DITA file an element with the same name and with the same conref
attribute value (and optionally with the same conrefend attribute value) as the element(s) selected in the dialog.

DITA Profiling / Conditional Text

Conditional text is a way to mark blocks of text meant to appear in some renditions of the document, but not in others.
It differs from one variant of the document to another, while unconditional text appear in all document versions.
For instance you can mark a section of a document to be included in the manual designated for the expert users, other
for the novice users manual while unmarked sections are included in any rendition.
You can use conditional text when you develop documentation for:
• a series of similar products
• different releases of a product
• various audiences
The benefits of using conditional text include reduced effort for updating and translating your content and an easy way
to customize the output for various audiences.
Oxygen offers full support for DITA conditional text processing: profiling attributes can be easily managed to filter
content in the published output. You can toggle between different profile sets to see how the edited content looks like
before publishing.
DITA offers support for profiling/conditional text by using profiling attributes. With Oxygen you can define values for
the DITA profiling attributes. The profiling configuration can be shared between content authors through the project
file. There is no need for coding or editing configuration files.
Several profiling attributes can be aggregated into a profiling condition set that allow apply more complex filters on the
document content. A Profiling Condition Set is a very powerful and convenient tool used to preview the content that
goes into the published output. For example, an installation manual available both in Windows and Linux variants can
be profiled to highlight only the Linux procedures for more advanced users.
Oxygen XML Author | Author for DITA | 125

Profiling / Conditional Text Markers

If Show Profiling Attributes option (available in the Profiling / Conditional Text toolbar menu) is set all profiling
attributes set on the current element are listed at the end of the highlighted block. Profiled text is marked in the Author
page with a light green border.

Figure 76: Profiling in Author

In the DITA Maps Manager View view different decorators are user to mark profiled and non-profiled topics:
• - the topic contains profiling attributes;
• - the topic inherits profiling attribute from its ancestors;
• - the topic contains and inherits profiling attributes;
• (dash) - the topic neither contains, nor inherits profiling attributes.

Figure 77: Profiling in DITA Maps Manager

The profiled content that does not match the rules imposed by the current condition sets is grayed-out, meaning that it
will not be included in the published output.

Publish Profiled Text

Oxygen comes with preconfigured transformation scenarios for DITA. All these scenarios take into account the current
profiling condition set.
126 | Oxygen XML Author | Author for DITA

Working with MathML

You can add MathML equations in a DITA document using one of the following methods:
• embed MathML directly into a DITA topic. You can start with the Framework templates / DITA / topic / Composite
with MathML document template, available in the New file action wizard.
• reference an external MathML file as an image, using the Browse for image toolbar action.
Note that MathML equations contained in DITA topics can only be published out-of-the-box in PDF using the DITA
PDF transformation scenario. For other publishing formats users must employ additional customizations for handling
MathML content.
Chapter
7
Predefined Document Types
Topics: This chapter includes short presentations of the document types that come
bundled with Oxygen. For each document type there are enumerated the built-in
• Document Type transformation scenarios, document templates and Author extension actions.
• The DocBook 4 Document Type
• The DocBook 5 Document Type
• The DocBook Targetset
Document Type
• The DITA Topics Document Type
• The DITA Map Document Type
• The XHTML Document Type
• The TEI P4 Document Type
• The TEI P5 Document Type
• The MathML Document Type
• The Microsoft Office OOXML
Document Type
• The Open Office ODF Document
Type
• The OASIS XML Catalog
Document Type
• The XML Schema Document
Type
• The Relax NG Document Type
• The NVDL Document Type
• The Schematron Document Type
• The Schematron 1.5 Document
Type
• The XSLT Document Type
• The XMLSpec Document Type
• The FO Document Type
• The EAD Document Type
• The EPUB Document Type
128 | Oxygen XML Author | Predefined Document Types

Document Type
A document type or framework is associated to an XML file according to a set of rules. It includes also many settings
that improve editing in the Tagless editor for the category of XML files it applies for. These settings include:
• a default grammar used for validation and content completion in both Author mode and Text mode
• CSS stylesheet(s) for rendering XML documents in Author mode
• user actions invoked from toolbar or menu in Author mode
• predefined scenarios used for transformation of the class of XML documents defined by the document type
• XML catalogs
• directories with file templates
• user defined extensions for customizing the interaction with the content author in Author mode
The tagless editor comes with some predefined document types already configured when the application is installed on
the computer. These document types describe well-known XML frameworks largely used today for authoring XML
documents. Editing a document which conforms to one of these types is as easy as opening it or creating it from one of
the predefined document templates which also come with the application.

Figure 78: Document Type preferences page

The DocBook 4 Document Type

DocBook is a very popular set of tags for describing books, articles, and other prose documents, particularly technical
documentation.
A file is considered to be a DocBook 4 document when one of the following conditions are true:
• root element name is book or article
Oxygen XML Author | Predefined Document Types | 129

• the PUBLIC ID of the document contains the string -//OASIS//DTD DocBook XML
The schema of DocBook 4 documents is ${frameworks}/docbook/dtd/docbookx.dtd, where
${frameworks} is a subdirectory of the Oxygen install directory.
The CSS file used for rendering DocBook content is located in ${frameworks}/docbook/css/docbook.css.
The XML catalog is stored in ${frameworks}/docbook/catalog.xml.

Author Extensions
Specific actions for DocBook documents are:
• Bold emphasized text - Emphasizes the selected text by surrounding it with <emphasis role="bold"/>
tag.
• Italic emphasized text - Emphasizes the selected text by surrounding it with <emphasis role="italic"/>
tag.
• Underline emphasized text - Emphasizes the selected text by surrounding it with <emphasis
role="italic"/> tag.
Note: For all of the above actions, if there is no selection then a new emphasis tag with specific role is
inserted. These actions are available in any document context and are grouped under the Emphasize toolbar
actions group.

• link - Inserts a hypertext link.

• ulink - Inserts a link that addresses its target with an URL (Universal Resource Locator).
• olink - Inserts a link that addresses its target indirectly, using the targetdoc and targetptr values which are
present in a Targetset file.

Figure 79: Insert OLink Dialog

After you choose the Targetset URL, the structure of the target documents is presented. For each target document
(targetdoc), the content is displayed allowing for easy identification of the targetptr for the olink element
130 | Oxygen XML Author | Predefined Document Types

which will be inserted. You can use the search fields to quickly identify a target. If you already know the values for
the targetdoc and targetptr, you can insert them directly in the corresponding fields. You also have the
possibility to edit an olink using the action Edit OLink available on the contextual menu. The last used Targetset
URL will be used to identify the edited target.
• URI - Inserts an URI element. The URI identifies a Uniform Resource Identifier (URI) in content.
• xref - Inserts a cross reference to another part of the document.
Note: These actions are grouped under the Link toolbar actions group.

• Insert Section - Inserts a new section / subsection in the document, depending on the current context. For
example if the current context is sect1 then a sect2 is inserted, and so on.
• Insert Paragraph - Inserts a new paragraph depending on the current context. If current context is a paragraph
context (one of the ancestors of the element at caret position is para) then a new paragraph will be inserted after
the paragraph at caret. Otherwise a new paragraph is inserted at caret position.
• Insert Graphic - Inserts a graphic object at the caret position. This is done by inserting either <figure> or
<inlinegraphic> element depending on the current context. The following graphical formats are supported:
GIF, JPG, JPEG, BMP, PNG, SVG.
• Insert Ordered List - Inserts an ordered list. A child list item is also inserted automatically by default.
• Insert Itemized List - Inserts an itemized list. A child list item is also inserted automatically by default.
• Insert Variable List - Inserts a DocBook variable list. A child list item is also inserted automatically by default.
• Insert List Item - Inserts a new list item in any of the above three list types.
• Insert Table - Opens a dialog that allows you to configure the table to be inserted. The dialog allows the user
to configure the number of rows and columns of the table, if the header and footer will be generated and how the
table will be framed. CALS or HTML table model can be selected.
Note: If the Title checkbox is unchecked, an informaltable element is inserted.

• Split Cell To The Right - Splits the cell from current caret position in two, inserting a new empty table cell to
the right. This action works only if the current cell spans over more than one column. The column span of the source
cell is decreased with one.
• Split Cell Above - Splits the cell from current caret position in two, inserting a new empty table cell above it.
This action works only if the current cell spans over more than one row. The row span of the source cell is decreased
with one.
• Split Cell Below - Splits the cell from current caret position in two, inserting a new empty table cell below it.
This action works only if the current cell spans over more than one row. The row span of the source cell is decreased
with one.
Note: DocBook 4 supports only CALS table model. HTML table model is supported only in DocBook 5.

Caution: Column specifications are required for table actions to work properly.

• Generate IDs - Allows generating ID for the current selection or for the element at caret position if the element
appears in ID Generation dialog.
In this dialog, you can specify the elements for which Oxygen generates an ID. You can choose to automatically
generate an ID for these elements by selecting Auto generate ID's for elements. You can choose a pattern for the
generated ID using the field ID Pattern. If the element already has an ID, this ID is preserved.

All actions described above are available in the contextual menu, the DocBook4 submenu of the main menu and in the
Author custom actions toolbar.
Dragging a file from the Project view or from the DITA Maps Manager view and dropping it into a DocBook 4 document
that is edited in Author mode creates a link to the dragged file (the ulink DocBook element) at the drop location.
Dragging an image file from the default file system application (Windows Explorer on Windows or Finder on Mac OS
X, for example) and dropping it into a DocBook 4 document inserts an image element (the inlinegraphic DocBook
element with the fileref attribute) with the location of the dragged file at the drop location (similar with the Insert
Graphic toolbar action).

Transformation Scenarios
Default transformation scenarios allow you to convert DocBook 4 to DocBook 5 documents and transform DocBook
documents to HTML, HTML Chunk, PDF, XHTML, XHTML Chunk, WebHelp (experimental) and EPUB.

Templates
Default templates are available in the New File wizard and can be used for easily creating a skeletal form of a DocBook
4 book or article. These templates are stored in the ${frameworks}/docbook/templates/DocBook 4 folder.

The DocBook 5 Document Type

A file is considered to be a DocBook 5 document when the namespace is http://docbook.org/ns/docbook.
DocBook 5 documents use a Relax NG and Schematron schema located in
${frameworks}/docbook/5.0/rng/docbookxi.rng, where ${frameworks} is a subdirectory of the Oxygen
install directory.
The CSS file used for rendering DocBook content is located in ${frameworks}/docbook/css/docbook.css.
The XML catalog is stored in ${frameworks}/docbook/5.0/catalog.xml.
132 | Oxygen XML Author | Predefined Document Types

Author Extensions
The DocBook 5 extensions are the same as the DocBook 4 extensions. In addition the table actions work also for HTML
tables.
A drag and drop with a file from the Project view or from the DITA Maps Manager view to a DocBook 5 document
that is edited in Author mode will create a link to the dragged file (the link DocBook element) at the drop location. A
drag and drop with an image file from the default file system application (Windows Explorer on Windows, Finder on
Mac OS X, etc) will insert an image element (the inlinemediaobject DocBook element with an imagedata
child element) with the location of the dragged file at the drop location, like the Insert Graphic toolbar action.

Transformation Scenarios
Default transformation scenarios allow you to transform DocBook 5 documents to HTML, HTML Chunk, PDF, XHTML,
XHTML Chunk, WebHelp (experimental) and EPUB.

DocBook to EPUB Transformation

The EPUB specification recommends the use of OpenType fonts (recognized by their .otf file extension) when possible.
To use a specific font:
• first you need to declare it in your CSS file, like:
@font-face {
font-family: "MyFont";
font-weight: bold;
font-style: normal;
src: url(fonts/MyFont.otf);
}

• tell the CSS where this font is used. To set it as default for h1 elements, use the font-family rule as in the
following example:
h1 {
font-size:20pt;
margin-bottom:20px;
font-weight: bold;
font-family: "MyFont";
text-align: center;
}

• in your DocBook to EPUB transformation, set the epub.embedded.fonts parameter to fonts/MyFont.otf.

If you need to provide more files, use comma to separate their file paths.

Templates
Default templates are available in the New File wizard and can be used for easily creating a skeletal form of a DocBook
5 book or article. These templates are stored in the ${frameworks}/docbook/templates/DocBook 5 folder.

The DocBook Targetset Document Type

DocBook Targetset documents are used to resolve cross references with DocBook olink's.
A file is considered to be a Targetset when the root name is targetset.
This type of documents use a DTD and schema located in
${frameworks}/docbook/xsl/common/targetdatabase.dtd, where ${frameworks} is a subdirectory
of the Oxygen install directory.
Oxygen XML Author | Predefined Document Types | 133

Templates
There is a default template for Targetset documents in the ${frameworks}/docbook/templates/Targetset
folder. It is available when creating new documents from templates.
• Docbook Targetset - Map - New Targetset Map.

The DITA Topics Document Type

The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing, and
delivering technical information. It divides content into small, self-contained topics that can be reused in different
deliverables. The extensibility of DITA permits organizations to define specific information structures and still use
standard tools to work with them.
A file is considered to be a DITA topic document when either of the following occurs:
• the root element name is one of the following: concept, task, reference, dita, topic
• PUBLIC ID of the document is one of the PUBLIC ID's for the elements above
• the root element of the file has an attribute named DITAArchVersion attribute from the
“http://dita.oasis-open.org/architecture/2005/” namespace. This enhanced case of matching is only applied when the
Enable DTD processing option from the Document Type Detection option page is enabled.
The default schema used for DITA topic documents is located in ${frameworks}/dita/dtd/ditabase.dtd,
where ${frameworks} is a subdirectory of the Oxygen install directory.
The CSS file used for rendering DITA content in Author mode is ${frameworks}/dita/css/dita.css.
The default XML catalog is ${frameworks}/dita/catalog.xml.

Author Extensions
The specific actions for DITA topic documents are:
• Bold - Surrounds the selected text with a b tag.
• Italic - Surrounds the selected text with an i tag.
• Underline - Surrounds the selected text with a u tag.
Note: For all of the above actions if there is no selection then a new specific tag will be inserted. These actions
are available in any document context.

• Cross Reference - Inserts an xref element with the value of attribute format set to dita. The target of the xref
is selected in a dialog which lists all the IDs available in a file selected by the user.
134 | Oxygen XML Author | Predefined Document Types

Figure 80: Insert a cross reference in a DITA document

• Key Reference - Inserts a user specified element with the value of attribute keyref attribute set to a specific key
name. As stated in the DITA 1.2 specification keys can be defined at map level which can be then referenced. The
target of the keyref is selected in a dialog which lists all the keys available in the current opened map from the
DITA Maps Manager.
You can also reference elements at sub-topic level by pressing the Sub-topic button and choosing the target.
Important: All keys which are presented in the dialog are gathered from the current opened DITA map.
Elements which have the keyref attribute set are displayed as links. The current opened DITA map is also
used to resolve references when navigating keyref links in the Author page. Image elements which use key
references are rendered as images.

• File Reference - Inserts an xref element with the value of attribute format set to xml.
• Web Link - Inserts an xref element with the value of attribute format set to html, and scope set to external.
• Related Link to Topic - Inserts a link element inside a related-links parent.
• Related Link to File - Inserts a link element with the format attribute set to xml inside a related-links
parent.
• Related Link to Web Page - Inserts a link element with the attribute format set to html and scope set to
external inside a related-links parent.
Note: The actions for inserting references described above are grouped inside link toolbar actions group.

• Paste as Link (available on the contextual menu of Author editor for any topic file) - Inserts a link element or an
xref one (depending on the location of the paste) that points to the DITA XML element from the clipboard. An
entire DITA XML element with an ID attribute must be present in the clipboard when the action is invoked. The
href attribute of link/href will point to this ID value.
• Paste as Content Reference (available on the contextual menu of Author editor for any topic file) - Inserts a content
reference (a DITA element with a conref attribute) to the DITA XML element from the clipboard. An entire DITA
XML element with an ID attribute must be present in the clipboard when the action is invoked. The conref attribute
will point to this ID value.
• Insert Section / Step - Inserts a new section / step in the document, depending on the current context. A new
section will be inserted in either one of the following contexts:
• section context, when the value of class attribute of the current element or one of its ancestors contains topic
or section.
• topic's body context, when the value of class attribute of the current element contains topic/body.
Oxygen XML Author | Predefined Document Types | 135

A new step will be inserted in either one of the following contexts:

• task step context, when the value of class attribute of the current element or one of its ancestors contains
task/step.
• task steps context, when the value of class attribute of the current element contains task/steps.

• Insert Paragraph - Inserts a new paragraph depending on the current context. If current context is a paragraph
context (the value of class attribute of the current element or one of its ancestors contains topic/p) then a new
paragraph will be inserted after this paragraph. Otherwise a new paragraph is inserted at caret position.
• Insert Concept - Inserts a new concept. Concepts provide background information that users must know before
they can successfully work with a product or interface. This action is available in one of the following contexts:
• concept context, one of the current element ancestors is a concept. In this case an empty concept will be
inserted after the current concept.
• concept or DITA context, current element is a concept or dita. In this case an empty concept will be
inserted at current caret position.
• DITA topic context, current element is a topic child of a dita element. In this case an empty concept will
be inserted at current caret position.
• DITA topic context, one of the current element ancestors is a DITA topic. In this case an empty concept
will be inserted after the first topic ancestor.

• Insert Task - Inserts a new task. Tasks are the main building blocks for task-oriented user assistance. They
generally provide step-by-step instructions that will enable a user to perform a task. This action is available in one
of the following contexts:
• task context, one of the current element ancestors is a task. In this case an empty task will be inserted after
the last child of the first concept's ancestor.
• task context, the current element is a task. In this case an empty task will be inserted at current caret position.
• topic context, the current element is a dita topic. An empty task will be inserted at current caret position.
• topic context, one of the current element ancestors is a dita topic. An empty task will be inserted after the
last child of the first ancestor that is a topic.

• Insert Reference - Inserts a new reference in the document. A reference is a top-level container for a reference
topic. This action is available in one of the following contexts:
• reference context - one of the current element ancestors is a reference. In this case an empty reference
will be inserted after the last child of the first ancestor that is a reference.
• reference or dita context - the current element is either a dita or a reference. An empty reference
will be inserted at caret position.
• topic context - the current element is topic descendant of dita element. An empty reference will be
inserted at caret position.
• topic context - the current element is descendant of dita element and descendant of topic element. An empty
reference will be inserted after the last child of the first ancestor that is a topic.

• Browse for image - Inserts a graphic object at the caret position. Depending on the current context, an image-type
DITA element is inserted. The following graphical formats are supported: GIF, JPG, JPEG, BMP, PNG, SVG. Also
you can use this action to refer MathML files.
• Insert Content Reference - Inserts a content reference at the caret position.
The DITA conref attribute provides a mechanism for reuse of content fragments. The conref attribute stores a
reference to another element and is processed to replace the referencing element with the referenced element. The
element containing the content reference acts as a placeholder for the referenced element. The identifier for the
referenced element must be either absolute or resolvable in the context of the referencing element. See here for more
details.
136 | Oxygen XML Author | Predefined Document Types

Oxygen will display the referred content of a DITA conref if it can resolve it to a valid resource. If you have URI's
instead of local paths in the XML documents and your DITA OT transformation needs an XML catalog to map the
URI's to local paths you have add the catalog to Oxygen. If the URI's can be resolved the referred content will be
displayed in Author mode and in the transformation output.
A content reference is inserted with the action Insert a DITA Content Reference available on the toolbar Author
custom actions and on the menu DITA > Insert .

Figure 81: Insert Content Reference Dialog

In the URL chooser you set the URL of the file from which you want to reuse content. Depending on the Target
type filter you will see a tree of elements which can be referred (which have ID's). For each element the XML content
is shown in the preview area. The Conref value is computed automatically for the selected tree element. After
pressing OK an element with the same name as the target element and having the attribute conref with the value
specified in the Conref value field will be inserted at caret position.
According to the DITA 1.2 specification the conrefend attribute can be used to specify content reference ranges.
This is a very useful feature when referencing multiple consecutive steps or list items. If you use multiple contiguous
sibling selection the conrefend value will also be set to the value of the last selected ID path. Oxygen XML
Author will present the entire referenced range as read-only content.
• Insert Content Key Reference - Inserts a content key reference at the caret position.
As stated in the DITA 1.2 specification the conkeyref attribute provides a mechanism for reuse of content fragments
similar with the conref mechanism. Keys are defined at map level which can be referenced using conkeyref.
The conkeyref attribute contains a key reference to another element and is processed to replace the referencing
element with the referenced element. The element containing the content key reference acts as a placeholder for the
referenced element. The identifier for the referenced element must be either absolute or resolvable in the context of
the referencing element.
Oxygen will display the key referred content of a DITA conkeyref if it can resolve it to a valid resource in the
context of the current opened DITA map.
A content key reference is inserted with the action Insert a DITA Content Key Reference available on the toolbar
Author custom actions and on the menu DITA > Insert .
Oxygen XML Author | Predefined Document Types | 137

Figure 82: Insert Content Key Reference Dialog

To reference target elements at sub-topic level just press the Sub-topic button and choose the target.
According to the DITA 1.2 specification the conrefend attribute can be used to specify content reference ranges.
This is a very useful feature when referencing multiple consecutive steps or list items. If you use multiple contiguous
sibling selection for IDs at sub-topic level the conrefend value will also be set to the value of the last selected ID
path. Oxygen XML Author will present the entire referenced range as read-only content.
Important: All keys which are presented in the dialog are gathered from the current opened DITA map.
Elements which have the conkeyref attribute set are displayed by default with the target content expanded.
The current opened DITA map is also used to resolve references when navigating conkeyref links in the
Author page.

• Replace conref / conkeyref reference with content - Replaces the content reference fragment or the conkeyref
at caret position with the referenced content. This action is useful when you want to make changes to the content
but decide to keep the referenced fragment unchanged.
• Insert Equation - Allows you to insert an MathML equation. .
• Create Reusable Component - Creates a reusable component from a selected fragment of text. For more information,
see Reusing Content.
• Insert Reusable Component - Inserts a reusable component at cursor location. For more information, see Reusing
Content.
• Remove Content Reference - Removes the conref attribute of an element. For more information, see Reusing
Content.
• Add/Edit Content Reference - Add or edit the conref attribute of an element. For more information, see Reusing
Content.
• Paste as Content Reference - Pastes the content of the clipboard as a content reference. Note that the copied
element must have the id attribute set.
• Paste as Link - Pastes the content of the clipboard as a link. Note that the copied element must have the id
attribute set.
• Insert Ordered List - Inserts an ordered list with one list item.
• Insert Unordered List - Inserts an unordered list with one list item.
• Insert List Item - Inserts a new list item for in any of the above two list types.
• Insert Table - Opens a dialog that allows you to configure the table to be inserted. The dialog allows the user
to configure:
• the number of rows and columns of the table
138 | Oxygen XML Author | Predefined Document Types

• if the header will be generated

• if the title will be added
• how the table will be framed

• Insert Row - Inserts a new table row with empty cells. The action is available when the caret position is inside
a table.
• Insert Column - Inserts a new table column with empty cells after the current column. The action is available
when the caret position is inside a table.
• Insert Cell - Inserts a new empty cell depending on the current context. If the caret is positioned between two
cells, a new one will be inserted at caret's position. If the caret is inside a cell, then the new one will be created after
the current cell.
• Delete Column - Deletes the table column where the caret is located.
• Delete Row - Deletes the table row where the caret is located.
• Join Row Cells - Joins the content of the selected cells. The operation is available if the selected cells are from
the same row and they have the same row span. The action is also available when the selection is missing, but the
caret is positioned between two cells.
• Join Cell Above - Joins the content of cell from current caret position with that of the cell above it. Note that
this action works only if both cells have the same column span.
• Join Cell Below - Joins the content of cell from current caret position with that of the cell below it. Note that
this action works only if both cells have the same column span.
• Split Cell To The Left - Splits the cell from current caret position in two, inserting a new empty table cell to
the left. Note that this action works only if the current cell spans over more than one column. The column span of
the source cell will be decreased with one.
• Split Cell To The Right - Splits the cell from current caret position in two, inserting a new empty table cell to
the right. Note that this action works only if the current cell spans over more than one column. The column span of
the source cell will be decreased with one.
• Split Cell Above - Splits the cell from current caret position in two, inserting a new empty table cell above.
Note that this action works only if the current cell spans over more than one row. The row span of the source cell
will be decreased with one.
• Split Cell Below - splits the cell from current caret position in two, inserting a new empty table cell below.
Note that this action works only if the current cell spans over more than one row. The row span of the source cell
will be decreased with one.

Note: DITA supports the CALS table model similar with DocBook document type in addition to the simpletable
element specific for DITA.

Caution: Column specifications are required for table actions to work properly.

• Generate IDs - Allows you to generate an unique ID for the element at caret position. You can set the ID pattern
using the ID Generation dialog, available in the DITA main menu, ID Generation Options submenu. In this dialog
you can specify the elements for which Oxygen generates an ID if the Auto generate ID's for elements is enabled.
If the element already has an ID, it is preserved.
All actions described above are available in the contextual menu, the DITA submenu of the main menu and in the
Author custom actions toolbar.
A drag and drop with a file from the Project view or from the DITA Maps Manager view to a DITA topic document
that is edited in Author mode will create a link to the dragged file (the xref DITA element with the href attribute) at
the drop location. A drag and drop with an image file from the default file system application (Windows Explorer on
Windows, Finder on Mac OS X, etc) will insert an image element (the image DITA element with the href attribute)
with the location of the dragged file at the drop location, like the Insert Graphic toolbar action.
Oxygen XML Author | Predefined Document Types | 139

Transformation Scenarios
The following default transformation scenarios are available for DITA Topics:
• DITA XHTML - Transforms a DITA topic to XHTML using DITA Open Toolkit 1.5.2;
• DITA PDF (Idiom FO Plugin) - Transforms a DITA topic to PDF using the DITA Open Toolkit 1.5.2 and the
Apache FOP engine.

Templates
The default templates available for DITA topics are stored in ${frameworks}/dita/templates/topic folder.
They can be used for easily creating a DITA concept, reference, task or topic.
These templates are available when creating new documents from templates.
• DITA - Composite - New DITA Composite
• DITA - Concept - New DITA Concept
• DITA - General Task - New DITA Task
• DITA - Glossentry - New DITA Glossentry
• DITA - Reference - New DITA Reference
• DITA - Task - New DITA Task
• DITA - Topic - New DITA Topic
• DITA - Learning Assessment - New DITA Learning Assessment (learning specialization in DITA 1.2)
• DITA - Learning Content - New DITA Learning Content (learning specialization in DITA 1.2)
• DITA - Learning Summary - New DITA Learning Summary (learning specialization in DITA 1.2)
• DITA - Learning Overview - New DITA Learning Overview (learning specialization in DITA 1.2)

The DITA Map Document Type

DITA maps are documents that collect and organize references to DITA topics to indicate the relationships among the
topics. They can also serve as outlines or tables of contents for DITA deliverables and as build manifests for DITA
projects.
Maps allow scalable reuse of content across multiple contexts. They can be used by information architects, writers, and
publishers to plan, develop, and deliver content.
A file is considered to be a DITA map document when either of the following occurs:
• root element name is one of the following: map, bookmap
• public id of the document is -//OASIS//DTD DITA Map or -//OASIS//DTD DITA BookMap.
• the root element of the file has an attribute named class which contains the value map/map and a
DITAArchVersion attribute from the http://dita.oasis-open.org/architecture/2005/ namespace. This enhanced
case of matching is only applied when the Enable DTD processing option from the Document Type Detection
option page is enabled.
The default schema used for DITA map documents is located in ${frameworks}/dita/DITA-OT/dtd/map.dtd,
where ${frameworks} is a subdirectory of the Oxygen install directory.
The CSS file used for rendering DITA content is located in ${frameworks}/dita/css/dita.css.
The default XML catalog is stored in ${frameworks}/dita/catalog.xml.
140 | Oxygen XML Author | Predefined Document Types

Author Extensions
Specific actions for DITA map documents are:
• Insert Topic Reference - Inserts a reference to a topic.
• Insert Content Reference - Inserts a content reference at the caret position.
• Insert Content Key Reference - Inserts a content reference at the caret position.
• Insert Table - Opens a dialog that allows you to configure the relationship table to be inserted. The dialog allows
the user to configure the number of rows and columns of the relationship table, if the header will be generated and
if the title will be added.
• Insert Row - Inserts a new table row with empty cells. The action is available when the caret position is inside
a table.
• Insert Column - Inserts a new table column with empty cells after the current column. The action is available
when the caret position is inside a table.
• Delete Column - Deletes the table column where the caret is located.
• Delete Row - Deletes the table row where the caret is located.
All actions described above are available in the contextual menu, the DITA submenu of the main menu and in the
Author custom actions toolbar.
A drag and drop with a file from the Project view or from the DITA Maps Manager view to a DITA map document that
is edited in Author mode will create a link to the dragged file (a topicref element, a chapter one, a part one,
etc.) at the drop location.

Transformation Scenarios
Predefined transformation scenarios allow you to transform a DITA Map to PDF, XHTML, WebHelp, EPUB and CHM
files. Many more output formats are available by clicking the New button. The transformation process relies on DITA
Open Toolkit 1.5.2.

Templates
The default templates available for DITA maps are stored in ${frameworks}/dita/templates/map folder.
They can be used for easily creating a DITA map and bookmap files.
These templates are available when creating new documents from templates.
• DITA Map - Bookmap - New DITA Bookmap
• DITA Map - Map - New DITA Map
• DITA Map - Learning Map - New DITA learning and training content specialization map
• DITA Map - Learning Bookmap - New DITA learning and training content specialization bookmap
• DITA Map - Eclipse Map - New DITA learning and training content specialization bookmap

The XHTML Document Type

The Extensible HyperText Markup Language, or XHTML, is a markup language that has the same depth of expression
as HTML, but also conforms to XML syntax.
A file is considered to be a XHTML document when the root element name is a html.
Oxygen XML Author | Predefined Document Types | 141

The schema used for these documents is located in ${frameworks}/xhtml/dtd/xhtml1-strict.dtd, where

${frameworks} is a subdirectory of the Oxygen install directory.
The default CSS options for the XHTML document type are set to merge the CSSs specified in the document with the
CSSs defined in the XHTML document type.
The CSS file used for rendering XHTML content is located in ${frameworks}/xhtml/css/xhtml.css.
There are three default catalogs for XHTML document type:
• ${frameworks}/xhtml/dtd/xhtmlcatalog.xml
• ${frameworks}/xhtml11/dtd/xhtmlcatalog.xml
• ${frameworks}/xhtml11/schema/xhtmlcatalog.xml

Author Extensions
Specific actions are:
• Bold - Changes the style of the selected text to bold by surrounding it with b tag.
• Italic - Changes the style of the selected text to italic by surrounding it with i tag.
• Underline - Changes the style of the selected text to underline by surrounding it with u tag.
Note: For all of the above actions if there is no selection then a new specific tag will be inserted. These actions
are available in any document context.

• Headings - Groups actions for inserting h1, h2, h3, h4, h5, h6 elements.
• Insert Paragraph - Inserts a new paragraph depending on the current context. If current context is a paragraph
context (one of the ancestors of the element at caret position is p) then a new paragraph will be inserted after the
paragraph at caret. Otherwise a new paragraph is inserted at caret position.
• Insert Graphic - Inserts a graphic object at the caret position. This is done by inserting an img element regardless
of the current context. The following graphical formats are supported: GIF, JPG, JPEG, BMP, PNG, SVG.
• Insert Ordered List - Inserts an ordered list (ol element) with one list item (li child element).
• Insert Unordered List - Inserts an unordered list (ul element) with one list item (li child element).
• Insert Definition List - Inserts a definition list (dl element) with one list item (a dt child element and a dd
child element).
• Insert List Item - Inserts a new list item for in any of the above two list types.
• Insert Table - Opens a dialog that allows you to configure the table to be inserted. The dialog allows the user
to configure the number of rows and columns of the table, if the header and footer will be generated and how the
table will be framed.
• Insert Row - Inserts a new table row with empty cells. The action is available when the caret position is inside
a table.
• Insert Column - Inserts a new table column with empty cells after the current column. The action is available
when the caret position is inside a table.
• Insert Cell - Inserts a new empty cell depending on the current context. If the caret is positioned between two
cells, a new one will be inserted at caret's position. If the caret is inside a cell, then the new one will be created after
the current cell.
• Delete Column - Deletes the table column where the caret is located.
• Delete Row - Deletes the table row where the caret is located.
142 | Oxygen XML Author | Predefined Document Types

• Join Row Cells - Joins the content of the selected cells. The operation is available if the selected cells are from
the same row and they have the same row span. The action is also available when the selection is missing, but the
caret is positioned between two cells.
• Join Cell Above - Joins the content of cell from current caret position with that of the cell above it. Note that
this action works only if both cells have the same column span.
• Join Cell Below - Joins the content of cell from current caret position with that of the cell below it. Note that
this action works only if both cells have the same column span.
• Split Cell To The Left - Splits the cell from current caret position in two, inserting a new empty table cell to
the left. Note that this action works only if the current cell spans over more than one column. The column span of
the source cell will be decreased with one.
• Split Cell To The Right - Splits the cell from current caret position in two, inserting a new empty table cell to
the right. Note that this action works only if the current cell spans over more than one column. The column span of
the source cell will be decreased with one.
• Split Cell Above - Splits the cell from current caret position in two, inserting a new empty table cell above.
Note that this action works only if the current cell spans over more than one row. The row span of the source cell
will be decreased with one.
• Split Cell Below - Splits the cell from current caret position in two, inserting a new empty table cell below.
Note that this action works only if the current cell spans over more than one row. The row span of the source cell
will be decreased with one.
All actions described above are available in the contextual menu, the XHTML submenu of the main menu and in the
Author custom actions toolbar.
A drag and drop with a file from the Project view or from the DITA Maps Manager view to a DITA topic document
that is edited in Author mode will create a link to the dragged file (the xref DITA element with the href attribute) at
the drop location. A drag and drop with an image file from the default file system application (Windows Explorer on
Windows, Finder on Mac OS X, etc) will insert an image element (the image DITA element with the href attribute)
with the location of the dragged file at the drop location, like the Insert Graphic toolbar action.

Transformation Scenarios
The following default transformation scenarios are available for XHTML:
• XHTML to DITA concept - Converts an XHTML document to a DITA concept document
• XHTML to DITA reference - Converts an XHTML document to a DITA reference document
• XHTML to DITA task - Converts an XHTML document to a DITA task document
• XHTML to DITA topic - Converts an XHTML document to a DITA topic document

Templates
Default templates are available for XHTML. They are stored in ${frameworksDir}/xhtml/templates folder
and they can be used for easily creating basic XHTML documents.
These templates are available when creating new documents from templates.
• XHTML - 1.0 Strict - New Strict XHTML 1.0
• XHTML - 1.0 Transitional - New Transitional XHTML 1.0
• XHTML - 1.1 DTD Based - New DTD based XHTML 1.1
• XHTML - 1.1 DTD Based + MathML 2.0 + SVG 1.1 - New XHTML 1.1 with MathML and SVG insertions
• XHTML - 1.1 Schema based - New XHTML 1.1 XML Schema based
Oxygen XML Author | Predefined Document Types | 143

The TEI P4 Document Type

The Text Encoding Initiative (TEI) Guidelines is an international and interdisciplinary standard that enables libraries,
museums, publishers, and individual scholars to represent a variety of literary and linguistic texts for online research,
teaching, and preservation.
A file is considered to be a TEI P4 document when either of the following occurs:
• the root's local name is TEI.2
• the document's public id is -//TEI P4
The DTD schema used for these documents is located in ${frameworks}/tei/tei2xml.dtd, where
${frameworks} is a subdirectory of the Oxygen install directory.
The CSS file used for rendering TEI P4 content is located in
${frameworks}/tei/xml/tei/css/tei_oxygen.css.
There are two default catalogs for TEI P4 document type:
• ${frameworks}/tei/xml/teip4/schema/dtd/catalog.xml
• ${frameworks}/tei/xml/teip4/custom/schema/dtd/catalog.xml

Author Extensions
The specific actions for TEI P4 documents are:
• Bold - Changes the style of the selected text to bold by surrounding it with hi tag and setting the rend attribute
to bold.
• Italic - Changes the style of the selected text to italic by surrounding it with hi tag and setting the rend
attribute to italic.
• Underline - Changes the style of the selected text to underline by surrounding it with hi tag and setting the
rend attribute to ul.
Note: For all of the above actions if there is no selection then a new specific tag will be inserted. These actions
are available in any document context.

• Insert Section - Inserts a new section / subsection, depending on the current context. For example if the current
context is div1 then a div2 will be inserted and so on.
• Insert Paragraph - Inserts a new paragraph depending on the current context. If current context is a paragraph
context (one of the ancestors of the element at caret position is p) then a new paragraph will be inserted after the
paragraph at caret. Otherwise a new paragraph is inserted at caret position.
• Insert Image - Inserts a graphic object at the caret position. The following dialog is displayed allowing the user
to specify the entity that refers the image itself.
• Insert Ordered List - Inserts an ordered list (list element with type attribute set to ordered) with one
list item (item element).
• Insert Itemized List - Inserts an unordered list (list element with type attribute set to bulleted) with
one list item (item element).
• Insert List Item - Inserts a new list item for in any of the above two list types.
• Insert Table - Opens a dialog that allows you to configure the table to be inserted. The dialog allows the user
to configure the number of rows and columns of the table and if the header will be generated.
• Insert Row - Inserts a new table row with empty cells. The action is available when the caret position is inside
a table.
144 | Oxygen XML Author | Predefined Document Types

• Insert Column - Inserts a new table column with empty cells after the current column. The action is available
when the caret position is inside a table.
• Insert Cell - Inserts a new empty cell depending on the current context. If the caret is positioned between two
cells, a new one will be inserted at caret's position. If the caret is inside a cell, then the new one will be created after
the current cell.
• Delete Column - Deletes the table column where the caret is located.
• Delete Row - Deletes the table row where the caret is located.
• Join Row Cells - Joins the content of the selected cells. The operation is available if the selected cells are from
the same row and they have the same row span. The action is also available when the selection is missing, but the
caret is positioned between two cells.
• Join Cell Above - Joins the content of cell from current caret position with that of the cell above it. Note that
this action works only if both cells have the same column span.
• Join Cell Below - Joins the content of cell from current caret position with that of the cell below it. Note that
this action works only if both cells have the same column span.
• Split Cell To The Left - Splits the cell from current caret position in two, inserting a new empty table cell to
the left. Note that this action works only if the current cell spans over more than one column. The column span of
the source cell will be decreased with one.
• Split Cell To The Right - Splits the cell from current caret position in two, inserting a new empty table cell to
the right. Note that this action works only if the current cell spans over more than one column. The column span of
the source cell will be decreased with one.
• Split Cell Above - Splits the cell from current caret position in two, inserting a new empty table cell above.
Note that this action works only if the current cell spans over more than one row. The row span of the source cell
will be decreased with one.
• Split Cell Below - Splits the cell from current caret position in two, inserting a new empty table cell below.
Note that this action works only if the current cell spans over more than one row. The row span of the source cell
will be decreased with one.
• Generate IDs - Allows you to generate ID for the current selection or for the element at caret position if the element
appears in ID Generation dialog. In this dialog you can specify the elements for which Oxygen should generate an
ID. You can choose to automatically generate an ID for these elements by selecting Auto generate ID's for elements.
You can choose a pattern for the generated ID using the field ID Pattern. If the element already has an ID, this ID
is preserved.
All actions described above are available in the contextual menu, the TEI P4 submenu of the main menu and in the
Author custom actions toolbar.
A drag and drop with a file from the Project view or from the DITA Maps Manager view to a TEI P4 document that is
edited in Author mode will create a link to the dragged file (the ptr element with the target attribute) at the drop
location.

Transformation Scenarios
The following default transformations are available:
• TEI HTML - Transforms a TEI document into a HTML document
• TEI P4 -> TEI P5 Conversion - Convert a TEI P4 document into a TEI P5 document
• TEI PDF - Transforms a TEI document into a PDF document using the Apache FOP engine

Templates
The default templates are stored in ${frameworks}/tei/templates/TEI P4 folder and they can be used for
easily creating basic TEI P4 documents. These templates are available when creating new documents from templates.
Oxygen XML Author | Predefined Document Types | 145

• TEI P4 - Lite - New TEI P4 Lite

• TEI P4 - New Document - New TEI P4 standard document

The TEI P5 Document Type

The TEI P5 document type is the same with that for TEI P4 with the following exceptions:
• A file is considered to be a TEI P5 document when the namespace is http://www.tei-c.org/ns/1.0.
• The schema is located in ${frameworks}/tei/xml/tei/custom/schema/relaxng/tei_allPlus.rng,
where ${frameworks} is a subdirectory of the Oxygen install directory.
• A drag and drop with an image file from the default file system application (Windows Explorer on Windows, Finder
on Mac OS X, etc) will insert an image element (the graphic DITA element with the url attribute) with the
location of the dragged file at the drop location, like the Insert Graphic toolbar action.

Transformation Scenarios
The following default transformations are available:
• TEI P5 XHTML - Transforms a TEI document into a XHTML document
• TEI P5 PDF - Transforms a TEI document into a PDF document using the Apache FOP engine

Templates
The default templates are stored in ${frameworks}/tei/templates/TEI P5 folder and they can be used for
easily creating basic TEI P5 documents. These templates are available when creating new documents from templates.
• TEI P5 - All - New TEI P5 All
• TEI P5 - Bare - New TEI P5 Bare
• TEI P5 - Lite - New TEI P5 Lite
• TEI P5 - Math - New TEI P5 Math
• TEI P5 - Speech - New TEI P5 Speech
• TEI P5 - SVG - New TEI P5 with SVG extensions
• TEI P5 - XInclude - New TEI P5 XInclude aware

The MathML Document Type

Mathematical Markup Language (MathML) is an application of XML for describing mathematical notations and capturing
both its structure and content. It aims at integrating mathematical formulae into World Wide Web documents.
Oxygen offers support for editing and validating MathML 2.0 documents.
A file is considered to be a MathML document when the root element name is a math or it's namespace is
http://www.w3.org/1998/Math/MathML.
The schema used for these documents is located in ${frameworks}/mathml2/dtd/mathml2.dtd, where
${frameworks} is a subdirectory of the Oxygen install directory.

Templates
There is one default template for MathML stored in the ${frameworks}/mathml2/templates folder.
146 | Oxygen XML Author | Predefined Document Types

This template is available when creating new documents from templates.

• Equation 2.0 DTD Based - DTD based MathML 2.0 equation template file.
• Equation 2.0 Schema Based - XML Schema-based MathML 2.0 equation template file.

The Microsoft Office OOXML Document Type

Office Open XML (also referred to as OOXML or OpenXML) is a free and open Ecma international standard document
format, and a proposed ISO/IEC standard for representing spreadsheets, charts, presentations and word processing
documents.
OOXML uses a file package conforming to the Open Packaging Convention. This format uses the ZIP file format and
contains the individual files that form the basis of the document. In addition to Office markup, the package can also
include embedded files such as images, videos, or other documents.
Oxygen offers support for editing, transforming and validating documents composing the OOXML package directly
through the archive support.

Figure 83: Editing OOXML packages in Oxygen

A file is considered to be an OOXML document when it has one of the following namespaces:
• http://schemas.openxmlformats.org/wordprocessingml/2006/main
• http://schemas.openxmlformats.org/package/2006/content-types
• http://schemas.openxmlformats.org/drawingml/2006/main
• http://schemas.openxmlformats.org/package/2006/metadata/core-properties
• http://schemas.openxmlformats.org/package/2006/relationships
• http://schemas.openxmlformats.org/presentationml/2006/main
• http://schemas.openxmlformats.org/officeDocument/2006/custom-properties
Oxygen XML Author | Predefined Document Types | 147

• http://schemas.openxmlformats.org/officeDocument/2006/extended-properties
• http://schemas.openxmlformats.org/spreadsheetml/2006/main
• http://schemas.openxmlformats.org/drawingml/2006/chart
The schema used for these documents is located in ${frameworks}/ooxml/schemas/main.nvdl, where
${frameworks} is a subdirectory of the Oxygen install directory. The schema can be easily customized to allow user
defined extension schemas for use in the OOXML files. See the Markup Compatibility and Extensibility Ecma PDF
document for more details.

The Open Office ODF Document Type

The OpenDocument format (ODF) is a free and open file format for electronic office documents, such as spreadsheets,
charts, presentations and word processing documents. The standard was developed by the Open Office XML technical
committee of the Organization for the Advancement of Structured Information Standards (OASIS) consortium and based
on the XML format originally created and implemented by the OpenOffice.org office suite.
A basic OpenDocument file consists of an XML document that has <document> as its root element. OpenDocument
files can also take the format of a ZIP compressed archive containing a number of files and directories. These can contain
binary content and benefit from ZIP lossless compression to reduce file size. OpenDocument benefits from separation
of concerns by separating the content, styles, metadata and application settings into four separate XML files.
Oxygen offers support for editing, manipulating and validating documents composing the ODF package directly through
the archive support.

Figure 84: Editing ODF packages in Oxygen

A file is considered to be an ODF document when it has the namespace

“urn:oasis:names:tc:opendocument:xmlns:office:1.0”.
The schema used for these documents is located in
${frameworks}/odf/schemas/OpenDocument-schema-v1.1.rng, where ${frameworks} is a
subdirectory of the Oxygen install directory.
148 | Oxygen XML Author | Predefined Document Types

The OASIS XML Catalog Document Type

The OASIS XML catalog is a document describing a mapping between external entity references or URI's and
locally-cached equivalents.
A file is considered to be an XML Catalog document when it has the namespace
“urn:oasis:names:tc:entity:xmlns:xml:catalog” or when its root element name is catalog.
The OASIS 1.1 schema used for these documents is located in ${frameworks}/xml/catalog1.1.xsd, where
${frameworks} is a subdirectory of the Oxygen install directory.

The XML Schema Document Type

This document type is used to associated CSS stylesheets to an XML Schema so it can be visualized in the Author page.
A file is considered to be an XML Schema document when the root name is schema and namespace is
http://www.w3.org/2001/XMLSchema.
The following CSS alternatives are proposed for visualizing XML Schemas in the Author page.
• ${frameworks}/xmlschema/schema-main.css - Documentation - representation of XML Schema
optimized for editing and viewing documentation
• ${frameworks}/xmlschema/schemaISOSchematron.css - XMLSchema+ISOSchematron - representation
of XML Schema with embedded ISO Schematron rules
• ${frameworks}/xmlschema/schemaSchematron.css - XMLSchema+Schematron - representation of
XML Schema with embedded Schematron rules
• ${frameworks}/xmlschema/default.css - representation of XML Schema for general editing

The Relax NG Document Type

This document type is used to associated CSS stylesheets to an Relax NG file so it can be visualized in the Author page.
A file is considered to be an Relax NG document when the namespace is http://relaxng.org/ns/structure/1.0.
The following CSS alternatives are proposed for visualizing RelaxNG schemas in the Author page.
• ${frameworks}/relaxng/relaxng-main.css - Relax NG - representation of Relax NG optimized for
editing in the Author mode
• ${frameworks}/relaxng/relaxngISOSchematron.css - Relax NG (XML Syntax)+ISOSchematron
- representation of Relax NG (XML syntax) with embedded ISO Schematron rules. Embedded Schematron rules are
not supported in Relax NG schemas with compact syntax.
• ${frameworks}/relaxng/relaxngSchematron.css - Relax NG (XML Syntax)+Schematron -
representation of Relax NG (XML syntax) with embedded Schematron rules. Embedded Schematron rules are not
supported in Relax NG schemas with compact syntax.

The NVDL Document Type

This document type is used to associated CSS stylesheets to a NVDL file so it can be visualized in the Author page.
Oxygen XML Author | Predefined Document Types | 149

A file is considered to be a NVDL document when the namespace is http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0.

The following CSS is proposed for visualizing NVDL schemas in the Author page:
• ${frameworks}/nvdl/nvdl.css - Representation of Relax NG schema optimized for editing in the Author
mode.

The Schematron Document Type

This document type is used to associate CSS stylesheets to a Schematron file so it can be visualized in the Author page.
A file is considered to be a Schematron document when the namespace is http://purl.oclc.org/dsdl/schematron.
The following CSS is proposed for visualizing Schematron schemas in the Author page:
• ${frameworks}/schematron/iso-schematron.css - Representation of Schematron optimized for
editing in the Author mode.

The Schematron 1.5 Document Type

This document type is used to associate CSS stylesheets to a Schematron 1.5 file so it can be visualized in the Author
page.
A file is considered to be a Schematron 1.5 document when the namespace is http://www.ascc.net/xml/schematron.
The following CSS is proposed for visualizing Schematron 1.5 schemas in the Author page:
• ${frameworks}/schematron/schematron15.css - Representation of Schematron 1.5 optimized for
editing in the Author mode.

The XSLT Document Type

This document type is used to associate CSS stylesheets to an XSLT stylesheet file so it can be visualized in the Author
page.
A file is considered to be a XSLT document when the namespace is http://www.w3.org/1999/XSL/Transform.
The following CSS is proposed for visualizing XSLT stylesheets in the Author page:
• ${frameworks}/xslt/xslt.css - Representation of XSLT optimized for editing in the Author mode.

The XMLSpec Document Type

XMLSpec is a markup language for W3C specifications and other technical reports.
A file is considered to be an XMLSpec document when the root name is spec.
XMLSpec documents use a Relax NG schema located in ${frameworks}/xmlspec/schema/xmlspec.rng,
where ${frameworks} is a subdirectory of the Oxygen install directory.
The default XML catalog is stored in ${frameworks}/xmlspec/catalog.xml.
150 | Oxygen XML Author | Predefined Document Types

Transformation Scenarios
The following default transformation scenarios are available:
• XMLSpec PDF - Transforms an XMLSpec document into PDF document using the Apache FOP engine
• XMLSpec HTML - Transforms an XMLSpec document into HTML document
• XMLSpec HTML Diff - Produces color-coded HTML from diff markup
• XMLSpec HTML Slices - Produces chunked HTML specifications

Templates
The default templates for XMLSpec are stored in ${frameworks}/xmlspec/templates folder and they can be
used for easily creating an XMLSpec. These templates are available when creating new documents from templates.
• XMLSpec - New Document - New XMLSpec document

The FO Document Type

FO describes the formatting of XML data for output to screen, paper or other media.
A file is considered to be an FO document when the namespace is http://www.w3.org/1999/XSL/Format.
FO documents use a XML Schema located in ${frameworks}/fo/xsd/fo.xsd, where ${frameworks} is a
subdirectory of the Oxygen install directory.

Transformation Scenarios
The following default transformation scenarios are available:
• FO PDF - Transforms an FO document into PDF document using the Apache FOP engine.

The EAD Document Type

EAD Document Type Definition (DTD) is a standard for encoding archival finding aids using Extensible Markup
Language (XML). The standard is maintained in the Network Development and MARC Standards Office of the Library
of Congress (LC) in partnership with the Society of American Archivists.
A file is considered to be an EAD document when its namespace is “urn:isbn:1-931666-22-9” or its public ID is “//DTD
ead.dtd (Encoded Archival Description (EAD) Version 2002)//EN”.
EAD documents use a Relax NG Schema located in ${frameworks}/ead/rng/ead.rng, where ${frameworks}
is a subdirectory of the Oxygen install directory.
The default XML catalog is stored in ${frameworks}/ead/catalog.xml.

Templates
The default templates for EAD are stored in ${frameworks}/ead/templates folder and they can be used for
easily creating an EAD document. These templates are available when creating new documents from templates.
• EAD - NWDA Template 2008-04-08 - New EAD document
Oxygen XML Author | Predefined Document Types | 151

The EPUB Document Type

Three distinct frameworks support the EPUB document type:
• NCX - A declarative global navigation definition.
• OCF - The Open Container Format(OCF) defines a mechanism by which all components of an Open Publication
Structure(OPS) can be combined into a single file-system entity.
• OPF: - The Open Packaging Format(OPF) defines the mechanism by which all components of a published work
conforming to the Open Publication Structure(OPS) standard including metadata, reading order and navigational
information are packaged into an OPS Publication.
Chapter
8
Author Developer Guide
Topics: The Author editor from Oxygen was designed to bridge the gap between the
XML source editing and a friendly user interface. The main achievement is the
• Simple Customization Tutorial fact that the Author combines the power of source editing with the intuitive
• Advanced Customization Tutorial interface of a text editor.
- Document Type Associations This guide is targeted at advanced authors who want to customize the Author
• CSS Support in Oxygen Author editing environment and is included both as a chapter in the Oxygen user manual
• Example Files Listings - The and as a separate document in the Author SDK.
Simple Documentation
Framework Files
• Oxygen XML Author Component

Figure 85: Oxygen Author Visual Editor

Although Oxygen comes with already configured frameworks for DocBook,

DITA, TEI, XHTML, you might need to create a customization of the editor to
handle other types of documents. The common use case is when your
organization holds a collection of XML document types used to define the
structure of internal documents and they need to be visually edited by people
with no experience in working with XML files.
There are several ways to customize the editor:
1. Create a CSS file defining styles for the XML elements the user will work
with, and create XML files that refer the CSS through an xml-stylesheet
processing instruction.
154 | Oxygen XML Author | Author Developer Guide

2. Fully configure a document type association. This involves putting together

the CSSs, the XML schemes, actions, menus, etc, bundling them and
distributing an archive. The CSS and the GUI elements are settings of the
Oxygen Author. The other settings like the templates, catalogs, transformation
scenarios are general settings and are enabled whenever the association is
active, no matter the editing mode (Text, Grid or Author).
Both approaches will be discussed in the following sections.
Oxygen XML Author | Author Developer Guide | 155

Simple Customization Tutorial

The most important elements of a document type customization are represented by an XML Schema to define the XML
structure, the CSS to render the information and the XML instance template which links the first two together.

XML Schema
Let's consider the following XML Schema, test_report.xsd defining a report with results of a testing session.
The report consists of a title, few lines describing the test suite that was run and a list of test results, each with a name
and a boolean value indicating if the test passed or failed.

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="report">
<xs:complexType>
<xs:sequence>
<xs:element ref="title"/>
<xs:element ref="description"/>
<xs:element ref="results"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="title" type="xs:string"/>
<xs:element name="description">
<xs:complexType>
<xs:sequence maxOccurs="unbounded">
<xs:element name="line">
<xs:complexType mixed="true">
<xs:sequence minOccurs="0"
maxOccurs="unbounded">
<xs:element name="important"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="results">
<xs:complexType>
<xs:sequence maxOccurs="unbounded">
<xs:element name="entry">
<xs:complexType>
<xs:sequence>
<xs:element name="test_name"
type="xs:string"/>
<xs:element name="passed"
type="xs:boolean"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
The use-case is that several users are testing a system and must send report results to a content management system.
The Author customization should provide a visual editor for this kind of documents.
156 | Oxygen XML Author | Author Developer Guide

CSS Stylesheet
A set of rules must be defined for describing how the XML document is to be rendered into the Oxygen Author. This
is done using Cascading Style Sheets or CSS on short. CSS is a language used to describe how an HTML or XML
document should be formatted by a browser. CSS is widely used in the majority of websites.
The elements from an XML document are displayed in the layout as a series of boxes. Some of the boxes contain text
and may flow one after the other, from left to right. These are called in-line boxes. There are also other type of boxes
that flow one below the other, like paragraphs. These are called block boxes.
For example consider the way a traditional text editor arranges the text. A paragraph is a block, because it contains a
vertical list of lines. The lines are also blocks. But any block that contains inline boxes is arranging its children in a
horizontal flow. That is why the paragraph lines are also blocks, but the traditional "bold" and "italic" sections are
represented as inline boxes.
The CSS allows us to specify that some elements are displayed as tables. In CSS a table is a complex structure and
consists of rows and cells. The "table" element must have children that have "table-row" style. Similarly, the "row"
elements must contain elements with "table-cell" style.
To make it easy to understand, the following section describes the way each element from the above schema is formatted
using a CSS file. Please note that this is just one from an infinite number of possibilities of formatting the content.

report
This element is the root element of the report document. It should be rendered as a box that contains
all other elements. To achieve this the display type is set to block. Additionally some margins are
set for it. The CSS rule that matches this element is:
report{
display:block;
margin:1em;
}

title
The title of the report. Usually titles have a larger font. The block display should also be used - the
next elements will be placed below it, and change its font to double the size of the normal text.
title {
display:block;
font-size:2em;
}

description
This element contains several lines of text describing the report. The lines of text are displayed one
below the other, so the description will have the same block display. To make it standout the
background color is changed.
description {
display:block;
background-color:#EEEEFF;
color:black;
}

line
A line of text in the description. A specific aspect is not defined for it, just indicate that the display
should be block.
line {
display:block;
}
Oxygen XML Author | Author Developer Guide | 157

important
The important element defines important text from the description. Because it can be mixed with
text, its display property must be set to inline. To make it easier to spot, the text will be emphasized.
important {
display:inline;
font-weight:bold;
}

results
The results element shows the list of test_names and the result for each one. To make it easier
to read, it is displayed as a table with a green border and margins.
results{
display:table;
margin:2em;
border:1px solid green;
}

entry
An item in the results element. The results are displayed as a table so the entry is a row in the table.
Thus, the display is table-row.
entry {
display:table-row;
}

test_name,
The name of the individual test, and its result. They are cells in the results table with display set to
passed
table-cell. Padding and a border are added to emphasize the table grid.

test_name, passed{
display:table-cell;
border:1px solid green;
padding:20px;
}

passed{
font-weight:bold;
}

The full content of the CSS file test_report.css is:

report {
display:block;
margin:1em;
}

description {
display:block;
background-color:#EEEEFF;
color:black;
}

line {
display:block;
}

important {
display:inline;
font-weight:bold;
}
158 | Oxygen XML Author | Author Developer Guide

title {
display:block;
font-size:2em;
}

results{
display:table;
margin:2em;
border:1px solid green;
}

entry {
display:table-row;
}

test_name, passed{
display:table-cell;
border:1px solid green;
padding:20px;
}

passed{
font-weight:bold;
}

Figure 86: A report opened in the Author

The XML Instance Template

Based on the XML Schema and the CSS file the Oxygen Author can help the content author in loading, editing and
validating the test reports. An XML file template must be created, a kind of skeleton, that the users can use as a starting
point for creating new test reports. The template must be generic enough and refer the XML Schema file and the CSS
stylesheet.
This is an example:

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/css" href="test_report.css"?>
Oxygen XML Author | Author Developer Guide | 159

<report xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="test_report.xsd">
<title>Automated test report</title>
<description>
<line>This is the report of the test automatically ran. Each test suite is
ran at 20:00h each
day. Please <important>check</important> the failed ones!</line>
</description>
<results>
<entry>
<test_name>Database connection test</test_name>
<passed>true</passed>
</entry>
<entry>
<test_name>XSLT Transformation test</test_name>
<passed>true</passed>
</entry>
<entry>
<test_name>DTD validation test</test_name>
<passed>false</passed>
</entry>
</results>
</report>
The processing instruction xml-stylesheet associates the CSS stylesheet to the XML file. The href pseudo attribute
contains the URI reference to the stylesheet file. In our case the CSS is in the same directory as the XML file.
The next step is to place the XSD file and the CSS file on a web server and modify the template to use the HTTP URLs,
like this:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css"
href="http://www.mysite.com/reports/test_report.css"?>
<report xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=
"http://www.mysite.com/reports/test_report.xsd">
<title>Test report title</title>
<description>
.......
The alternative is to create an archive containing the test_report.xml, test_report.css and
test_report.xsd and send it to the content authors.

Advanced Customization Tutorial - Document Type Associations

Oxygen Author is highly customizable. Practically you can associate an entire class of documents (grouped logically
by some common features like namespace, root element name or filename) to a bundle consisting of CSS stylesheets,
validation schemas, catalog files, new files templates, transformation scenarios and even custom actions. The bundle is
called document type and the association is called Document Type Association.
In this tutorial a Document Type Association will be created for a set of documents. As an example a light documentation
framework (similar to DocBook) will be created, then complete customization of the Author editor will be set up.
Note: The samples used in this tutorial can be found in the Example Files Listings.

Note: The complete source code can be found in the Simple Documentation Framework project, included in the
Oxygen Author SDK zip available for download on the Oxygen website.

Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.
160 | Oxygen XML Author | Author Developer Guide

Author Settings
You can add a new Document Type Association or edit the properties of an existing one from the Options > Preferences
> Document Type Association option pane. All the changes can be made into the Document type edit dialog.

Figure 87: The Document Type Dialog

You can specify the following properties for a document type:

• Name - The name of the document type.
• Description - The document type description displayed as a tooltip in the Document Type Association table.
• Storage - The location where the document type is saved. If you select the External storage, the document type is
saved in the specified file with a mandatory framework extension, located in a subfolder of the current frameworks
directory. If you select the Internal storage option, the document type data is saved in the current .xpr Oxygen
project file for Project-level Document Type Association Options or in the Oxygen internal options for Global-level
Document Type Association Options. You can change the Document Type Association Options level in the Document
Type Association panel.
• Initial page - Allows you to select the initial editing mode (Text, Author, Grid, Design - available only for the
W3C XML Schema editor) for this document type.
Note: The initial page for an document type can also be customized from the Pages preferences panel located in
Window > Preferences > oXygen > Editor > Pages
Oxygen XML Author | Author Developer Guide | 161

You can specify the association rules used for determining a document type for an opened XML document. A rule can
define one or more conditions. All conditions need to be fulfilled in order for a specific rule to be chosen. Conditions
can specify:
• Namespace - The namespace of the document that matches the document type.
• Root local name of document - The local name of the document that matches the document type.
• File name - The file name (including the extension) of the document that matches the document type.
• Public ID (for DTDs) - The PUBLIC identifier of the document that matches the document type.
• Java class - Name of Java class that is called for finding if the document type should be used for an XML document.
Java class must implement ro.sync.ecss.extensions.api.DocumentTypeCustomRuleMatcher
interface from Author API.
In the Schema tab, you can specify the type and URI of schema used for validation and content completion of all
documents from the document type, when there is no schema detected in the document.
You can choose one of the following schema types:
• DTD
• Relax NG schema (XML syntax)
• Relax NG schema (XML syntax) + Schematron
• Relax NG schema (compact syntax)
• XML Schema
• XML Schema + Schematron rules
• NVDL schema

Configuring Actions, Menus and Toolbars

The Oxygen Author toolbars and menus can be changed to provide a productive editing experience for the content
authors. You can create a set of actions that are specific to a document type.
In the example with the sdf framework, you created the stylesheet and the validation schema. Now let's add some
actions to insert a section and a table. To add a new action, follow the procedure:

1. Open the Options Dialog, and select the Document Types Association option pane.
2. In the lower part of the Document Type Association dialog, click on the Author tab, then select the Actions label.
3. To add a new action click on the Add button.

The Insert Section Action

This section shows all the steps needed to define the Insert Section action. We assume the icon files (Section16.png)
for the menu item and (Section20.png) for the toolbar, are already available. Although you could use the same
icon size for both menu and toolbar, usually the icons from the toolbars are larger than the ones found in the menus.
These files should be placed in the frameworks / sdf directory.
162 | Oxygen XML Author | Author Developer Guide

Figure 88: The Action Edit Dialog

1. Set the ID field to insert_section. This is an unique action identifier.

2. Set the Name field to Insert Section. This will be the action's name, displayed as a tooltip when the action is placed
in the toolbar, or as the menu item name.
3. Set the Menu access key to i. On Windows, the menu items can be accessed using (ALT + letter) combination, when
the menu is visible. The letter is visually represented by underlining the first letter from the menu item name having
the same value.
4. Set the Description field to Insert a section at caret position.
5. Set the Large icon (20x20) field to ${frameworks} / sdf / Section20.png. A good practice is to store the image files
inside the framework directory and use editor variable ${frameworks} to make the image relative to the framework
location.
If the images are bundled in a jar archive together with some Java operations implementation for instance, it might
be convenient for you to refer the images not by the file name, but by their relative path location in the class-path.
If the image file Section20.png is located in the images directory inside the jar archive, you can refer to it by
using /images/Section20.png. The jar file must be added into the Classpath list.
6. Set the Small icon (16x16) field to ${frameworks} / sdf / Section16.png.
Oxygen XML Author | Author Developer Guide | 163

7. Click the text field next to Shortcut key and set it to Ctrl+Shift+S. This will be the key combination to trigger the
action using the keyboard only.
The shortcut is enabled only by adding the action to the main menu of the Author mode which contains all the actions
that the author will have in a menu for the current document type.
8. At this time the action has no functionality added to it. Next you must define how this action operates. An action
can have multiple operation modes, each of them activated by the evaluation of an XPath version 2.0 expression.
The scope of the XPath expression must be only element nodes and attribute nodes of the edited document, otherwise
the expression will not return a match and will not fire the action. For this example we'll suppose you want allow
the action to add a section only if the current element is either a book, article or another section.
a) Set the XPath expression field to:
local-name()='section' or local-name()='book' or
local-name()='article'

b) Set the invoke operation field to InsertFragmentOperation built-in operation, designed to insert an XML
fragment at caret position. This belongs to a set of built-in operations, a complete list of which can be found in
the Author Default Operations section. This set can be expanded with your own Java operation implementations.
c) Configure the arguments section as follows:
<section xmlns=
"http://www.oxygenxml.com/sample/documentation">
<title/>
</section>
insertLocation - leave it empty. This means the location will be at the caret position.
insertPosition - select "Inside".

The Insert Table Action

You will create an action that inserts into the document a table with three rows and three columns. The first row is the
table header. Similarly to the insert section action, you will use the InsertFragmentOperation.
Place the icon files for the menu item and for the toolbar in the frameworks / sdf directory.

1. Set ID field to insert_table.

2. Set Name field to Insert table.
3. Set Menu access key field to t.
4. Set Description field to Adds a section element.
5. Set Toolbar icon to ${frameworks} / sdf / toolbarIcon.png.
6. Set Menu icon to ${frameworks} / sdf / menuIcon.png.
7. Set Shortcut key to Ctrl+Shift+T.
8. Set up the action's functionality:
a) Set XPath expression field to true().
true() is equivalent with leaving this field empty.
b) Set Invoke operation to use InvokeFragmentOperation built-in operation that inserts an XML fragment to the
caret position.
c) Configure operation's arguments as follows:
fragment - set it to:
<table xmlns=
"http://www.oxygenxml.com/sample/documentation">
<header><td/><td/><td/></header>
<tr><td/><td/><td/></tr>
<tr><td/><td/><td/></tr>
</table>
164 | Oxygen XML Author | Author Developer Guide

insertLocation - to add tables at the end of the section use the following code:
ancestor::section/*[last()]
insertPosition - Select After.

Configuring the Toolbars

Now that you have defined the Insert Section action and the Insert Table action, you can add them to the toolbar. You
can configure additional toolbars on which to add your custom actions.
The first thing to check is that the toolbar Author custom actions 1 is displayed when switching to the Author mode:
right click in the upper part of application window, in the area that contains the toolbar buttons and check if Author
custom actions 1 in the displayed menu if it is unchecked.

1. Open the Document Type edit dialog for the SDF framework and select on the Author tab. Next click on the Toolbar
label.

Figure 89: Configuring the Toolbar

The panel is divided in two sections: the left side contains a list of actions, while the right one contains an action
tree, displaying the list of actions added in the toolbar. The special entry called Separator allows you to visually
separate the actions in the toolbar.
2. Select the Insert section action in the left panel section and the Toolbar label in the right panel section, then press
the Add as child button.
3. Select the Insert table action in the left panel section and the Insert section in the right panel section. Press the
Add as sibling button.
4. When opening a Simple Documentation Framework test document in Author mode, the toolbar below will be
displayed at the top of the editor.
Figure 90: Author Custom Actions Toolbar

Tip: If you have many custom toolbar actions or want to group actions according to their category you can add
additional toolbars with custom names and split the actions to better suit your purpose.

Configuring the Main Menu

Defined actions can be grouped into customized menus in the Oxygen menu bar.
Oxygen XML Author | Author Developer Guide | 165

1. Open the Document Type dialog for the SDF framework and click on the Author tab.
2. Click on the Menu label. In the left side you have the list of actions and some special entries:
• Submenu - Creates a submenu. You can nest an unlimited number of menus.
• Separator - Creates a separator into a menu. This way you can logically separate the menu entries.

3. The right side of the panel displays the menu tree with Menu entry as root. To change its name click on this label
to select it, then press the Edit button. Enter SD Framework as name, and D as menu access key.
4. Select the Submenu label in the left panel section and the SD Framework label in the right panel section, then press
the Add as child button. Change the submenu name to Table, using the Edit button.
5. Select the Insert section action in the left panel section and the Table label in the right panel section, then press the
Add as sibling button.
6. Now select the Insert table action in the left panel section and the Table in the right panel section. Press the Add
as child button.

Figure 91: Configuring the Menu

When opening a Simple Documentation Framework test document in Author mode, the menu you created is displayed
in the editor menu bar, between the Debugger and the Document menus. The upper part of the menu contains generic
Author actions (common to all document types) and the two actions created previously (with Insert table under the
Table submenu).

Figure 92: Author Menu

Configuring the Contextual Menu

The contextual menu is shown when you right click (ctrl + mouse click on Mac) in the Author editing area. In fact you
are configuring the bottom part of the menu, since the top part is reserved for a list of generic actions like Copy, Paste,
Undo, etc.

1. Open the Document Type dialog for the SDF framework and click on the Author tab. Next click on the Contextual
Menu label.
2. Follow the same steps as explained in the Configuring the Main Menu, except changing the menu name because the
contextual menu does not have a name.
166 | Oxygen XML Author | Author Developer Guide

Figure 93: Configuring the Contextual Menu

To test it, open the test file, and open the contextual menu. In the lower part there is shown the Table sub-menu and the
Insert section action.
Customize Content Completion
You can customize the content of the following Author controls, adding items (which, when invoked, perform custom
actions) or filtering the default contributed ones:
• Content Completion window;
• Elements view;
• Element Insert menus (from the Outline view or breadcrumb contextual menus).
You can use the content completion customization support in the Simple Documentation Framework following the next
steps:

1. Open the Document type edit dialog for the SDF framework and select the Author tab. Next click on the Content
Completion tab.

Figure 94: Customize content completion

The top side of the Content Completion section contains the list with all the actions defined within the simple
documentation framework and the list of actions that you decided to include in the Content Completion items lists.
The bottom side contains the list with all the items that you decided to remove from the Content Completion items
lists.
2. If you want to add a custom action to the list of current Content Completion items, select the action item from the
Available actions list and press the Add as child or Add as sibling button to include it in the Current
actions list. The following dialog appears, giving you the possibility to select where to provide the selected action:
Oxygen XML Author | Author Developer Guide | 167

Figure 95: Insert action dialog

3. If you want to exclude a certain item from the Content Completion items list, you can use the Add button from
the Filter - Remove content completion items list. The following dialog is displayed, allowing you to input the
item name and to choose the controls that filter it.

Figure 96: Remove item dialog

Author Default Operations

Below are listed all the operations and their arguments.

InsertFragmentOperation
Inserts an XML fragment at the current cursor position. The selection - if there
is one, remains unchanged. The fragment will be inserted in the current context
of the cursor position meaning that if the current XML document uses some
namespace declarations then the inserted fragment must use the same
declarations. The inserted fragment will not be copied and pasted to the cursor
position, but the namespace declarations of the fragment will be adapted if
needed to the existing namespace declarations of the XML document.

InsertOrReplaceFragmentOperation
Similar to InsertFragmentOperation, except it removes the selected content
before inserting the fragment.

InsertOrReplaceTextOperation
Inserts a text at current position removing the selected content, if any.

text
The text section to insert.

SurroundWithFragmentOperation
Surrounds the selected content with a text fragment. Since the fragment can
have multiple nodes, the surrounded content will be always placed in the first
leaf element. If there is no selection, the operation will simply insert the
fragment at the caret position.

SurroundWithTextOperation
This operation has two arguments (two text values) that will be inserted before
and after the selected content. If there is no selected content, the two sections
will be inserted at the caret position. The arguments of the operation are:
168 | Oxygen XML Author | Author Developer Guide

header
The text that will be placed before the selection.

footer
The text that will be placed after the selection.

The arguments of InsertFragmentOperation operation

fragment
The value for this argument is a text. This is parsed by Oxygen Author as it was already in the document
at the caret position. You can use entity references declared in the document and it is namespace aware.
The fragment may have multiple roots.
Note:
You can even use namespace prefixes that are not declared in the inserted fragment, if they are
declared in the document where the insertion is done. For the sake of clarity, you should always
prefix and declare namespaces in the inserted fragment!

Note:
If the fragment contains namespace declarations that are identical to those found in the document,
the namespace declaration attributes will be removed from elements contained by the inserted
fragment.

There are two possible scenarios:

1. Prefixes that are not bound explicitly
For instance, the fragment:
<x:item id="dty2"/>
&ent;
<x:item id="dty3"/>
Can be correctly inserted in the document: ('|' marks the insertion point):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE x:root [
<!ENTITY ent "entity">
]>

<x:root xmlns:x="nsp">
|
</x:root>
Result:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE x:root [
<!ENTITY ent "entity">
]>
<x:root xmlns:x="nsp">
<x:item id="dty2"/>
&ent;
<x:item id="dty3"/>
</x:root>

2. Default namespaces
If there is a default namespace declared in the document and the document fragment does not declare
a namespace, the elements from the fragment are considered to be in no namespace.
Oxygen XML Author | Author Developer Guide | 169

For instance the fragment:

<item id="dty2"/>
<item id="dty3"/>
Inserted in the document:
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="nsp">
|
</root>
Gives the result document:
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="nsp">
<item xmlns="" id="dty2"/>
<item xmlns="" id="dty3"/>
</root>

insertLocation
An XPath expression that is relative to the current node. It selects the reference node for the fragment
insertion.

insertPosition
One of the three constants: "Inside", "After", or "Before" , showing where the insertion is made relative
to the reference node selected by the insertLocation. "Inside" has the meaning of the first child of the
reference node.

The arguments of SurroundWithFragmentOperation

The Author operation SurroundWithFragmentOperation has only one argument:
• fragment -
The XML fragment that will surround the selection. For example let's consider the fragment:
<F>
<A></A>
<B>
<C></C>
</B>
</F>
and the document:
<doc>
<X></X>
<Y></Y>
<Z></Z>
<doc>
Considering the selected content to be surrounded is the sequence of elements X and Y, then the result is:
<doc>
<F>
<A>
<X></X>
<Y></Y>
</A>
<B>
<C></C>
</B>
</F>
<Z></Z>
<doc>
170 | Oxygen XML Author | Author Developer Guide

Because the element A was the first leaf in the fragment, it received the selected content. The fragment was then
inserted in the place of the selection.

How to Add a Custom Action to an Existing Document Type

This task explains how to add a custom Author operation to an existing document type.

1. Download the Author SDK toolkit:http://www.oxygenxml.com/developer.html#XML_Editor_Authoring_SDK

2. Create a Java project with a custom implementation of ro.sync.ecss.extensions.api.AuthorOperation which performs
your custom operation and updates the Author page using our API like:
AuthorAccess.getDocumentController().insertXMLFragment.
3. Pack the operation class inside a Java jar library.
4. Copy the jar library to the OXYGEN_INSTALL_DIR/frameworks/framework_dir directory.
5. Go to Oxygen Preferences > Document Type Association page and set the user role to Developer (you need write
access to the OXYGEN_INSTALLATION_DIR). Edit the document type.
a) In the Classpath tab, add a new entry like: ${frameworks}/docbook/customAction.jar.
b) In the Author tab, add a new action which uses your custom operation.
c) Mount the action to the toolbars or menus.
6. Share the modifications with your colleagues. The files which should be shared are your customAction.jar
library and the .framework configuration file from the
OXYGEN_INSTALL_DIR/frameworks/framework_dir directory.

Java API - Extending Author Functionality through Java

Oxygen Author has a built-in set of operations covering the insertion of text and XML fragments (see the Author Default
Operations) and the execution of XPath expressions on the current document edited in Author mode. However, there
are situations in which you need to extend this set. For instance if you need to enter an element whose attributes should
be edited by the user through a graphical user interface. Or the users must send the selected element content or even the
whole document to a server, for some kind of processing or the content authors must extract pieces of information from
a server and insert it directly into the edited XML document. Or you need to apply an XPath expression on the current
Author document and process the nodes of the result nodeset.
The following sections contain the Java programming interface (API) available to the developers. You will need the
Oxygen Author SDK available on the Oxygen website which includes the source code of the Author operations in the
predefined document types and the full documentation in Javadoc format of the public API available for the developer
of Author custom actions.
The next Java examples are making use of AWT classes. If you are developing extensions for the Oxygen XML Editor
plugin for Eclipse you will have to use their SWT counterparts.
It is assumed you already read the Configuring Actions, Menus, Toolbar section and you are familiar with the Oxygen
Author customization. You can find the XML schema, CSS and XML sample in the Example Files Listings.
Attention:
Make sure the Java classes of your custom Author operations are compiled with the same Java version used by .
Otherwise the classes may not be loaded by the Java virtual machine. For example if you run with a Java 1.5 virtual
machine but the Java classes of your custom Author operations are compiled with a Java 1.6 virtual machine then
the custom operations cannot be loaded and used by the Java 1.5 virtual machine.

Example 1. Step by Step Example. Simple Use of a Dialog from an Author Operation.
Let's start adding functionality for inserting images in the Simple Documentation Framework (shortly SDF). The
images are represented by the image element. The location of the image file is represented by the value of the href
attribute. In the Java implementation you will show a dialog with a text field, in which the user can enter a full URL, or
he can browse for a local file.
Oxygen XML Author | Author Developer Guide | 171

1. Create a new Java project, in your IDE of choice. Create the lib folder in the project folder. Copy the oxygen.jar
file from the {oXygen_installation_directory}/lib folder into the newly created lib folder.
oxygen.jar contains the Java interfaces you have to implement and the API needed to access the Author features.
2. Create the simple.documentation.framework.InsertImageOperation class that implements the
ro.sync.ecss.extensions.api.AuthorOperation interface. This interface defines three methods:
doOperation, getArguments and getDescription

A short description of these methods follows:

• The doOperation method is invoked when the action is performed either by pressing the toolbar button, by
selecting the menu item or by pressing the shortcut key. The arguments taken by this methods can be one of the
following combinations:
• an object of type AuthorAccess and a map
• argument names and values

• The getArguments method is used by Oxygen when the action is configured. It returns the list of arguments
(name and type) that are accepted by the operation.
• The getDescription method is used by Oxygen when the operation is configured. It returns a description
of the operation.
Here is the implementation of these three methods:
/**
* Performs the operation.
*/
public void doOperation(
AuthorAccess authorAccess,
ArgumentsMap arguments)
throws IllegalArgumentException,
AuthorOperationException {

JFrame oxygenFrame = (JFrame) authorAccess.getParentFrame();

String href = displayURLDialog(oxygenFrame);
if (href.length() != 0) {
// Creates the image XML fragment.
String imageFragment =
"<image xmlns='http://www.oxygenxml.com/sample/documentation' href='"

+ href + "'/>";

// Inserts this fragment at the caret position.

int caretPosition = authorAccess.getCaretOffset();
authorAccess.insertXMLFragment(imageFragment, caretPosition);
}
}

/**
* Has no arguments.
*
* @return null.
*/
public ArgumentDescriptor[] getArguments() {
return null;
}

/**
* @return A description of the operation.
*/
public String getDescription() {
return "Inserts an image element. Asks the user for a URL reference.";
}
172 | Oxygen XML Author | Author Developer Guide

Note: The complete source code can be found in the Simple Documentation Framework project, included in
the Oxygen Author SDK zip available for download on the Oxygen website.

Important:
Make sure you always specify the namespace of the inserted fragments.

3. Package the compiled class into a jar file. An example of an ANT script that packages the classes folder content
into a jar archive named sdf.jar is listed below:
<?xml version="1.0" encoding="UTF-8"?>
<project name="project" default="dist">
<target name="dist">
<jar destfile="sdf.jar" basedir="classes">
<fileset dir="classes">
<include name="**/*"/>
</fileset>
</jar>
</target>
</project>

4. Copy the sdf.jar file into the frameworks / sdf folder.

5. Add the sdf.jar to the Author class path. To do this, open the Options > Preferences > Document Type
Association dialog, select SDF and press the Edit button.
6. Select the Classpath tab in the lower part of the dialog and press the Add button . In the displayed dialog enter
the location of the jar file, relative to the Oxygen frameworks folder.
7. Let's create now the action which will use the defined operation. Click on the Actions label. Copy the icon files for
the menu item and for the toolbar in the frameworks / sdf folder.
8. Define the action's properties:
• Set ID to insert_image.
• Set Name to Insert image.
• Set Menu access key to letter i.
• Set Toolbar action to ${frameworks}/sdf/toolbarImage.png.
• Set Menu icon to ${frameworks}/sdf/menuImage.png.
• Set Shortcut key to Ctrl+Shift+i.

9. Now let's set up the operation. You want to add images only if the current element is a section, book or article.
• Set the value of XPath expression to
local-name()='section' or local-name()='book'
or local-name()='article'

• Set the Invoke operation field to simple.documentation.framework.InsertImageOperation.

Oxygen XML Author | Author Developer Guide | 173

Figure 97: Selecting the Operation

10. Add the action to the toolbar, using the Toolbar panel.

To test the action, you can open the sdf_sample.xml sample, then place the caret inside a section between two
para elements for instance. Press the button associated with the action from the toolbar. In the dialog select an image
URL and press OK. The image is inserted into the document.
Example 2. Operations with Arguments. Report from Database Operation.
In this example you will create an operation that connects to a relational database and executes an SQL statement. The
result should be inserted in the edited XML document as a table. To make the operation fully configurable, it will
have arguments for the database connection string, the user name, the password and the SQL expression.

1. Create a new Java project in your preferred IDE. Create the lib folder in the Java project directory and copy the
oxygen.jar file from the {oXygen_installation_directory}/lib directory.
2. Create the class simple.documentation.framework.QueryDatabaseOperation. This class must
implements the ro.sync.ecss.extensions.api.AuthorOperation interface.

import ro.sync.ecss.extensions.api.ArgumentDescriptor;
import ro.sync.ecss.extensions.api.ArgumentsMap;
import ro.sync.ecss.extensions.api.AuthorAccess;
import ro.sync.ecss.extensions.api.AuthorOperation;
import ro.sync.ecss.extensions.api.AuthorOperationException;

public class QueryDatabaseOperation implements AuthorOperation{

3. Now define the operation's arguments. For each of them you will use a String constant representing the argument
name:
private static final String ARG_JDBC_DRIVER ="jdbc_driver";
private static final String ARG_USER ="user";
private static final String ARG_PASSWORD ="password";
174 | Oxygen XML Author | Author Developer Guide

private static final String ARG_SQL ="sql";

private static final String ARG_CONNECTION ="connection";

4. You must describe each of the argument name and type. To do this implement the getArguments method which
will return an array of argument descriptors:
public ArgumentDescriptor[] getArguments() {
ArgumentDescriptor args[] = new ArgumentDescriptor[] {
new ArgumentDescriptor(
ARG_JDBC_DRIVER,
ArgumentDescriptor.TYPE_STRING,
"The name of the Java class that is the JDBC driver."),
new ArgumentDescriptor(
ARG_CONNECTION,
ArgumentDescriptor.TYPE_STRING,
"The database URL connection string."),
new ArgumentDescriptor(
ARG_USER,
ArgumentDescriptor.TYPE_STRING,
"The name of the database user."),
new ArgumentDescriptor(
ARG_PASSWORD,
ArgumentDescriptor.TYPE_STRING,
"The database password."),
new ArgumentDescriptor(
ARG_SQL,
ArgumentDescriptor.TYPE_STRING,
"The SQL statement to be executed.")
};
return args;
}
These names, types and descriptions will be listed in the Arguments table when the operation is configured.
5. When the operation is invoked, the implementation of the doOperation method extracts the arguments, forwards
them to the method that connects to the database and generates the XML fragment. The XML fragment is then
inserted at the caret position.
public void doOperation(AuthorAccess authorAccess, ArgumentsMap map)
throws IllegalArgumentException, AuthorOperationException {

// Collects the arguments.

String jdbcDriver =
(String)map.getArgumentValue(ARG_JDBC_DRIVER);
String connection =
(String)map.getArgumentValue(ARG_CONNECTION);
String user =
(String)map.getArgumentValue(ARG_USER);
String password =
(String)map.getArgumentValue(ARG_PASSWORD);
String sql =
(String)map.getArgumentValue(ARG_SQL);

int caretPosition = authorAccess.getCaretOffset();

try {
authorAccess.insertXMLFragment(
getFragment(jdbcDriver, connection, user, password, sql),
caretPosition);
} catch (SQLException e) {
throw new AuthorOperationException(
"The operation failed due to the following database error: "
+ e.getMessage(), e);
} catch (ClassNotFoundException e) {
throw new AuthorOperationException(
"The JDBC database driver was not found. Tried to load ' "
Oxygen XML Author | Author Developer Guide | 175

+ jdbcDriver + "'", e);

}
}

6. The getFragment method loads the JDBC driver, connects to the database and extracts the data. The result is a
table element from the http://www.oxygenxml.com/sample/documentation namespace. The
header element contains the names of the SQL columns. All the text from the XML fragment is escaped. This
means that the '<' and '&' characters are replaced with the '<' and '&' character entities to ensure the fragment
is well-formed.
private String getFragment(
String jdbcDriver,
String connectionURL,
String user,
String password,
String sql) throws
SQLException,
ClassNotFoundException {

Properties pr = new Properties();

pr.put("characterEncoding", "UTF8");
pr.put("useUnicode", "TRUE");
pr.put("user", user);
pr.put("password", password);

// Loads the database driver.

Class.forName(jdbcDriver);
// Opens the connection
Connection connection =
DriverManager.getConnection(connectionURL, pr);
java.sql.Statement statement =
connection.createStatement();
ResultSet resultSet =
statement.executeQuery(sql);

StringBuffer fragmentBuffer = new StringBuffer();

fragmentBuffer.append(
"<table xmlns=" +
"'http://www.oxygenxml.com/sample/documentation'>");

//
// Creates the table header.
//
fragmentBuffer.append("<header>");
ResultSetMetaData metaData = resultSet.getMetaData();
int columnCount = metaData.getColumnCount();
for (int i = 1; i <= columnCount; i++) {
fragmentBuffer.append("<td>");
fragmentBuffer.append(
xmlEscape(metaData.getColumnName(i)));
fragmentBuffer.append("</td>");
}
fragmentBuffer.append("</header>");

//
// Creates the table content.
//
while (resultSet.next()) {
fragmentBuffer.append("<tr>");
for (int i = 1; i <= columnCount; i++) {
fragmentBuffer.append("<td>");
fragmentBuffer.append(
xmlEscape(resultSet.getObject(i)));
176 | Oxygen XML Author | Author Developer Guide

fragmentBuffer.append("</td>");
}
fragmentBuffer.append("</tr>");
}

fragmentBuffer.append("</table>");

// Cleanup
resultSet.close();
statement.close();
connection.close();
return fragmentBuffer.toString();
}
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the Oxygen Author SDK zip available for download on the Oxygen website.

7. Package the compiled class into a jar file.

8. Copy the jar file and the JDBC driver files into the frameworks / sdf directory.
9. Add the jars to the Author class path. For this, Open the options Document Type Dialog, select SDF and press the
Edit button. Select the Classpath tab in the lower part of the dialog.
10. Click on the Actions label. The action properties are:
• Set ID to clients_report.
• Set Name to Clients Report.
• Set Menu access key to letter r.
• Set Description to Connects to the database and collects the list of clients.
•
Set Toolbar icon to ${frameworks}/sdf/TableDB20.png (image TableDB20.png is already stored in the
frameworks / sdf folder).
• Leave empty the Menu icon.
• Set shortcut key to Ctrl+Shift+C.

11. The action will work only if the current element is a section. Set up the operation as follows:
• Set XPath expression to:
local-name()='section'

• Use the Java operation defined earlier to set the Invoke operation field. Press the Choose button, then select
simple.documentation.framework.QueryDatabaseOperation. Once selected, the list of arguments
is displayed. In the figure below the first argument, jdbc_driver, represents the class name of the MySQL JDBC
driver. The connection string has the URL syntax : jdbc://<database_host>:<database_port>/<database_name>.
The SQL expression used in the example follows, but it can be any valid SELECT expression which can be
applied to the database:
SELECT userID, email FROM users

12. Add the action to the toolbar, using the Toolbar panel.
Oxygen XML Author | Author Developer Guide | 177

Figure 98: Java Operation Arguments Setup

To test the action you can open the sdf_sample.xml sample place the caret inside a section between two para
elements for instance. Press the Create Report button from the toolbar. You can see below the toolbar with the
action button and sample table inserted by the Clients Report action.

Figure 99: Table Content Extracted from the Database

Configuring New File Templates

You will create a set of document templates that the content authors will use as starting points for creating new Simple
Document Framework books and articles.
178 | Oxygen XML Author | Author Developer Guide

Each of the Document Type Associations can point to a directory usually named templates containing the file
templates. All files found here are considered templates for the respective document type. The template name is taken
from the file name, and the template type is detected from the file extension.

1. Create the templates directory into the frameworks / sdf directory. The directory tree for the documentation
framework is now:
oxygen
frameworks
sdf
schema
css
templates

2. Now let's create in this templates directory two files, one for the book template and another for the article template.
The Book.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://www.oxygenxml.com/sample/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:abs="http://www.oxygenxml.com/sample/documentation/abstracts">
<title>Book Template Title</title>
<section>
<title>Section Title</title>
<abs:def/>
<para>This content is copyrighted:</para>
<table>
<header>
<td>Company</td>
<td>Date</td>
</header>
<tr>
<td/>
<td/>
</tr>
</table>
</section>
</book>
The Article.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<article
xmlns="http://www.oxygenxml.com/sample/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<title></title>
<section>
<title></title>
<para></para>
<para></para>
</section>
</article>
You can also use editor variables in the template files' content and they will be expanded when the files are opened.
3. Open the Document Type dialog for the SDF framework and click on the Templates tab. Enter in the Templates
directory text field the value ${frameworksDir} / sdf / templates. As you already seen before, it is
recommended that all the file references made from a Document Type Association to be relative to the
${frameworksDir} directory. Binding a Document Type Association to an absolute file (e. g.:
"C:\some_dir\templates") makes the association difficult to share between users.
4. To test the templates settings, press the File/New menu item to display the New dialog. The names of the two
templates are prefixed with the name of the Document Type Association, in our case SDF. Selecting one of them
should create a new XML file with the content specified in the template file.
Oxygen XML Author | Author Developer Guide | 179

Configuring XML Catalogs

In the XML sample file for SDF you did not use a xsi:schemaLocation attribute, but instead you let the editor use the
schema from the association. However there are cases in which you must refer for instance the location of a schema file
from a remote web location and an Internet connection may not be available. In such cases an XML catalog may be
used to map the web location to a local file system entry. The following procedure presents an example of using an
XML catalogs, by modifying our sdf.xsd XML Schema file from the Example Files Listings.

1. Create a catalog file that will help the parser locate the schema for validating the XML document. The file must map
the location of the schema to a local version of the schema.
Create a new XML file called catalog.xml and save it into the {oXygen_installation_directory}
/ frameworks / sdf directory. The content of the file should be:
<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<system systemId="http://www.oxygenxml.com/SDF/abs.xsd"
uri="schema/abs.xsd"/>
<uri name="http://www.oxygenxml.com/SDF/abs.xsd"
uri="schema/abs.xsd"/>
</catalog>

2. Add catalog files to your Document Type Association using the Catalogs tab from the Document Type dialog.

To test the catalog settings, restart Oxygen and try to validate a new sample Simple Documentation Framework
document. There should be no errors.

The sdf.xsd schema that validates the document refers the other file abs.xsd through an import
element:
<xs:import namespace=
"http://www.oxygenxml.com/sample/documentation/abstracts"
schemaLocation="http://www.oxygenxml.com/SDF/abs.xsd"/>
The schemaLocation attribute references the abs.xsd file:
xsi:schemaLocation="http://www.oxygenxml.com/sample/documentation/abstracts

http://www.oxygenxml.com/SDF/abs.xsd"/>
The catalog mapping is:
http://www.oxygenxml.com/SDF/abs.xsd -> schema/abs.xsd
This means that all the references to http://www.oxygenxml.com/SDF/abs.xsd must be resolved to
the abs.xsd file located in the schema directory. The URI element is used by URI resolvers,
for example for resolving a URI reference used in an XSLT stylesheet.

Configuring Transformation Scenarios

When distributing a framework to the users, it is a good idea to have the transformation scenarios already configured.
This would help the content authors publish their work in different formats. Being contained in the Document Type
Association the scenarios can be distributed along with the actions, menus, toolbars, catalogs, etc.
These are the steps that allow you to create a transformation scenario for your framework.

1. Create a xsl folder inside the frameworks / sdf folder.

The folder structure for the documentation framework should be:
oxygen
frameworks
sdf
180 | Oxygen XML Author | Author Developer Guide

schema
css
templates
xsl

2. Create the sdf.xsl file in the xsl folder. The complete content of the sdf.xsl file is found in the Example
Files Listings.
3. Open the Options/Preferences/Document Type Associations. Open the Document Type dialog for the SDF
framework then choose the Transformation tab. Click the New button.
In the Edit Scenario dialog, fill the following fields:
• Fill in the Name field with SDF to HTML. This will be the name of your transformation scenario.
• Set the XSL URL field to ${frameworks}/sdf/xsl/sdf.xsl.
• Set the Transformer to Saxon 9B.

Figure 100: Configuring a transformation scenario

4. Change to the Output tab. Configure the fields as follows:

• Set the Save as field to ${cfd}/${cfn}.html. This means the transformation output file will have the name
of the XML file and the html extension and will be stored in the same folder.
• Enable the Open in browser option.
• Enable the Saved file option.

Now the scenario is listed in the Transformation tab:

Oxygen XML Author | Author Developer Guide | 181

Figure 101: The transformation tab

To test the transformation scenario you just created, open the SDF XML sample from the Example Files Listings. Click
on the Apply Transformation Scenario button to display the Configure Transformation Dialog. Its scenario
list contains the scenario you defined earlier SDF to HTML. Click it then choose Transform now. The HTML file
should be saved in the same folder as the XML file and displayed in the browser.

Figure 102: Selecting the predefined scenario

Configuring Validation Scenarios

You can distribute a framework with a series of already configured validation scenarios. Also, this provides enhanced
validation support allowing you to use multiple grammars to check the document. For example, you can use Schematron
rules to impose guidelines, otherwise impossible to enforce using conventional validation.
To associate a validation scenario with a specific framework, follow these steps:

1. Open the Options/Preferences/Document Type Associations. Open the Document Type dialog for the SDF
framework, then choose the Validation tab. This tab holds a list of document types for which you can define validation
scenarios. To set one of the validation scenarios as default for a specific document type, select it and press /
Toggle default.
2. Press the New button to add a new scenario.
182 | Oxygen XML Author | Author Developer Guide

3. Press the Add button to add a new validation unit with default settings.
The dialog that lists all validation units of the scenario is opened.

Figure 103: Add / Edit a Validation Unit

The table holds the following information:

4. Edit the URL of the main validation module.

Figure 104: Insert an Editor Variable

5. Select the type of the validated document.

Configuring Extensions
You can add extensions to your Document Type Association using the Extensions tab from the Document Type dialog.

Figure 105: Configure extensions for a document type

Configuring an Extensions Bundle

Starting with Oxygen 10.3 version a single bundle was introduced acting as a provider for all other extensions. The
individual extensions can still be set and if present they take precedence over the single provider, but this practice is
being discouraged and the single provider should be used instead.
184 | Oxygen XML Author | Author Developer Guide

The extensions bundle is represented by the ro.sync.ecss.extensions.api.ExtensionsBundle class.

The provided implementation of the ExtensionsBundle is instantiated when the rules of the Document Type
Association defined for the custom framework match a document opened in the editor. Therefor references to objects
which need to be persistent throughout the application running session must not be kept in the bundle because the next
detection event can result in creating another ExtensionsBundle instance.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

1. Create a new Java project, in your IDE. Create the lib folder in the Java project folder and copy in it the
oxygen.jar file from the {oXygen_installation_directory}/lib folder.
2. Create the class simple.documentation.framework.SDFExtensionsBundle which must extend the
abstract class ro.sync.ecss.extensions.api.ExtensionsBundle.
public class SDFExtensionsBundle extends ExtensionsBundle {

3. A Document Type ID and a short description should be defined first by implementing the methods
getDocumentTypeID and getDescription. The Document Type ID is used to uniquely identify the current
framework. Such an ID must be provided especially if options related to the framework need to be persistently stored
and retrieved between sessions.
public String getDocumentTypeID() {
return "Simple.Document.Framework.document.type";
}

public String getDescription() {

return "A custom extensions bundle used for the Simple Document" +
"Framework document type";
}

4. In order to be notified about the activation of the custom Author extension in relation with an opened document an
ro.sync.ecss.extensions.api.AuthorExtensionStateListener should be implemented. The
activation and deactivation events received by this listener should be used to perform custom initializations and to
register / remove listeners like ro.sync.ecss.extensions.api.AuthorListener,
ro.sync.ecss.extensions.api.AuthorMouseListener or
ro.sync.ecss.extensions.api.AuthorCaretListener. The custom author extension state listener
should be provided by implementing the method createAuthorExtensionStateListener.
public AuthorExtensionStateListener createAuthorExtensionStateListener() {
return new SDFAuthorExtensionStateListener();
}
The AuthorExtensionStateListener is instantiated and notified about the activation of the framework
when the rules of the Document Type Association match a document opened in the Author editor page. The listener
is notified about the deactivation when another framework is activated for the same document, the user switches to
another page or the editor is closed. A complete description and implementation of an
ro.sync.ecss.extensions.api.AuthorExtensionStateListener can be found in the Implementing
an Author Extension State Listener.
If Schema Aware mode is active in Oxygen, all actions that can generate invalid content will be redirected toward
the AuthorSchemaAwareEditingHandler. The handler can either resolve a specific case, let the default
implementation take place or reject the edit entirely by throwing an InvalidEditException. The actions that
are forwarded to this handler include typing, delete or paste.
See the Implementing an Author Schema Aware Editing Handler section for more details about this handler.
5. Customizations of the content completion proposals are permitted by creating a schema manager filter extension.
The interface that declares the methods used for content completion proposals filtering is
ro.sync.contentcompletion.xml.SchemaManagerFilter. The filter can be applied on elements,
attributes or on their values. Responsible for creating the content completion filter is the method
Oxygen XML Author | Author Developer Guide | 185

createSchemaManagerFilter. A new SchemaManagerFilter will be created each time a document

matches the rules defined by the Document Type Association which contains the filter declaration.
public SchemaManagerFilter createSchemaManagerFilter() {
return new SDFSchemaManagerFilter();
}
A detailed presentation of the schema manager filter can be found in Configuring a Content completion handler
section.
6. The Oxygen Author supports link based navigation between documents and document sections. Therefore, if the
document contains elements defined as links to other elements, for example links based on the id attributes, the
extension should provide the means to find the referred content. To do this an implementation of the
ro.sync.ecss.extensions.api.link.ElementLocatorProvider interface should be returned by
the createElementLocatorProvider method. Each time an element pointed by a link needs to be located
the method is invoked.
public ElementLocatorProvider createElementLocatorProvider() {
return new DefaultElementLocatorProvider();
}
The section that explains how to implement an element locator provider is Configuring a Link target element finder.
7. The drag and drop functionality can be extended by implementing the
ro.sync.exml.editor.xmleditor.pageauthor.AuthorDnDListener interface. Relevant methods
from the listener are invoked when the mouse is dragged, moved over, or exits the author editor page, when the drop
action changes, and when the drop occurs. Each method receives the DropTargetEvent containing information
about the drag and drop operation. The drag and drop extensions are available on Author page for both Oxygen
Eclipse plugin and standalone application. The Text page corresponding listener is available only for Oxygen Eclipse
plugin. The methods corresponding to each implementation are: createAuthorAWTDndListener,
createTextSWTDndListener and createAuthorSWTDndListener.
public AuthorDnDListener createAuthorAWTDndListener() {
return new SDFAuthorDndListener();
}
For more details about the Author drag and drop listeners see the Configuring a custom Drag and Drop listener
section.
8. Another extension which can be included in the bundle is the reference resolver. In our case the references are
represented by the ref element and the attribute indicating the referred resource is location. To be able to obtain the
content of the referred resources you will have to implement a Java extension class which implements the
ro.sync.ecss.extensions.api.AuthorReferenceResolver. The method responsible for creating
the custom references resolver is createAuthorReferenceResolver. The method is called each time a
document opened in an Author editor page matches the Document Type Association where the extensions bundle
is defined. The instantiated references resolver object is kept and used until another extensions bundle corresponding
to another Document Type is activated as result of the detection process.
public AuthorReferenceResolver createAuthorReferenceResolver() {
return new ReferencesResolver();
}
A more detailed description of the references resolver can be found in the Configuring a References Resolver section.
9. To be able to dynamically customize the default CSS styles for a certain AuthorNode an implementation of the
ro.sync.ecss.extensions.api.StylesFilter can be provided. The extensions bundle method responsible
for creating the StylesFilter is createAuthorStylesFilter. The method is called each time a document
opened in an Author editor page matches the document type association where the extensions bundle is defined. The
instantiated filter object is kept and used until another extensions bundle corresponding to another Document Type
is activated as a result of the detection process.
public StylesFilter createAuthorStylesFilter() {
return new SDFStylesFilter();
}
186 | Oxygen XML Author | Author Developer Guide

See the Configuring CSS styles filter section for more details about the styles filter extension.
10. In order to edit data in custom tabular format implementations of the
ro.sync.ecss.extensions.api.AuthorTableCellSpanProvider and the
ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider interfaces should be provided.
The two methods from the ExtensionsBundle specifying these two extension points are
createAuthorTableCellSpanProvider and createAuthorTableColumnWidthProvider.
public AuthorTableCellSpanProvider createAuthorTableCellSpanProvider() {
return new TableCellSpanProvider();
}

public AuthorTableColumnWidthProvider
createAuthorTableColumnWidthProvider() {
return new TableColumnWidthProvider();
}
The two table information providers are not reused for different tables. The methods are called for each table in the
document so new instances should be provided every time. Read more about the cell span and column width
information providers in Configuring a Table Cell Span Provider and Configuring a Table Column Width Provider
sections.
If the functionality related to one of the previous extension point does not need to be modified then the developed
ExtensionsBundle should not override the corresponding method and leave the default base implementation
to return null.
11. Package the compiled class into a jar file.
12. Copy the jar file into the frameworks / sdf directory.
13. Add the jar file to the Author class path.
14. Register the Java class by clicking on the Extensions tab. Press the Choose button and select from the displayed
dialog the name of the class: SDFExtensionsBundle.
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the Oxygen Author SDK zip available for download on the Oxygen website.

Preserve Style Markup on Copy and Paste from External Applications

Styled content can be inserted in the Author editor by copying or dragging it from:
• Office-type applications (Microsoft Word and Microsoft Excel, OpenOffice.org Writer and OpenOffice.org
Calc);
• Web browsers (like Mozilla Firefox or Microsoft Internet Explorer);
• the Data Source Explorer view (where resources are available from WebDAV or CMS servers).
The styles and general layout of the copied content like: sections with headings, tables, list items, bold and italic text,
hyperlinks, etc. are preserved by the paste operation by transforming them to the equivalent XML markup of the target
document type. This is available by default in the following predefined document types: DITA, DocBook 4, DocBook
5, TEI 4, TEI 5, XHTML.
For other document types the default behavior of the paste operation is to keep only the text content without the styling
markup but it can be customized by setting an XSLT stylesheet in that document type. The XSLT stylesheet should
accept as input an XHTML flavor of the copied content and transform it to the equivalent XML markup that is appropriate
for the target document type of the paste operation. The stylesheet is set up by implementing the
getImporterStylesheetFileName method of an instance object of the
AuthorExternalObjectInsertionHandler class which is returned by the
createExternalObjectInsertionHandler method of the ExtensionsBundle instance of the target
document type.
Oxygen XML Author | Author Developer Guide | 187

Implementing an Author Extension State Listener

The ro.sync.ecss.extensions.api.AuthorExtensionStateListener implementation is notified
when the Author extension where the listener is defined is activated or deactivated in the Document Type detection
process.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

import ro.sync.ecss.extensions.api.AuthorAccess;
import ro.sync.ecss.extensions.api.AuthorExtensionStateListener;

public class SDFAuthorExtensionStateListener implements

AuthorExtensionStateListener {
private AuthorListener sdfAuthorDocumentListener;
private AuthorMouseListener sdfMouseListener;
private AuthorCaretListener sdfCaretListener;
private OptionListener sdfOptionListener;
The activation event received by this listener when the rules of the Document Type Association match a document
opened in the Author editor page, should be used to perform custom initializations and to register listeners like
ro.sync.ecss.extensions.api.AuthorListener,
ro.sync.ecss.extensions.api.AuthorMouseListener or
ro.sync.ecss.extensions.api.AuthorCaretListener.
public void activated(AuthorAccess authorAccess) {
// Get the value of the option.
String option = authorAccess.getOptionsStorage().getOption(
"sdf.custom.option.key", "");
// Use the option for some initializations...

// Add an option listener.

authorAccess.getOptionsStorage().addOptionListener(sdfOptionListener);

// Add author document listeners.

sdfAuthorDocumentListener = new SDFAuthorListener();
authorAccess.getDocumentController().addAuthorListener(
sdfAuthorDocumentListener);

// Add mouse listener.

sdfMouseListener = new SDFAuthorMouseListener();
authorAccess.getEditorAccess().addAuthorMouseListener(sdfMouseListener);

// Add caret listener.

sdfCaretListener = new SDFAuthorCaretListener();
authorAccess.getEditorAccess().addAuthorCaretListener(sdfCaretListener);

// Other custom initializations...

}
The authorAccess parameter received by the activated method can be used to gain access to Author specific actions
and informations related to components like the editor, document, workspace, tables, or the change tracking manager.
If options specific to the custom developed Author extension need to be stored or retrieved, a reference to the
OptionsStorage can be obtained by calling the getOptionsStorage method from the author access. The same
object can be used to register OptionListener listeners. An option listener is registered in relation with an option
key and will be notified about the value changes of that option.
An AuthorListener can be used if events related to the Author document modifications are of interest. The listener
can be added to the AuthorDocumentController. A reference to the document controller is returned by the
188 | Oxygen XML Author | Author Developer Guide

getDocumentController method from the author access. The document controller can also be used to perform
operations involving document modifications.
To provide access to Author editor component related functionality and information, the author access has a reference
to the AuthorEditorAccess that can be obtained when calling the getEditorAccess method. At this level
AuthorMouseListener and AuthorCaretListener can be added which will be notified about mouse and
caret events occurring in the Author editor page.
The deactivation event is received when another framework is activated for the same document, the user switches to
another editor page or the editor is closed. The deactivate method is typically used to unregister the listeners
previously added on the activate method and to perform other actions. For example, options related to the deactivated
author extension can be saved at this point.
public void deactivated(AuthorAccess authorAccess) {
// Store the option.
authorAccess.getOptionsStorage().setOption(
"sdf.custom.option.key", optionValue);

// Remove the option listener.

authorAccess.getOptionsStorage().removeOptionListener(sdfOptionListener);

// Remove document listeners.

authorAccess.getDocumentController().removeAuthorListener(
sdfAuthorDocumentListener);

// Remove mouse listener.

authorAccess.getEditorAccess().removeAuthorMouseListener(sdfMouseListener);

// Remove caret listener.

authorAccess.getEditorAccess().removeAuthorCaretListener(sdfCaretListener);

// Other actions...

Implementing an Author Schema Aware Editing Handler

You can implement your own handler for actions like typing, delete or paste by providing an implementation of
ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandler. The Schema Aware Editing
must be On or Custom in order for this handler to be called. The handler can either resolve a specific case, let the default
implementation take place or reject the edit entirely by throwing an InvalidEditException.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

package simple.documentation.framework.extensions;

/**
* Specific editing support for SDF documents.
* Handles typing and paste events inside section and tables.
*/
public class SDFSchemaAwareEditingHandler implements
AuthorSchemaAwareEditingHandler {
Typing events can be handled using the handleTyping method. For example, the
SDFSchemaAwareEditingHandler checks if the schema is not a learned one, was loaded successfully and Smart
Paste is active. If these conditions are met, the event will be handled.
/**
* @see
ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandler#handleTyping(int,
char, ro.sync.ecss.extensions.api.AuthorAccess)
*/
Oxygen XML Author | Author Developer Guide | 189

public boolean handleTyping(int offset, char ch, AuthorAccess authorAccess)

throws InvalidEditException {
boolean handleTyping = false;
AuthorSchemaManager authorSchemaManager =
authorAccess.getDocumentController().getAuthorSchemaManager();
if (!authorSchemaManager.isLearnSchema() &&
!authorSchemaManager.hasLoadingErrors() &&
authorSchemaManager.getAuthorSchemaAwareOptions().isEnableSmartTyping())
{
try {
AuthorDocumentFragment characterFragment =

authorAccess.getDocumentController().createNewDocumentTextFragment(String.valueOf(ch));

handleTyping = handleInsertionEvent(offset, new AuthorDocumentFragment[]

{characterFragment}, authorAccess);
} catch (AuthorOperationException e) {
throw new InvalidEditException(e.getMessage(), "Invalid typing event: " +
e.getMessage(), e, false);
}
}
return handleTyping;
}
Implementing the AuthorSchemaAwareEditingHandler gives the possibility to handle other events like: the
keyboard delete event at the given offset (using Delete or Backspace keys), delete element tags, delete selection, join
elements or paste fragment.
Note: The complete source code can be found in the Simple Documentation Framework project, included in the
Oxygen Author SDK zip available for download on the Oxygen website.

Configuring a Content Completion Handler

You can filter or contribute to items offered for content completion by implementing the
ro.sync.contentcompletion.xml.SchemaManagerFilter interface.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

import java.util.List;

import ro.sync.contentcompletion.xml.CIAttribute;
import ro.sync.contentcompletion.xml.CIElement;
import ro.sync.contentcompletion.xml.CIValue;
import ro.sync.contentcompletion.xml.Context;
import ro.sync.contentcompletion.xml.SchemaManagerFilter;
import ro.sync.contentcompletion.xml.WhatAttributesCanGoHereContext;
import ro.sync.contentcompletion.xml.WhatElementsCanGoHereContext;
import ro.sync.contentcompletion.xml.WhatPossibleValuesHasAttributeContext;

public class SDFSchemaManagerFilter implements SchemaManagerFilter {

You can implement the various callbacks of the interface either by returning the default values given by Oxygen or by
contributing to the list of proposals. The filter can be applied on elements, attributes or on their values. Attributes filtering
can be implemented using the filterAttributes method and changing the default content completion list of
ro.sync.contentcompletion.xml.CIAttribute for the element provided by the current
ro.sync.contentcompletion.xml.WhatAttributesCanGoHereContext context. For example, the
SDFSchemaManagerFilter checks if the element from the current context is the table element and adds the
frame attribute to the table list of attributes.
/**
* Filter attributes of the "table" element.
190 | Oxygen XML Author | Author Developer Guide

*/
public List<CIAttribute> filterAttributes(List<CIAttribute> attributes,
WhatAttributesCanGoHereContext context) {
// If the element from the current context is the 'table' element add the
// attribute named 'frame' to the list of default content completion proposals

if (context != null) {
ContextElement contextElement = context.getParentElement();
if ("table".equals(contextElement.getQName())) {
CIAttribute frameAttribute = new CIAttribute();
frameAttribute.setName("frame");
frameAttribute.setRequired(false);
frameAttribute.setFixed(false);
frameAttribute.setDefaultValue("void");
if (attributes == null) {
attributes = new ArrayList<CIAttribute>();
}
attributes.add(frameAttribute);
}
}
return attributes;
}
The elements that can be inserted in a specific context can be filtered using the filterElements method. The
SDFSchemaManagerFilter uses this method to replace the td child element with the th element when header
is the current context element.
public List<CIElement> filterElements(List<CIElement> elements,
WhatElementsCanGoHereContext context) {
// If the element from the current context is the 'header' element remove the

// 'td' element from the list of content completion proposals and add the
// 'th' element.
if (context != null) {
Stack<ContextElement> elementStack = context.getElementStack();
if (elementStack != null) {
ContextElement contextElement = context.getElementStack().peek();
if ("header".equals(contextElement.getQName())) {
if (elements != null) {
for (Iterator<CIElement> iterator = elements.iterator();
iterator.hasNext();) {
CIElement element = iterator.next();
// Remove the 'td' element
if ("td".equals(element.getQName())) {
elements.remove(element);
break;
}
}
} else {
elements = new ArrayList<CIElement>();
}
// Insert the 'th' element in the list of content completion proposals
CIElement thElement = new SDFElement();
thElement.setName("th");
elements.add(thElement);
}
}
} else {
// If the given context is null then the given list of content completion
elements contains
// global elements.
}
return elements;
}
Oxygen XML Author | Author Developer Guide | 191

The elements or attributes values can be filtered using the filterElementValues or filterAttributeValues
methods.
Note: The complete source code can be found in the Simple Documentation Framework project, included in the
Oxygen Author SDK zip available for download on the Oxygen website.

Configuring a Link target element finder

The link target reference finder represents the support for finding references from links which indicate specific elements
inside an XML document. This support will only be available if a schema is associated with the document type.
If you do not define a custom link target reference finder, the DefaultElementLocatorProvider implementation
will be used by default. The interface which should be implemented for a custom link target reference finder is
ro.sync.ecss.extensions.api.link.ElementLocatorProvider. As an alternative, the
ro.sync.ecss.extensions.commons.DefaultElementLocatorProvider implementation can also be
extended.
The used ElementLocatorProvider will be queried for an ElementLocator when a link location must be
determined (when a link is clicked). Then, to find the corresponding (linked) element, the obtained ElementLocator
will be queried for each element from the document.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

The DefaultElementLocatorProvider implementation

The DefaultElementLocatorProvider implementation offers support for the most common types of links:
• links based on ID attribute values
• XPointer element() scheme

The method getElementLocator determines what ElementLocator should be used. In the default implementation
it checks if the link is an XPointer element() scheme otherwise it assumes it is an ID. A non-null IDTypeVerifier
will always be provided if a schema is associated with the document type.
The link string argument is the "anchor" part of the of the URL which is composed from the value of the link property
specified for the link element in the CSS.
public ElementLocator getElementLocator(IDTypeVerifier idVerifier,
String link) {
ElementLocator elementLocator = null;
try {
if(link.startsWith("element(")){
// xpointer element() scheme
elementLocator = new XPointerElementLocator(idVerifier, link);
} else {
// Locate link element by ID
elementLocator = new IDElementLocator(idVerifier, link);
}
} catch (ElementLocatorException e) {
logger.warn("Exception when create element locator for link: "
+ link + ". Cause: " + e, e);
}
return elementLocator;
}
The XPointerElementLocator implementation
XPointerElementLocator is an implementation of the abstract class
ro.sync.ecss.extensions.api.link.ElementLocator for links that have one of the following XPointer
element() scheme patterns:
192 | Oxygen XML Author | Author Developer Guide

element(elementID)
Locate the element with the specified id.

element(/1/2/3)
A child sequence appearing alone identifies an element by means of stepwise
navigation, which is directed by a sequence of integers separated by slashes (/); each
integer n locates the nth child element of the previously located element.

element(elementID/3/4)
A child sequence appearing after a NCName identifies an element by means of stepwise
navigation, starting from the element located by the given name.

The constructor separates the id/integers which are delimited by slashes(/) into a sequence of identifiers (an XPointer
path). It will also check that the link has one of the supported patterns of the XPointer element() scheme.
public XPointerElementLocator(IDTypeVerifier idVerifier, String link)
throws ElementLocatorException {
super(link);
this.idVerifier = idVerifier;

link = link.substring("element(".length(), link.length() - 1);

StringTokenizer stringTokenizer = new StringTokenizer(link, "/", false);

xpointerPath = new String[stringTokenizer.countTokens()];
int i = 0;
while (stringTokenizer.hasMoreTokens()) {
xpointerPath[i] = stringTokenizer.nextToken();
boolean invalidFormat = false;

// Empty xpointer component is not supported

if(xpointerPath[i].length() == 0){
invalidFormat = true;
}

if(i > 0){

try {
Integer.parseInt(xpointerPath[i]);
} catch (NumberFormatException e) {
invalidFormat = true;
}
}

if(invalidFormat){
throw new ElementLocatorException(
"Only the element() scheme is supported when locating XPointer links."
+ "Supported formats: element(elementID), element(/1/2/3),
element(elemID/2/3/4).");
}
i++;
}

if(Character.isDigit(xpointerPath[0].charAt(0))){
// This is the case when xpointer have the following pattern /1/5/7
xpointerPathDepth = xpointerPath.length;
} else {
// This is the case when xpointer starts with an element ID
xpointerPathDepth = -1;
startWithElementID = true;
}
}
The method startElement will be invoked at the beginning of every element in the XML document(even when the
element is empty). The arguments it takes are
Oxygen XML Author | Author Developer Guide | 193

uri
The namespace URI, or the empty string if the element has no namespace URI or if
namespace processing is disabled.

localName
Local name of the element.

qName
Qualified name of the element.

atts
Attributes attached to the element. If there are no attributes, this argument will be empty.

The method returns true if the processed element is found to be the one indicated by the link.
The XPointerElementLocator implementation of the startElement will update the depth of the current
element and keep the index of the element in its parent. If the xpointerPath starts with an element ID then the
current element ID is verified to match the specified ID. If this is the case the depth of the XPointer is updated taking
into account the depth of the current element.
If the XPointer path depth is the same as the current element depth then the kept indices of the current element path are
compared to the indices in the XPointer path. If all of them match then the element has been found.
public boolean startElement(String uri, String localName,
String name, Attr[] atts) {
boolean linkLocated = false;
// Increase current element document depth
startElementDepth ++;

if (endElementDepth != startElementDepth) {
// The current element is the first child of the parent
currentElementIndexStack.push(new Integer(1));
} else {
// Another element in the parent element
currentElementIndexStack.push(new Integer(lastIndexInParent + 1));
}

if (startWithElementID) {
// This the case when xpointer path starts with an element ID.
String xpointerElement = xpointerPath[0];
for (int i = 0; i < atts.length; i++) {
if(xpointerElement.equals(atts[i].getValue())){
if(idVerifier.hasIDType(
localName, uri, atts[i].getQName(), atts[i].getNamespace())){
xpointerPathDepth = startElementDepth + xpointerPath.length - 1;
break;
}
}
}
}

if (xpointerPathDepth == startElementDepth){
// check if xpointer path matches with the current element path
linkLocated = true;
try {
int xpointerIdx = xpointerPath.length - 1;
int stackIdx = currentElementIndexStack.size() - 1;
int stopIdx = startWithElementID ? 1 : 0;
while (xpointerIdx >= stopIdx && stackIdx >= 0) {
int xpointerIndex = Integer.parseInt(xpointerPath[xpointerIdx]);
int currentElementIndex =
((Integer)currentElementIndexStack.get(stackIdx)).intValue();
if(xpointerIndex != currentElementIndex) {
linkLocated = false;
break;
194 | Oxygen XML Author | Author Developer Guide

xpointerIdx--;
stackIdx--;
}

} catch (NumberFormatException e) {
logger.warn(e,e);
}
}
return linkLocated;
}
The method endElement will be invoked at the end of every element in the XML document (even when the element
is empty).
The XPointerElementLocator implementation of the endElement updates the depth of the current element
path and the index of the element in its parent.
public void endElement(String uri, String localName, String name) {
endElementDepth = startElementDepth;
startElementDepth --;
lastIndexInParent = ((Integer)currentElementIndexStack.pop()).intValue();
}
The IDElementLocator implementation
The IDElementLocator is an implementation of the abstract class
ro.sync.ecss.extensions.api.link.ElementLocator for links that use an id.
The constructor only assigns field values and the method endElement is empty for this implementation.
The method startElement checks each of the element's attribute values and when one matches the link, it considers
the element found if one of the following conditions is satisfied:
• the qualified name of the attribute is xml:id
• the attribute type is ID

The attribute type is checked with the help of the method IDTypeVerifier.hasIDType.
public boolean startElement(String uri, String localName,
String name, Attr[] atts) {
boolean elementFound = false;
for (int i = 0; i < atts.length; i++) {
if (link.equals(atts[i].getValue())) {
if("xml:id".equals(atts[i].getQName())) {
// xml:id attribute
elementFound = true;
} else {
// check if attribute has ID type
String attrLocalName =
ExtensionUtil.getLocalName(atts[i].getQName());
String attrUri = atts[i].getNamespace();
if (idVerifier.hasIDType(localName, uri, attrLocalName, attrUri)) {
elementFound = true;
}
}
}
}

return elementFound;
}
Oxygen XML Author | Author Developer Guide | 195

Creating a customized link target reference finder

If you need to create a custom link target reference finder you can do so by creating the class which will implement the
ro.sync.ecss.extensions.api.link.ElementLocatorProvider interface. As an alternative, your
class could extend ro.sync.ecss.extensions.commons.DefaultElementLocatorProvider, the
default implementation.
Note: The complete source code of the DefaultElementLocator, IDElementLocator or
XPointerElementLocator can be found in the Oxygen Default Frameworks project, included in the Oxygen
Author SDK zip available for download on the Oxygen website.

Configuring a custom Drag and Drop listener

You can add your own drag and drop listener implementation of ro.sync.ecss.extensions.api.DnDHandler.
You can choose from three interfaces to implement depending on whether you are using the framework with the Oxygen
Eclipse plugin or the standalone version or if you want to add the handler for the Text or Author pages.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

Table 1: Interfaces for the DnD listener

Interface Description
ro.sync.exml.editor.xmleditor.pageauthor.AuthorCustomDnDHandler
Receives callbacks from the Oxygen standalone application
for Drag And Drop in Author mode.

com.oxygenxml.editor.editors.author.AuthorDnDListener
Receives callbacks from the Oxygen Eclipse plugin for
Drag And Drop in Author mode.

com.oxygenxml.editor.editors.TextDnDListener
Receives callbacks from the Oxygen Eclipse plugin for
Drag And Drop in Text mode.

Configuring a References Resolver

You need to provide a handler for resolving references and obtain the content they refer. In our case the element which
has references is ref and the attribute indicating the referred resource is location. You will have to implement a Java
extension class for obtaining the referred resources.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

1. Create the class simple.documentation.framework.ReferencesResolver. This class must implement

the ro.sync.ecss.extensions.api.AuthorReferenceResolver interface.
import ro.sync.ecss.extensions.api.AuthorReferenceResolver;
import ro.sync.ecss.extensions.api.AuthorAccess;
import ro.sync.ecss.extensions.api.node.AttrValue;
import ro.sync.ecss.extensions.api.node.AuthorElement;
import ro.sync.ecss.extensions.api.node.AuthorNode;

public class ReferencesResolver

implements AuthorReferenceResolver {

2. The hasReferences method verifies if the handler considers the node to have references. It takes as argument
an AuthorNode that represents the node which will be verified. The method will return true if the node is
196 | Oxygen XML Author | Author Developer Guide

considered to have references. In our case, to be a reference the node must be an element with the name ref and it
must have an attribute named location.
public boolean hasReferences(AuthorNode node) {
boolean hasReferences = false;
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
hasReferences = attrValue != null;
}
}
return hasReferences;
}

3. The method getDisplayName returns the display name of the node that contains the expanded referred content.
It takes as argument an AuthorNode that represents the node for which the display name is needed. The referred
content engine will ask this AuthorReferenceResolver implementation what is the display name for each
node which is considered a reference. In our case the display name is the value of the location attribute from the ref
element.
public String getDisplayName(AuthorNode node) {
String displayName = "ref-fragment";
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
displayName = attrValue.getValue();
}
}
}
return displayName;
}

4. The method resolveReference resolves the reference of the node and returns a SAXSource with the parser
and the parser's input source. It takes as arguments an AuthorNode that represents the node for which the reference
needs resolving, the systemID of the node, the AuthorAccess with access methods to the Author data model and
a SAX EntityResolver which resolves resources that are already opened in another editor or resolve resources
through the XML catalog. In the implementation you need to resolve the reference relative to the systemID, and
create a parser and an input source over the resolved reference.
public SAXSource resolveReference(
AuthorNode node,
String systemID,
AuthorAccess authorAccess,
EntityResolver entityResolver) {
SAXSource saxSource = null;

if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
String attrStringVal = attrValue.getValue();
try {
URL absoluteUrl = new URL(new URL(systemID),
authorAccess.correctURL(attrStringVal));

InputSource inputSource = entityResolver.resolveEntity(null,

absoluteUrl.toString());
if(inputSource == null) {
inputSource = new InputSource(absoluteUrl.toString());
}
Oxygen XML Author | Author Developer Guide | 197

XMLReader xmlReader = authorAccess.newNonValidatingXMLReader();

xmlReader.setEntityResolver(entityResolver);

saxSource = new SAXSource(xmlReader, inputSource);

} catch (MalformedURLException e) {
logger.error(e, e);
} catch (SAXException e) {
logger.error(e, e);
} catch (IOException e) {
logger.error(e, e);
}
}
}
}

return saxSource;
}

5. The method getReferenceUniqueID should return an unique identifier for the node reference. The unique
identifier is used to avoid resolving the references recursively. The method takes as argument an AuthorNode that
represents the node with the reference. In the implementation the unique identifier is the value of the location attribute
from the ref element.
public String getDisplayName(AuthorNode node) {
String displayName = "ref-fragment";
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
displayName = attrValue.getValue();
}
}
}
return displayName;
}

6. The method getReferenceSystemIDshould return the systemID of the referred content. It takes as arguments
an AuthorNode that represents the node with the reference and the AuthorAccess with access methods to the
Author data model. In the implementation you use the value of the location attribute from the ref element and resolve
it relatively to the XML base URL of the node.
public String getReferenceSystemID(AuthorNode node,
AuthorAccess authorAccess) {
String systemID = null;
if (node.getType() == AuthorNode.NODE_TYPE_ELEMENT) {
AuthorElement element = (AuthorElement) node;
if ("ref".equals(element.getLocalName())) {
AttrValue attrValue = element.getAttribute("location");
if (attrValue != null) {
String attrStringVal = attrValue.getValue();
try {
URL absoluteUrl = new URL(node.getXMLBaseURL(),
authorAccess.correctURL(attrStringVal));
systemID = absoluteUrl.toString();
} catch (MalformedURLException e) {
logger.error(e, e);
}
}
}
}
198 | Oxygen XML Author | Author Developer Guide

return systemID;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the Oxygen Author SDK zip available for download on the Oxygen website.

In the listing below, the XML document contains the ref element:
<ref location="referred.xml">Reference</ref>

When no reference resolver is specified, the reference has the following layout:

Figure 106: Reference with no specified reference resolver

When the above implementation is configured, the reference has the expected layout:

Figure 107: Reference with reference resolver

Configuring CSS Styles Filter

You can modify the CSS styles for each ro.sync.ecss.extensions.api.node.AuthorNode rendered in
the Author page using an implementation of ro.sync.ecss.extensions.api.StylesFilter. You can
implement the various callbacks of the interface either by returning the default value given by Oxygen or by contributing
to the value. The received styles ro.sync.ecss.css.Styles can be processed and values can be overwritten with
your own. For example you can override the KEY_BACKGROUND_COLOR style to return your own implementation of
ro.sync.exml.view.graphics.Color or override the KEY_FONT style to return your own implementation
of ro.sync.exml.view.graphics.Font.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

For instance in our simple document example the filter can change the value of the KEY_FONT property for the table
element:

package simple.documentation.framework;

import ro.sync.ecss.css.Styles;
import ro.sync.ecss.extensions.api.StylesFilter;
import ro.sync.ecss.extensions.api.node.AuthorNode;
import ro.sync.exml.view.graphics.Font;

public class SDFStylesFilter implements StylesFilter {

public Styles filter(Styles styles, AuthorNode authorNode) {

if (AuthorNode.NODE_TYPE_ELEMENT == authorNode.getType()
&& "table".equals(authorNode.getName())) {
styles.setProperty(Styles.KEY_FONT, new Font(null, Font.BOLD, 12));
}
return styles;
Oxygen XML Author | Author Developer Guide | 199

}
}

Configuring a Table Column Width Provider

In the documentation framework the table element as well as the table columns can have specified widths. In order
for these widths to be considered by Oxygen Author we need to provide the means to determine them. As explained in
the Styling the Table Element section which describes the CSS properties needed for defining a table, if you use the
table element attribute width Oxygen can determine the table width automatically. In this example the table has col
elements with width attributes that are not recognized by default. You will need to implement a Java extension class to
determine the column widths.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

1. Create the class simple.documentation.framework.TableColumnWidthProvider. This class must

implement the ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider interface.
import ro.sync.ecss.extensions.api.AuthorAccess;
import ro.sync.ecss.extensions.api.AuthorOperationException;
import ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider;
import ro.sync.ecss.extensions.api.WidthRepresentation;
import ro.sync.ecss.extensions.api.node.AuthorElement;

public class TableColumnWidthProvider

implements AuthorTableColumnWidthProvider {

2. Method init is taking as argument an AuthorElement that represents the XML table element. In our case
the column widths are specified in col elements from the table element. In such cases you must collect the span
information by analyzing the table element.
public void init(AuthorElement tableElement) {
this.tableElement = tableElement;
AuthorElement[] colChildren =
tableElement.getElementsByLocalName("customcol");
if (colChildren != null && colChildren.length > 0) {
for (int i = 0; i < colChildren.length; i++) {
AuthorElement colChild = colChildren[i];
if (i == 0) {
colsStartOffset = colChild.getStartOffset();
}
if (i == colChildren.length - 1) {
colsEndOffset = colChild.getEndOffset();
}
// Determine the 'width' for this col.
AttrValue colWidthAttribute = colChild.getAttribute("width");
String colWidth = null;
if (colWidthAttribute != null) {
colWidth = colWidthAttribute.getValue();
// Add WidthRepresentation objects for the columns this 'customcol'
specification
// spans over.
colWidthSpecs.add(new WidthRepresentation(colWidth, true));
}
}
}
}

3. The method isTableAcceptingWidth should check if the table cells are td.
public boolean isTableAcceptingWidth(String tableCellsTagName) {
return "td".equals(tableCellsTagName);
}
200 | Oxygen XML Author | Author Developer Guide

4. The method isTableAndColumnsResizable should check if the table cells are td. This method determines
if the table and its columns can be resized by dragging the edge of a column.
public boolean isTableAndColumnsResizable(String tableCellsTagName) {
return "td".equals(tableCellsTagName);
}

5. Methods getTableWidth and getCellWidth are used to determine the table and column width. The table
layout engine will ask this AuthorTableColumnWidthProvider implementation what is the table width for
each table element and the cell width for each cell element from the table that was marked as cell in the CSS using
the property display:table-cell. The implementation is simple and just parses the value of the width attribute.
The methods must return null for the tables / cells that do not have a specified width.
public WidthRepresentation getTableWidth(String tableCellsTagName) {
WidthRepresentation toReturn = null;
if (tableElement != null && "td".equals(tableCellsTagName)) {
AttrValue widthAttr = tableElement.getAttribute("width");
if (widthAttr != null) {
String width = widthAttr.getValue();
if (width != null) {
toReturn = new WidthRepresentation(width, true);
}
}
}
return toReturn;
}
public List<WidthRepresentation> getCellWidth(AuthorElement cellElement, int
colNumberStart,
int colSpan) {
List<WidthRepresentation> toReturn = null;
int size = colWidthSpecs.size();
if (size >= colNumberStart && size >= colNumberStart + colSpan) {
toReturn = new ArrayList<WidthRepresentation>(colSpan);
for (int i = colNumberStart; i < colNumberStart + colSpan; i ++) {
// Add the column widths
toReturn.add(colWidthSpecs.get(i));
}
}
return toReturn;
}

6. Methods commitTableWidthModification and commitColumnWidthModifications are used to

commit changes made to the width of the table or its columns when using the mouse drag gestures.
public void commitTableWidthModification(AuthorDocumentController
authorDocumentController,
int newTableWidth, String tableCellsTagName) throws AuthorOperationException
{
if ("td".equals(tableCellsTagName)) {
if (newTableWidth > 0) {
if (tableElement != null) {
String newWidth = String.valueOf(newTableWidth);

authorDocumentController.setAttribute(
"width",
new AttrValue(newWidth),
tableElement);
} else {
throw new AuthorOperationException("Cannot find the element representing
the table.");
}
}
Oxygen XML Author | Author Developer Guide | 201

}
}
public void commitColumnWidthModifications(AuthorDocumentController
authorDocumentController,
WidthRepresentation[] colWidths, String tableCellsTagName) throws
AuthorOperationException {
if ("td".equals(tableCellsTagName)) {
if (colWidths != null && tableElement != null) {
if (colsStartOffset >= 0 && colsEndOffset >= 0 && colsStartOffset <
colsEndOffset) {
authorDocumentController.delete(colsStartOffset,
colsEndOffset);
}
String xmlFragment = createXMLFragment(colWidths);
int offset = -1;
AuthorElement[] header = tableElement.getElementsByLocalName("header");
if (header != null && header.length > 0) {
// Insert the cols elements before the 'header' element
offset = header[0].getStartOffset();
}
if (offset == -1) {
throw new AuthorOperationException("No valid offset to insert the columns
width specification.");
}
authorDocumentController.insertXMLFragment(xmlFragment, offset);
}
}
}

private String createXMLFragment(WidthRepresentation[] widthRepresentations)

{
StringBuffer fragment = new StringBuffer();
String ns = tableElement.getNamespace();
for (int i = 0; i < widthRepresentations.length; i++) {
WidthRepresentation width = widthRepresentations[i];
fragment.append("<customcol");
String strRepresentation = width.getWidthRepresentation();
if (strRepresentation != null) {
fragment.append(" width=\"" + width.getWidthRepresentation() + "\"");
}
if (ns != null && ns.length() > 0) {
fragment.append(" xmlns=\"" + ns + "\"");
}
fragment.append("/>");
}
return fragment.toString();
}

7. The following three methods are used to determine what type of column width specifications the table column width
provider support. In our case all types of specifications are allowed:

public boolean isAcceptingFixedColumnWidths(String tableCellsTagName) {

return true;
}

public boolean isAcceptingPercentageColumnWidths(String tableCellsTagName) {

return true;
}

public boolean isAcceptingProportionalColumnWidths(String tableCellsTagName)

{
202 | Oxygen XML Author | Author Developer Guide

return true;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the Oxygen Author SDK zip available for download on the Oxygen website.

In the listing below, the XML document contains the table element:
<table width="300">
<customcol width="50.0px"/>
<customcol width="1*"/>
<customcol width="2*"/>
<customcol width="20%"/>
<header>
<td>C1</td>
<td>C2</td>
<td>C3</td>
<td>C4</td>
</header>
<tr>
<td>cs=1, rs=1</td>
<td>cs=1, rs=1</td>
<td row_span="2">cs=1, rs=2</td>
<td row_span="3">cs=1, rs=3</td>
</tr>
<tr>
<td>cs=1, rs=1</td>
<td>cs=1, rs=1</td>
</tr>
<tr>
<td column_span="3">cs=3, rs=1</td>
</tr>
</table>
When no table column width provider is specified, the table has the following layout:

Figure 108: Table layout when no column width provider is specified

When the above implementation is configured, the table has the correct layout:
Oxygen XML Author | Author Developer Guide | 203

Figure 109: Columns with custom widths

Configuring a Table Cell Span Provider

In the documentation framework the table element can have cells that span over multiple columns and rows. As
explained in the Styling the Table Element section which describes the CSS properties needed for defining a table, you
need to indicate Oxygen Author a method to determine the cell spanning. If you use the cell element attributes rowspan
and colspan or rows and cols, Oxygen can determine the cell spanning automatically. In our example the td element
uses the attributes row_span and column_span that are not recognized by default. You will need to implement a Java
extension class for defining the cell spanning.
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.

1. Create the class simple.documentation.framework.TableCellSpanProvider. This class must

implement the ro.sync.ecss.extensions.api.AuthorTableCellSpanProvider interface.
import ro.sync.ecss.extensions.api.AuthorTableCellSpanProvider;
import ro.sync.ecss.extensions.api.node.AttrValue;
import ro.sync.ecss.extensions.api.node.AuthorElement;

public class TableCellSpanProvider

implements AuthorTableCellSpanProvider {

2. The init method is taking as argument the AuthorElement that represents the XML table element. In our
case the cell span is specified for each of the cells so you leave this method empty. However there are cases like the
table CALS model when the cell spanning is specified in the table element. In such cases you must collect the
span information by analyzing the table element.
public void init(AuthorElement table) {
}

3. The getColSpan method is taking as argument the table cell. The table layout engine will ask this
AuthorTableSpanSupport implementation what is the column span and the row span for each XML element
from the table that was marked as cell in the CSS using the property display:table-cell. The implementation
is simple and just parses the value of column_span attribute. The method must return null for all the cells that do
not change the span specification.
public Integer getColSpan(AuthorElement cell) {
Integer colSpan = null;

AttrValue attrValue = cell.getAttribute("column_span");

if(attrValue != null) {
// The attribute was found.
String cs = attrValue.getValue();
if(cs != null) {
try {
204 | Oxygen XML Author | Author Developer Guide

colSpan = new Integer(cs);

} catch (NumberFormatException ex) {
// The attribute value was not a number.
}
}
}
return colSpan;
}

4. The row span is determined in a similar manner:

public Integer getRowSpan(AuthorElement cell) {
Integer rowSpan = null;

AttrValue attrValue = cell.getAttribute("row_span");

if(attrValue != null) {
// The attribute was found.
String rs = attrValue.getValue();
if(rs != null) {
try {
rowSpan = new Integer(rs);
} catch (NumberFormatException ex) {
// The attribute value was not a number.
}
}
}
return rowSpan;
}

5. The method hasColumnSpecifications always returns true considering column specifications always
available.
public boolean hasColumnSpecifications(AuthorElement tableElement) {
return true;
}
Note: The complete source code can be found in the Simple Documentation Framework project, included in
the Oxygen Author SDK zip available for download on the Oxygen website.

6. In the listing below, the XML document contains the table element:
<table>
<header>
<td>C1</td>
<td>C2</td>
<td>C3</td>
<td>C4</td>
</header>
<tr>
<td>cs=1, rs=1</td>
<td column_span="2" row_span="2">cs=2, rs=2</td>
<td row_span="3">cs=1, rs=3</td>
</tr>
<tr>
<td>cs=1, rs=1</td>
</tr>
<tr>
<td column_span="3">cs=3, rs=1</td>
</tr>
</table>

When no table cell span provider is specified, the table has the following layout:
Oxygen XML Author | Author Developer Guide | 205

Figure 110: Table layout when no cell span provider is specified

When the above implementation is configured, the table has the correct layout:

Figure 111: Cells spanning multiple rows and columns.

Configuring an Unique Attributes Recognizer

The ro.sync.ecss.extensions.api.UniqueAttributesRecognizer interface can be implemented if
you want to provide for your framework the following features:
Note: The Javadoc documentation of the Author API used in the example files is available on the Oxygen website.
Also it can be downloaded as a zip archive from the website.
206 | Oxygen XML Author | Author Developer Guide

Automatic
You can automatically generate unique IDs for newly inserted elements. Implementations are already
ID
available for the DITA and Docbook frameworks. The following methods can be implemented to accomplish
generation
this:
/**
* Assign unique IDs between a start
* and an end offset in the document
* @param startOffset Start offset
* @param endOffset End offset
*/
void assignUniqueIDs(int startOffset, int endOffset);

/**
* @return true if auto
*/
boolean isAutoIDGenerationActive();

Avoiding
You can split the current block element by pressing the "Enter" key and then choosing "Split". This is a
copying
very useful way to create new paragraphs, for example. All attributes are by default copied on the new
unique
element but if those attributes are IDs you sometimes want to avoid creating validation errors in the editor.
attributes
Implementing the following method, you can decide whether an attribute should be copied or not during
when
the split:
"Split" is
called /**
inside an * Check if the attribute specified by QName can
* be considered as a valid attribute to copy
element
* when the element is split.
*
* @param attrQName The attribute qualified name
* @param element The element
* @return true if the attribute should be copied
* when Split is performed.
*/
boolean copyAttributeOnSplit(String attrQName,
AuthorElement element);
Tip:
The ro.sync.ecss.extensions.commons.id.DefaultUniqueAttributesRecognizer
class is an implementation of the interface which can be extended by your customization to provide
easy assignation of IDs in your framework. You can also check out the DITA and Docbook
implementations of ro.sync.ecss.extensions.api.UniqueAttributesRecognizer
to see how they were implemented and connected to the extensions bundle.

Customizing the Default CSS of a Document Type

The easiest way of customizing the default CSS stylesheet of a document type is to create a new CSS stylesheet in the
same folder as the customized one, import the customized CSS stylesheet and set the new stylesheet as the default CSS
of the document type. For example let us customize the default CSS for DITA documents by changing the background
color of the task and topic elements to red.

1. First you create a new CSS stylesheet called my_dita.css in the folder ${frameworks}/dita/css_classed
where the default stylesheet called dita.css is located. ${frameworks} is the subfolder frameworks of the
Oxygen XML Editor. The new stylesheet my_dita.css contains:
@import "dita.css";

task, topic{
background-color:red;
}
Oxygen XML Author | Author Developer Guide | 207

2. To set the new stylesheet as the default CSS stylesheet for DITA documents first open the Document Type Association
preferences panel from menu Options > Preferences > Document Type Association . Select the DITA document
type and start editing it by pressing the Edit button. The user role must be set to Developer otherwise a warning is
displayed and a duplicate copy of the DITA document type is created and edited. This check makes sure that regular
content authors who just edit the content of XML documents do not accidentally modify the document type. In the
Author tab of the document type edit dialog change the URI of the default CSS stylesheet from
${frameworks}/dita/css_classed/dita.css to
${frameworks}/dita/css_classed/my_dita.css.

Figure 112: Set the location of the default CSS stylesheet

3. Press OK in all the dialogs to validate the changes. Now you can start editing DITA documents based on the new
CSS stylesheet. You can edit the new CSS stylesheet itself at any time and see the effects on rendering DITA XML
documents in the Author mode by running the Refresh action available on the Author toolbar and on the DITA menu.

Document Type Sharing

Oxygen has support for allowing you to share the customizations which you have made for a specific XML type by
creating your own Document Type in the Document Type Association preferences page.
A document type can be shared between authors in two ways:
• Save it externally in a separate framework folder in the OXYGEN_INSTALL_DIR/frameworks directory.
Important: In order for this approach to work you will need to have Oxygen installed to a folder with full
write access.

Please see the following steps:

1. Create a new directory in the OXYGEN_INSTALL_DIR/frameworks for your new framework. This directory
will contain resources for your framework (CSS files, new file templates, schemas used for validation, catalogs).
See the Docbook framework structure from the OXYGEN_INSTALL_DIR/frameworks/docbook as an
example.
2. Switch the user role to Developer in the Oxygen Preferences Document Type Association page.
3. Create your new custom document type and save it external in the newly created framework directory (with a
name like custom.framework).
4. Configure the custom document type according to your needs, take special care to make all file references relative
to the OXYGEN_INSTALL_DIR/frameworks directory by using the ${frameworks} editor variable. The
Author Developer Guide contains all details necessary for creating and configuring a new document type.
5. If everything went fine then you should have a new configuration file saved in:
OXYGEN_INSTALL_DIR/frameworks/your_framework_dir/custom.framework after the
Preferences are saved.
208 | Oxygen XML Author | Author Developer Guide

6. You can then share the new framework directory with other users (have them copy it to their
OXYGEN_INSTALL_DIR/frameworks directory) and the new document type will be available in the list of
Document Types when Oxygen is started.

• Save the document type at project level in the Document Type Association page.
Please see the following steps:
1. Create a new directory with full write access somewhere on your local drive which will contain the Oxygen
project file and associated document type resources (CSS files, new file templates, schemas used for validation,
catalogs).
2. From the Oxygen Project view create a new project and save it in the newly created directory.
3. In the Oxygen Preferences Document Type Association page switch the radio button at the bottom of the page
to Project Options.
4. Create your new custom document type using the default internal storage for it. It will actually be saved in the
previously chosen Oxygen project .xpr file.
5. Configure the custom document type according to your needs, take special care to make all file references relative
to the project directory by using the ${pd} editor variable. The Author Developer Guide contains all details
necessary for creating and configuring a new document type.
6. You can then share the new project directory with other users and if they open in the Project view the customized
project then the new document type will be available in the list of Document Types.

CSS Support in Oxygen Author

Author editing mode supports most CSS 2.1 selectors, a lot of CSS 2.1 properties and a few CSS 3 selectors. Also some
custom functions and properties that extend the W3C CSS specification and are useful for URL and string manipulation
are available to the developer who creates an Author editing framework.

CSS 2.1 Features

This section enumerates the CSS 2.1 features that are supported by Oxygen XML Author.

Supported CSS 2.1 Selectors

Expression Name Description / Example

* Universal selector Matches any element
E Type selector Matches any E element (i. e. an element with the local
name E)
E F Descendant selector Matches any F element that is a descendant of an E
element.
E > F Child selectors Matches any F element that is a child of an element
E.
E:first-child The :first-child pseudo-class Matches element E when E is the first child of its
parent.
E:lang(c) The :lang() pseudo-class Matches element of type E if it is in (human) language
c (the document language specifies how language is
determined).
E + F Adjacent selector Matches any F element immediately preceded by a
sibling element E.
Oxygen XML Author | Author Developer Guide | 209

Expression Name Description / Example

E[foo] Attribute selector Matches any E element with the "foo" attribute set
(whatever the value).
E[foo="warning"] Attribute selector Matches any E element whose "foo" attribute value
is exactly equal to "warning".
E[foo~="warning"] Attribute selector Matches any E element whose "foo" attribute value
is a list of space-separated values, one of which is
exactly equal to "warning".
E[lang|="en"] Attribute selector Matches any E element whose "lang" attribute has
a hyphen-separated list of values beginning (from the
left) with "en".
E:before and Pseudo elements The ':before' and ':after' pseudo-elements
E:after can be used to insert generated content before or after
an element's content.

Unsupported CSS 2.1 Selectors

Expression Name Description / Example

E#myid ID selectors Matches any E element with ID equal to "myid".
E:link, E:visited The link pseudo-class Matches element E if E is the source anchor of a hyperlink of which
the target is not yet visited (:link) or already visited (:visited).
E:active, E:hover, The dynamic Matches E during certain user actions.
E:focus pseudo-classes
E:first-line The :first-line The :first-line pseudo-element applies special styles to the contents of
pseudo-class the first formatted line of a paragraph.
E:first-letter The :first-letter The :first-letter pseudo-element must select the first letter of the first
pseudo-class line of a block, if it is not preceded by any other content (such as images
or inline tables) on its line. The :first-letter pseudo-element may be
used for "initial caps" and "drop caps", which are common
typographical effects.

CSS 2.1 Properties

All the properties belonging to the aural and paged categories are not supported in Oxygen Author. The properties
from the table below belong to the visual category.

Name Supported Values Not Supported Values

'background-attachment' ALL
'background-color' <color> | inherit transparent
'background-image' ALL
'background-position' ALL
'background-repeat' ALL
'background' ALL
'border-collapse' ALL
210 | Oxygen XML Author | Author Developer Guide

Name Supported Values Not Supported Values

'border-color' <color> | inherit transparent
'border-spacing' ALL
'border-style' <border-style> | inherit
'border-top' 'border-right' [ <border-width> ||
'border-bottom' <border-style> ||
'border-left' 'border-top-color' ] |
inherit
'border-top-color' <color> | inherit transparent
'border-right-color'
'border-bottom-color'
'border-left-color'
'border-top-style' <border-style> | inherit
'border-right-style'
'border-bottom-style'
'border-left-style'
'border-top-width' <border-width> | inherit
'border-right-width'
'border-bottom-width'
'border-left-width'
'border-width' <border-width> | inherit
'border' [ <border-width> ||
<border-style> ||
'border-top-color' ] |
inherit
'bottom' ALL
'caption-side' ALL
'clear' ALL
'clip' ALL
'color' <color> | inherit
'content' normal | none | [ <string> no-open-quote |
| <URI> | <counter> | no-close-quote
attr( <identifier> ) |
open-quote | close-quote
]+ | inherit
'counter-increment' [ <identifier> <integer>
? ]+ | none | inherit
'counter-reset' [ <identifier> <integer>
? ]+ | none | inherit
'cursor' ALL
'direction' ltr rtl | inherit
Oxygen XML Author | Author Developer Guide | 211

Name Supported Values Not Supported Values

'display' inline | block | list-item run-in | inline-block |
| table | table-row-group inline-table - considered
| table-header-group | block
table-footer-group |
table-row |
table-column-group |
table-column | table-cell
| table-caption | none |
inherit
'empty-cells' show | hide | inherit
'float' ALL
'font-family' [[ <family-name> |
<generic-family> ] [,
<family-name> |
<generic-family> ]* ] |
inherit
'font-size' <absolute-size> |
<relative-size> | <length>
| <percentage> | inherit
'font-style' normal | italic | oblique
| inherit
'font-variant' ALL
'font-weight' normal | bold | bolder |
lighter | 100 | 200 | 300
| 400 | 500 | 600 | 700 |
800 | 900 | inherit
'font' [ [ 'font-style' || 'font-variant'
'font-weight' ]? 'line-height' caption |
'font-size' [ / icon | menu | message-box
'line-height' ]? | small-caption |
'font-family' ] | inherit status-bar
'height' ALL
'left' ALL
'letter-spacing' ALL
'line-height' normal | <number> |
<length> | <percentage> |
inherit
'list-style-image' ALL
'list-style-position' ALL
'list-style-type' disc | circle | square | lower-greek | armenian |
decimal | lower-roman | georgian
upper-roman | lower-latin
| upper-latin |
lower-alpha | upper-alpha
| none | inherit
212 | Oxygen XML Author | Author Developer Guide

Name Supported Values Not Supported Values

'list-style' [ 'list-style-type' ] | 'list-style-position' ||
inherit 'list-style-image'
'margin-right' 'margin-left' <margin-width> | inherit
| auto
'margin-top' 'margin-bottom' <margin-width> | inherit
'margin' <margin-width> | inherit
| auto
'max-height' ALL
'max-width' <length> | <percentage> |
none | inherit - supported for
block-level and replaced elements, e.g.
images, tables, table cells.
'min-height' ALL
'min-width' <length> | <percentage> |
inherit - supported for block-level
and replaced elements, e. g. images,
tables, table cells.
'outline-color' ALL
'outline-style' ALL
'outline-width' ALL
'outline' ALL
'overflow' ALL
'padding-top' <padding-width> | inherit
'padding-right'
'padding-bottom'
'padding-left'
'padding' <padding-width> | inherit
'position' ALL
'quotes' ALL
'right' ALL
'table-layout' auto fixed | inherit
'text-align' left | right | center | justify
inherit
'text-decoration' none | [ underline || blink
overline || line-through
] | inherit
'text-indent' ALL
'text-transform' ALL
'top' ALL
'unicode-bidi' ALL
Oxygen XML Author | Author Developer Guide | 213

Name Supported Values Not Supported Values

CSS 3 Features
This section enumerates the CSS 3 features that are supported by Oxygen XML Author.

CSS 3 Namespace Selectors

In the CSS 2.1 standard the element selectors are ignoring the namespaces of the elements they are matching. Only the
local name of the elements are considered in the selector matching process.
Oxygen Author uses a different approach similar to the CSS Level 3 specification. If the element name from the CSS
selector is not preceded by a namespace prefix it is considered to match an element with the same local name as the
selector value and ANY namespace, otherwise the element must match both the local name and the namespace.
In CSS up to version 2.1 the name tokens from selectors are matching all elements from ANY namespace that have the
same local name. Example:
<x:b xmlns:x="ns_x"/>
<y:b xmlns:y="ns_y"/>
Are both matched by the rule:
b {font-weight:bold}
Starting with CSS Level 3 you can create selectors that are namespace aware.

Defining both prefixed namespaces and the default namespace

Given the namespace declarations:
@namespace sync "http://sync.example.org";
@namespace "http://example.com/foo";
In a context where the default namespace applies:

sync|A
represents the name A in the http://sync.example.org namespace.

|B
represents the name B that belongs to NO NAMESPACE.

*|C
represents the name C in ANY namespace, including NO NAMESPACE.
214 | Oxygen XML Author | Author Developer Guide

D
represents the name D in the http://example.com/foo namespace.

Defining only prefixed namespaces

Given the namespace declaration:
@namespace sync "http://sync.example.org";
Then:

sync|A
represents the name A in the http://sync.example.org namespace.

|B
represents the name B that belongs to NO NAMESPACE.

*|C
represents the name C in ANY namespace, including NO NAMESPACE.

D
represents the name D in ANY namespace, including NO NAMESPACE.

The attr() Function: Properties Values Collected from the Edited Document.
In CSS Level 2.1 you may collect attribute values and use them as content only for the pseudo-elements. For instance
the :before pseudo-element can be used to insert some content before an element. This is valid in CSS 2.1:
title:before{
content: "Title id=(" attr(id) ")";
}
If the title element from the XML document is:
<title id="title12">My title.</title>
Then the title will be displayed as:
Title id=(title12) My title.
In Oxygen Author the use of attr() function is available not only for the content property, but also for any other
property. This is similar to the CSS Level 3 working draft:
http://www.w3.org/TR/2006/WD-css3-values-20060919/#functional. The arguments of the function are:
attr ( attribute_name , attribute_type , default_value )

attribute_name
The attribute name. This argument is required.

attribute_type
The attribute type. This argument is optional. If it is missing, argument's type is considered
string. This argument indicates what is the meaning of the attribute value and helps to perform
conversions of this value. Oxygen Author accepts one of the following types:

color
The value represents a color. The attribute may specify a color in different
formats. Oxygen Author supports colors specified either by name: red, blue,
green, etc. or as an RGB hexadecimal value #FFEEFF.

url
The value is an URL pointing to a media object. Oxygen Author supports only
images. The attribute value can be a complete URL, or a relative one to the
XML document. Please note that this URL is also resolved through the catalog
resolver.
Oxygen XML Author | Author Developer Guide | 215

integer
The value must be interpreted as an integer.

number
The value must be interpreted as a float number.

length
The value must be interpreted as an integer.

percentage
The value must be interpreted relative to another value (length, size) expressed
in percents.

em
The value must be interpreted as a size. 1 em is equal to the font-size of the
relevant font.

ex
The value must be interpreted as a size. 1 ex is equal to the height of the x
character of the relevant font.

px
The value must be interpreted as a size expressed in pixels relative to the
viewing device.

mm
The value must be interpreted as a size expressed in millimeters.

cm
The value must be interpreted as a size expressed in centimeters.

in
The value must be interpreted as a size expressed in inches. 1 inch is equal to
2.54 centimeters.

pt
The value must be interpreted as a size expressed in points. The points used
by CSS2 are equal to 1/72th of an inch.

pc
The value must be interpreted as a size expressed in picas. 1 pica is equal to
12 points.

default_value
This argument specifies a value that is used by default if the attribute value is missing. This
argument is optional.

Usage samples for the attr() function

Consider the following XML instance:
<sample>
<para bg_color="#AAAAFF">Blue paragraph.</para>
<para bg_color="red">Red paragraph.</para>
<para bg_color="red" font_size="2">Red paragraph with large
font.</para>
<para bg_color="#00AA00" font_size="0.8" space="4">
Green paragraph with small font and margin.</para>
</sample>
The para elements have bg_color attributes with RGB color values like #AAAAFF. You can
use the attr() function to change the elements appearance in the editor based on the value of
this attribute:
background-color:attr(bg_color, color);
216 | Oxygen XML Author | Author Developer Guide

The attribute font_size represents the font size in em units. You can use this value to change
the style of the element:
font-size:attr(font_size, em);
The complete CSS rule is:
para{
display:block;
background-color:attr(bg_color, color);
font-size:attr(font_size, em);
margin:attr(space, em);
}
The document is rendered as:

Additional Custom Selectors

Oxygen Author provides support for selecting additional types of nodes. These custom selectors apply to: document,
doctype sections, processing-instructions, comments, CDATA sections, and entities. In order for the custom selectors to
work in your CSSs you will have to declare the Author extensions namespace at the beginning of the stylesheet documents:
@namespace oxy url('http://www.oxygenxml.com/extensions/author');

Example rules:
• document:
oxy|document {
display:block;
}

• doctype sections:
oxy|doctype {
display:block;
color:blue;
background-color:transparent;
}
Oxygen XML Author | Author Developer Guide | 217

• processing-instructions:
oxy|processing-instruction {
display:block;
color:purple;
background-color:transparent;
}

• comments:
oxy|comment {
display:block;
color:green;
background-color:transparent;
}

• CDATA sections:
oxy|cdata{
display:block;
color:gray;
background-color:transparent;
}

• entities:
oxy|entity {
display:morph;
editable:false;
color:orange;
background-color:transparent;
}

A sample document rendered using these rules:

Oxygen CSS Extensions

CSS stylesheets provide support mainly for displaying documents. When editing documents some extensions of the
W3C CSS specification are useful, for example:
• property for marking foldable elements in large files
• enforcing a display mode for the XML tags regardless of the current mode selected by the author user
• construct a URL from a relative path location
• string processing functions

Media Type oxygen

The style sheets can specify how a document is to be presented on different media: on the screen, on paper, speech
synthesizer, etc. You can specify that some of the features of your CSS stylesheet should be taken into account only in
the Oxygen Author and ignored in the rest. This can be accomplished by using the media type oxygen.
218 | Oxygen XML Author | Author Developer Guide

For instance using the following CSS:

b{
font-weight:bold;
display:inline;
}

@media oxygen{
b{
text-decoration:underline;
}
}
would make a text bold if the document was opened in a web browser who does not recognize @media oxygen and
bold and underlined in Oxygen Author.
You can use this media type to group specific Oxygen CSS features and also to hide them when opening the documents
with other viewers.

Folding Elements: foldable and not-foldable-child Properties

Oxygen Author allows you to declare some elements to be foldable (collapsible). This is especially useful when working
with large documents organized in logical blocks, editing a large DocBook article or book for instance.
To define the element whose content can be folded by the user, you must use the property: foldable:true;.
When collapsing an element, it is useful to keep some of its content visible, like a short description of the collapsed
region. The property not-foldable-child is used to identify the child elements that are kept visible. It accepts as
value an element name or a list of comma separated element names. If the element is marked as foldable
(foldable:true;) but it doesn't have the property not-foldable-child or none of the specified non-foldable
children exists then the element will still be foldable. In this case the element that will be kept visible when folded will
be the before pseudo-element.

Folding DocBook Elements

All the elements below can have a title child element and are considered to be logical sections.
You mark them as being foldable leaving the title element visible.
set,
book,
part,
reference,
chapter,
preface,
article,
sect1,
sect2,
sect3,
sect4,
section,
appendix,
figure,
example,
table {
foldable:true;
not-foldable-child: title;
}

Link Elements
Oxygen Author allows you to declare some elements to be links. This is especially useful when working with many
documents which refer each other. The links allow for an easy way to get from one document to another. Clicking on
the link marker will open the referred resource in an editor.
Oxygen XML Author | Author Developer Guide | 219

To define the element which should be considered a link, you must use the property link on the before or after pseudo
element. The value of the property indicates the location of the linked resource. Since links are usually indicated by the
value of an attribute in most cases it will have a value similar to attr(href)

Docbook Link Elements

All the elements below are defined to be links on the before pseudo element and their value is
defined by the value of an attribute.
*[href]:before{
link:attr(href);
content: "Click " attr(href) " for opening" ;
}

ulink[url]:before{
link:attr(url);
content: "Click to open: " attr(url);
}

olink[targetdoc]:before{
link: attr(targetdoc);
content: "Click to open: " attr(targetdoc);
}

Display Tag Markers

Oxygen Author allows you to choose whether tag markers of an element should never be presented or the current display
mode should be respected. This is especially useful when working with :before and :after pseudo-elements in
which case the element range is already visually defined so the tag markers are redundant.
The property is named display-tags. Its possible values are :
• none Tags markers must not be presented regardless of the current Display mode.
• default The tag markers will be created depending on the current Display mode.
• inherit The value of the property is inherited from an ancestor element.

display-tags
Value: none | default | inherit
Initial: default
Applies to: all nodes(comments, elements, CDATA, etc)
Inherited: false
Media: all

Docbook Para elements

In this example the para element from Docbook is using an :before and :after element so
you don't want its tag markers to be visible.
para:before{
content: "{";
}

para:after{
content: "}";
}

para{
display-tags: none;
display:block;
margin: 0.5em 0;
}
220 | Oxygen XML Author | Author Developer Guide

Oxygen Custom CSS Functions

In Oxygen Author there are implemented a few Oxygen specific custom CSS functions. Imbricated custom functions
are also supported.

Imbricated functions
The result of the functions below will be the local name of the current node with the first letter
capitalized.
capitalize(local-name())
The local-name() Function
This function evaluates the local name of the current node. It does not have any arguments.
The name() Function
This function evaluates the qualified name of the current node. It does not have any arguments.
The url() function
This function evaluates the URL of a location relative to the CSS file location and appends each of the relative path
components to the final location.
url ( location , loc_1 , loc_2 )

location The location as string. If not absolute, will be solved relative to the CSS file URL.
loc_1 ... loc_n Relative location path components as string. (optional)

The base-uri() Function

This function evaluates the base URL in the context of the current node. It does not have any arguments and takes into
account the xml:base context of the current node. See the XML Base specification for more details.
The parent-url() Function
This function evaluates the parent URL of an URL received as string.
parent-url ( URL )

URL The URL as string.

The capitalize() Function

This function capitalizes the first letter of the text received as argument.
capitalize ( text )

text The text for which the first letter will be capitalized.

The uppercase() Function

This function transforms to upper case the text received as argument.
uppercase ( text )

text The text to be capitalized.

The lowercase() Function

This function transforms to lower case the text received as argument.
lowercase ( text )

text The text to be lower cased.

The concat() Function

This function concatenates the received string arguments.
Oxygen XML Author | Author Developer Guide | 221

concat ( str_1 , str_2 )

str_1 ... str_n The string arguments to be concatenated.

The replace() Function

This function has two signatures:
• replace ( text , target , replacement )
This function replaces each substring of the text that matches the literal target string with the specified literal
replacement string.

text The text in which the replace will occur.

target The target string to be replaced.
replacement The string replacement.

• replace ( text , target , replacement , isRegExp )

This function replaces each substring of the text that matches the target string with the specified replacement string.

text The text in which the replace will occur.

target The target string to be replaced.
replacement The string replacement.
isRegExp If true the target and replacement arguments are considered regular expressions
in PERL syntax, if false they are considered literal strings.

The unparsed-entity-uri() Function

This function returns the URI value of an unparsed entity name.
unparsed-entity-uri ( unparsedEntityName )

unparsedEntityName The name of an unparsed entity defined in the DTD.

This function can be useful to display images which are referred with unparsed entity names.

CSS for displaying the image in Author for an imagedata with entityref to an
unparsed entity

imagedata[entityref]{
content: url(unparsed-entity-uri(attr(entityref)));
}

The attributes() Function

This function concatenates the attributes for an element and returns the serialization.
attributes ( )

attributes()
For the following XML fragment:<element att1="x" xmlns:a="2" x="""/>
the attributes() function will return att1="x" xmlns:a="2" x=""".

The substring() Function

This function has two signatures:
• substring ( text , startOffset )
222 | Oxygen XML Author | Author Developer Guide

Returns a new string that is a substring of the original text string. It begins with the character at the specified index
and extends to the end of text string.

text The original string.

startOffset The beginning index, inclusive

• substring ( text , startOffset , endOffset )

Returns a new string that is a substring of the original text string. The substring begins at the specified startOffset
and extends to the character at index endOffset - 1.

text The original string.

startOffset The beginning index, inclusive
endOffset The ending index, exclusive.

substring('abcd', 1) returns the string 'bcd'.

substring('abcd', 4) returns an empty string.
substring('abcd', 1, 3) returns the string 'bc'.

The indexof() Function

This function has two signatures:
• indexof ( text , toFind )
Returns the index within text string of the first occurrence of the toFind substring.

text Text to search in.

toFind The searched substring.

• indexof ( text , toFind , fromOffset )

Returns the index within text string of the first occurrence of the toFind substring. The search starts from fromOffset
index.

text Text to search in.

toFind The searched substring.
fromOffset The index from which to start the search.

indexof('abcd', 'bc') returns 1.

indexof('abcdbc', 'bc', 2) returns 4.

The lastindexof() Function

This function has two signatures:
• lastindexof ( text , toFind )
Returns the index within text string of the rightmost occurrence of the toFind substring.

text Text to search in.

toFind The searched substring.

• lastindexof ( text , toFind , fromOffset )

Oxygen XML Author | Author Developer Guide | 223

The search starts from fromOffset index. Returns the index within text string of the last occurrence of the toFind
substring, searching backwards starting from the fromOffset index.

text Text to search in.

toFind The searched substring.
fromOffset The index from which to start the search backwards.

lastindexof('abcdbc', 'bc') returns 4.

lastindexof('abcdbccdbc', 'bc', 2) returns 1.

The xpath() Function

This function has one signature:
• xpath ( expression )
Evaluates the given XPath expression and returns the result.

expression XPath expression to be evaluated.

The following example counts the number of words from a paragraph and displays the result in
front of it:
para:before{ content: concat("|Number of words:",
xpath("count(tokenize(normalize-space(string-join(text(), '')), '
'))"), "| "); }

Example Files Listings - The Simple Documentation Framework Files

This section lists the files used in the customization tutorials: the XML Schema, CSS files, XML files, XSLT stylesheets.

XML Schema files

sdf.xsd
This sample file can also be found in the Author SDK distribution in the "oxygenAuthorSDK\samples\Simple
Documentation Framework - SDF\framework\schema" directory.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.oxygenxml.com/sample/documentation"
xmlns:doc="http://www.oxygenxml.com/sample/documentation"
xmlns:abs="http://www.oxygenxml.com/sample/documentation/abstracts"
elementFormDefault="qualified">

<xs:import
namespace="http://www.oxygenxml.com/sample/documentation/abstracts"
schemaLocation="abs.xsd"/>

<xs:element name="book" type="doc:sectionType"/>

<xs:element name="article" type="doc:sectionType"/>
<xs:element name="section" type="doc:sectionType"/>

<xs:complexType name="sectionType">
<xs:sequence>
224 | Oxygen XML Author | Author Developer Guide

<xs:element name="title" type="xs:string"/>

<xs:element ref="abs:def" minOccurs="0"/>
<xs:choice>
<xs:sequence>
<xs:element ref="doc:section"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:choice maxOccurs="unbounded">
<xs:element ref="doc:para"/>
<xs:element ref="doc:ref"/>
<xs:element ref="doc:image"/>
<xs:element ref="doc:table"/>
</xs:choice>
</xs:choice>
</xs:sequence>
</xs:complexType>

<xs:element name="para" type="doc:paragraphType"/>

<xs:complexType name="paragraphType" mixed="true">

<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="b"/>
<xs:element name="i"/>
<xs:element name="link"/>
</xs:choice>
</xs:complexType>

<xs:element name="ref">
<xs:complexType>
<xs:attribute name="location" type="xs:anyURI"
use="required"/>
</xs:complexType>
</xs:element>

<xs:element name="image">
<xs:complexType>
<xs:attribute name="href" type="xs:anyURI"
use="required"/>
</xs:complexType>
</xs:element>

<xs:element name="table">
<xs:complexType>
<xs:sequence>
<xs:element name="customcol" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="width" type="xs:string"/>
</xs:complexType>
</xs:element>
<xs:element name="header">
<xs:complexType>
<xs:sequence>
<xs:element name="td"
maxOccurs="unbounded"
type="doc:paragraphType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="tr" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="td"
type="doc:tdType"
maxOccurs="unbounded"/>
Oxygen XML Author | Author Developer Guide | 225

</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="width" type="xs:string"/>
</xs:complexType>
</xs:element>

<xs:complexType name="tdType">
<xs:complexContent>
<xs:extension base="doc:paragraphType">
<xs:attribute name="row_span"
type="xs:integer"/>
<xs:attribute name="column_span"
type="xs:integer"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:schema>

abs.xsd
This sample file can also be found in the Author SDK distribution in the "oxygenAuthorSDK\samples\Simple
Documentation Framework - SDF\framework\schema" directory.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace=
"http://www.oxygenxml.com/sample/documentation/abstracts">
<xs:element name="def" type="xs:string"/>
</xs:schema>

CSS Files

sdf.css
This sample file can also be found in the Author SDK distribution in the "oxygenAuthorSDK\samples\Simple
Documentation Framework - SDF\framework\css" directory.
/* Element from another namespace */
@namespace abs "http://www.oxygenxml.com/sample/documentation/abstracts";

abs|def{
font-family:monospace;
font-size:smaller;
}
abs|def:before{
content:"Definition:";
color:gray;
}

/* Vertical flow */
book,
section,
para,
title,
image,
ref {
display:block;
}

/* Horizontal flow */
226 | Oxygen XML Author | Author Developer Guide

b,i {
display:inline;
}

section{
margin-left:1em;
margin-top:1em;
}

section{
foldable:true;
not-foldable-child: title;
}

link[href]:before{
display:inline;
link:attr(href);
content: "Click to open: " attr(href);
}

/* Title rendering*/
title{
font-size: 2.4em;
font-weight:bold;
}

* * title{
font-size: 2.0em;
}
* * * title{
font-size: 1.6em;
}
* * * * title{
font-size: 1.2em;
}

book,
article{
counter-reset:sect;
}
book > section,
article > section{
counter-increment:sect;
}
book > section > title:before,
article > section > title:before{
content: "Section: " counter(sect) " ";
}

/* Inlines rendering*/
b {
font-weight:bold;
}

i {
font-style:italic;
}

/*Table rendering */
table{
display:table;
border:1px solid navy;
margin:1em;
max-width:1000px;
Oxygen XML Author | Author Developer Guide | 227

min-width:150px;
}

table[width]{
width:attr(width, length);
}

tr, header{
display:table-row;
}

header{
background-color: silver;
color:inherit
}

td{
display:table-cell;
border:1px solid navy;
padding:1em;
}

image{
display:block;
content: attr(href, url);
margin-left:2em;
}

XML Files

sdf_sample.xml
This sample file can also be found in the Author SDK distribution in the "oxygenAuthorSDK\samples\Simple
Documentation Framework - SDF\framework" directory.
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://www.oxygenxml.com/sample/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:abs="http://www.oxygenxml.com/sample/documentation/abstracts">
<title>My Technical Book</title>
<section>
<title>XML</title>
<abs:def>Extensible Markup Language</abs:def>
<para>In this section of the book I will explain
different XML applications.</para>
</section>
<section>
<title>Accessing XML data.</title>
<section>
<title>XSLT</title>
<abs:def>Extensible stylesheet language
transformation (XSLT) is a language for
transforming XML documents into other XML
documents.</abs:def>
<para>A list of XSL elements and what they do..</para>
<table>
<header>
<td>XSLT Elements</td>
<td>Description</td>
</header>
<tr>
<td>
<b>xsl:stylesheet</b>
228 | Oxygen XML Author | Author Developer Guide

</td>
<td>The <i>xsl:stylesheet</i> element is
always the top-level element of an
XSL stylesheet. The name
<i>xsl:transform</i> may be used
as a synonym.</td>
</tr>
<tr>
<td>
<b>xsl:template</b>
</td>
<td>The <i>xsl:template</i> element has
an optional mode attribute. If this
is present, the template will only
be matched when the same mode is
used in the invoking
<i>xsl:apply-templates</i>
element.</td>
</tr>
<tr>
<td>
<b>for-each</b>
</td>
<td>The xsl:for-each element causes
iteration over the nodes selected by
a node-set expression.</td>
</tr>
<tr>
<td column_span="2">End of the list</td>
</tr>
</table>
</section>
<section>
<title>XPath</title>
<abs:def>XPath (XML Path Language) is a terse
(non-XML) syntax for addressing portions of
an XML document. </abs:def>
<para>Some of the XPath functions.</para>
<table>
<header>
<td>Function</td>
<td>Description</td>
</header>
<tr>
<td>format-number</td>
<td>The <i>format-number</i> function
converts its first argument to a
string using the format pattern
string specified by the second
argument and the decimal-format
named by the third argument, or the
default decimal-format, if there is
no third argument</td>
</tr>
<tr>
<td>current</td>
<td>The <i>current</i> function returns
a node-set that has the current node
as its only member.</td>
</tr>
<tr>
<td>generate-id</td>
<td>The <i>generate-id</i> function
returns a string that uniquely
Oxygen XML Author | Author Developer Guide | 229

identifies the node in the argument

node-set that is first in document
order.</td>
</tr>
</table>
</section>
</section>
<section>
<title>Documentation frameworks</title>
<para>One of the most important documentation
frameworks is Docbook.</para>
<image
href="http://www.xmlhack.com/images/docbook.png"/>
<para>The other is the topic oriented DITA, promoted
by OASIS.</para>
<image
href="http://www.oasis-open.org/images/standards/oasis_standard.jpg"
/>
</section>
</book>

XSL Files

sdf.xsl
This sample file can also be found in the Author SDK distribution in the "oxygenAuthorSDK\samples\Simple
Documentation Framework - SDF\framework\xsl" directory.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"
xpath-default-namespace=
"http://www.oxygenxml.com/sample/documentation">

<xsl:template match="/">
<html><xsl:apply-templates/></html>
</xsl:template>

<xsl:template match="section">
<xsl:apply-templates/>
</xsl:template>

<xsl:template match="image">
<img src="{@href}"/>
</xsl:template>

<xsl:template match="para">
<p>
<xsl:apply-templates/>
</p>
</xsl:template>

<xsl:template match="abs:def"
xmlns:abs=
"http://www.oxygenxml.com/sample/documentation/abstracts">
<p>
<u><xsl:apply-templates/></u>
</p>
</xsl:template>

<xsl:template match="title">
<h1><xsl:apply-templates/></h1>
</xsl:template>
230 | Oxygen XML Author | Author Developer Guide

<xsl:template match="b">
<b><xsl:apply-templates/></b>
</xsl:template>

<xsl:template match="i">
<i><xsl:apply-templates/></i>
</xsl:template>

<xsl:template match="table">
<table frame="box" border="1px">
<xsl:apply-templates/>
</table>
</xsl:template>

<xsl:template match="header">
<tr>
<xsl:apply-templates/>
</tr>
</xsl:template>

<xsl:template match="tr">
<tr>
<xsl:apply-templates/>
</tr>
</xsl:template>

<xsl:template match="td">
<td>
<xsl:apply-templates/>
</td>
</xsl:template>

<xsl:template match="header/header/td">
<th>
<xsl:apply-templates/>
</th>
</xsl:template>

</xsl:stylesheet>

Oxygen XML Author Component

The Oxygen XML Author component was designed as a separate product to provide the functionality of the standard
Author page. The component can be embedded either in a third-party standalone Java application or customized as a
Java Web Applet to provide WYSIWYG-like XML editing directly in your web browser of choice.
The Author Component SDK for Java/Swing integrations is available online on the oXygen XML website:
http://www.oxygenxml.com/demo/AuthorDemoApplet/author-component-sample.zip

Licensing
Just like the oXygen standard deployment, the Author component requires license information in order to run. Licensing
information must follow the same models imposed for the standard oXygen application, namely the floating, named-user
based or group licenses. You can license an Author component using standard oXygen XML Editor/Author license keys.
You can set the component to:
Oxygen XML Author | Author Developer Guide | 231

• display the license registration dialog to the end user. This is the default behavior and transfers the licensing
responsibility to the end-user. The standard licensing procedure applies.
• programmatically inject the licensing information directly in the component. This is especially useful when you use
a multiple-user or group license.
: You must make sure only the authorized users will access the application.
• programmatically set-up floating license server details.
The most common use-case is when you as a developer customize the component and then want to deliver it to end
users (either embedded in a Java application or a Java Web applet). Your licensing options are:
• named-user based model, where users provide their own oXygen license keys and register the component;
• floating license model, where the component comes pre-configured to use one of the oXygen floating license servers
(either the standalone or the servlet version).

Installation Requirements
Running the Author component as a Java applet requires:
• Oracle (Sun) Java JRE version 1.6 update 10 or newer;
• At least 100 MB disk space and 100MB free memory;
• The applet needs to be signed with a valid certificate and will request full access to the user machine, in order to
store customization data (like options and framework files);
• The applet was tested for compatibility with the following browsers:

IE 7 IE 8 (32bit) IE 9 (64bit) Firefox 3 Firefox 4 Safari 5 Chrome

Windows XP Passed Passed - Passed Passed - Passed
Vista Failed Passed Failed Passed Passed Failed Passed
Windows 7 - - Passed Passed Passed - Passed
Mac OS X - - - Failed Passed Passed Failed
10.6
Linux - - - Failed - - Failed
Ubuntu 10

Running the Author component embedded in a third-party Java/Swing application requires:

232 | Oxygen XML Author | Author Developer Guide

• Oracle (Sun) Java JRE version 1.6 or newer;

• At least 100 MB disk space and 100MB free memory;

Customization
For a special type of XML, you can create a custom framework (which also works in an Oxygen standalone version).
Oxygen already has frameworks for editing DocBook, DITA, TEI, and so on. Their sources are available in the Author
SDK. This custom framework is then packed in a zip archive and used to deploy the component.
The following diagram shows the components of a custom framework.

More than one framework can coexist in the same component and can be used at the same time for editing XML
documents.
Oxygen XML Author | Author Developer Guide | 233

You can add on your custom toolbar all actions available in the standalone Oxygen application for editing in the Author
page. You can also add custom actions defined in the framework customized for each XML type.
The Author component can also provide the Outline, Model, Elements and Attributes views which can be added to your
own developed containers.

Deployment
The Author Component Java API allows you to use it in your Java application or as a Java applet. The JavaDoc for the
API can be found in the sample project in the lib/apiSrc.zip archive. The sample project also comes with Java
sources (ro/sync/ecss/samples/AuthorComponentSample.java) demonstrating how the component is
created, licensed and used in a Java application.

Web Deployment
The Author Component can be deployed as a Java Applet using the new Applet with JNLP Java technology, available
in Oracle (Sun) Java JRE version 1.6 update 10 or newer.
The sample project demonstrates how the Author component can be distributed as an applet.
Here are the main steps you need to follow in order to deploy the Author component as a Java Applet:
• Unpack the sample project archive and look for Java sources of the sample Applet implementation. They can be
customized to fit your requirements.
• The default.properties configuration file must first be edited to specify your custom certificate information
used to sign the applet libraries. You also have to specify the code base from where the applet will be downloaded.
• You can look inside the author-component-dita.html and author-component-dita.js sample
Web resources to see how the applet is embedded in the page and how it can be controlled using Javascript (to set
and get XML content from it).
234 | Oxygen XML Author | Author Developer Guide

• The sample Applet author-component-dita.jnlp JNLP file can be edited to add more libraries. The packed
frameworks and options are delivered using the JNLP file as JAR archives:
<jar href="resources/frameworks.zip.jar"/>
<jar href="resources/options.zip.jar"/>

• The sample frameworks and options JAR archives can be found in the resources directory.
• Use the build.xml ANT build file to pack the component. The resulting applet distribution is copied in the dist
directory. From this on, you can copy the applet files on your web server.

Figure 113: Oxygen Author Component deployed as a Java applet

Troubleshooting
When the applet fails to start:
1. Make sure that your Web browser really runs the next generation Java plug-in and not the legacy Java plug-in.
2. Refresh the web page.
3. Remove the Java Webstart cache from the local drive and try again.
• On Windows this folder is located in: %APPDATA%\LocalLow\Sun\Java\Deployment\cache;
• On Mac OSX this folder is located in: /Users/user_name/Library/Caches/Java/cache;
• On Linux this folder is located in: /home/user/.java/deployment/cache.

4. Remove the Author Applet Frameworks cache from the local drive and try again:
• On Windows Vista or 7 this folder is located in:
%APPDATA%\Roaming\com.oxygenxml.author.component;
• On Windows XP this folder is located in: %APPDATA%\com.oxygenxml.author.component;
• On Mac OSX this folder is located in:
/Users/user_name/Library/Preferences/com.oxygenxml.author.component;
• On Linux this folder is located in: /home/user/.com.oxygenxml.author.component.
Oxygen XML Author | Author Developer Guide | 235

5. Problems sometimes occur after upgrading the Web browser and/or the JavaTM runtime. Redeploy the applet on
the server by running ANT in your Author Component project. However, doing this does not always fix the problem,
which often lies in the Web browser and/or in the Java plug-in itself.
Enable JavaWebstart logging on your computer to get additional debug information:
1. Open a console and run javaws -viewer;
2. In the Advanced tab expand the Debugging category and check all boxes.
3. Expand the Java console category and choose Show console.
4. Save settings.
5. After running the applet you will find the log files in:
• On Windows this folder is located in: %APPDATA%\LocalLow\Sun\Java\Deployment\log;
• On Mac OSX this folder is located in: /Users/user_name/Library/Caches/Java/log;
• On Linux this folder is located in: /home/user/.java/deployment/log.
Chapter
9
Grid Editor
Topics: In the grid editor the XML document is displayed as a structured grid of nested
tables in which the text content can be modified by non technical users without
• Layouts: Grid and Tree editing directly the XML tags. The tables can be expanded and collapsed with
• Navigating the Grid a mouse click to show or hide the elements of the document as needed. Also
• Specific Grid Actions the document structure can be changed easily with drag and drop operations on
• Drag and Drop in the Grid Editor the grid components. The tables can be zoomed using (Ctrl - +) , (Ctrl - -),
(Ctrl - 0) or (Ctrl - mouse wheel).
• Copy and Paste in the Grid Editor
• Bidirectional Text Support in the
Grid Editor

Figure 114: The Grid Editor

You can switch between the text tab and the grid tab of the editor panel with
the two buttons Text and Grid available at the bottom of the editor panel. .
If the edited document is associated with a schema (DTD, XML Schema, Relax
NG, etc.), the editor offers content completion for the element and attributes
names and values. If you choose to insert an element that has required content,
it will be inserted automatically including the subtree of needed elements and
attributes.
To display the content completion popup you have to start editing, for example
by double clicking the cell. When editing, pressing (Ctrl - Space) redisplays
the popup.
238 | Oxygen XML Author | Grid Editor

Figure 115: Content Completion in Grid Editor

Oxygen XML Author | Grid Editor | 239

Layouts: Grid and Tree

The grid editor has two modes for the layout. The default one is the grid layout. This smart layout detects the recurring
elements in the XML document and creates tables having as columns the children (including the attributes) of these
elements. In this way it is possible to have tables nested in other tables, reflecting the structure of your document.

Figure 116: Grid Layout

The other layout mode is tree-like. This layout does not create any table. It presents the structure of the document directly.

Figure 117: Tree Layout

You can switch between the two modes using the contextual menu > Grid mode/Tree mode .

Navigating the Grid

When you open a document first in the grid tab, the document is collapsed so that it shows just the root element and its
attributes. The grid disposition of the node names and values are very similar to a web form or a dialog. The same set
of key shortcuts used to select dialog components are used in the grid. For instance moving to the next editable value
in a table row is done using the (Tab) key. Moving to the previous cell employs the (Shift-Tab) key. Changing a value
assumes pressing the (Enter) key or start typing directly the new value, and, when the editing is finished, pressing
(Enter) again to commit the data into the document.
The arrow keys and the (Page Up/Down) keys can be used for navigation. By pressing (Shift) while using these keys
you can create a selection zone. To add other nodes that are not close to this zone, you can use the mouse and the (Ctrl)
key ( (Command) on Mac OS X).
The following key combination may be used to scroll the grid:
• Ctrl - Up scrolls the grid upwards
• Ctrl - Down scrolls the grid downwards
• Ctrl - Left scrolls the grid to the left
• Ctrl - Right scrolls the grid to the right
240 | Oxygen XML Author | Grid Editor

A left arrow sign displayed to the left of the node name indicates that this node has child nodes. You can click this sign
to display the children. The expand/collapse actions can be also invoked by pressing the (NumPad Plus) and (NumPad
Minus) keys.
A set of expand/collapse actions can be accessed from the submenu Expand/Collapse of the contextual menu.
The following actions are available on the Expand/Collapse menu:
• Expand All - Expands the selection and all its children.
• Collapse All - Collapses the selection and all its children.
• Expand Children - Expands all the children of the selection but not the selection.
• Collapse Children - Collapses all the children of the selection but not the selection.
• Collapse Others - Collapses all the siblings of the current selection but not the selection.

Specific Grid Actions

In order to access these actions you can click the column header and choose from the contextual menu the item Table
. The same set of actions are available in the menu Document and on the Grid toolbar which is opened from menu
Window > Show Toolbar > Grid .

Sorting a Table Column

You can sort the table by a specific column. The sorting can be either ascending or descending.
The icons for this pair of actions are:
The sorting result depends on the data type of the column content. It can be different in case of number (numerical
sorting) or text information (alphabetical sorting). The editor analyses automatically the content and decides what type
of sorting to apply. If there is present a mixed set of values in the column, a dialog will be displayed allowing to choose
the desired type between numerical and alphabetical.

Inserting a Row in a Table

You can add a row by either a copy/paste operation over a row, or directly, by invoking the action from the contextual
menu: Table > Insert row .
A shorter way of inserting a new row is to move the selection over the row header, and then to press (Enter). The row
header is the zone in the left of the row that holds the row number. The inserted row will be below the selection.

Inserting a Column in a Table

You can insert a column after the selected one, using the action from the contextual menu Table > Insert column
.

Clearing the Content of a Column

You can clear all the cells from a column, using the action from the contextual menu: Table > Clear content .

Adding Nodes
Using the contextual menu you can add nodes before, after, or as last child of the currently selected node.
The sub-menus containing detailed actions are:
• Insert before
Oxygen XML Author | Grid Editor | 241

• Insert after
• Append child

Duplicating Nodes
A quicker way of creating new nodes is to duplicate the existing ones. The action is available in the contextual menu:
Duplicate and in the menu Document > Grid Edit > Duplicate .

Refresh Layout
When using drag and drop to reorganize the document, the resulted layout may be different from the expected one. For
instance, the layout may contain a set of sibling tables that could be joined together. To force the layout to be recomputed
you can use the action Refresh. The action is available in the contextual menu Refresh selected and in the menu
Document > Grid Edit > Refresh selected .

Start Editing a Cell Value

You can simply press (Enter) after you have selected the grid cell.

Stop Editing a Cell Value

You stop editing a cell value when you press (Enter).
To cancel the editing without saving in the document the current changes, you have to press the (Esc) key.

Drag and Drop in the Grid Editor

The drag and drop features of the grid editor make easy the arrangement of the different sections in your XML document.
Using drag and drop you can:
• Copy or move a set of nodes.
• Change the order of columns in the tables.
• Move the rows from the tables.
These operations are available for single selection and multiple selection.
Note that when dragging the editor paints guide-lines showing accepted locations where the nodes can be dropped.
Nodes can be dragged outside the grid editor and text from other applications can be dropped inside the grid. See Copy
and Paste in the Grid Editor for details.

Copy and Paste in the Grid Editor

The selection in the grid is a bit complex relative to the selection in a text component. It consists of a current selected
cell and additional selected cells. These additional cells are either hand picked by the user using the mouse, or are implied
by the current selected cell. To be more specific, let's consider you click the name of the column - this becomes the
current selected cell; the editor automatically extends the selection so it contains also all the cells from that column. The
current selected cell is painted with a color that is different from the rest of the selection.
You can select discontinuous regions of nodes and place them in the clipboard using the copy action. Pasting these nodes
may be done in two ways, relative to the current selected cell: by default as brother, just below (after) , or as last child
of the selected cell.
242 | Oxygen XML Author | Grid Editor

The Paste as Child action is available in the contextual menu.

The copied nodes from the grid can be pasted also into the text editor or other applications. When copying from grid
into the text editor or other text based applications the inserted string represents the nodes serialization. The nodes from
tables can be copied using HTML or RTF in table format. The resulting cells contain only the concatenated values of
the text nodes.

Figure 118: Copying from grid to other editors

In the grid editor you can paste wellformed xml content or tab separated values from other editors. If you paste xml
content the result will be the insertion of the nodes obtained by parsing this content.

Figure 119: Copying XML data into grid

If the pasted text contains multiple lines of tab separated values it can be considered as a matrix of values. By pasting
this matrix of values into the grid editor the result will be a matrix of cells. If the operation is performed inside existing
cells the values from these cells will be overwritten and new ones will be created if needed. This is useful for example
when trying to transfer data from Excel like editors into grid editor.
Oxygen XML Author | Grid Editor | 243

Figure 120: Copying tab separated values into grid

Bidirectional Text Support in the Grid Editor

If you are editing documents employing a different text orientation you can change the way text is rendered and edited
in the grid cells. For this, you can use the shortcut (Ctrl-Shift-O) to toggle from the default left to right text orientation
to the right to left orientation.
Note that this change applies only to the text from the cells, not to the layout of the grid editor.

Figure 121: Default left to right text orientation

Figure 122: Right to left text orientation

Chapter
10
Transforming Documents
Topics: 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
• Output Formats or transform it to a format that can be read by other user agents. This process is
• Transformation Scenario known as transformation.
• XSLT Processors Status messages generated during transformation are displayed in the Console
• XSL-FO Processors view.
• XProc Transformations
246 | Oxygen XML Author | Transforming Documents

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/Oracle 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.
Oxygen XML Author | Transforming Documents | 247

• 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.3.0.5 HE, Saxon 9.3.0.5 PE, and Saxon 9.3.0.5 EE.

Transformation Scenario
Before transforming an 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.
• Scenarios that apply to SQL files - Such a scenario specifies a database connection for the database server that
will run the SQL file associated with the scenario. The data processed by the SQL script is located in the database.
• Scenarios that apply to XProc files - Such a scenario contains the location of an XProc script and other transform
parameters.
• DITA-OT scenarios - Such a scenario provides the parameters for an Ant transformation that will execute a DITA-OT
build script. Oxygen comes with a built-in version of Ant and a built-in version of DITA-OT but different versions
can be set in 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
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. The default scenario contains in the XSL URL field
the URL from the href attribute of the processing instruction. This scenario will have the Use xml-stylesheet declaration
248 | Oxygen XML Author | Transforming Documents

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
Scenario button before associating a scenario with the edited document will invoke first the Configure Transformation
Scenario dialog and then apply the selected scenario.
If there is only one scenario that can be associated with edited document, Configure Transformation Scenario dialog
is not displayed, scenario is associated with edited document and transformation is executed. This situation can appear
both for project scenarios and global scenarios when there is only one scenario in list of possible scenarios that include
document type scenarios and project/global scenarios. Association of that scenario can be changed by opening Configure
Transformation Scenario dialog with an action having the same name ( Configure Transformation Scenario)
from the toolbar.
Open the Configure Transformation Scenario dialog using one of the methods previously presented or by selecting
XML > Configure transformation scenario. (Alt+Shift+T C) ( (Cmd+Alt+T C on Mac OS)) .

Figure 123: Configure Transformation Scenario Dialog

The Scenario type allows you to choose what type of user defined transformation scenario is displayed:
• All - No filtering. All user-defined scenarios are displayed.
• XML transformation with XSLT - Transformation scenarios that apply an XSLT stylesheet over an XML.
• XML transformation with XQuery - Transformation scenarios that apply an XQuery over an XML.
• DITA OT transformation - Transformation scenarios that use the DITA Open Toolkit (DITA-OT) to transform
XML content into an output format.
Oxygen XML Author | Transforming Documents | 249

• ANT transformation - Transformation scenarios that execute ANT scripts.

• XSLT transformation - Transformation scenarios that apply an XSLT stylesheet over an XML file.
• XProc transformation - Transformation scenarios that execute XProc XML pipelines.
• XQuery transformation - Represents a transformation that consists in applying an XQuery over an XML.
• SQL transformation - Executes an SQL over a database.
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 124: 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 transformer 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.

Note: If the transformer engine is one of the built-in XSLT 2.0 engines and the name of an initial template is
specified in the scenario then the XML URL field can be empty. Also the XML URL field can be empty in
case of external XSLT processors. In all other cases a non-empty XML URL value is mandatory.

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.
250 | Oxygen XML Author | Transforming Documents

• 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 XSLT/XQuery files only, if no validation
scenario is associated, the transformer engine will be used in validation process, if it 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. If the XSLT transformer engine is custom defined this dialog cannot be used to
configure the parameters sent to the custom engine. In this case you can copy all parameters from the dialog using
the contextual menu actions and edit the custom XSLT engine to include in the command line the necessary parameters.
• 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.
Oxygen XML Author | Transforming Documents | 251

Figure 125: The advanced options of Saxon HE / PE / EE

The advanced options specific for Saxon HE / PE / EE are:

• Mode ("-im") - Specifies to the transformer the initial template mode
• Template ("-it") - 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 ("-config") - The URL input points to Saxon advanced options configuration file.
• Version warnings ("-versmsg") - Warns you when the transformation is applied to an XSLT 1.0 stylesheet.
• Line numbering ("-l") - Error line number is included in the output messages.
• Debugger trace into XPath expressions (applies to debugging sessions) - Instructs the XSLT Debugger to step
into XPath expressions.
• DTD validation of the source ("-dtd") - The following options are available:
• On, requests DTD-based validation of the source file and of any files read using the document() function;
• Off (default setting) suppresses DTD validation.
• Recover, performs DTD validation but treats the error as non-fatal if it fails
Note that any external DTD is likely to be read even if not used for validation, because DTDs can contain definitions
of entities.
• Recoverable errors ("-warnings") - Policy for handling recoverable errors in the stylesheet: Allows you to choose
how dynamic errors are handled. Either one of the following options can be selected:
252 | Oxygen XML Author | Transforming Documents

• Recover silently ("silent") ;

• Recover with warnings ("recover") . Default setting;
• Signal the error and do not attempt recovery ("fatal").

• Strip whitespaces ("-strip") - Strip whitespaces feature can be one of the following three options:
• All ("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 ("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 ("none") - Default setting. Strips no whitespace before further processing. However, whitespace will still
be stripped if this is specified in the stylesheet using xsl:strip-space.

• Optimization level ("-opt") - Set optimization level. The value is an integer in the range 0 (no optimization) to 10
(full optimization); currently all values other than 0 result in full optimization but this is likely to change in future.
The default is full optimization; this feature allows optimization to be suppressed in cases where reducing compile
time is important, or where optimization gets in the way of debugging, or causes extension functions with side-effects
to behave unpredictably. (Note however, that even with no optimization, lazy evaluation may still cause the evaluation
order to be not as expected.)
The advanced options available only in Saxon PE / EE are:
• Allow calls on extension functions ("-ext") - If checked, the stylesheet is allowed to call external Java functions.
This does not affect calls on integrated extension functions, including Saxon and EXSLT extension functions. This
option is useful when loading an untrusted stylesheet, perhaps from a remote site using an http:// URL; it ensures
that the stylesheet cannot call arbitrary Java methods and thereby gain privileged access to resources on your machine.
The advanced options available only in Saxon EE are:
• Validation of the source file ("-val") - Requests schema-based validation of the source file and of any files read
using the document() or similar functions. Validation is available only with Saxon-EE, and this flag automatically
switches on the -sa option. Available options:
• Schema validation ("strict") - This mode requires an XML Schema and determines whether source documents
should be parsed with schema-validation enabled.
• Lax schema validation ("lax") - 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 ("-outval") - Normally, if validation of result documents
is requested, a validation error is fatal. Enabling this option causes such validation failures to be treated as warnings.
• Write comments for non-fatal validation errors of the result document - The validation messages are written
(where possible) as a comment in the result document itself.
When creating a scenario that applies to an XML file, Oxygen fills the XML URL field with the default variable
${currentFileURL}. 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.
Oxygen XML Author | Transforming Documents | 253

Figure 126: The Configure Transformation Dialog - FO Processor Tab

• Perform FO Processing - Enables or disables applying an FO processor (either the built-in Apache FOP engine or
an external engine defined in Preferences) during the transformation.
• XSLT result as input - The FO processor is applied to the result of the XSLT transformation defined on the XSLT
tab of the dialog.
• XML URL as input - The FO processor is applied to the input XML file.
• Method - The output format of the FO processing. Available options depend on the selected processor type.
• Processor - The FO processor, which can be the built-in Apache FOP processor or an external processor.

Figure 127: The Configure Transformation Dialog - Output Tab

254 | Oxygen XML Author | Transforming Documents

• 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.
• 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.
• 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).
Note: Go to Window > Preferences > General > Web Browser to set the web browser that will be used for
displaying HTML/XHTML pages.

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

• 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.
• 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:
Oxygen XML Author | Transforming Documents | 255

Figure 128: Configure parameters dialog

The table presents all the parameters of the XSLT stylesheet, all imported and included stylesheets and all additional
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 having a namespace, for example like:
<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

If the XPath column is checked, the parameter value is evaluated as an XPath expression before starting the XSLT
transformation.

For example you can use expressions like:

doc('test.xml')//entry
//person[@atr='val']

Note:
1. The doc function solves the argument relative to the XSL stylesheet location. You can use full paths or editor
variables like ${cfdu} (current file directory) to specify other locations: doc('${cfdu}/test.xml')//*
2. You cannot use XSLT Functions. Only the XPath functions are allowed.

The following actions are available for managing parameters:

• New - Adds a new parameter to the list.
• Edit - Edits the value of the selected parameter.
• Unset - Resets the selected parameter to its default value. Available only for parameters with set values.
256 | Oxygen XML Author | Transforming Documents

• Delete - Removes the selected parameter from the list. It is enabled only for parameters added to the list with the
New 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'.

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. 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 - Moves the selected stylesheet up in the list.
• Down - Moves 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 transformation scenario.

1. Go to menu XML > Configure 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.

ANT Transformations
The following options are available in the Options tab:
• Working directory - Path of the directory where results are stored.
Oxygen XML Author | Transforming Documents | 257

• Build file - ANT script file.

• Build target - You can specify a build target to the ANT script file. By default no target is necessary and the default
init target is used.
• Additional arguments - Additional command-line arguments to be passed to the ANT transformation (for example
-verbose).
• Ant Home - Path to the custom ANT installation to run the transformation. By default it is the ANT installation
bundled with Oxygen.
• Java Home - You can specify a custom Java Virtual Machine to run the ANT transformation. By default it is the
Java Virtual Machine used by Oxygen.
• JVM Arguments - This parameter allows you to set specific parameters to the Java Virtual Machine used by ANT.
By default it is set to -Xmx256m which means the transformation process is allowed to use 256 megabytes of memory.
Sometimes, when performing a large DITA map transformation you may want to increase the memory allocated to
the Java Virtual Machine from the default value (256 MB) to a higher value, like 512 MB. In this way, you can avoid
running out of memory when running and ANT process.
In the Parameters tab use the toolbar buttons to add, edit or remove transformation parameters.
Use the Output tab to set the file to open after the transformation has finished. Also you can choose what application
is used for opening the output file.

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 129: The Scenarios view

258 | Oxygen XML Author | Transforming Documents

The actions available on the right click menu allow the same operations as in the dialog Configure Transformation
Scenario:
• Apply - Runs the current transformation scenario that is selected in the list of scenarios.
• Debug Scenario - Switches to the Debugger perspective and initialize it with the parameters from the scenario:
the XML input, the XSLT or XQuery input, the transformation engine, the XSLT parameters.
• New - Creates a new transformation scenario.
•
Duplicate - Adds a new scenario to the list that is a duplicate of the current scenario. It is useful for creating a
new scenario that is the same as an existing one but needs some changes.
• Edit - Opens the dialog for editing the parameters of a transformation scenario.
• Remove - Removes the current scenario from the list. This action is also available on the Delete key.
• Show all scenarios / Show current editor scenarios - A toggle action that switches between two modes: show
/ hide the scenarios that are specified in the document type corresponding to the current editor. All global scenarios
(the scenarios that are not specified in a document type) are always displayed in the view regardless of the state of
this action.

XSLT Processors
This section explains how to configure an XSLT processor and extensions for such a processor in Oxygen.

Supported XSLT Processors

Oxygen comes with the following XSLT processors:
• Xalan 2.7.1 - Xalan-Java 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.3.0.5 Home Edition (HE), Professional Edition (PE) - Saxon-HE/PE implements the basic conformance
level for XSLT 2.0 and XQuery 1.0. 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.3.0.5 Enterprise Edition (EE) - Saxon EE is the schema-aware edition of Saxon 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 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
Oxygen XML Author | Transforming Documents | 259

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 the root of the com.oxygenxml.editor_12.2.0 plugin:
• on Windows: xsltproc.exe, zlib1.dll,libxslt.dll,libxml2.dll, libexslt.dll,iconv.dll
• on Linux: xsltproc,libexslt.so.0, libxslt.so.1,libxsml2.so.2
• on Mac OS X: xsltproc.mac, libexslt, libxslt, libxml
The Xsltproc processor can be configured from the XSLTPROC options page.
Caution: 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 is available only on Windows 2000, Windows NT and Windows XP platforms.
It can be used for transformation .
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
• MSXML .NET - MSXML .NET is available only on Windows NT4, Windows 2000 and Windows XP platforms. It
can be used for transformation .
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 the Microsoft website
• .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 the Microsoft website
• .NET 2.0 - A transformer based on the System.Xml 2.0 library available in the .NET 2.0 framework from Microsoft.
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 the Microsoft website

Configuring Custom XSLT Processors

You 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
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.
260 | Oxygen XML Author | Transforming Documents

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:
• 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.3.0.5 - http://www.saxonica.com/documentation/extensibility/intro.xml
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.

XSL-FO Processors
This section explains how to apply XSL-FO processors when transforming XML documents to various output formats
in Oxygen.

The Built-in XSL-FO Processor

The Oxygen installation package is distributed with the Apache FOP that is a 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.
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.
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 can include the directory containing the native libraries
(mlib_jai.dll and mlib_jai_mmx.dll on Windows) in the PATH system variable.
The Mac OS 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.
Oxygen XML Author | Transforming Documents | 261

Other FO processors can be configured in the Preferences dialog.

Add a Font to the Built-in FOP - The Simple Version

If the font that must be set to Apache FOP is one of the fonts that are installed in the operating system you should follow
the next steps for creating and setting a FOP configuration file that looks for the font that it needs in the system fonts.
It is a simplified version of the procedure for setting a custom font in Apache FOP.

1. Register the font in FOP configuration. (not necessary in case of DITA PDF transformations, see next step)
a) Create a FOP configuration file that specifies that FOP should look for fonts in the installed fonts of the operating
system.
<fop version="1.0">
<renderers>
<renderer mime="application/pdf">
<fonts>
<auto-detect/>
</fonts>
</renderer>
</renderers>
</fop>

b) Set the FOP configuration file in Preferences.

Go to menu Options > Preferences > XML > XSLT/FO/XQuery > FO Processors and enter the path of the
FOP configuration file in the Configuration file for the built-in FOP text field.

2. Set the font on the document content.

This is done usually with XSLT stylesheet parameters and depends on the document type processed by the stylesheet.
• For DocBook documents you can start with the predefined scenario called DocBook PDF, edit the XSLT parameters
and set the font name (in our example the font family name is Arial Unicode MS) to the parameters
body.font.family and title.font.family.
• For TEI documents you can start with the predefined scenario called TEI PDF, edit the XSLT parameters and
set the font name (in our example Arial Unicode MS) to the parameters bodyFont and sansFont.
• For DITA transformations using DITA-OT you should use an IDIOM FOP transformation and modify the
following two files:
• ${frameworks}/dita/DITA-OT/demo/fo/cfg/fo/font-mappings.xml - the font-face
element included in each element physical-font having the attribute char-set="default"
must contain the name of the font (Arial Unicode MS in our example)
• ${frameworks}/dita/DITA-OT/demo/fo/fop/conf/fop.xconf - an element auto-detect
must be inserted in the element fonts which is inside the element renderer having the attribute
mime="application/pdf":
<renderer mime="application/pdf">
. . .
<fonts>
<auto-detect/>
</fonts>
. . .
</renderer>

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 special font that is capable to render these characters
must be configured and embedded in the PDF result.
262 | Oxygen XML Author | Transforming Documents

Important: If the special font that must be set to Apache FOP is installed in the operating system there is a simple
way of telling FOP to look for the font. See the simplified procedure for adding a font to FOP.

1. Locate the 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.
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.
2. Generate a font metrics file from the font file.
a) Open a terminal.
b) Change the working directory to the Oxygen install directory.
c) Create the following script file in the Oxygen installation directory.
For Mac OS X and Linux create a file 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 create a file 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 relative paths specified in the file are relative to the Oxygen installation directory so if you decide to create
it in other directory you have to change the file paths.
The FONT_DIR can be different on your system. Make sure it points to the correct font directory. If the Java
executable is not in the PATH you will have to specify the full path of the executable.
If the font has bold and italic variants, you will have to convert those too. For this you add two more lines to the
script file:
• for Mac OS X and Linux:
$CMD $FONT_DIR/Arialuni-Bold.ttf Arialuni-Bold.xml
$CMD $FONT_DIR/Arialuni-Italic.ttf Arialuni-Italic.xml

• for Windows:
%CMD% %FONT_DIR%\Arialuni-Bold.ttf Arialuni-Bold.xml
%CMD% %FONT_DIR%\Arialuni-Italic.ttf Arialuni-Italic.xml

d) Execute the script.

On Linux and Mac OS X you should execute the command sh ttfConvert.sh from the command line. On
Windows you should run the command ttfConvert.bat from the command line or double click on the file
ttfConvert.bat.

3. Register the font in FOP configuration. (not necessary in case of DITA PDF transformations, see next step)
a) Create a FOP configuration file that specifies the font metrics file for your font.
<fop version="1.0">
<base>./</base>
<font-base>file:/C:/path/to/FOP/font/metrics/files/</font-base>
Oxygen XML Author | Transforming Documents | 263

<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 font 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 example
for 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.
b) Set the FOP configuration file in Preferences.
Go to menu Options > Preferences > XML > XSLT/FO/XQuery > FO Processors and enter the path of the
FOP configuration file in the Configuration file for the built-in FOP text field.

4. Set the font on the document content.

This is done usually with XSLT stylesheet parameters and depends on the document type processed by the stylesheet.
For DocBook documents you can start with the predefined scenario called DocBook PDF, edit the XSLT parameters
and set the font name (in our example Arialuni) to the parameters body.font.family and title.font.family.
For TEI documents you can start with the predefined scenario called TEI PDF, edit the XSLT parameters and set
the font name (in our example Arialuni) to the parameters bodyFont and sansFont.
264 | Oxygen XML Author | Transforming Documents

For DITA transformations using DITA-OT you should use an IDIOM FOP transformation and modify the following
two files:
• ${frameworks}/dita/DITA-OT/demo/fo/cfg/fo/font-mappings.xml - 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)
• ${frameworks}/dita/DITA-OT/demo/fo/fop/conf/fop.xconf - an element font must be
inserted in the element fonts which is inside the element renderer having the attribute
mime="application/pdf":
<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>

XProc Transformations
This section explains how to configure and run XProc transformations in Oxygen.

XProc Transformation Scenario

A sequence of transformations described by an XProc script can be executed with an XProc transformation scenario. In
the scenario the parameters of the transformation are specified:
• the URL of the XProc script
• the XProc engine
• the input ports
• the output ports
On the XProc tab of the scenario edit dialog it is selected the URL of the XProc script and the XProc engine. The engine
can be the built-in one (Calabash) or a custom engine configured in the Preferences dialog.
On the Inputs tab of the dialog is configured each port that is used in the XProc script for reading input data. Each input
port has a name that is assigned in the XProc script and that is used for identifying the port in the list from the Port
combo box. The XProc engine will read data from the URLs specified in the URLs list. The built-in editor variables
and the custom editor variables can be used for specifying a URL.
On the Parameters tab you can specify the parameters available on each port.
Each port where is sent the output of the XProc transformation is associated with a URL on the Outputs tab of the
dialog. The built-in editor variables and the custom editor variables can be used for specifying a URL.
The result of the XProc transformation can be displayed as a sequence in an output view with two sides: a list with the
output ports on the left side and the content of the document(s) that correspond to the output port selected on the left
side. If the option Open in editor is selected, the XProc transformation result will be opened automatically in an editor
panel. If the option Open in browser is selected, you can specify a file to be opened in the default browser at the end
of the XProc transformation.
Oxygen XML Author | Transforming Documents | 265

Figure 130: XProc Transformation results view

Integration of an External XProc Engine

The Javadoc documentation of the XProc API is available for download in the following zip file: xprocAPI.zip. In
order to create an XProc integration project the following requirements must be fulfilled:

1. Take the oxygen.jar from [Oxygen-install-folder]/lib and put it in the lib folder of your project.
2. Implement the ro.sync.xml.transformer.xproc.api.XProcTransformerInterface interface.
The Javadoc documentation for the XProc API is available on our website: xprocAPI.zip.
3. Create a new Java archive (jar) from the classes you created.
4. Create a new engine.xml file according with the engine.dtd file. The attributes of the engine tag have the
following meanings:
1. name - The name of the XProc engine.
2. description - A short description of the XProc engine.
3. class - The complete name of the class that implements
ro.sync.xml.transformer.xproc.api.XProcTransformerInterface.
4. version - The version of this integration.
5. engineVersion - The version of the integrated engine.
6. vendor - The name of the vendor / implementor.
7. supportsValidation - true if the engine supports validation, false otherwise.
The engine tag has only one child, runtime. The runtime tag contains several library elements who's
attribute name contains the relative or absolute location of the libraries necessary to run this integration.
5. Create a new folder with the name of the integration in the [Oxygen-install-folder]/lib/xproc.
6. Put there the engine.xml, and all the libraries necessary to run properly the new integration.
Chapter
11
Querying Documents
Topics: This chapter shows how to query XML documents in Oxygen with XPath
expressions and with the XQuery language.
• Running XPath Expressions
• Working with XQuery
268 | Oxygen XML Author | Querying Documents

Running XPath Expressions

This section explains possible ways of running an XPath expression on an XML document.

What is XPath
XPath is a language for addressing specific parts of an XML document. XPath, like the Document Object Model (DOM),
models an XML document as a tree of nodes. An XPath expression is a mechanism for navigating through and selecting
nodes from the XML document. An XPath expression is in a way analogous to a Structured Query Language (SQL)
query used to select records from a database.
XPath models an XML document as a tree of nodes. There are different types of nodes, including element nodes, attribute
nodes and text nodes. XPath defines a way to compute a string-value for each type of node.
XPath defines a library of standard functions for working with strings, numbers and boolean expressions.

Some examples:
• child::* - Selects all children of the root node.
• .//name - Selects all elements having the name "name", descendants of the current node.
• /catalog/cd[price>10.80] - Selects all the cd elements that have a price element with
a value larger than 10.80.

To find out more about XPath, the following URL is recommended: http://www.w3.org/TR/xpath.

Oxygen's XPath Console

To use XPath effectively requires at least an understanding of the XPath Core Function Library. If you have this
knowledge the Oxygen XPath expression field part of the current editor toolbar can be used to aid you in XML document
development.
In Oxygen a XPath 1.0 or XPath 2.0 expression is typed and executed on the current document from the menu XML
> XPath (Ctrl+Shift+X) ( (Cmd+Shift+X on Mac OS)) or from the toolbar button . Both XPath 2.0 basic and
XPath 2.0 schema aware expressions can be executed in the XPath console. XPath 2.0 schema aware also takes into
account the Saxon EE XML Schema version option.
The content completion assistant that helps in entering XPath expressions in attributes of XSLT stylesheets elements is
also available in the XPath console and offers always proposals dependent of the current context of the cursor inside
the edited document. The set of XPath functions proposed by the assistant depends on the XPath version selected from
the drop-down menu of the XPath button (1.0 or 2.0).
In the following figure the cursor is on a person element and the content completion assistant offers all the child
elements of the person element and all XPath 2.0 functions:
Oxygen XML Author | Querying Documents | 269

Figure 131: Content Completion in the XPath console

The evaluation of the XPath expression tries to resolve the locations of documents referred in the expression through
the XML catalogs which are configured in Preferences and the current XInclude preferences. An example is evaluating
the collection(URIofCollection) function (XPath 2.0). If you need to resolve the references from the files
returned by the collection() function with an XML catalog set up in the Oxygen preferences you have to specify
the class name of the XML catalog enabled parser for parsing these collection files. The class name is
ro.sync.xml.parser.CatalogEnabledXMLReader and you specify it like this:
let $docs := collection(iri-to-uri(
"file:///D:/temp/test/XQuery-catalog/mydocsdir?recurse=yes;select=*.xml;
parser=ro.sync.xml.parser.CatalogEnabledXMLReader"))
The results of an XPath query are returned in the message panel. Clicking a record in the result list highlights the nodes
within the text editor panel with a character level precision. Results are returned in a format that is a valid XPath
expression:
- [FileName.xml] /node[value]/node[value]/node[value] -
270 | Oxygen XML Author | Querying Documents

Figure 132: XPath results highlighted in editor panel with character precision

When using the grid editor, clicking a result record will highlight the entire node.

Figure 133: XPath results highlighted in the Grid Editor

The popup menu of the history list of the XPath dialog contains the action Remove for removing the selected expression
from the history list.
Oxygen XML Author | Querying Documents | 271

XPath Utilization with DocBook DTD

The following examples are taken from a DocBook book based on the DocBook XML DTD. The
book contains a number of chapters. DocBook defines that chapters have a <chapter> start tag
and a matching </chapter> end tag to close the element. To return all the chapter nodes of the
book you should enter //chapter into the XPath expression field then press (Enter). This will
return all the chapter nodes of the DocBook book, in the message panel. If your book has six
chapters, they will be six records in the result list. Each record when clicked will locate and highlight
the chapter and all sibling nodes contained between the start and end tags of the chapter.
If you want to find all example nodes contained in the section 2 nodes of a DocBook XML
document you should use the following XPath expression:
//chapter/sect1/sect2/example. If an example node is found in any section 2
node, a result will be returned to the message panel. For each occurrence of the element node a
record will be created in the result list.
For example one of the results of the previous XPath query on the file oxygen.xml is:
- [oxygen.xml] /chapter[1]/sect1[3]/sect2[7]/example[1]
which means that in the file oxygen.xml, first chapter, third section level 1, seventh section level
2, the example node found is the first in the section.

Important: If the document defines a default namespace then Oxygen will bind this namespace to the first free
prefix from the list: default, default1, default2, etc. For example if the document defines the default
namespace xmlns="something" and the prefix default is not associated with a namespace then you can
match tags without prefix in a XPath expression typed in the XPath console by using the prefix default. For
example to find all the level elements when the root element defines a default namespace you should execute in
the XPath console the expression: //default:level.

To define default mappings between prefixes that can be used in the XPath console and namespace URIs go to the
XPath Options user preferences panel and enter the mappings in the Default prefix-namespace mappings table. The
same preferences panel allows also the configuration of the default namespace used in XPath 2.0 expressions entered
into the XPath toolbar and the creation of different message panels for XPath queries executed on different XML
documents.
To apply a XPath expression relative to the element on which the caret is positioned use the following actions:
• XML editor contextual menu > XML Document > Copy XPath (Ctrl+Shift+.) (also available on the context
menu of the main editor panel) to copy the XPath expression of the current element or attribute to the clipboard
• the Paste action of the contextual menu of the XPath console to paste this expression in the console
• add your relative expression in the console and execute the resulting complete expression
The popup menu available on right click in the Expression panel of the XPath expressions dialog offers the usual edit
actions: Cut, Copy, Paste, Select All.

Working with XQuery

This section explains how to edit and run XQuery queries in Oxygen.

What is XQuery
XQuery is the query language for XML and is officially defined by a W3C Recommendation document. The many
benefits of XQuery include:
272 | Oxygen XML Author | Querying Documents

• XQuery allows you to work in one common model no matter what type of data you're working with: relational,
XML, or object data.
• XQuery is ideal for queries that must represent results as XML, to query XML stored inside or outside the database,
and to span relational and XML sources.
• XQuery allows you to create many different types of XML representations of the same data.
• XQuery allows you to query both relational sources and XML sources, and create one XML result.

Syntax Highlight and Content Completion

To create a new XQuery document select File > New (Ctrl+N) and when the New dialog appears select XQuery entry.
In the XQuery document Oxygen provides syntax highlight for keywords and all known XQuery functions and operators.
Also for these there is available a content completion component that is activated with the (Ctrl-Space) shortcut. The
functions and operators are presented together with a comment about parameters and functionality. For some supported
database engines like eXist and Berkeley DB, the content completion lists contain the XQuery functions implemented
by that engine. The XQuery file must have an associated transformation scenario which uses one of the specified engines
or the validation uses one of these engines.
The extension functions built in the Saxon product are available on content completion if one of the following conditions
are true:
• the edited file has a transformation scenario associated that uses as transformation engine Saxon 9.3.0.5 PE or Saxon
9.3.0.5 EE
• the edited file has a validation scenario associated that use as validation engine Saxon 9.3.0.5 PE or Saxon 9.3.0.5
EE
• the validation engine specified in Preferences is Saxon 9.3.0.5 PE or Saxon 9.3.0.5 EE.
If the Saxon namespace (http://saxon.sf.net) is mapped to a prefix this prefix is used when the functions are presented,
otherwise the default prefix for the Saxon namespace (saxon) is used.
If you want to use a function from a namespace mapped to a prefix, just type that prefix and the content completion will
display all the XQuery functions from that namespace. The XQuery functions from default namespace offered by content
completion are prefixed if the default namespace is mapped to a prefix, otherwise is displayed just the name of this.
The content completion popup window presents all the variables and functions from both the edited XQuery file and its
imports.

XQuery Outline View

The XQuery document structure is presented in the XQuery Outline view. The outline tree presents the list of all the
components (namespaces, imports, variables, and functions) from both the edited XQuery file and its imports. It allows
a quick access to a component by knowing its name. It is opened from menu .
The following actions are available in the View menu on the Outline view's action bar:
• Selection update on caret move - Allows a synchronization between Outline view and source document. The
selection in the Outline view can be synchronized with the caret's moves or the changes in the XQuery editor.
Selecting one of the components from the Outline view also selects the corresponding item in the source document.
• Sort - Allows you to sort alphabetically the XQuery components.
• Show all components - Displays all components that were collected starting from the current file. This option is set
by default.
• Show local components - Displays components defined in the current file only.
• Group by location/namespace/type - Allows you to group the components by location, namespace, and type. When
grouping by namespace, the main XQuery module namespace is the first presented in the Outline view.
If you know the component name, you can search it in the Outline view by typing its name in the filter text field from
the bottom of the view or directly on the tree structure. When you type the component name in the filter text field you
Oxygen XML Author | Querying Documents | 273

can switch to the tree structure using the arrow keys of the keyboard, (Enter), (Tab), (Shift-Tab). To switch from
tree structure to the filter text field, you can use (Tab), (Shift-Tab).
Tip: The search filter is case insensitive. The following wildcards are accepted:
• * - any string
• ? - any character
• , - patterns separator
If no wildcards are specified, the string to search is searched as a partial match (like *textToFind*).

The upper part of the view contains a filter box which allows you to focus on the relevant components. Type a text
fragment in the filter box and only the components that match it are presented. For advanced usage you can use wildcard
characters (*, ?) and separate multiple patterns with commas.

The XQuery Input View

A node can be dragged and dropped in the editor area for quickly inserting doc() or other XQuery expressions.

Create FLWOR by drag and drop

For the following XML documents:

<movies>
<movie id="1">
<title>The Green Mile</title>
<year>1999</year>
</movie>
<movie id="2">
<title>Taxi Driver</title>
<year>1976</year>
</movie>
</movies>
and

<reviews>
<review id="100" movie-id="1">
<rating>5</rating>
<comment>It is made after a great Stephen King
book.
</comment>
<author>Paul</author>
</review>
<review id="101" movie-id="1">
<rating>3</rating>
<comment>Tom Hanks does a really nice
acting.</comment>
<author>Beatrice</author>
</review>
<review id="104" movie-id="2">
<rating>4</rating>
<comment>Robert De Niro is my favorite
actor.</comment>
<author>Maria</author>
</review>
</reviews>
and the following XQuery:

let $review := doc("reviews.xml")

274 | Oxygen XML Author | Querying Documents

for $movie in doc("movies.xml")/movies/movie

let $movie-id := $movie/@id
return
<movie id="{$movie/@id}">
{$movie/title}
{$movie/year}
<maxRating>
{

}
</maxRating>
</movie>
if you drag the rating element and drop between the braces a popup menu will be displayed.
Select FLWOR rating and the result document will be:

XQuery Validation
With Oxygen you can validate your documents before using them in your transformation scenarios. The validation uses
the Saxon 9.3.0.5 PE processor or the 9.3.0.5 EE, IBM DB2, eXist, Software AG Tamino, Berkeley DB XML or
Documentum xDb (X-Hive/DB) 10 if you installed them. Also any XQuery processor that offers an XQJ API
implementation can be used. This is in conformance with the XQuery Working Draft. The processor is used in two cases:
validation of the expression and execution. Although the execution implies a validation, it is faster to syntactically check
the expression without executing it. The errors that occurred in the document are presented in the messages view at the
bottom of editor window, with a full description message. As with all error messages, if you click on one entry, the line
where the error appeared is highlighted.
Please note that if you choose a processor that doesn't support XQuery validation you will receive a warning when trying
to validate.

Other XQuery Editing Actions

The XQuery editor type offers a reduced version of the popup menu available in the XML editor type, that means:
• the folding actions
• the edit actions
• a part of the source actions:
• To lower case
• To upper case
• Capitalize lines

• open actions:
• Open file at Caret
• Open file at Caret in System Application

Transforming XML Documents Using XQuery

XQueries are very similar to the XSL stylesheets in the sense they both are capable of transforming an XML input into
another format. You specify the input URL when you define the transformation scenario. The result can be saved and
opened in the associated application. You can even run a FO processor on the output of an XQuery. The transformation
scenarios may be shared between many XQuery files, are exported at the same time with the XSLT scenarios and can
be managed in the dialog Configure Transformation Scenario or in the Scenarios view. The transformation performed
can be based on the XML document specified in the XML URL field, or, if this field is empty, the documents referred
from the query expression are used instead. The parameters of XQuery transforms must be set in the Parameters dialog.
Oxygen XML Author | Querying Documents | 275

Parameters that are in a namespace must be specified using the qualified name, for example a param parameter in the
http://www.oxygenxml.com/ns namespace must be set with the name {http://www.oxygenxml.com/ns}param.
The transformation uses the processor Saxon 9.3.0.5 HE, Saxon 9.3.0.5 PE, Saxon 9.3.0.5 EE or a database connection
or any XQuery processor that provides an XQJ API implementation.
The Saxon 9.3.0.5 EE processor supports also XQuery 1.1 transformations. If the option Enable XQuery 1.1 support
is enabled Saxon EE runs an XQuery transformation as an XQuery 1.1 one.

XQJ Transformers
This section describes the procedures necessary to apply before running an XQJ transformation.
How to Configure an XQJ Data Source
Any transformer that offers an XQJ API implementation can be used when validating XQuery or transforming XML
documents.

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
4. Select XQuery API for Java(XQJ) in the Type combo box.
5. Press the Add button to add XQJ API specific files.
You can manage the driver files using the Add, Remove, Detect and Stop buttons.
Oxygen will detect any implementation of javax.xml.xquery.XQDataSource and present it in Driver class
field.
6. Select the most suited driver in the Driver class combo box.
7. Click the OK button to finish the data source configuration.

How to Configure an XQJ Connection

The steps for configuring an XQJ connection are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Connections panel.
3. Enter a unique name for this connection.
4. Select one of the previously configured XQJ data sources in the Data Source combo box.
5. Fill-in the connection details.
The properties presented in the connection details table are automatically detected depending on the selected data
source.
6. Click the OK button.

Display Result in Sequence View

The result of an XQuery executed on a database can be very large and sometimes only a part of the full result is needed.
For avoiding the long time necessary for fetching the full result the Evaluate as sequence option of the XQuery
transformation scenario should be used. This option fetches only the first chunk of the result and the user decides if he
wants to fetch the next chunk after looking at the first chunk in the Sequence result view.
The Evaluate as sequence option of the XQuery scenario must be selected in the Output tab of the dialog for editing
the transformation scenario.
A chunk of the XQuery transformation result is displayed in the Sequence view.

Advanced Saxon HE/PE/EE Transform Options

The XQuery transformation scenario allows configuring advanced options specific for the Saxon HE (Home Edition) /
PE (Professional Edition) / EE (Enterprise Edition) engine. The advanced options specific for Saxon HE / PE / EE are:
276 | Oxygen XML Author | Querying Documents

• Use a configuration file - If checked, the specified Saxon configuration file will be used to specify the Saxon
advanced options.
• Recoverable 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
• signal the error and do not attempt recovery

• Strip whitespaces - Can have one of the three options:

• 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).

• Optimization level - Allows optimization to be suppressed in cases where reducing compile time is important, or
where optimization gets in the way of debugging, or causes extension functions with side-effects to behave
unpredictably.
• Disable calls on extension functions - If checked, calling external Java functions is disallowed.
• Validation of the source file - Available only for Saxon EE. It can have the values:
• 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 EE. If checked, all validation
errors are treated as warnings, otherwise they are treated as fatal.
• Enable XQuery 1.1 support - If it is checked Saxon EE runs the XQuery transformation with the XQuery 1.1
support.
• Backup files updated by XQuery ("-backup:(on|off)") - If checked, a backup version is generated for any XML
files that is updated with XQuery Update.

Updating XML Documents using XQuery

Using the bundled Saxon 9.3.0.5 EE XQuery processor Oxygen now offers support for XQuery Update 1.0. The XQuery
Update Facility provides expressions that can be used to make persistent changes to instances of the XQuery 1.0 and
XPath 2.0 Data Model. Thus, besides querying XML documents, you can modify them using the various
insert/delete/modify/create methods available in the XQuery Update 1.0 standard.
Just choose Saxon 9.3.0.5 EE as a transformer in the scenario associated with XQuery files containing update statements
and Oxygen will notify you if the update was successful.

Using XQuery Update to modify a tag name in an XML file

rename node doc("books.xml")//publisher[1]//book[1] as "firstBook"
Chapter
12
Working with Archives
Topics: Oxygen offers the means to manipulate files directly from ZIP type archives.
By manipulation one should understand opening and saving files directly in
• Browsing and Modifying Archive archives, browsing and modifying archive structures. The archive support is
Structure available for all ZIP-type archives, which includes:
• Working with EPUB
• ZIP archives
• Editing Files From Archives
• EPUB books
• JAR archives
• Office Open XML (OOXML) files
• Open Document Format (ODF) files
• IDML files
This means that you can modify, transform, validate files directly from OOXML
or ODF packages. The structure and content of an EPUB book, OOXML file
or ODF file can be opened, edited and saved as for any other ZIP archive.
You can transform, validate and perform many other operations on files directly
from an archive. When selecting an URL for a specific operation like
transformation or validation you can click the Browse for archived file
button to navigate and choose the file from a certain archive.
278 | Oxygen XML Author | Working with Archives

Browsing and Modifying Archive Structure

You can navigate archives in the Archives Browser either by opening them from the Navigator or by using the integration
with the Eclipse File System. For the EFS (Eclipse File System) integration you must right click the archive in the
Navigator and choose Expand Zip Archive. All the standard Eclipse Navigator actions are available on the mounted
archive. If you decide to close the archive you can use the Collapse ZIP Archive action located in the contextual menu
for the expanded archive. Any file opened from the archive expanded in the EFS will be closed when the archive in
unmounted.
Attention: The ZIP support needs the IBM437 character set to be properly installed in the Java Runtime Environment
in order to be able to navigate / open ZIP archives. If you encounter an error message when expanding a ZIP archive
about the JVM that is missing a charset then the JVM used to run Eclipse does not have the character set library
properly installed.

If you open an archive as an Eclipse editor, the archive will be unmounted when the editor is closed.
Important: If a file is not recognized by Oxygen as a supported archive type, you can add it from the Archive
preferences page.

Figure 134: Browsing an Archive

The following operations are available on the Archive Browser toolbar:

• New folder... - Creates a new folder as child of the selected folder in the browsed archive.
• New file... - Creates a new file as child of the selected folder in the browsed archive.
• Add files... - Adds already existing files as children of the selected folder in the browsed archive.
Note: You can also add files in the archive by dragging them from the file browser and dropping them in the
Archive Browser view.

• Delete - Deletes the selected resource in the browsed archive.

• Archive Options... - Opens the Archive preferences page.
The following additional operations are available from the Archive Browser contextual menu:
• Open - Opens a resource from the archive in the editor.
• New folder... - Creates a new folder as child of the selected folder in the browsed archive.
• New file... - Creates a new file as child of the selected folder in the browsed archive.
• Add files... - Adds already existing files as children of the selected folder in the browsed archive.
Oxygen XML Author | Working with Archives | 279

Note: On Mac OS X, there is also available the Add file... action, which allows you to add one file at a time.

•
Find/Replace in Files - Allows you to search for and replace specific pieces of text inside the archive.
• Copy location - Copies the URL location of the selected resource.
• Refresh - Refreshes the selected resource.
• Properties - Views properties for the selected resource.

Working with EPUB

EPUB is a free and open electronic book standard by the International Digital Publishing Forum (IDPF). It was designed
for reflowable content, meaning that the text display can be optimized for the particular display device used by the reader
of the EPUB-formatted book.
Oxygen opens EPUB files in the Archive Browser view, exposing all their internal bits and pieces:
• document content (XHTML and image files);
• packaging files;
• container files.

Figure 135: EPUB file displayed in the Archive Browser view

Here you can edit, delete and add files that compose the EPUB structure. To check that the EPUB file you are currently
working is valid, invoke the Validate and Check for Completeness action. To perform the operation, Oxygen uses
the open-source EpubCheck validator which detects many types of errors, including OCF container structure, OPF and
OPS mark-up, as well as internal reference consistency. All errors found during validation are displayed in a separate
tab in the Errors view.
280 | Oxygen XML Author | Working with Archives

Create an EPUB
To begin writing an EPUB file from scratch, do the following:

1.
Select File > New (Ctrl+N) or press the New toolbar button.
2. Choose EPUB Book template. Click Create. Choose the name and location of the file. Click Save.
A skeleton EPUB file is saved on disk and open in the Archive Browser view.
3. Use the Archive Browser view specific actions to edit, add and remove resources from the archive.
4. Use the Validate and Check for Completeness action to verify the integrity of the EPUB archive.

Publish to EPUB
Oxygen comes with built-in support for publishing Docbook and DITA XML documents directly to EPUB.

1. Open the Configure Transformation Scenario dialog and choose a predefined transformation scenario.
2. Start the transformation scenario.

Editing Files From Archives

You can open in Oxygen and edit files directly from an archive using the Archive Browser view. When saving the
archived file you will be prompted with some backup operations which can be performed to ensure that your archive
data will not be corrupted. You have the following backup before save options:
• No backup - No backups are made.
• Single file backup - When you modify an archive, its content is backed up under the name
originalArchiveFileName.bak. You can find the backup file in the same folder as the original archive.
Note: The backup is done only once per application session for each archive open in the Archive Browser
view.

• Incremental backup - When you modify an archive, its content is backed up under the name
originalArchiveFileName.bakNumber. Number is an incremental integer, indicating how many backups
were made so far. You can find the backup file in the same folder as the original archive.
Note: The backup is done only once per application session for each archive open in the Archive Browser
view.

• Never ask me again - Check this option if you do not want to be notified again to backup. The last backup option
you chose will always be used as the default one. You can re-enable the dialog pop-up from the Archive preferences
page.
Chapter
13
Working with Databases
Topics: XML is a storage and interchange format for structured data and it is supported
by all major database systems. Oxygen offers the means of managing the
• Relational Database Support interaction with some of the widely used databases, both relational ones and
• Native XML Database (NXD) Native XML Databases. By interaction, one should understand browsing,
Support querying, SQL execution support, content editing, importing from databases,
• WebDAV Connection generating XML Schema from database structure.
282 | Oxygen XML Author | Working with Databases

Relational Database Support

Relational databases use a relational model and are based on tables linked by a common key. Oxygen offers support for
the following relational databases: IBM DB2, JDBC-ODBC Bridge, MySQL, Microsoft SQL Server, Oracle 11g:
• browsing the tables of these types of database in the Data Source Explorer view
• executing SQL queries against them
• calling stored procedures with input and output parameters

Configuring Database Data Sources

This section describes the procedures for configuring the data sources for relational databases.

How to Configure an IBM DB2 Data Source

The steps for configuring a data source for connecting to an IBM DB2 server are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
The dialog for configuring a data source will be opened.

Figure 136: Data Source Drivers Configuration Dialog

3. Enter a unique name for the data source.

4. Select DB2 in the driver type combo box.
5. Add the driver files for IBM DB2 using the Add button.
The IBM DB2 driver files are:
Oxygen XML Author | Working with Databases | 283

• db2jcc.jar
• db2jcc_license_cisuz.jar
• db2jcc_license_cu.jar
In the Download links for database drivers section there are listed the URLs from where to download the drivers
necessary for accessing IBM DB2 databases in Oxygen.
6. Select the most suited Driver class.
7. Click the OK button to finish the data source configuration.

How to Configure a Generic JDBC Data Source

Oxygen's default configuration already contains a generic JDBC data source called JDBC-ODBC Bridge. Oxygen can
display and edit XML data stored in PostgreSQL and Microsoft SQL Server databases accessible through a JDBC 4
driver. To do this, configure a Generic JDBC data source that uses a JDBC 4 driver. The following procedure shows
you how to configure a generic JDBC data source:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
The following dialog is displayed:

Figure 137: Data Source Drivers Configuration Dialog

3. Enter a unique name for the data source.

4. Select Generic JDBC in the driver type combo box.
5. Add the driver file(s) using the Add button.
6. Select the most suited Driver class.
7. Click the OK button to finish the data source configuration.
284 | Oxygen XML Author | Working with Databases

How to Configure a Microsoft SQL Server Data Source

The steps for configuring a data source for connecting to a Microsoft SQL server are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
The dialog for configuring a data source will be opened.

Figure 138: Data Source Drivers Configuration Dialog

3. Enter a unique name for the data source.

4. Select SQLServer in the driver type combo box.
5. Add the Microsoft SQL Server driver file using the Add button.
The SQL Server driver file is called sqljdbc.jar. In the Download links for database drivers section there are
listed the URLs from where to download the drivers necessary for accessing Microsoft SQL Server databases in
Oxygen.
6. Select the most suited Driver class.
7. Click the OK button to finish the data source configuration.

How to Configure a MySQL Data Source

Previous versions of Oxygen (up to version 11.2) included a built-in type of data sources called MySQL and based on
the JDBC driver for the MySQL 4 server. That type of data source is still available but is marked outdated because it
does not support more recent versions of the MySQL server (starting from version 5.0) and it will be removed in a future
version of Oxygen.For connecting to a MySQL server you should create a new data source of type Generic JDBC based
on the MySQL JDBC driver available from the MySQL website. The steps for configuring such a data source are the
following:
Oxygen XML Author | Working with Databases | 285

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
The dialog for configuring a data source will be opened.

Figure 139: Data Source Drivers Configuration Dialog

3. Enter a unique name for the data source.

4. Select Generic JDBC in the driver type combo box.
5. Add the MySQL 5 driver files using the Add button.
The driver file for the MySQL server is called mysql-com.jar. In the Download links for database drivers section
there are listed the URLs from where to download the drivers necessary for accessing MySQL databases in Oxygen.
6. Select the most suited Driver class.
7. Click the OK button to finish the data source configuration.

How to Configure an Oracle 11g Data Source

The steps for configuring a data source for connecting to an Oracle 11g server are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
The dialog for configuring a data source will be opened.
286 | Oxygen XML Author | Working with Databases

Figure 140: Data Source Drivers Configuration Dialog

3. Enter a unique name for the data source.

4. Select Oracle in the driver type combo box.
5. Add the Oracle driver file using the Add button.
The Oracle driver file is called ojdbc5.jar. In the Download links for database drivers section there are listed
the URLs from where to download the drivers necessary for accessing Oracle databases in Oxygen.
6. Select the most suited Driver class.
7. Click the OK button to finish the data source configuration.

How to Configure a PostgreSQL 8.3 Data Source

The steps for configuring a data source for connecting to a PostgreSQL server are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
The dialog for configuring a data source will be opened.
Oxygen XML Author | Working with Databases | 287

Figure 141: Data Source Drivers Configuration Dialog

Figure 142: Data Source Drivers Configuration Dialog

3. Enter a unique name for the data source.

288 | Oxygen XML Author | Working with Databases

4. Select PostgreSQL in the driver type combo box.

5. Add the PostgreSQL driver file using the Add button.
The PostgreSQL driver file is called postgresql-8.3-603.jdbc3.jar. In the Download links for database
drivers section there are listed the URLs from where to download the drivers necessary for accessing PostgreSQL
databases in Oxygen.
6. Select the most suited Driver class.
7. Click the OK button to finish the data source configuration.

Configuring Database Connections

This section describes the procedures for configuring the connections for relational databases:

How to Configure an IBM DB2 Connection

Available in the Enterprise edition only.
The steps for configuring a connection to an IBM DB2 server are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
The dialog for configuring a database connection will be displayed.

Figure 143: The Connection Configuration Dialog

3. Enter a unique name for the connection.

4. Select an IBM DB2 data sources in the Data Source combo box.
5. Fill-in the connection details.
a) Fill-in the URL to the installed IBM DB2 engine.
b) Fill-in the user name to access the IBM DB2 engine.
c) Fill-in the password to access the IBM DB2 engine.
6. Click the OK button to finish the configuration of the database connection.
Oxygen XML Author | Working with Databases | 289

How to Configure a JDBC-ODBC Connection

The steps for configuring a connection to an ODBC data source are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
The dialog for configuring a database connection will be displayed.

Figure 144: The Connection Configuration Dialog

3. Enter a unique name for the connection.

4. Select JDBC-ODBC bridge in the Data Source combo box.
5. Fill-in the connection details.
a) Fill-in the URL of the ODBC source.
b) Fill-in the user name of the ODBC source.
c) Fill-in the password of the ODBC source.
6. Click the OK button to finish the configuration of the database connection.

How to Configure a Microsoft SQL Server Connection

Available in the Enterprise edition only.
The steps for configuring a connection to a Microsoft SQL Server server are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
The dialog for configuring a database connection will be displayed.
290 | Oxygen XML Author | Working with Databases

Figure 145: The Connection Configuration Dialog

3. Enter a unique name for the connection.

4. Select a SQL Server data source in the Data Source combo box.
5. Fill-in the connection details.
a) Fill-in the URL of the SQL Server server.
b) Fill-in the user name for the connection to the SQL Server.
c) Fill-in the password for the connection to the SQL Server.
6. Click the OK button to finish the configuration of the database connection.

How to Configure a MySQL Connection

The steps for configuring a connection to a MySQL server are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
The dialog for configuring a database connection will be displayed.
Oxygen XML Author | Working with Databases | 291

Figure 146: The Connection Configuration Dialog

3. Enter a unique name for the connection.

4. Select a MySQL data source in the Data Source combo box.
5. Fill-in the connection details.
a) Fill-in the URL of the MySQL server.
b) Fill-in the user name for the connection to the MySQL server.
c) Fill-in the password for the connection to the MySQL server.
6. Click the OK button to finish the configuration of the database connection.

How to Configure an Oracle 11g Connection

Available in the Enterprise edition only.
The steps for configuring a connection to an Oracle 11g server are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
The dialog for configuring a database connection will be displayed.
292 | Oxygen XML Author | Working with Databases

Figure 147: The Connection Configuration Dialog

3. Enter a unique name for the connection.

4. Select an Oracle 11g data source in the Data Source combo box.
5. Fill-in the connection details.
a) Fill-in the URL of the Oracle server.
b) Fill-in the user name for the connection to the Oracle server.
c) Fill-in the password for the connection to the Oracle server.
6. Click the OK button to finish the configuration of the database connection.

How to Configure a PostgreSQL 8.3 Connection

Available in the Enterprise edition only.
The steps for configuring a connection to a PostgreSQL 8.3 server are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
The dialog for configuring a database connection will be displayed.
Oxygen XML Author | Working with Databases | 293

Figure 148: The Connection Configuration Dialog

3. Enter a unique name for the connection.

4. Select a PostgreSQL 8.3 data source in the Data Source combo box.
5. Fill-in the connection details.
a) Fill-in the URL of the PostgreSQL 8.3 server.
b) Fill-in the user name for the connection to the PostgreSQL 8.3 server.
c) Fill-in the password for the connection to the PostgreSQL 8.3 server.
6. Click the OK button to finish the configuration of the database connection.

Resource Management
This section explains the resource management actions for relational databases.

Data Source Explorer View

This view presents in a tree-like fashion the database connections configured from menu Options > Preferences >
Data Sources . You can connect to a database simply by expanding the connection node. The database structure can be
expanded up to column level. Oxygen supports multiple simultaneous database connections and the connections tree
provides an easy way to browse them.
294 | Oxygen XML Author | Working with Databases

Figure 149: Data Source Explorer View

The following objects are displayed by the Data Source Explorer view:
• Connection
• Catalog (Collection)
• XML Schema Repository
• XML Schema Component
• Schema
• Table
• System Table
• Table Column

A collection (called catalog in some databases) is a hierarchical container for resources and further
sub-collections. There are two types of resources:
• XML resource - an XML document or a document fragment, selected by a previously executed XPath query.
• non XML resource
The following actions are available in the view's toolbar:
• The Filters button opens the Data Sources / Table Filters Preferences page, allowing you to decide which
table types will be displayed in the Data Source Explorer view.
• The Configure Database Sources button opens the Data Sources preferences page where you can configure
both data sources and connections.
Actions Available at Connection Level in Data Source Explorer View
The contextual menu of a Connection node of the tree from the Data Source Explorer view contains the following
actions:
• Refresh - Performs a refresh of the selected node's subtree.
Oxygen XML Author | Working with Databases | 295

• Disconnect - Closes the current database connection. If a table is already open, you are warned to close it before
proceeding.
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
Actions Available at Catalog Level in Data Source Explorer View
The contextual menu of a Catalog node of the tree from the Data Source Explorer view contains the following
actions:
• Refresh - Performs a refresh of the selected node's subtree.
Actions Available at Schema Level in Data Source Explorer View
The contextual menu of a Schema node of the tree from the Data Source Explorer view contains the following
actions:
• Refresh - Performs a refresh of the selected node's subtree.
Actions Available at Table Level in Data Source Explorer View
The contextual menu of a Table node of the tree from the Data Source Explorer view contains the following
actions:
• Refresh - Performs a refresh of the selected node's subtree.
• Edit - Opens the selected table in the Table Explorer view.
• Export to XML - Opens the Export Criteria dialog .
XML Schema Repository Level
This section explains the actions available at XML Schema Repository level.
Oracle's XML Schema Repository Level
The Oracle database supports XML schema repository (XSR) in the database catalogs. The contextual menu of a
XML Schema Repository node of the tree from the Data Source Explorer view contains the following actions:
• Refresh - Performs a refresh of the selected node's subtree.
• Register - Opens a dialog for adding a new schema file in the XML repository. To add an XML Schema, enter the
schema URI and location on your file system. Local scope means that the schema will be visible only to the user
who registers it. Global scope means that the schema is public.
IBM DB2's XML Schema Repository Level
The contextual menu of a XML Schema Repository node of the tree from the Data Source Explorer view
contains the following actions:
• Refresh - Performs a refresh of the selected node's subtree.
• Register - Opens a dialog for adding a new schema file in the XML Schema repository. In this dialog the following
fields can be set:
• XML schema file - Location on your file system.
• XSR name - Schema name.
• Comment - Short comment (optional).
• Schema location - Primary schema name (optional).
Decomposition means that parts of the XML documents are stored into relational tables. Which parts map to which
tables and columns is specified into the schema annotations.
Schema dependencies management is done by using the Add and Remove buttons.

The actions available at Schema level are the following:

296 | Oxygen XML Author | Working with Databases

• Refresh - Performs a refresh of the selected node (and it's subtree).

• Unregister - Removes the selected schema from the XML Schema Repository.
• View - Opens the selected schema in Oxygen.
Microsoft SQL Server's XML Schema Repository Level
The contextual menu of a XML Schema Repository node of the tree from the Data Source Explorer view
contains the following actions:
• Refresh - Performs a refresh of the selected node's subtree.
• Register - Opens a dialog for adding a new schema file in the DB XML repository. In this dialog you enter a collection
name and the necessary schema files. XML Schema files management is done by using the Add and Remove buttons.

The actions available at Schema level are the following:

• Refresh - Performs a refresh of the selected node (and it's subtree).
• Add - Adds a new schema to the XML Schema files.
• Unregister - Removes the selected schema from the XML Schema Repository.
• View - Opens the selected schema in Oxygen.

Table Explorer View

Every table from the Data Source Explorer view can be displayed and edited in the Table Explorer view by pressing
the Edit button from the contextual menu or by double-clicking one of its fields. To modify a cell's content, double click
it and start typing. When editing is finished, Oxygen will try to update the database with the new cell content.

Figure 150: The Table Explorer View

You can sort the content of a table by one of its columns by clicking on its column header.
Note the following:
• The first column is an index (does not belong to the table structure).
• Every column header contains the field name and its data type.
• The primary key columns are marked with this symbol: .
• Multiple tables are presented in a tabbed manner
For performance issues, you can set the maximum number of cells that will be displayed in the Table Explorer view (
the Limit the number of cells field from the Data Sources Preferences page). If a table having more cells than the value
set in Oxygen's options is displayed in the Table Explorer view, a warning dialog will inform you that the table is only
partially shown.
Oxygen XML Author | Working with Databases | 297

You will be notified if the value you have entered in a cell is not valid (and thus it cannot be updated).
• If the content of the edited cell does not belong to the data type of the column, an Information dialog will appear,
notifying you that the value you have inserted cannot be converted to the SQL type of that field. For example, in the
above figure propID contains LONG values. If a character or string was inserted, you would get the error message
that a String value cannot be converted to the requested SQL type (NUMBER).
• If the constraints of the database are not met (like primary key constraints for example), an Information dialog will
appear, notifying you of the reason the database has not been updated. For example, if you'd try to set the primary
key propID for the second record in the table to 10 also, you would get the following message:

Figure 151: Duplicate entry for primary key

The usual edit actions (Cut, Copy, Paste, Select All, Undo, Redo) are available in the popup menu of the edited cell.
The contextual menu available on every cell has the following actions:
• Set NULL - Sets the content of the cell to (null). This action is disabled for columns that cannot be null.
• Insert row - Inserts an empty row in the table.
• Duplicate row - Makes a copy of the selected row and adds it in the Table Explorer view. You should note
that the new row will not be inserted in the database table until all conflicts are solved.
• Commit row - Commits the selected row.
• Delete row - Deletes the selected row.
• Copy - Copies the content of the cell.
• Paste - Performs paste in the selected cell.
Some of the above actions are also available on the Table Explorer toolbar:
• Export to XML - Opens the Export Criteria dialog .
• Refresh - Performs a refresh of the selected node's subtree.
• Insert row - Inserts an empty row in the table.
• Duplicate row - Makes a copy of the selected row and adds it in the Table Explorer view. You should note
that the new row will not be inserted in the database table until all conflicts are solved.
• Commit row - Commits the selected row.
• Delete row - Deletes the selected row.
298 | Oxygen XML Author | Working with Databases

Native XML Database (NXD) Support

Native XML databases have an XML-based internal model and their fundamental unit of storage is XML. Oxygen offers
support for the following native XML databases:
• Berkeley DB XML
• eXist
• MarkLogic
• Software AG Tamino
• Raining Data TigerLogic
• Documentum xDb (X-Hive/DB) 10
• Oracle XML DB

Configuring Database Data Sources

This section describes the procedures for configuring the data sources for native databases.

How to Configure a Berkeley DB XML Data Source

The latest instructions on how to configure Berkeley DB XML support in Oxygen can be found on our website.
Oxygen supports Berkeley DB XML versions 2.3.10, 2.4.13, 2.4.16 & 2.5.16. The following directory definitions shall
apply:
• OXY_DIR - Oxygen installation root directory. (for example on Windows C:\Program Files\Oxygen 12.2)
• DBXML_DIR - Berkeley DB XML database root directory. (for example on Windows C:\Program
Files\Oracle\Berkeley DB XML <version>)
• DBXML_LIBRARY_DIR (usually on Mac and Unix is DBXML_DIR / lib and on Windows is DBXML_DIR
/ bin)

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
4. Select Berkeley DBXML from the Driver type combo box.
5. Press the Add button to add the Berkeley DB driver files.
The driver files for the Berkeley DB database are the following:
• db.jar (check for it into DBXML_DIR / lib or DBXML_DIR / jar)
• dbxml.jar (check for it into DBXML_DIR / lib or DBXML_DIR / jar)

6. Click the OK button to finish the data source configuration.

How to Configure an eXist Data Source

The latest instructions on how to configure eXist support in Oxygen can be found on our website.
Oxygen supports eXist database server versions 1.3, 1.4 and 1.5.

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
4. Select eXist from the Driver type combo box.
5. Press the Add button to add the eXist driver files.
Oxygen XML Author | Working with Databases | 299

The following driver files should be added in the dialog box for setting up the eXist datasource. They are found in
the installation directory of the eXist database server. Please make sure you copy the files from the installation of
the eXist server where you want to connect from Oxygen.
• exist.jar
• lib/core/xmldb.jar
• lib/core/xmlrpc-client-3.1.1.jar
• lib/core/xmlrpc-common-3.1.1.jar
• lib/core/ws-commons-util-1.0.2.jar
The version number from the driver file names may be different for your eXist server installation.
6. Click the OK button to finish the data source configuration.

How to Configure a MarkLogic Data Source

The latest instructions on how to configure MarkLogic support in Oxygen can be found on our website.

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
4. Select MarkLogic from the Driver type combo box.
5. Press the Add button to add the MarkLogic driver files.
The driver file for the MarkLogic database is called xcc.jar. In the Download links for database drivers section
there are listed the URLs from where to download the drivers necessary for accessing MarkLogic databases in
Oxygen.
6. Click the OK button to finish the data source configuration.

How to Configure a Software AG Tamino Data Source

The latest instructions on how to configure Software AG Tamino support in Oxygen can be found on our website .

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
4. Select Tamino from the Driver type combo box.
5. Press the Add button to add the Tamino driver files.
The driver files for the Tamino database are the following:
• TaminoAPI4J.jar
• TaminoAPI4J-l10n.jar
• TaminoJCA.jar
Note: You must use the jar files from the version 4.4.1 of the Tamino database.

6. Click the OK button to finish the data source configuration.

How to Configure a Raining Data TigerLogic Data Source

The latest instructions on how to configure TigerLogic support in Oxygen can be found on our website .

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
300 | Oxygen XML Author | Working with Databases

4. Select TigerLogic from the Driver type combo box.

5. Press the Add button to add the TigerLogic driver files.
The driver files for the TigerLogic database are found in the TigerLogic JDK lib directory from the server side:
• connector.jar
• jca-connector.jar
• tlapi.jar
• tlerror.jar
• utility.jar
• xmlparser.jar
• xmltypes.jar

6. Click the OK button to finish the data source configuration.

How to Configure a Documentum xDb (X-Hive/DB) 10 Data Source

The latest instructions on how to configure support for Documentum xDb (X-Hive/DB) 10 versions 8 and 9 in Oxygen
can be found on our website.

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Data Sources panel.
3. Enter a unique name for the data source.
4. Select XHive from the Driver type combo box.
5. Press the Add button to add the XHive driver files.
The driver files for the Documentum xDb (X-Hive/DB) 10 database are found in the Documentum xDb (X-Hive/DB)
10 lib directory from the server installation folder:
• antlr-runtime.jar
• aspectjrt.jar
• icu4j.jar
• xhive.jar
• google-collect.jar

6. Click the OK button to finish the data source configuration.

Configuring Database Connections

This section describes the procedures for configuring the connections for native databases.

How to Configure a Berkeley DB XML Connection

Oxygen supports Berkeley DB XML versions 2.3.10, 2.4.13, 2.4.16 & 2.5.16. The steps for configuring a connection
to a Berkeley DB XML database are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Connections panel.
3. Enter a unique name for the connection.
4. Select one of the previously configured data sources from the Data Source combo box.
5. Fill-in the connection details.
a) Set the path to the Berkeley DB XML home directory in the Environment home directory field.
b) Select the Verbosity level: DEBUG, INFO, WARNING or ERROR.
c) Optionally, you can select the checkbox Join existing environment.
Oxygen XML Author | Working with Databases | 301

If checked, an attempt will be made to join an existing environment in the specified home directory and all the
original environment settings will be preserved. If that fails, you should consider reconfiguring the connection
with this option unchecked.

6. Click the OK button to finish the connection configuration.

How to Configure an eXist Connection

The steps for configuring a connection to an eXist database are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Connections panel.
3. Enter a unique name for the connection.
4. Select one of the previously configured data sources from the Data Source combo box.
5. Fill-in the connection details.
a) Set the URI to the installed eXist engine in the XML DB URI field.
b) Set the user name in the User field.
c) Set the password in the Password field.
d) Enter the start collection in the Collection field.
eXist organizes all documents in hierarchical collections. Collections are like directories. They are used to group
related documents together. This text field allows the user to set the default collection name.

6. Click the OK button to finish the connection configuration.

How to Configure a MarkLogic Connection

Available in the Enterprise edition only.
The steps for configuring a connection to a MarkLogic database are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Connections panel.
3. Enter a unique name for the connection.
4. Select one of the previously configured data sources from the Data Source combo box.
5. Fill-in the connection details.
a) The host name or IP address of the installed MarkLogic engine in the XDBC Host field.
Oxygen uses XCC connector to interact with MarkLogic XDBC server and requires the basic authentication
schema to be set. Starting with version MarkLogic 4.0 the default authentication method when you create a HTTP
or WebDAV Server is digest, so make sure to change it to basic.
b) Set the port number of the MarkLogic engine the Port field.
c) Set the user name to access the MarkLogic engine in the User field.
d) Set the password to access the MarkLogic engine in the Password field.
e) Optionally set the URL used for browsing the MarkLogic database in the Data Source Explorer view in the
WebDAV URL field.
6. Click the OK button to finish the connection configuration.

How to Configure a Software AG Tamino Connection

Available in the Enterprise edition only.
The steps for configuring a connection to a Tamino database are the following:

1. Go to menu Preferences > Data Sources .

302 | Oxygen XML Author | Working with Databases

2. Click the New button in the Connections panel.

3. Enter a unique name for the connection.
4. Select one of the previously configured data sources from the Data Source combo box.
5. Fill-in the connection details.
a) Set the URI to the installed Tamino engine in the XML DB URI field.
b) Set the user name to access the Tamino engine in the User field.
c) Set the password to access the Tamino engine in the Password field.
d) Set the name of the database to access from the Tamino engine in the Database field.
e) Check the checkbox Show system collections if you want to see the Tamino system collections in the Data
Source Explorer view.
6. Click the OK button to finish the connection configuration.

How to Configure a Raining Data TigerLogic Connection

Available in the Enterprise edition only.
The steps for configuring a connection to a TigerLogic database are the following:

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Connections panel.
3. Enter a unique name for the connection.
4. Select one of the previously configured data sources from the Data Source combo box.
5. Fill-in the connection details.
a) Set the host name or IP address of the TigerLogic engine in the Host field.
b) Set the port number of the TigerLogic engine in the Port field.
c) Set the user name to access the TigerLogic engine in the User field.
d) Set the password to access the TigerLogic engine in the Password field.
e) Set the name of the database to access from the TigerLogic database engine in the Database field.
6. Click the OK button to finish the connection configuration.

How to Configure an Documentum xDb (X-Hive/DB) 10 Connection

The steps for configuring a connection to a Documentum xDb (X-Hive/DB) 10 database are the following.
Note: The bootstrap type of X-Hive/DB connections is not supported in Oxygen. The following procedure explains
the xhive:// protocol connection type.

1. Go to menu Preferences > Data Sources .

2. Click the New button in the Connections panel.
3. Enter a unique name for the connection.
4. Select one of the previously configured data sources from the Data Source combo box.
5. Fill-in the connection details.
a) Set the URL property of the connection in the URL field.
If the property is a URL of the form xhive://host:port, the Documentum xDb (X-Hive/DB) 10 connection will
attempt to connect to a Documentum xDb (X-Hive/DB) 10 server running behind the specified TCP/IP port.
b) Set the user name to access the Documentum xDb (X-Hive/DB) 10 engine in the User field.
c) Set the password to access the Documentum xDb (X-Hive/DB) 10 engine in the Password field.
d) Set the name of the database to access from the Documentum xDb (X-Hive/DB) 10 engine in the Database field.
e) Check the checkbox Run XQuery in read / write session (with committing) if you want to end the session
with a commit, otherwise the session ends with a rollback.
Oxygen XML Author | Working with Databases | 303

6. Click the OK button to finish the connection configuration.

Data Source Explorer View

Figure 152: Data Source Explorer View

• The Configure Database Sources button opens the Data Sources preferences page where you can configure
both data sources and connections.

Berkeley DB XML Connection

This section explains the actions that are available on a Berkeley DB XML connection.
Actions Available at Connection Level
In a Berkeley DB XML repository the actions available at connection level in the Data Source Explorer view are the
following:
• Refresh - Performs a refresh of the selected node's subtree.
• Disconnect - Closes the current database connection.
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
• Add container - Adds a new container in the repository with the following attributes.
• Name - The name of the new container.
• Container type - At creation time, every container must have a type defined for it. This container type identifies
how XML documents are stored in the container. As such, the container type can only be determined at container
creation time; you cannot change it on subsequent container opens. Containers can have one of the following
types specified for them:
• Node container - XML documents are stored as individual nodes in the container. That is, each record in the
underlying database contains a single leaf node, its attributes and attribute values if any, and its text nodes,
if any. Berkeley DB XML also keeps the information it needs to reassemble the document from the individual
nodes stored in the underlying databases. This is the default, and preferred, container type.
• Whole document container - The container contains entire documents. The documents are stored without
any manipulation of line breaks or whitespace.

• Allow validation - If checked it causes documents to be validated when they are loaded into the container. The
default behavior is to not validate documents.
• Index nodes - If checked it causes indices for the container to return nodes rather than documents. The default
is to index at the document level. This property has no meaning if the container type is whole document container.

• Properties - Shows a dialog containing a list of the Berkeley connection properties: version, home location, default
container type, compression algorithm, etc.
Actions Available at Container Level
In a Berkeley DB XML repository the actions available at container level in the Data Source Explorer view are the
following:
• Add Resource - Adds a new XML resource to the selected container.
• Rename - Allows you to specify a new name for the selected container.
• Delete - Removes the selected container from the database tree.
• Edit indices - Allows you to edit the indices for the selected container.
Oxygen XML Author | Working with Databases | 305

Figure 153: Container indices

The fields of the dialog are the following:

• Granularity:
• Document level granularity is good for retrieving large documents.
• Node level granularity is good for retrieving nodes from within documents.

• Add / Edit indices:

• Node - The node name.
• Namespace - The index namespace
• Index strategy:
• Index type:
• Uniqueness - Indicates whether the indexed value must be unique within the container
• Path type:
• node - Indicates that you want to index a single node in the path
• edge - Indicates that you want to index the portion of the path where two nodes meet

• Node type:
• element - An element node in the document content.
• attribute - An attribute node in the document content.
• metadata - A node found only in a document's metadata content.

• Key type:
306 | Oxygen XML Author | Working with Databases

• equality - Improves the performances of tests that look for nodes with a specific value
• presence - Improves the performances of tests that look for the existence of a node regardless of
its value
• substring - Improves the performance of tests that look for a node whose value contains a given
substring

• Syntax types - The syntax describes what sort of data the index will contain and is mostly used to determine
how indexed values are compared.

• Refresh - Performs a refresh of the selected node's subtree.

• Properties - Displays a dialog with a list of properties of the Berkeley container like: container type, auto indexing,
page size, validate on load, compression algorithm, number of documents, etc.
Actions Available at Resource Level
In a Berkeley DB XML repository the actions available at resource level in the Data Source Explorer view are the
following:
• Refresh - Performs a refresh of the selected resource.
• Open - Opens the selected resource in the editor.
• Rename - Allows you to change the name of the selected resource.
• Move - Allows you to move the selected resource in a different container in the database tree (also available through
drag and drop).
• Delete - Removes the selected resource from the container.
• Copy location - Allows you to copy to clipboard an application specific URL for the resource which can then be
used for various actions like opening or transforming the resources.

eXist Connection
This section explains the actions that are available on an eXist connection.
Actions Available at Connection Level
For an eXist database the actions available at connection level in the Data Source Explorer view are the following:
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
• Disconnect - Closes the current database connection.
• Refresh - Performs a refresh of the selected node's subtree.
Actions Available at Container Level
For an eXist database the actions available at container level in the Data Source Explorer view are the following:
• Refresh - Performs a refresh of the selected node's subtree.
• New Collection - Creates a new collection.
• Import Folders - Adds recursively the content of specified folders from the local filesystem.
• Import Files - Adds a set of XML resources from the local filesystem.
• Delete - Removes the selected collection.
• Rename - Allows you to change the name of the selected collection.
• Move - Allows you to move the selected collection in a different location in the database tree (also available through
drag and drop).
Actions Available at Resource Level
For an eXist database the actions available at resource level in the Data Source Explorer view are the following:
Oxygen XML Author | Working with Databases | 307

• Refresh - Performs a refresh of the selected resource.

• Open - Opens the selected resource in the editor.
• Rename - Allows you to change the name of the selected resource.
• Move - Allows you to move the selected resource in a different collection in the database tree (also available through
drag and drop).
• Delete - Removes the selected resource from the collection.
• Copy location - Allows you to copy to clipboard an application specific URL for the resource which can then be
used for various actions like opening or transforming the resources.
• Properties - Allows the user to view various useful properties associated with the resource.
• Save As - Allows you to save the name of the selected binary resource as a file on disk.

Software AG Tamino Connection

This section explains the actions that are available on a Tamino connection.
Actions Available at Connection Level
For a Tamino database the actions available at connection level in the Data Source Explorer view are the following:
• Refresh - Performs a refresh of the selected node's subtree.
• Disconnect - Closes the current database connection.
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
• Add container - Allows you to create a new collection in the database.
Actions Available at Collection Level
For every new Tamino collection created in the Data Source Explorer view, you can specify if a schema is required,
optional or prohibited. The following actions are available at collection level:
• Refresh - Performs a refresh of the selected node's subtree.
• Filter ... - An XQuery expression can be specified for filtering the nodes displayed in the selected Tamino container.
It is only possible to specify one predicate. In the XQuery syntax a predicate is enclosed in square brackets. The
square brackets, however, must not be specified in the dialog box displayed by this action. Only the predicate must
be specified and it will be applied on the selected document type. For example: name/surname between 'B',
'C'
• Insert XML instance - Allows you to load a new XML document.
• Insert non XML instance - Allows you to load a non XML document.
• Modify Collection Properties - Allows you to change the schema usage for the selected collection to optional. This
action is available on collections with required and prohibited schema usage.
• Define schema - Allows you to add a new schema in the Schema Repository. This action is available on collections
with optional and required schema usage.
• Delete - Removes the selected collection. If it is a Tamino doctype then the action removes all the XML instances
contained in the document type.
• Set default - Sets this collection as the default collection for running queries with the input() function.
Actions Available at Schema Level
For a Tamino database the actions available at schema level in the Data Source Explorer view are the following:
• Refresh - Performs a refresh of the selected schema.
• Open - Opens the selected schema in the editor. There are supported schema changes that preserve the validity
relative to the existent instances.
• Delete - Removes the selected schema from the Schema Repository.
308 | Oxygen XML Author | Working with Databases

Actions Available at Resource Level

For a Tamino database the actions available at resource level in the Data Source Explorer view are the following:
• Refresh - Performs a refresh of the selected resource.
• Open - Opens the selected resource in the editor.
• Rename - Allows you to change the name of the selected resource.
• Delete - Removes the selected resource.
• Copy location - Allows you to copy to clipboard an application specific URL for the resource which can then be
used for various actions like opening or transforming the resources.
• Properties - Allows the user to view various useful properties associated with the resource.
• Save As - Allows you to save the name of the selected binary resource as a file on disk.
Validation of an XML resource stored in a Tamino database is done against the schema associated with the resource in
the database.

Documentum xDb (X-Hive/DB) Connection

This section explains the actions that are available on a Documentum xDb (X-Hive/DB) 10 connection.
Actions Available at Connection Level
For a Documentum xDb (X-Hive/DB) 10 database the actions available at connection level in the Data Source Explorer
view are the following:
• Refresh - Performs a refresh of the selected node's subtree.
• Disconnect - Closes the current database connection.
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
• Add library - Allows you to add a new library.
• Insert XML Instance - Allows you to add a new XML resource directly into the database root. See Documentum
xDb (X-Hive/DB) 10 Parser Configuration for more details.
• Insert non XML Instance - Allows you to add a new non XML resource directly into the database root.
• Properties - Displays the connection properties.
Actions Available at Catalog Level
For a Documentum xDb (X-Hive/DB) 10 database the actions available at catalog level in the Data Source Explorer
view are the following:
• Refresh - Performs a refresh of the selected catalog.
• Add AS models - Allows you to add a new abstract schema model to the selected catalog.
• Set default schema - Allows you to set a default DTD to be used for parsing. It is not possible to set a default XML
Schema.
• Clear default schema - Allows you to clear the default DTD. The action is available only if there is a DTD set as
default.
• Properties - Displays the catalog properties.
Actions Available at Schema Resource Level
For a Documentum xDb (X-Hive/DB) 10 database the actions available at schema resource level in the Data Source
Explorer view are the following:
• Refresh - Performs a refresh of the selected schema resource.
• Open - Opens the selected schema resource in the editor.
• Rename - Allows you to change the name of the selected schema resource.
• Save As - Allows you to save the selected schema resource as a file on disk.
• Delete - Removes the selected schema resource from the catalog
Oxygen XML Author | Working with Databases | 309

• Copy location - Allows you to copy to clipboard the URL of the selected schema resource.
• Set default schema - Allows you to set the selected DTD to be used as default for parsing. The action is available
only for DTD.
• Clear default schema - Allows you to unset the selected DTD. The action is available only if the selected DTD is
the current default to be used for parsing.
Actions Available at Library Level
For a Documentum xDb (X-Hive/DB) 10 database the actions available at library level in the Data Source Explorer
view are the following:
• Refresh - Performs a refresh of the selected library.
• Add library - Adds a new library as child of the selected library.
• Add local catalog - Adds a catalog to the selected library. By default, only the root-library has a catalog, and all
models would be stored there.
• Insert XML Instance - Allows you to add a new XML resource to the selected library. See Documentum xDb
(X-Hive/DB) 10 Parser Configuration for more details.
• Insert non XML Instance - Allows you to add a new non XML resource to the selected library.
• Rename - Allows you to specify a new name for the selected library.
• Move - Allows you to move the selected library to a different one (also available through drag and drop).
• Delete - Removes the selected library.
• Properties - Displays the library properties.
Actions Available at Resource Level
When an XML instance document is added For a Documentum xDb (X-Hive/DB) 10 database the actions available at
resource level in the Data Source Explorer view are the following:
• Refresh - Performs a refresh of the selected resource.
• Open - Opens the selected resource in the editor.
• Rename - Allows you to change the name of the selected resource.
• Move - Allows you to move the selected resource in a different library in the database tree (also available through
drag and drop).
• Save As - Allows you to save the selected binary resource as a file on disk.
• Delete - Removes the selected resource from the library.
• Copy location - Allows you to copy to clipboard the URL of the selected resource.
• Add AS model - Allows you to add an XML schema to the selected XML resource.
• Set AS model - Allows you to set an active AS model for the selected XML resource.
• Clear AS model - Allows you to clear the active AS model of the selected XML resource.
• Properties - Displays the resource properties. Available only for XML resources.
Validation of an XML resource stored in an Documentum xDb (X-Hive/DB) 10 database is done against the schema
associated with the resource in the database.
Documentum xDb (X-Hive/DB) 10 Parser Configuration for Adding XML Instances
When an XML instance document is added to a Documentum xDb (X-Hive/DB) 10 connection or library it is parsed
with an internal XML parser of the database server. The following options are available for configuring this parser:
• DOM Level 3 parser configuration parameters. More about each parameter can be found here: DOM Level 3
Configuration.
• Documentum xDb (X-Hive/DB) 10 specific parser parameters (for more information please consult the Documentum
xDb (X-Hive/DB) 10 manual):
• xhive-store-schema - If checked, the corresponding DTD's or XML schemas are stored in the catalog during
validated parsing.
310 | Oxygen XML Author | Working with Databases

• xhive-store-schema-only-internal-subset - Stores only the internal subset of the document (not any external
subset). This options modifies the xhive-store-schema one (only has a function when that parameter is set to
true, and when DTD's are involved). Select this option this option if you only want to store the internal subset
of the document (not the external subset).
• xhive-ignore-catalog - Ignores the corresponding DTD's and XML schemas in the catalog during validated
parsing.
• xhive-psvi - Stores psvi information on elements and attributes. Documents parsed with this feature turned on,
give access to psvi information and enable support of data types by XQuery queries.
• xhive-sync-features - Convenience setting. With this setting turned on, parameter settings of XhiveDocumentIf
are synchronized with the parameter settings of LSParser. Note that parameter settings xhive-psvi and
schema-location are always synchronized.

WebDAV Connection
This section explains how to work with a WebDAV connection in the Data Source Explorer view.

How to Configure a WebDAV Connection

Oxygen's default configuration already contains a WebDAV data source called WebDAV. Based on this data source
you can create a WebDAV connection for browsing and editing data from a database that provides a WebDAV interface.
The connection will be available in the Data Source Explorer view. The steps for configuring a WebDAV connection
are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
3. Enter a unique name for the connection.
4. Select one of the WebDAV data sources in the Data Source combo box.
5. Fill-in the connection details:
a) Set the URL to the WebDAV repository in the field WebDAV URL.
b) Set the user name to access the WebDAV repository in the field User.
c) Set the password to access the WebDAV repository in the field Password.
6. Click the OK button.

WebDAV Connection Actions

This section explains the actions that are available on a WebDAV connection in the Data Source Explorer view.

Actions Available at Connection Level

The contextual menu of a WebDAV connection in the Data Source Explorer view contains the following actions:
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
• Add Resource ... - Allows you to add a new file on the server.
• Add Container ... - Allows you to create a new folder on the server.
• Refresh - Performs a refresh of the connection.
Oxygen XML Author | Working with Databases | 311

Actions Available at Folder Level

The contextual menu of a folder node in a WebDAV connection in the Data Source Explorer view contains the following
actions:
• Add Container - Allows you to create a new folder on the server.
• Add Resource - Allows you to add a new file on the server in the current folder.
• Rename - Allows you to change the name of the selected folder.
• Move - Allows you to move the selected folder in a different location in the tree (also available through drag and
drop).
• Delete - Removes the selected folder.
• Refresh - Performs a refresh of the selected node's subtree.

Actions Available at File Level

The contextual menu of a file node in a WebDAV connection in the Data Source Explorer view contains the following
actions:
• Open - Allows you to open the selected file in the editor.
• Unlock - Removes the lock from the current file in the database.
• Rename - Allows you to change the name of the selected file.
• Move - Allows you to move the selected file in a different location in the tree (also available through drag and drop).
• Delete - Removes the selected file.
• Copy Location - Allows you to copy to clipboard an application specific URL for the resource which can then be
used for various actions like opening or transforming the resources.
• Refresh - Performs a refresh of the selected node.
• Properties - Displays the properties of the current file in a dialog.
Chapter
14
Content Management System (CMS) Integration
Topics: This chapter explains how Oxygen can be integrated with a content management
system (CMS) so that the data stored in the CMS can be edited directly in the
• Integration with Documentum Oxygen editor. Only the integration with the Documentum (CMS) is explained
(CMS) .
314 | Oxygen XML Author | Content Management System (CMS) Integration

Integration with Documentum (CMS)

Oxygen provides support for browsing and managing Documentum repositories in the Data Source Explorer. You can
easily create new resources on the repository, copy and move them using contextual actions or the drag and drop support,
edit and transform the documents in the editor. The operations that can be performed on repository resources are described
in the Documentum (CMS) actions section.
Oxygen supports Documentum (CMS) version 6.5 or later with Documentum Foundation Services 6.5 or later installed.
Attention:
It is recommended to use the latest 1.5.x or 1.6.x Java version. It is possible that the Documentum (CMS) support
will not work properly if you use other Java versions.

Configure Connection to Documentum Server

This section explains how to configure a connection to a Documentum server.

How to Configure a Documentum (CMS) Data Source

To configure a Documentum (CMS) data source you need the Documentum Foundation Services Software Development
Kit (DFS SDK) corresponding to your server version. The DFS SDK can be found in the Documentum (CMS) server
installation kit or it can be downloaded from EMC Community Network.
Note: The DFS SDK can be found in the form of an archive named, for example, emc-dfs-sdk-6.5.zip for
Documentum (CMS) 6.5.

1. Go to menu Preferences > Data Sources .

The Preferences dialog is opened at the Data Sources panel.
2. In the Data Sources panel click the New button.
3. Enter a unique name for the data source.
4. Select Documentum (CMS) from the driver type combo box.
5. Press the Choose DFS SDK Folder button.
6. Select the folder where you have unpacked the DFS SDK archive file.
If you have indicated the correct folder the following Java libraries (jar files) will be added to the list (some variation
of the library names is possible in future versions of the DFS SDK):
• lib/java/emc-bpm-services-remote.jar
• lib/java/emc-ci-services-remote.jar
• lib/java/emc-collaboration-services-remote.jar
• lib/java/emc-dfs-rt-remote.jar
• lib/java/emc-dfs-services-remote.jar
• lib/java/emc-dfs-tools.jar
• lib/java/emc-search-services-remote.jar
• lib/java/ucf/client/ucf-installer.jar
• lib/java/commons/*.jar (multiple jar files)
• lib/java/jaxws/*.jar (multiple jar files)
• lib/java/utils/*.jar (multiple jar files)
Note: If for some reason the jar files are not found, you can add them manually by using the Add Files and
Add Recursively buttons and navigating to the lib/java folder from the DFS SDK.

7. Click the OK button to finish the data source configuration.

Oxygen XML Author | Content Management System (CMS) Integration | 315

How to Configure a Documentum (CMS) Connection

The steps for configuring a connection to a Documentum (CMS) server are the following:

1. Go to menu Preferences > Data Sources .

2. In the Connections panel click the New button.
3. Enter a unique name for the connection.
4. Select one of the previously configured Documentum (CMS) data sources in the Data Source combo box.
5. Fill-in the connection details:
• URL - The URL to the Documentum (CMS) server: http://<hostname>:<port>
• User - The user name to access the Documentum (CMS) repository.
• Password - The password to access the Documentum (CMS) repository.
• Repository - The name of the repository to log into.

6. Click the OK button to finish the configuration of the connection.

Known Issues
The following are known issues with the Documentum (CMS):
1. Please note that at the time of this implementation there is a problem in the UCF Client implementation for MAC
OS X which prevents you from viewing or editing XML documents from the repository. The UCF Client is the
component responsible for file transfer between the repository and the local machine. This component is deployed
automatically from the server.
2. In order for the Documentum driver to work faster, you need to specify to the JVM to use a weaker random generator,
instead of the very slow native implementation. This can be done by modifying in the Oxygen startup scripts (or in
the *.vmoptions file) the system property:
-Djava.security.egd=file:/dev/./urandom

Documentum (CMS) Actions in the Data Source Explorer View

Oxygen allows you to browse the structure of a Documentum repository in the Data Source Explorer view and perform
various operations on the repository resources.
You can drag and drop folders and resources to other folders to perform move or copy operations with ease. If the drag
and drop is between resources (drag the child item to the parent item) you can create a relationship between the respective
resources.
316 | Oxygen XML Author | Content Management System (CMS) Integration

Figure 154: Browsing a Documentum repository

Actions Available on Connection

The actions available on a Documentum (CMS) connection in the Data Source Explorer view are the following:
• Configure Database Sources - Opens the Data Sources preferences page where you can configure both data
sources and connections.
• New Cabinet - Creates a new cabinet in the repository. The cabinet properties are:
• Type - The type of the new cabinet (default is dm_cabinet).
• Name - The name of the new cabinet.
• Title - The title property of the cabinet.
• Subject - The subject property of the cabinet.

• Refresh - Refreshes the connection.

Actions Available on Cabinets / Folders

The actions available on a Documentum (CMS) cabinet in the Data Source Explorer view are the following:
• New Folder - Creates a new folder in the current cabinet / folder. The folder properties are the following:
• Path - Shows the path where the new folder will be created.
• Type - The type of the new folder (default is dm_folder).
• Name - The name of the new folder.
• Title - The title property of the folder.
• Subject - The subject property of the folder.

• New Document - Creates a new document in the current cabinet / folder. The document properties are the
following:
• Path - Shows the path where the new document will be created.
Oxygen XML Author | Content Management System (CMS) Integration | 317

• Name - The name of the new document.

• Type - The type of the new document (default is dm_document).
• Format - The document content type format.

• Import - Imports local files / folders in the selected cabinet / folder of the repository. Actions available in the import
dialog:
• Add Files - Shows a file browse dialog and allows you to select files to add to the list.
• Add Folders - Shows a folder browse dialog that allows you to select folders to add to the list. The subfolders
will be added recursively.
• Edit - Shows a dialog where you can change the properties of the selected file / folder from the list.
• Remove - Removes the selected files / folders from the list.

• Rename - Changes the name of the selected cabinet / folder.

• Copy - Copies the selected folder to a different location in the tree (available only upon folders). This action can
also be performed with drag and drop while holding the (Ctrl) key pressed.
• Move - Moves the selected folder to a different location in the tree (available only upon folders). This action can
also be performed with drag and drop.
• Delete - Deletes the selected cabinet / folder from the repository. The following options are available:
• Folder(s) - Allows you to delete only the selected folder or to delete recursively the folder and all subfolders and
objects.
• Version(s) - Allows you to specify what versions of the resources will be deleted.
• Virtual document(s) - Here you can specify what happens when virtual documents are encountered. They can
be either deleted either by themselves or together with their descendants.

• Refresh - Performs a refresh of the selected node's subtree.

• Properties - Displays the list of properties of the selected cabinet / folder.

Actions Available on Resources

The actions available on a Documentum (CMS) resource in the Data Source Explorer view are the following:
• Edit - Checks out (if not already checked out) and opens the selected object in the editor.
• Edit with - Checks out (if not already checked out) and opens the selected object in the specified editor / tool.
• Open (Read-only) - Opens the selected object in the editor for viewing.
• Open with - Opens the selected object in the specified editor / tool for viewing.
• Check Out - Checks out the selected object from the repository. The action is not available if the object is already
checked out.
• Check In - Checks in the selected object (commits changes) into the repository. The action is only available if the
object is checked out.
318 | Oxygen XML Author | Content Management System (CMS) Integration

Figure 155: Check In Dialog

The properties of a resource are the following:

• Name - The name the file will have on the repository.
• Version - Allows you to choose what version the object will have after being checked in.
• Version label - The label of the updated version.
• Description - An optional description of the file.
• Keep Locks - If checked the updated file is checked into the repository but it is also kept checked out in your
name.
• Make this the current version - Makes the updated file the current version (will have the CURRENT version
label).

• Cancel Checkout - Cancels the check out and loses all modifications since the check out. Action is only available
if the object is checked out.
• Export - Allows you to export the object and save it locally.
• Rename - Changes the name of the selected object.
• Copy - Copies the selected object to a different location in the tree. Action is not available on virtual document
descendants. This action can also be performed with drag and drop while holding the (Ctrl) key pressed.
• Move - Moves the selected object to a different location in the tree. Action is not available on virtual document
descendants and on checked out objects. This action can also be performed with drag and drop.
• Delete - Deletes the selected object from the repository. Action is not available on virtual document descendants
and on checked out objects.
• Add Relationship - Adds a new relationship for the selected object. This action can also be performed with drag
and drop between objects.
• Convert to Virtual Document - Allows you to convert a simple document to a virtual document. Action is available
only if the object is a simple document.
• Convert to Simple Document - Allows you to convert a virtual document to a simple document. Action is available
only if the object is a virtual document with no descendants.
• Copy location - Allows you to copy to clipboard an application specific URL for the object which can then be used
for various actions like opening or transforming the resources.
• Refresh - Performs a refresh of the selected object.
• Properties - Displays the list of properties of the selected object.
Oxygen XML Author | Content Management System (CMS) Integration | 319

Transformations on DITA Content from Documentum (CMS)

Oxygen comes with the DITA Open Toolkit which is able to transform a DITA map to various output formats. However
DITA Open Toolkit requires local DITA files so first you need to check out a local version of your DITA content. Once
you have a local version of a DITA map just load it in the DITA Maps Manager view and run one of the DITA
transformations that are predefined in Oxygen or a customization of such a predefined DITA transformation.
Chapter
15
Digital Signatures
Topics: This chapter explains how to apply and verify digital signatures on XML
documents.
• Overview
• Canonicalizing Files
• Certificates
• Signing Files
• Verifying the Signature
322 | Oxygen XML Author | Digital Signatures

Overview
Digital signatures are widely used as security tokens, not just in XML. A digital signature provides a mechanism for
assuring integrity of data, the authentication of its signer, and the non-repudiation of the entire signature to an external
party:
• A digital signature must provide a way to verify that the data has not been modified or replaced to ensure integrity.
• The signature must provide a way to establish the identity of the data's signer for authentication.
• The signature must provide the ability for the data's integrity and authentication to be provable to a third party for
non-repudiation.
A public key system is used to create the digital signature and it's also used for verification. The signature binds the
signer to the document because digitally signing a document requires the originator to create a hash of the message and
then encrypt that hash value with his own private key. Only the originator has that private key and he is the only one
that can encrypt the hash so that it can be unencrypted using his public key. The recipient, upon receiving both the
message and the encrypted hash value, can decrypt the hash value, knowing the originator's public key. The recipient
must also try to generate the hash value of the message and compare the newly generated hash value with the unencrypted
hash value received from the originator. If the hash values are identical, it proves that the originator created the message,
because only the actual originator could encrypt the hash value correctly.
XML Signatures can be applied to any digital content (data object), including XML (see W3C Recommendation,
XML-Signature Syntax and Processing ). An XML Signature may be applied to the content of one or more resources:
• enveloped or enveloping signatures are applied over data within the same XML document as the signature
• detached signatures are applied over data external to the signature element; the signature is "detached" from the
content it signs. This definition typically applies to separate data objects, but it also includes the instance where the
signature and data object reside within the same XML document but are sibling elements.
The XML Signature is a method of associating a key with referenced data. It does not normatively specify how keys
are associated with persons or institutions, nor the meaning of the data being referenced and signed.
The original data is not actually signed. Instead, the signature is applied to the output of a chain of canonicalization and
transformation algorithms, which are applied to the data in a designated sequence. This system provides the flexibility
to accommodate whatever "normalization" or desired preprocessing of the data that might be required or desired before
subjecting it to being signed.
To canonicalize something means to put it in a standard format that everyone generally uses. Because the signature is
dependent on the content it is signing, a signature produced from a not canonicalized document could possibly be different
from one produced from a canonicalized document. The canonical form of an XML document is physical representation
of the document produced by the method described in this specification. The term canonical XML refers to XML that
is in canonical form. The XML canonicalization method is the algorithm defined by this specification that generates the
canonical form of a given XML document or document subset. The term XML canonicalization refers to the process of
applying the XML canonicalization method to an XML document or document subset. XML canonicalization is designed
to be useful to applications that require the ability to test whether the information content of a document or document
subset has been changed. This is done by comparing the canonical form of the original document before application
processing with the canonical form of the document result of the application processing.
A digital signature over the canonical form of an XML document or document subset would allows the signature digest
calculations to be oblivious to changes in the original document's physical representation. During signature generation,
the digest is computed over the canonical form of the document. The document is then transferred to the relying party,
which validates the signature by reading the document and computing a digest of the canonical form of the received
document. The equivalence of the digests computed by the signing and relying parties (and hence the equivalence of
the canonical forms over which they were computed) ensures that the information content of the document has not been
altered since it was signed.
Oxygen XML Author | Digital Signatures | 323

The following canonicalization algorithms are used in Oxygen: Canonical XML (or Inclusive XML
Canonicalization)(XMLC14N) and Exclusive XML Canonicalization(EXCC14N). The first is used for XML where the
context doesn't change while the second was designed for canonicalization where the context might change.
Inclusive Canonicalization copies all the declarations, even if they are defined outside of the scope of the signature. In
this way all the declarations you might use will be unambiguously specified. A problem appears when the signed XML
is moved into another XML document which has other declarations because the Inclusive Canonicalization will copy
then and the signature will be invalid.
Exclusive Canonicalization finds out what namespaces you are actually using (the ones that are a part of the XML
syntax) and just copies those. It does not look into attribute values or element content, so the namespace declarations
required to process these are not copied.
This type of canonicalization is useful when you have a signed XML document that you wish to insert into other XML
documents and it will insure the signature verifies correctly every time, so it is required when you need self-signed
structures that support placement within different XML contexts.
Inclusive Canonicalization is useful when it is less likely that the signed data will be inserted in other XML document
and it's the safer method from the security perspective because it requires no knowledge of the data that are to be secured
in order to safely sign them.
The canonicalization method can specify whether or not comments should be included in the canonical form output by
the XML canonicalization method. If a canonical form contains comments corresponding to the comment nodes in the
input node-set, the result is called canonical XML with comments. In an uncommented canonical form comments are
removed, including delimiter for comments outside document element.
These three operations: Digital Signing, Canonicalization and Verification of the signature are available from the Tools
menu or from the Editor's contextual menu > Source .

Canonicalizing Files
The user can select the canonicalization algorithm to be used for his document from the following dialog displayed by
the action Canonicalize available from the editor panel's contextual menu > Source .

Figure 156: Canonicalization settings dialog

The fields of the dialog are the following:

324 | Oxygen XML Author | Digital Signatures

• URL - Specifies the location of the input URL.

• Exclusive - If selected, the exclusive (uncommented) canonicalization method is used.
• Exclusive with comments - If selected, the exclusive with comments canonicalization method is used.
• Inclusive - If selected, the inclusive (uncommented) canonicalization method is used.
• Inclusive with comments - If selected, the inclusive with comments canonicalization method is used.
• XPath - The XPath expression provides the fragments of the XML document to be signed.
• Output - Specifies the output file path where the signed XML document will be saved.
• Open in editor - If checked, the output file will be opened in the editor.

Certificates
A certificate is a digitally signed statement from the issuer (an individual, an organization, a website or a firm), saying
that the public key (and some other information) of some other entity has a particular value. When data is digitally
signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not
been modified. Authenticity means the data comes indeed from the entity that claims to have created and signed it.
Certificates are kept in special repositories called keystores.
A keystore is an encrypted file that contains private keys and certificates. All keystore entries (key and trusted certificate
entries) are accessed via unique aliases. An alias must be assigned for every new entry of either a key or certificate as
a reference for that entity. No keystore can store an entity if it's alias already exists in that keystore and no keystore can
store trusted certificates generated with keys in it's keystore.
In Oxygen there are provided two types of keystores: Java Key Store (JKS) and Public-Key Cryptography Standards
version 12 (PKCS-12). A keystore file is protected by a password. In a PKCS 12 keystore you should not store a certificate
without alias together with other certificates, with or without alias, as in such a case the certificate without alias cannot
be extracted from the keystore.
To set the options for a certificate or to validate it, go to menu Options > Preferences > Certificates .

Signing Files
The user can select the type of signature to be used for his document from the following dialog displayed by the action
Sign available from the editor panel's contextual menu > Source
Oxygen XML Author | Digital Signatures | 325

Figure 157: Signature settings dialog

The following options are available:

• Input - Specifies the location of the input URL.
• None - If selected, no canonicalization algorithm is used.
• Exclusive - If selected, the exclusive (uncommented) canonicalization method is used.
• Exclusive with comments - If selected, the exclusive with comments canonicalization method is used.
• Inclusive - If selected, the inclusive (uncommented) canonicalization method is used.
• Inclusive with comments - If selected, the inclusive with comments canonicalization method is used.
• XPath - The XPath expression provides the fragments of the XML document to be signed.
• ID - Provides ID of the XML element to be signed.
• Envelope - If selected, the enveloping signature is used.
• Detached - If selected, the detached signature is used.
• Append KeyInfo - The element ds:KeyInfo will be added in the signed document only if this option is checked.
• Signature algorithm - Algorithm used for signing the document. The following options are available: RSA with
SHA1, RSA with SHA256, RSA with SHA384, and RSA with SHA512.
• Output - Specifies the output file path where the signed XML document will be saved.
• Open in editor - If checked, the output file will be opened in the editor.

Verifying the Signature

The user can select a file to verify its signature in the dialog opened by the action Verify Signature available from the
editor panel's contextual menu > Source . The dialog has a field URL that specifies the location of the document for
which to verify the signature.
326 | Oxygen XML Author | Digital Signatures

If the signature is valid, a dialog displaying the name of the signer will be opened. If not, an error message will show
details about the problem.
Chapter
16
Text Editor Specific Actions
Topics: The Text mode of the editor panel provides the usual actions specific for a plain
text editor: undo / redo, copy / paste, find / replace, etc. These actions are
• Finding and Replacing Text in the executed from the menu bar or toolbar and also by invoking their usual keyboard
Current File shortcuts.
• Spell Checking
328 | Oxygen XML Author | Text Editor Specific Actions

Finding and Replacing Text in the Current File

This section explains how to use the find and replace features of the application.

The Find All Elements / Attributes Dialog

This dialog is opened from menu Edit > Find All Elements... . It assists you in defining XML elements / attributes
search operations on the current document.

Figure 158: Find All Elements / Attributes dialog

The dialog can perform the following actions:

• Find all the elements with a specified name.
• Find all the elements which contain or not a specified string in their text content.
• Find all the elements which have a specified attribute.
• Find all the elements which have an attribute with or without a specified value.
All these search criteria can be combined to fine filter your results.
The results of all the operations in the Find All Elements / Attributes dialog will be presented as a list in the message
panel.
The dialog fields are described as follows:
• Element name - The target element name to search for. Only the elements with this exact name are returned. For
any element name just leave the field empty.
• Element text - The target element text to search for. The combo box beside this field allows you to specify that you
are looking for an exact or partial match of the element text. For any element text, select contains in the combo box
and leave the field empty.
If you leave the field empty but select equals in the combo box, only elements with no text will be found. Select not
contains to find all elements which do not have the specified text inside.
• Attribute name - The name of the attribute which needs to be present in the elements. Only the elements which
have an attribute with this name will be returned. For any / no attribute name just leave the field empty.
• Attribute value - The combo box beside this field allows you to specify that you are looking for an exact or partial
match of the attribute value. For any / no attribute value select contains in the combo box and leave the field empty.
If you leave the field empty but select equals in the combo box, only elements that have at least an attribute with an
empty value will be found.
Select not contains to find all elements which have attributes without a specified value.
• Case sensitive - When this option is checked, operations are case sensitive.
Oxygen XML Author | Text Editor Specific Actions | 329

Spell Checking
The Spelling dialog enables you to check the spelling of the current document. It is opened from menu XML > Check
Spelling (Ctrl+Shift+Q) or the toolbar button Check Spelling.

Figure 159: The Check Spelling Dialog

The dialog contains the following fields:

• Unrecognized word - Contains the word that cannot be found in the selected dictionary. The word is also highlighted
in the XML document.
• Replace with - The character string which is suggested to replace the unrecognized word.
• Guess - Displays a list of words suggested to replace the unknown word. Double click a word to automatically insert
it in the document and resume the spell checking process.
• Default language - Allows you to select the default dictionary used by the spelling engine.
• Paragraph language - In an XML document you can mix content written in different languages. To tell the spell
checker engine what language was used to write a specific section, you need to set the language code in the lang
or xml:lang attribute to that section. Oxygen automatically detects such sections and instructs the spell checker
engine to apply the appropriate dictionary.
• Replace - Replaces the currently highlighted word in the XML document, with the selected word in the Replace
with field.
• Replace All - Replaces all occurrences of the currently highlighted word in the XML document, with the selected
word in the Replace with field.
• Ignore - Ignores the first occurrence of the unrecognized word and allows you to continue checking the document.
Oxygen skips the content of the XML elements marked as ignorable.
• Ignore All - Ignores all instances of the unknown word in the current document.
• Learn - Includes the unrecognized word in the list of valid words.
• Options - Sets the configuration options of the spell checker.
330 | Oxygen XML Author | Text Editor Specific Actions

• Begin at caret position - Instructs the spell checker to begin checking the document starting from the current cursor
position.
• Close - Closes the dialog.

Spell Checking Dictionaries

There are two spell checking engines available in Oxygen: Hunspell checker (default setting) and Java checker. You
can set the spell check engine in the Spell checking engine preferences page. The dictionaries used by the two engines
differ in format, so you need to follow specific procedures in order to add another dictionary to your installation of
Oxygen.

Dictionaries for the Hunspell Checker

The Hunspell spell checker is open source and has LGPL license. The format of the Hunspell spell dictionary is supported
by Mozilla, OpenOffice and the Chrome browser. Oxygen comes with the following built-in dictionaries for the Hunspell
checker:
• English (US)
• English (UK)
• French
• German (old orthography)
• German (new orthography)
• Spanish
There is one dictionary for each language-country variant combination. If you cannot find a Hunspell dictionary that is
already built for your language you can build such a dictionary. First you need a list of correct words which you want
to check in your documents. You build a dictionary from this list following these instructions.
Adding a Dictionary for the Hunspell Checker
To add a new spelling dictionary to Oxygen or to replace an existing one you should follow these steps:

1. Download the archive with the files of your language dictionary.

A dictionary has two files with the same name and different extensions: a file with .dic extension and a file with
.aff extension.
2. Copy the .aff and .dic files to the spell subfolder (.spell subfolder on Linux and Mac OS X) of the Oxygen
preferences folder only if it is a new dictionary (it is not available as built-in dictionary in Oxygen).
The Oxygen preferences folder is , where [APPLICATION-DATA-FOLDER] is:
• C:\Documents and Settings\[LOGIN-USER-NAME]\Application Data on Windows XP
• C:\Users\[LOGIN-USER-NAME]\AppData\Roaming on Windows Vista
• [USER-HOME-FOLDER]/Library/Preferences on Mac OS X
• [USER-HOME-FOLDER] on Linux

3. Copy the .aff and .dic files into the folder [Oxygen-install-folder]/dicts only if it is an existing
dictionary.
4. Restart the application after copying the dictionary files.

Dictionaries for the Java Checker

A Java checker dictionary has the form of a .dar file located in the directory [Oxygen-install-folder]/dicts.
Oxygen comes with the following built-in dictionaries for the Java checker:
• English (US)
• English (UK)
• English (Canada)
Oxygen XML Author | Text Editor Specific Actions | 331

• French (France)
• French (Belgium)
• French (Canada)
• French (Switzerland)
• German (old orthography)
• German (new orthography)
• Spanish
A pre-built dictionary can be added by copying the corresponding .dar file to the folder
[Oxygen-install-folder]/dicts and restarting Oxygen. There is one dictionary for each language-country
variant combination. If you cannot find a dictionary that is already built for your language you can build such a dictionary
with the tool available at http://www.xmlmind.com/spellchecker/dictbuilder.shtml.

Learned Words
Spell checker engines rely on dictionary to decide that a word is correctly spelled. To tell the spell checker engine that
an unknown word is actually correctly spelled, you need to add that word to its dictionary. There are two ways to do so:
• press the Learn button from the Spelling dialog;
• invoke the contextual menu on an unknown word, then press Learn word.
Learned words are stored into a persistent dictionary file. Its name is composed of the currently checked language code
and the .tdi extension, for example en_US.tdi. It is located in the folder:
• folder on Windows XP
• folder on Windows Vista
• folder on Mac OS X
• folder on Linux
To delete items from the list of learned words, press Delete learned words from Spell Check preferences page.

Ignored Words
The content of some XML elements like programlisting, codeblock or screen should always be skipped by
the spell checking process. The skipping can be done manually word by word by the user using the Ignore button of
the Spelling dialog or, more conveniently, automatically by maintaining a set of known element names that should never
be checked. You maintain this set of element names in the user preferences as a list of XPath expressions that match
the elements.
Only a small subset of XPath expressions is supported, that is only the '/' and '//' separators and the '*' wildcard. Two
examples of supported expressions are /a/*/b and //c/d/*.

Automatic Spell Check

To allow Oxygen to automatically check the spelling as you write, you need to enable the Automatic spell check option
from the Spell Check preferences page. Unknown words are highlighted and feature a contextual menu which offers the
following:
• Delete Repeated Word action - allows you to delete repeated words;
• a list of words suggested by the spell checking engine as possible replacements of the unknown word;
• Learn Word action - allows you to add the current unknown word to the persistent dictionary.

Spell Checking in Multiple Files

The Check Spelling in Files action available from the Project contextual menu enables you to check spelling on multiple
documents.
332 | Oxygen XML Author | Text Editor Specific Actions

Figure 160: Check Spelling in Files Dialog

The following scopes are available:

• All opened files - Spell check in all opened files.
• Directory of the current file - All the files from the folder of the current edited file.
• Scope of the current DITA Map - All the files referred in the current DITA map opened in the DITA Maps
Manager view.
• Project files - All files from the current project.
• Selected project files - The selected files from the current project.
• Specified path - A custom path.
You can also choose a file filter, decide whether to recurse subdirectories or process hidden files.
The spell checker processor uses the options available in the Spell Check preferences panel .
Chapter
17
Configuring the Application
Topics: This chapter presents all the user preferences that allow you to configure the
application and the editor variables that are available for customizing the user
• Importing / Exporting Global defined commands.
Options
• Preferences
• Automatically Importing the
Preferences from the Other
Distribution
• Reset Global Options
• Scenarios Management
• Editor Variables
334 | Oxygen XML Author | Configuring the Application

Importing / Exporting Global Options

In the Oxygen preferences page opened from menu Window > Preferences > oXygen you can find the import / export
preferences buttons which allow you to move your global preferences in XML format from one computer to another.

Preferences
Once the application is installed you can use the Preferences dialog accessed from menu Options > Preferences to
customize the application settings for your requirements and network environment.
You can always revert modifications to their default values by pressing the Restore Defaults button, available in each
preference page.
If you don't know how to use a specific preference that is available in any Preferences panel or what effect it will have
you can open a help page about the current panel at any time pressing the help button located in the left bottom
corner of the dialog or pressing the F1 key.
A restricted version of the Preferences dialog is available at any time in the editors of the Oxygen plugin by right-clicking
in the editor panel and selecting Preferences:

Figure 161: Eclipse Preferences dialog - restricted version

Oxygen XML Author | Configuring the Application | 335

Oxygen License
The license information panel is opened from menu Window > Preferences > Author . This panel presents the data
of the license key which enables the Oxygen XML Author plugin: registration name, category and number of purchased
licenses, encrypted signature of the license key. Clicking on the Register button opens the Oxygen XML Author License
dialog that allows you to insert a new license key

Global
The Global preferences panel is opened from menu Window > Preferences > Author > Global .

Figure 162: The Global preferences panel

The following user preferences are av available in this panel:

• Use custom frameworks directory - For editing different types of XML documents (for content completion,
validation, authoring) Oxygen can use information from the document types which are stored in the frameworks
subfolder of the Oxygen install folder. If a custom frameworks folder is specified then Oxygen will load the
document types from this location.
• Show hidden files and directories - Shows system hidden files and folders in the file browser dialog and the folder
browser dialog. This setting is not available on Mac OS X.

Fonts
The Fonts preferences panel is opened from menu Window > Preferences > Author > Fonts .
336 | Oxygen XML Author | Configuring the Application

Figure 163: The Fonts preferences panel

The fonts that can be configured in are the following:

• Text - The font family and font size used in text-based editors. There are two options:
• Map to text font - Uses the same font as the one set in General / Appearance / Colors and Fonts for the basic
text editor.
• Customize - Allows you to choose a specific font.

• Author - Allows you to specify a font to be used in Author mode.

Document Type Association

The Document Type Association preferences panel is opened from menu Window > Preferences > Author > Document
Type Association .
Oxygen XML Author | Configuring the Application | 337

Figure 164: Document Type Association preferences panel

The following actions are available in this preferences panel:

• Change framework directory location - Specifies a custom frameworks folder from where Oxygen loads the
document types.
• User roles - Selects between two user roles: Content author and Developer. When the selected role is Content
author, you can modify only the properties of the Document Type Associations stored in the user preferences. The
externally stored associations (that means all the built-in document types) cannot be modified and you must duplicate
them to further customize these associations. The Developer user can change any document type association.
• Document types table - Presents the currently defined document type associations. The columns are:
• Document type - Contains the name of the document type.
• Enabled - When checked, the corresponding document type association is enabled. The association is analyzed
when trying to determine the type of a document opened in Oxygen.
• Storage - Displays the type of location where the framework configuration file is stored.
Note: Please note that if the document type association settings are already stored in a framework file, the
file will be removed and its content will be saved in Oxygen internal options.

When expanding a Document Type Association its defined rules are presented. A rule is described by:
• Namespace - Specifies the namespace of the root element from the association rules set (any by default). If you
want to apply the rule only when the root element is in no namespace, leave this field empty (remove the
ANY_VALUE string).
• Root local name - Specifies the local name of the root element (any by default).
• File name - Specifies the name of the file (any by default).
• Public ID - Represents the Public ID of the matched document.
• Java class - Presents the name of the class which is used to determine if a document matches the rule.

• New - Opens a dialog that allows you to add a new association. New association is added to top of document type
list.
338 | Oxygen XML Author | Configuring the Application

• Edit - Opens a new dialog allowing you to edit an existing association.

• Delete - Deletes one of the existing association.
• Up - Moves the selected association one level up (the order is important because the first document type association
in the list that matches the document will be used).
• Down - Moves the selected association one level down.
• Enable DTD/XML Schema processing in document type detection - When this option is enabled, the matching
process also examines the DTD/XML Schema associated with the document. For example, the fixed attributes
declared in the DTD for the root element are analyzed also, if this is specified in the association rules.
If you are writing DITA customizations, it is recommended to keep this checkbox enabled. DITA topics and maps
are also matched by looking for the DITAArchVersion attribute in the root element. If the DTD is not processed
on detection, then this attribute specified as default in the DTD will not be detected on the root element and the
DITA customization will not be correctly matched.
This option is enabled by default.
• Only for local DTD's / XML Schemas - When the previous feature is enabled, you can choose with this option to
process only the local DTD's / XML Schemas.
This option is enabled by default.

Editor
The Editor preferences panel is opened from menu Window > Preferences > Author > Editor .
Use these options to configure the visual aspect of the text editor. The same options panel is available in the restricted
version of the Preferences dialog.

Figure 165: The Editor Preferences Panel

The following options are available in this panel:

• Editor background color - Background color of the editor and also of the Diff Files editors.
• Completion proposal background - Background color for the content completion window.
• Completion proposal foreground - Foreground color for the content completion window.
• Documentation window background - Background color for the window containing documentation for the content
completion elements.
• Documentation window foreground - Foreground color for the window containing documentation for the content
completion elements.
• Line Wrap - Enables soft wrap of long lines, that is automatically wrap lines in edited documents without inserting
newline characters in the file.
Oxygen XML Author | Configuring the Application | 339

• Highlight matching tag - Enables highlight for the tag matching the one on which the caret is situated.
• Enable folding when opening a new editor - Enables folding when a new editor is opened.
• Minimum fold range (only for XML) - If Enable folding when opening a new editor is checked, you can specify
the minimum number of lines for folding. If you modify this value, you will notice the changes when you open /
reopen the editor.

Pages
The Pages preferences panel is opened from menu Window > Preferences > oXygen > Editor > Pages and allows
you to select the initial page for an editor. The mode in which a file was edited in the previous session is saved and will
be used when the application is restarted and the file reopened.
If the checkbox Allow Document Type specific page setting to override the general page setting is checked the
initial page setting from the Document Type dialog will override the initial page setting from the table that is explained
below.
The initial page of each editor type has one of the following values:
• Text
• Author
• Grid
• Design (available only for the W3C XML Schema editor)
The Oxygen Pages Preferences Panel

Grid
The Grid preferences panel is opened from menu Window > Preferences > Author > Editor > Pages > Grid .
340 | Oxygen XML Author | Configuring the Application

Figure 166: The Grid Editor Preferences Panel

The following preferences are available for Grid mode of the XML editor:
• Compact representation - If checked a child element is displayed at the same height level with the parent element.
If unchecked a child elements is presented nested with one level in the parent container, that is lower than the parent
with one row.
• Format and indent when passing from grid to text or on save - The content of the document is formatted by
applying the Format and Indent action on every switch from the grid editor to the text editor of the same document.
• Default column width (characters) - The default width in characters of a table column of the grid. A column can
hold an element name and its text content, an attribute name and its value. If the total width of the grid structure is
too large you can resize any column with the mouse but the change is not persistent. To make it persistent set the
new column width in this user option.
• Current selection color - Background color used in the focused selected cell of the grid to make it different in the
set of selected cells. For example when an entire row is selected only one cell of the row is the focused selected one.
• Selection color - Background color used in the selected cells of the grid except the focused selected cell which uses
a different background color.
• Border color - The color used for the lines that separate the grid cells.
• Background color - The background color of grid cells that are not selected.
• Foreground color - The color of the text used for the element names, text content of elements, attribute names and
attribute values.
• Row header colors - Background color - The background color of row headers that are not selected.
• Row header colors - Current selection color - The background color of the row header that is currently selected
and has the focus.
• Row header colors - Selection color - The background color of the row header that is currently selected and does
not have the focus.
• Column header colors - Background color - The background color of column headers that are not selected.
• Column header colors - Current selection color - The background color of the column header that is currently
selected and has the focus.
• Column header colors - Selection color - The background color of the column header that is currently selected and
does not have the focus.
Oxygen XML Author | Configuring the Application | 341

The column headers are painted with two color gradients, one for the upper 1/3 part of the header and the other for the
lower 2/3 part. The start and end colors of the first gradient are set with the first two color buttons. The start and end
colors of the second gradient are set with the last two color buttons.
Author
The Author preferences panel is opened from menu Window > Preferences > Author > Pages > Editor > Author .
The Oxygen Author Preferences Panel

• Show caret position tooltip - If checked, the position information tooltip is displayed. More information about the
position information tooltip can be found in the section Position information tooltip. The documentation tooltip can
be disabled from the Content Completion Annotations preferences panel.
• Show placeholders for empty elements - When checked, placeholders are displayed for empty elements to make
them clearly visible.
• Show Author layout messages - If checked, all errors reported during layout creation is presented in the Errors
view.
• Hide comments - When checked, comments from the documents edited in Author mode are hidden.
• Hide processing instructions - When checked, processing instructions from the documents edited in Author mode
are hidden.
• Hide doctype - When checked, doctype sections from the documents edited in Author mode are hidden.
• Show very large images - If unchecked, images larger than 6 megapixels (24MB uncompressed) are not loaded and
displayed in Author mode. Please be aware that this option is unchecked by default because of the large amounts of
application memory that images of high resolution can occupy. As a result, an OutOfMemory error could occur
which would practically make Oxygen unusable without a restart of the entire application.
• Display referred content (for example entities, XInclude, DITA conref, etc.) - When checked, the references
(entities, XInclude, DITA conref, etc) also display the content of the resources they refer.
• Highlight elements near caret - Background color of the element or elements at cursor position.
• Format and indent - Here you can set the method of format and indent that is applied when a document is saved
in Author mode:
• Only the modified content - The save operation formats only the nodes that were modified in Author mode.
342 | Oxygen XML Author | Configuring the Application

• The entire document - The save operation applies formatting to the entire document regardless of the nodes
that were modified in Author mode. If the checkbox Apply also the 'Text' page 'Format and Indent' action
is selected, the content of the document is formatted by applying the Format and Indent action on every switch
from the Author editor to the Text editor of the same document.

• Quick up / down navigation - Speeds up navigation between blocks when using up / down keys. The cursor stops
on the next / previous line.
• Tags display mode - Default display mode for element tags presented in Author mode. You can choose between:
• Full Tags with Attributes
• Full Tags
• Block Tags
• Inline Tags
• Partial Tags
• No Tags

• Tags background color - Allows you to configure the Author tags background color.
• Tags foreground color - Allows you to configure the Author tags foreground color.
Schema Aware
The Schema Aware preferences panel is opened from menu Window > Preferences > Author > Editor > Pages >
Author > Schema aware .
The Oxygen Schema Aware Preferences Panel

• Schema aware normalization, format and indent - When opening a document in Author, white spaces can be
normalized or removed in order to obtain a more compact display. The reverse process takes place when saving the
document in the Author. By default this algorithm is controlled by the CSS display property.
If this option is checked then this process will be schema aware so the algorithm will take into account if the element
is declared as element-only or mixed. It will also take into account options Preserve space elements, Default space
Oxygen XML Author | Configuring the Application | 343

elements, Mixed content elements from option page Window > Preferences > Author > Editor > Format >
XML
• Indent blocks-only content - If checked, even if an element is declared in the schema as being mixed but it has a
blocks-only content (as specified by the CSS property display of its children), it will be treated as being
element-only.
• Schema Aware Editing - Editing in Author will take into account the schema.
• On - Enables all schema aware editing options.
• Off - Disables all schema aware editing options.
• Custom -
• Delete element tags with backspace and delete - Controls the behaviour for deleting element tags using
delete or backspace keys. Available options:
• Smart delete - If the result of the delete action is invalid, different strategies will be applied in order to
keep the document valid. If backspace / delete is pressed at the beginning / end of an element the action
that should take place is unwrap (the element will be deleted and its content will be put in its place). If its
content is not accepted by the schema in that position, you can keep a valid document by applying different
strategies like:
• Search for a preceding (backspace case)/following (delete case) element in which you can append that
content.
• If the tag markers of the element to unwrap are not visible a caret move action in the delete action
direction will be performed.

• Reject action when its result is invalid - If checked and the result of the delete action is invalid, the
action will not be performed.

• Paste and Drag and Drop - Controls the behavior for paste and drag and drop actions. Available options:
• Smart paste and drag and drop - If the content inserted by a paste or drop action is not valid at the caret
position, according to the schema, different strategies are applied to find an appropriate insert position:
• If the sibling element can accept the content, then a new element with the same name as the sibling is
created in which the content will be inserted.
• You will iterate to the left or to the right of the insertion position, without leaving the current context,
and try to insert the fragment in one of the encountered elements (that accepts the content to be inserted).

• Reject action when its result is invalid - If checked and the result of the paste or drop action is invalid,
the action will not be performed.

• Typing - Controls the behaviour that takes place when typing. Available options:
• Smart typing - If the typed character cannot be inserted at element from the caret position then a sibling
element that can accept it will be searched for. If the sibling element can accept the content, then a new
element with the same name as the sibling is created in which the content will be inserted.
• Reject action when its result is invalid - If checked and the result of the typing action is invalid, the
action will not be performed.

• Content Completion - Controls the behaviour that takes place when inserting elements using content
completion. Available options:
• Allow only insertion of valid elements and attributes - If checked, only elements or attributes form the
content completion proposals list can be inserted in the document through content completion.

• Warn on invalid content when performing action - A warning message will be displayed when performing
an action that will result in invalid content. Available options:
• Delete Element Tags - If checked, when the Delete Element Tags action will result in an invalid content,
a warning message will be displayed in which the user is asked if the operation should continue.
344 | Oxygen XML Author | Configuring the Application

• Join Elements - If checked, when the Join Elements action will result in an invalid content, a warning
message will be displayed in which the user is asked if the operation should continue.

• Convert external content on paste - when checked, Oxygen preserves the formatting style when you paste content
copied from external applications (like web browsers or Office-like applications). This option is enabled by default
and applies only to the major document type frameworks (DocBook, DITA, TEI, XHTML).
If the Schema Aware Editing is On or Custom all actions that can generate invalid content will be forwarded first toward
AuthorSchemaAwareEditingHandler.
Review
The Author Review preferences panel is opened from menu Window > Preferences > Author > Editor > Pages >
Author > Review .

Figure 167: The Oxygen Review Preferences Panel

The available preferences are:

• Author - The name of the user who performs the changes when Track Changes is active for a given editor. This
information will be associated with each performed change.
• Initial Track Changes State - Controls the initial Track Changes state.
• Stored in document - Recommended when multiple editors work on the same set of documents because the
state of Track Changes (enabled/disabled) is kept in the edited document. When you open such a document and
the Store in document option is active, a processing instruction saved in the document decides to enable or
disable the Track Changes. When this option is enabled and you open a document in Oxygen Author, the Track
Changes state is restored from the previous use of the document. This means that if another user edited the
document with Track Changes turned on before sending it to you, you will also have Track Changes switched
on when you open it in Oxygen Author.
• Always On - The Track Changes is active every time you open a document.
• Always Off - The Track Changes is inactive every time you open a document.
Note: Initial Track Changes State options do not affect documents already open in Oxygen Author.
Oxygen XML Author | Configuring the Application | 345

• Inserted content color -

• Auto - Automatically assign colors for the insert changes based on the author name.
• Custom - Use a custom color for all insert changes, regardless of the author name.
• Use same color for text foreground - Use the same color to paint the inserted text foreground.
• Use same color for background - Use the same color for the insert text background with a certain transparency.

• Deleted content color -

• Auto - Automatically assign colors for the delete changes based on the author name.
• Custom - Use a custom color for all delete changes, regardless of the author name.
• Use same color for text foreground - Use the same color to paint the deleted text foreground.
• Use same color for background - Use the same color for the delete text background with a certain transparency.

• Commented content color -

• Auto - Automatically assign colors for the commented content based on the author name.
• Custom - Use a custom color for all commented content, regardless of the author name.

Profiling / Conditional Text

The Author Review preferences panel is opened from menu Window > Preferences > Author > Editor > Pages >
Author > Profiling/Conditional Text .

Figure 168: Profiling / Conditional Text Preferences Panel

Here you can define, edit, delete new profiling attributes and profiling condition sets.
346 | Oxygen XML Author | Configuring the Application

Format
The Format preferences panel is opened from menu Window > Preferences > Author > Editor > Format .

Figure 169: The Format Preferences Panel

The formatting preferences are the following:

• Detect indent on open - The editor tries to detect the indent settings of the opened XML document. In this way you
can correctly format (pretty-print) files that were created with different settings, without changing your options.
More than that you can activate the advanced option for detecting the maximum line width to be used for formatting
and hard wrap. These features were designed to minimize the differences created by the pretty print operation when
working with a versioning system, like CVS for example.
• Indent with tabs - When checked enables Indent with tabs to set the indent to a tab unit. When unchecked, the
indent will measure as many spaces as needed in order to go to the next tab stop position. The maximum number of
space characters is defined by the Indent size option.
• Indent size - Sets the number of spaces or the tab size that will equal a single indent. The indent can be spaces or a
tab, selected by the preference Indent with tabs. For example if set to 4 one tab will equal 4 white spaces or 1 tab
with size of 4 characters depending on the value of the Indent with tabs option.
• Hard line wrap - This feature saves time when writing an XML document with long lines. You can set a limit for
the length of the lines in your document. When this limit is exceeded the editor will insert a new line before the word
that breaks the limit, and indent the next line. This will minimize the need of reformatting the document.
• Indent on Enter - If checked, it indents the new line introduced when pressing Enter.
• Enable Smart Enter - If checked, it inserts a new indented line between start and end tag when Enter is pressed.
• Detect line width on open - If checked, it detects the line width automatically when the document is opened.
• Format and indent the document on open - When checked, an XML document will be formatted and indented
before opening it in the editor panel. This option applies only to documents associated with the XML editor, not to
documents associated with the XSD editor, RNG editor or XSL editor.
• Line width - Format and Indent - Defines the point at which the Format and Indent (pretty-print) function will
perform hard line wrapping. So if set to 100 pretty-print will wrap lines at the 100th space inclusive of white spaces,
tags and elements.
• Clear undo buffer before Format and Indent - If checked, you cannot undo anymore editing actions that preceded
the Format and Indent operation. Only modifications performed after you have performed the operation can be
undone. Check this option if you encounter out of memory problems when performing the Format and Indent
operation.
Oxygen XML Author | Configuring the Application | 347

XML
The XML Format preferences panel is opened from menu Window > Preferences > Author > Editor > Format >
XML .

Figure 170: The XML Format Preferences Panel

The formatting preferences specific for XML files are the following:
• Preserve empty lines - When checked, the Format and Indent operation preserves all empty lines found in the
document on which the pretty-print operation is applied.
• Preserve text as it is - If checked, the Format and Indent operation preserves text nodes as they are without
removing or adding any whitespace.
• Preserve line breaks in attributes - If checked, the Format and Indent operation preserves the line breaks found
in attributes. When this option is checked, Break long lines option is automatically disabled.
• Break long attributes - If checked, the Format and Indent operation breaks long attributes.
• Indent inline elements - If checked, the inline elements are broken and indented on separate lines if there are white
spaces to the left and they follow another element start or end tag. Inline elements are elements which appear in a
mixed-content context (parents with both non-whitespace text and elements). Example:
Original XML:
<root>
text <parent> <child></child> </parent>
</root>
Indent inline elements enabled:
<root> text <parent>
<child/>
</parent>
</root>
348 | Oxygen XML Author | Configuring the Application

Indent inline elements disabled:

• Expand empty elements - When checked, the Format and Indent operation outputs empty elements with a separate
closing tag, ex. <a atr1="v1"></a>. When not checked, the same operation represents an empty element in a more
compact form: <a atr1="v1"/>.
• Sort attributes - When checked, the Format and Indent operation sorts the attributes of an element alphabetically.
When not checked, the same operation leaves them in the same order as before applying the operation.
• Add space before slash in empty elements - Inserts a space character before the trailing / and > of empty elements.
Note: When formatting XHTML files, Oxygen always inserts a space character before the trailing / and > of
empty elements.

• Break line before attribute name - If checked, the Format and Indent operation breaks the line before the attribute
name.
• Preserve space elements (XPath) - This list contains simplified XPath expressions for the names of the elements
for which the contained white spaces like blanks, tabs and newlines are preserved by the Format and Indent
operation. The allowed XPath expressions are of the form:
• elementName
• //elementName
• /elementName1/elementName2/elementName3
• //xs:localName
The namespace prefixes like xs in the previous example are treated as part of the element name without taking into
account its binding to a namespace.
• Default space elements (XPath) - This list contains the names of the elements for which contiguous white spaces
like blanks, tabs, and newlines are merged by the Format and Indent operation into one blank.
• Mixed content elements (XPath) - The elements from this list are treated as mixed when applying the Format and
Indent operation, meaning that the operation breaks the line only when whitespaces are encountered.
• Schema aware format and indent - When checked, the Format and Indent operation takes into account the schema
information regarding the space preserve, mixed, or element only property of an element.
• Indent (when typing) in preserve space elements - If checked, automatic tags indentation while editing takes place
for all elements including the ones that are excluded from Format and Indent (default behavior). When unchecked,
indentation while editing does not take place in elements that have the xml:space attribute set on preserve or
are added to the list of Preserve space elements.
• Indent on paste - Indent paste text corresponding to the indent settings set by the user. This is useful for keeping
the indent style of text copied from other document.
Whitespaces
This panel displays the special whitespace characters of Unicode. Any character that is checked in this panel is considered
whitespace that can be normalized in an XML document. The whitespaces are normalized by the following actions:
• when the action Format and Indent is applied on an XML document
• when you switch from Text mode to Author mode
• when you switch from Author mode to Text mode
The characters with the codes 9, 10, 13 and 32 are always in the group of whitespace characters that must be normalized
so they are always enabled in this panel.
Oxygen XML Author | Configuring the Application | 349

Figure 171: The Whitespaces Preferences Panel

CSS
The CSS Format preferences panel is opened from menu Window > Preferences > Author > Editor > Format > CSS
.

Figure 172: The CSS format preferences panel

The CSS formatting preferences are the following:

• Indent class content - If checked, the class content is indented during a Format and Indent operation. Enabled by
default.
• Class body on new line - If checked, the class body (including the curly brackets) are placed on a new line after a
Format and Indent operation.
• Add new line between classes - If checked, an empty line is added between two classes after a Format and Indent
operation is performed.
• Preserve empty lines - If checked, the empty lines from the CSS content are preserved during the execution of a
Format and Indent operation. Enabled by default.
• Allow formatting embedded CSS - If checked, the CSS content embedded in XML is formatted when the XML
content is formatted by the Format and Indent operation. Enabled by default.
JavaScript
The JavaScript format preferences panel is opened from menu Window > Preferences > Author > Editor > Format
> JavaScript .
350 | Oxygen XML Author | Configuring the Application

Figure 173: The JavaScript Format Preferences Panel

The JavaScript formatting preferences are the following:

• Start curly brace on new line - If true, opening curly braces will start on a new line. Otherwise they will remain
on the same line as previous content of the JavaScript file.
• Preserve empty lines - If true, empty lines in the JavaScript code will be preserved.
• Allow formatting embedded JavaScript - Applied only to XHTML documents, this option allows the application
to format embedded JavaScript code, taking precedence over the Schema aware format and indent option.

Content Completion
The content completion feature enables inline syntax lookup and auto completion of mark-up elements and attributes
to streamline mark-up and reduce errors while editing. These settings define the operating mode of the content assistant.
The Content Completion preferences panel is opened from menu Window > Preferences > Author > Editor >
Content Completion .

Figure 174: The Content Completion Preferences Panel

The configurable content completion preferences are the following:

• Auto close the last opened tag - If the Use Content Completion option is not checked but this option is checked,
Oxygen will close the last opened tag when </ is typed.
• Automatically rename matching tag - If checked, Oxygen will automatically rename the matching end tag when
the start tag is modified in the editor.
• Use Content Completion - When unchecked, all content completion features are disabled.
Oxygen XML Author | Configuring the Application | 351

• Close the inserted element - When inserting elements from the content completion assistant, both start and end tags
are inserted.
• If it has no matching tag - When checked, the end tag of the inserted element will be automatically added only if
it is not already present in the document.
• Add element content - When checked, Oxygen will insert automatically the required elements from the DTD or
XML Schema or RELAX NG schema. This option is applied also in the Author mode of the XML editor.
• Add optional content - When checked, Oxygen will insert automatically the optional elements from the DTD or
XML Schema or RELAX NG schema. This option is applied also in the Author mode of the XML editor.
• Add first Choice particle - When checked, Oxygen will insert automatically the first choice particle from the DTD
or XML Schema or RELAX NG schema that is associated with the edited XML document. This option is applied
also in the Author mode of the XML editor.
• Case sensitive search - When checked, the search in the content completion window when you type a character is
case sensitive ('a' and 'A' are different characters). This option is applied also in the Author mode of the XML editor.
• Cursor position between tags - When checked, Oxygen will set the cursor automatically between tags. If the
auto-inserted elements have attributes that are not required, the position of cursor can be forced between tags instead
of inside the start tag.
• Show all entities - When checked, Oxygen will display a list with all the internal and external entities declared in
the current document when the user types the start character of an entity reference (i.e. &).
• Insert the required attributes - When checked, Oxygen will insert automatically the required attributes from the
DTD or XML Schema for an element inserted with the help of the content completion assistant. This option is applied
also in the Author mode of the XML editor.
• Insert the fixed attributes - When checked, Oxygen will insert automatically any FIXED attributes from the DTD
or XML Schema for an element inserted with the help of the content completion assistant. This option is applied
also in the Author mode of the XML editor.
• Show recently used items - When checked, Oxygen will remember the last inserted items from the content completion
window. The number of items to be remembered is limited by the Maximum number of recent items shown combo
box. These most frequently used items are displayed on the top of the content completion window and their icon is
decorated with a small red square. This option is applied also in the Author mode of the XML editor.
• Maximum number of recent items shown - Limits the number of recently used items presented at the top of the
content completion window. This option is applied also in the Author mode of the XML editor.
• Learn attributes values - When checked, Oxygen will display a list with all attributes values learned from the
current document. This option is applied also in the Author mode of the XML editor.
• Learn on open document - When checked, Oxygen will automatically learn the document structure when the
document is opened. This option is applied also in the Author mode of the XML editor.
• Learn words (Dynamic Abbreviations, available on CTRL+SPACE) - When checked, Oxygen will automatically
learn the typed words and will make them available in a content completion fashion by pressing (CTRL+SPACE).
Note: In order to be learned, the words need to be separated by space characters.

Annotations
The Annotations preferences panel is opened from menu Window > Preferences > Author > Editor > Content
Completion > Annotations .

Figure 175: The Content Completion Annotations Preferences Panel

The following preferences can be configured for the annotations of the elements and attributes displayed by the content
completion assistant:
352 | Oxygen XML Author | Configuring the Application

• Show annotations - When checked, Oxygen will display the schema annotations that are present in the used schema
for the current element, attribute or attribute value from the content completion window. This option is applied also
in the Author mode of the XML editor.
• Show annotations as tooltip - When checked, it shows the annotation of an elements and attributes as a tooltip
when the mouse pointer hovers over that element or attribute in the XML editor panel or in the Elements view (both
the Text editing mode one and the Author editing mode one). This option is applied also in the Author mode of the
XML editor.
• Use DTD comments as annotation - When checked, Oxygen will use all DTD comments as annotation. If it is not
checked the following decision is performed: if among the gathered comments there are special Oxygen doc:
comments, only those will be presented. If not, all encountered comments will be presented.
• Use all Relax NG annotations as documentation - When checked, any element that is not from the Relax NG
namespace, that is http://relaxng.org/ns/structure/1.0 will be considered annotation and will be
displayed in the annotation window next to the content completion window and in the Model view. When unchecked
only elements from the Relax NG annotations namespace, that is
http://relaxng.org/ns/compatibility/annotations/1.0 will be considered annotation.
XPath
The XPath preferences panel is opened from menu Window > Preferences > Author > Editor > Content Completion
> XPath .

Figure 176: The Content Completion XPath Preferences Panel

The preferences that allow configuring the content completion in the XPath expressions are the following:
• Enable content completion for XPath expressions - Disables and enables content completion in XPath expressions
entered in the XSL attributes match, select and test and also in the XPath toolbar. Options are available to
control if the XPath functions, XSLT functions and XSLT axes are presented in the content completion list when
editing XPath expressions.
• Show signatures of XSLT / XPath functions - If checked, the editor will indicate in a tooltip helper the signature
of the XPath function located at the caret position.

Syntax Highlight
Oxygen supports syntax highlight for XML, JavaScript, PHP,CSS documents. While Oxygen provides a default color
configuration for highlighting the tokens, you may choose to customize it, as required, using the Syntax Highlight
preferences panel.
The Syntax Highlight preferences panel is opened from menu Window > Preferences > Author > Editor > Syntax
Highlight .
Oxygen XML Author | Configuring the Application | 353

Figure 177: The Colors Preferences Panel

For each document type there is a set of tokens. When a document type node is expanded, the associated tokens are
listed. For each token the color and the font style that is configured here will be used in Text mode of the editor panel.
The tokens for XML documents are used also in XSD, XSL, RNG documents so the Preview area has 4 tabs when an
XML token is selected in the Element area : XML, XSD, XSL, RNG.
When you don't know the name of the token that you want to configure just select a token by clicking directly on that
type of token in the Preview area.
You can edit the following color properties of the selected token:
• Foreground color - The Foreground button opens a color dialog that allow setting the color properties for the
selected token with one of the methods: Swatches, HSB or RGB.
• Background color - The Background button opens the same color dialog as the Foreground button.
• Bold style - This checkbox enables the bold variant of the font for the selected token. This property is not applied
to a bidirectional document.
• Italic style - This checkbox enables the italic variant of the font for the selected token. This property is not applied
to a bidirectional document.
The Preview panel displays the appearance of all token colors in a sample document as they will be rendered in the
editor.
Modifications are saved when the OK button is clicked. The Restore Defaults button changes all the token colors to
the default values.
354 | Oxygen XML Author | Configuring the Application

Elements / Attributes by Prefix

The Elements / Attributes by Prefix preferences panel is opened from menu Window > Preferences > Author >
Editor > Syntax Highlight > Elements / Attributes by Prefix .

Figure 178: The Elements / Attributes by Prefix Preferences Panel

One row of the table contains the association between a namespace prefix and the properties to mark start tags and end
tags or attribute names in that prefix. Note that the marking mechanism does not look at the namespace bound to that
prefix. If the prefix is bound to different namespaces in different XML elements of the same file all the tags and attribute
names with the prefix will be marked with the same color.
You can edit the following color properties of the selected token:
• Foreground color - The Foreground button opens a color dialog that allow setting the color properties for the
selected token with one of the methods: Swatches, HSB or RGB.
• Background color - The Background button opens the same color dialog as the Foreground button.
You can choose that only the prefix is displayed with the selected color by checking the Draw only the prefix with a
separate color option.

Open / Save
The Open / Save preferences panel is opened from menu Window > Preferences > Author > Editor > Open / Save
.

Figure 179: The Open / Save Preferences Panel

Oxygen XML Author | Configuring the Application | 355

The preferences related with opening and saving documents are the following:
• Format document when longest line exceeds - Specifies the default behavior when the longest line of a document
exceeds the specified limit. You can choose between:
• Always format - Runs the action Format and Indent on a document with very long lines when opening it
without notification for the user.
• Never format - Never modifies a document with very long lines on opening it.
• Always ask - Asks the user if he wants to run the action Format and Indent on every open of a document with
very long lines.

• Save all files before transformation or validation - Saves all opened files before validating or transforming an
XML document. In this way the dependencies are resolved, for example when modifying both the XML document
and its XML Schema.
• Clear undo buffer on save - If checked, you cannot undo anymore editing actions that preceded the save operation.
Only modifications made after you have saved the document can be undone. Check this option if you encounter
frequent out of memory problems when performing modifications on very large documents.

Templates
This panel groups the preferences that are related with code templates and document templates:
• Code Templates
• Document Templates
Code Templates
Code templates are small document fragments that can be inserted quickly at the editing position and can be reused in
other editing sessions. Oxygen comes with a large set of ready-to use templates for XSL, XQuery and XML Schema.
You can even share your code templates with your colleagues using the template export and import functions.
To obtain the template list, you use:
• The shortcut key for content completion on request: (Ctrl+Space) on Windows and Linux, (Cmd+Space) on Mac
OS X. It displays the code templates in the same content completion window with elements from the schema of the
document.
• The shortcut key for code templates on request: (Ctrl+Shift+Space) on Windows and Linux, (Cmd+Shift+Space)
on Mac OS X. It displays only the code templates in the popup window.
The Code Templates preferences panel is opened from menu Window > Preferences > Author > Editor > Templates
> Code Templates . It contains a list with all available code templates (both built-in and custom created ones) and a
code preview area. You can disable any code template by unchecking its corresponding option box.
356 | Oxygen XML Author | Configuring the Application

Figure 180: The Code Templates Preferences Panel

• New - Defines a new code template. You can define a code template for a specific type of editor or for all editor
types.
• Edit - Edits the selected code template.
• Duplicate - Duplicates the code template that is selected in the list.
• Delete - Deletes the code template that is selected in the list. This action is disabled for the built-in code templates.
• Import - Imports a file with code templates that was created by the Export action.
• Export - Exports a file with code templates.
Document Templates
The list of document templates that are displayed in the New dialog can be extended with custom templates that are
specified in the Document Templates preferences panel. You have to add the template files in a folder that is specified
in this panel or in the templates folder of the Oxygen install directory.
The Document Templates preferences panel is opened from menu Window > Preferences > Author > Editor >
Templates > Document Templates .

Figure 181: Document Templates Preferences Panel

A new template folder is added with the New button which opens the following dialog:
Oxygen XML Author | Configuring the Application | 357

Figure 182: Document Templates Input Dialog

Spell Check
The Spell Check preferences panel is opened from menu Window > Preferences > Author > Editor > Spell Check
.

Figure 183: The Spell Check Preferences Panel

The spell check preferences are the following:

• Automatic Spell Check - When checked, the spell checker highlights the errors as you modify the document.
• Spell checking engine - The engines available are Hunspell and AZ Check. Each engine has a specific format of
spelling dictionaries. The languages of the built-in dictionaries of the selected engine are listed in the Default
language combo box.
• Default language - The default language combo allows you to choose the language used by default. If the language
of your documents is not listed in this combo box you can add a spelling dictionary for your language which will
be added to this list.
• Delete learned words - Press this button to open the list of learned words. Here you can select the items you want
to remove.
• Use "lang" and "xml:lang" attributes - If checked, the contents of any element with such an attribute will be
checked using a dictionary for the language specified in the attribute value if this dictionary is available. When these
358 | Oxygen XML Author | Configuring the Application

attributes are missing the language used is controlled by the two radio buttons: Use the default language or Do not
check.
• XML spell checking in - These options allow the user to specify if the spell checker will be enabled inside XML
comments, attribute values, text and CDATA sections.
• Case sensitive - When checked, spell checking reports capitalization errors, for example a word that starts with
lowercase after etc. or i.e..
• Ignore mixed case words - When checked, operations do not check words containing case mixing (e.g. SpellChecker).
• Ignore words with digits - When checked, the spell checker does not check words containing digits (e.g. b2b).
• Ignore Duplicates - When checked, the spell checker does not signal two successive identical words as an error.
• Ignore URL - When checked, ignores words looking like URL or file names (e.g. www.oxygenxml.com or c:\boot.ini)
.
• Check punctuation - When checked, punctuation checking is enabled: misplaced white space and wrong sequences,
like a dot following a comma, are highlighted as errors.
• Allow compounds words - When checked, all words formed by concatenating two legal words with an hyphen are
accepted. If the language allows it, two words concatenated without hyphen are also accepted.
• Allow general prefixes - When checked, a word formed by concatenating a registered prefix and a legal word is
accepted. For example if mini- is a registered prefix, the checker accepts mini-computer.
• Allow file extensions - When checked, accepts any word ending with registered file extensions (e.g. myfile.txt,
index.html, etc.).
• Ignore acronyms - When checked, the acronyms are not reported as errors.
• Ignore elements - A list of XPath expressions for the elements that will be ignored by spell checking. Only a small
subset of XPath expressions are supported, that is:
• only the '/' and '//' separators
• the '*' wildcard
An example of allowed XPath expression: /a/*/b.

Document Checking
The Document Checking preferences panel is opened from menu Window > Preferences > Author > Editor >
Document Checking . It contains preferences for configuring how a document is checker for errors, that is well-formed
errors and validation errors.

Figure 184: Document Checking Preferences Panel

The error checking preferences are the following:

• Maximum number of validation highlights - If validation generates more errors than the number from this option
only the first errors up to this number are highlighted in editor panel and on stripe that is displayed at right side of
editor panel. This option is applied both for automatic validation and manual validation.
• Clear validation markers on close - If this option is selected all the error markers added in the Problems view for
that document are removed when a document edited with the Oxygen plugin is closed.
• Enable automatic validation - Validation of edited document is executed in background as the document is modified
by editing in Oxygen.
• Delay after the last key event (s) - The period of keyboard inactivity which starts a new validation (in seconds).
Oxygen XML Author | Configuring the Application | 359

Custom Validation Engines

The Custom Validation Engines preferences panel is opened from menu Window > Preferences > Author > Editor
> Custom Validations .

Figure 185: Custom Validation Engines Preferences Panel

If you want to add a new custom validation tool or edit the properties of an exiting one you can use the Custom Validator
dialog displayed by pressing the New button or the Edit button.

Figure 186: Edit a Custom Validator

The configurable parameters of a custom validator are the following:

• Name - Name of the custom validation tool displayed in the Custom Validation Engines toolbar.
360 | Oxygen XML Author | Configuring the Application

• Executable path - Path to the executable file of the custom validation tool. You can insert here editor variables like
${home}, ${pd}, ${oxygenInstallDir}, etc.
• Working directory - The working directory of the custom validation tool. The following editor variables can be
used in this field:
• ${home} - The path to the user home directory.
• ${pd} - The current project directory.
• ${oxygenInstallDir} - The Oxygen installation directory.

• Associated editors - The editors which can perform validation with the external tool: the XML editor, the XSL
editor, the XSD editor, etc.
• Command line arguments for detected schemas - Command line arguments used in the commands that validate
the current edited file against different types of schema: W3C XML Schema, Relax NG full syntax, Relax NG
compact syntax, NVDL, Schematron, DTD, etc.. The arguments can include any custom switch (like -rng) and the
following editor variables:
• ${cf} - The path of the current file as a local file path.
• ${cfu} - The path of the current file as a URL.
• ${ds} - The path of the detected schema as a local file path.
• ${dsu} - The path of the detected schema as a URL.

CSS Validator
The CSS Validator preferences panel is opened from menu Window > Preferences > Author > CSS Validator .

Figure 187: The CSS Validator Preferences Panel

The following options can be configured for Oxygen's built-in CSS validator:
• Profile - Selects one of the available validation profiles: CSS 1, CSS 2, CSS 2.1, CSS 3, SVG, SVG Basic, SVG
Tiny, Mobile, TV Profile, ATSC TV Profile.
• Media Type - Selects one of the available mediums: all, aural, braille, embossed, hand-held, print, projection, screen.
• Warning Level - Sets the minimum severity level for reported validation warnings. It is one of: all, normal, most
important, no warnings.

XML
This section describes the panels that contain the user preferences related with XML.

XML Catalog
The XML Catalog preferences panel is opened from menu Window > Preferences > Author > XML > XML Catalog
.
Oxygen XML Author | Configuring the Application | 361

Figure 188: The XML Catalog Preferences Panel

The Prefer option is used to specify if Oxygen will try to resolve first the PUBLIC or SYSTEM reference from the
DOCTYPE declaration of the XML document. If PUBLIC is preferred and a PUBLIC reference is not mapped in any
of the XML catalogs then a SYSTEM reference is looked up.
When using catalogs it is sometimes useful to see what catalog files are parsed, if they are valid or not, and what identifiers
are resolved by the catalogs. The Verbosity option selects the detail level of such logging messages of the XML catalog
resolver that will be displayed in the Catalogs view at the bottom of the window:
• None - No message is displayed by the catalog resolver when it tries to resolve a URI reference, a SYSTEM one or
a PUBLIC one with the XML catalogs specified in this panel.
• Unresolved entities - Only the logging messages that track the failed attempts to resolve references are displayed.
• All messages - The messages of both failed attempts and successful ones are displayed.
If the Process namespaces through URI mappings for XML Schema option is not selected only the schema location
of an XML Schema that is declared in an XML document is searched in XML catalogs. If the option is selected the
schema location of an XML Schema is searched and if it is not resolved the namespace of the schema is also searched.
If the Use default catalog option is checked the first XML catalog which Oxygen will use to resolve references at
document validation and transformation will be a default built-in catalog. This catalog maps such references to the
built-in local copies of the schemas of the Oxygen frameworks: DocBook, DITA, TEI, XHTML, SVG, etc.
You can also add or configure catalogs at framework level in the Document Type Association preferences page.
When you add, delete or edit an XML catalog to / from the list you must reopen the current edited files which use the
modified catalog or run the action Reset Cache and Validate so that the XML catalog changes take full effect.

XML Parser
The XML Parser preferences panel is opened from menu Window > Preferences > Author > XML > XML Parser
.
362 | Oxygen XML Author | Configuring the Application

Figure 189: The XML Parser preferences panel

The configurable options of the built-in XML parser are the following:
• http://apache.org/xml/features/validation/schema-full-checking - Sets the schema-full-checking feature to true,
that is a validation of the parsed XML document is performed against a schema (W3C XML Schema or DTD) while
the document is parsed.
• http://apache.org/xml/features/honour-all-schema-location - Sets the honour-all-schema-location feature to true.
This means all the files that declare W3C XML Schema components from the same namespace are used to compose
the validation model. If this option is not selected only the first W3C XML Schema file that is encountered in the
XML Schema import tree is taken into account.
• Ignore the DTD for validation if a schema is specified - Forces validation against a referred schema (W3C XML
Schema, Relax NG schema, Schematron schema) even if the document includes also a DTD DOCTYPE declaration.
This option is useful when the DTD declaration is used only to declare DTD entities and the schema reference is
used for validation against a W3C XML Schema, a Relax NG schema or a Schematron schema.
• Enable XInclude processing - Enables XInclude processing. If checked, the XInclude support in Oxygen is turned
on for validation, rendering in Author mode and transformation of XML documents.
• Base URI fix-up - According to the specification for XInclude, processors must add an xml:base attribute to
elements included from locations with a different base URI. Without these attributes, the resulting infoset information
would be incorrect.
Unfortunately, these attributes make XInclude processing not transparent to Schema validation. One solution to this
is to modify your schema to allow xml:base attributes to appear on elements that might be included from different
base URIs.
If the addition of xml:base and / or xml:lang is undesired by your application, you can disable base URI fix-up.
• Language fix-up - The processor will preserve language information on a top-level included element by adding an
xml:lang attribute if its include parent has a different [language] property. If the addition of xml:lang is undesired
by your application, you can disable the language fix-up.
• Check ID/IDREF - Checks the ID/IDREF matches when the Relax NG document is validated.
• Check feasibly valid - Checks the Relax NG to be feasibly valid when this document is validated.
• Schematron XPath Version - Selects the version of XPath for the expressions that are allowed in Schematron
assertion tests: 1.0 or 2.0. This option is applied both in standalone Schematron schemas and in embedded Schematron
rules, both in Schematron 1.5 and in ISO Schematron.
Oxygen XML Author | Configuring the Application | 363

• Optimize (visit-no-attributes) - If your ISO Schematron assertion tests do not contain the attributes axis you should
check this option for faster ISO Schematron validation.
• Allow foreign elements (allow-foreign) - Enables support for allow-foreign on ISO Schematron. This option
is used to pass non-Schematron elements to the generated stylesheet.
• Use Saxon EE (schema aware) for xslt2 query binding - If checked, Saxon EE will be used for xslt2 query
binding. If not checked, Saxon PE will be used instead.
Saxon EE Validation
The Saxon EE Validation preferences panel is opened from menu Window > Preferences > Author > XML > XML
Parser > Saxon EE Validation .
The following options are available:
• XML Schema version - allows you to select the version of W3C XML Schema for validation against XML Schema
performed by the Saxon EE engine: XML Schema 1.0 or XML Schema 2.0.
• XML Schema validation - you can set Oxygen to use Saxon EE as default XML Schema validator. If enabled it is
used to validate XML Schema and XML documents against an XML Schema. By default this option is turned off.

Figure 190: The Saxon EE Validation Preferences Panel

XProc Engines
Oxygen comes with a built-in XProc engine called Calabash. An external XProc engine can be configured in this panel.

Figure 191: The XProc Preferences Panel

When Show XProc messages is selected all messages emitted by the XProc processor during a transformation will be
presented in the results view.
For an external engine the value of the Name field will be displayed in the XProc transformation scenario and in the
command line that will start it.
364 | Oxygen XML Author | Configuring the Application

Figure 192: Creating an XProc external engine

Other parameters that can be set for an XProc external engine are the following: , and the error stream of the engine,
the working directory of the command that will start the engine. The encodings will be used for reading and displaying
the output of the engine. The working directory and
• a textual description that will appear as tooltip where the XProc engine will be used
• the encoding for the output stream of the XProc engine, used for reading and displaying the output messages
• the encoding for the error stream of the XProc engine, used for reading and displaying the messages from the error
stream
• the working directory for resolving relative paths
• the command line that will run the XProc engine as an external process; the command line can use built-in editor
variables and custom editor variables for parameterizing a file path.

XSLT/FO/XQuery
The XSLT/FO/XQuery preferences panel is opened from menu Window > Preferences > Author > XML >
XSLT/FO/XQuery . This panel contains only the most generic options for working with XSLT / XSL-FO / XQuery
processors. The more specific options are grouped in other panels linked as child nodes of this panel in the tree of the
Preferences dialog.

Figure 193: The XSLT/FO/XQuery Preferences Panel

There is only one generic option available:

Create transformation temporary files in system temporary directory - It should be selected only when the temporary
files necessary for performing transformations are created in the same folder as the source of the transformation (the
Oxygen XML Author | Configuring the Application | 365

default behavior, when this option is not selected) and this breaks the transformation. An example of breaking the
transformation is when the transformation processes all the files located in the same folder as the source of the
transformation, which will include the temporary files, and the result is incorrect or the transformation fails due to this
fact.
XSLT
The XSLT preferences panel is opened from menu Window > Preferences > Author > XML > XSLT/FO/XQuery
> XSLT .

Figure 194: The XSLT Preferences Panel

If you want to use an XSLT transformer implemented in Java different than the ones that ship with Oxygen namely
Apache Xalan and Saxon all you have to do is to specify the name of the transformer's factory class which Oxygen will
set as the value of the Java property javax.xml.transform.TransformerFactory. For instance, to perform
an XSLT transformation with Saxon 9.3.0.5 you have to place the Saxon 9.3.0.5 jar file in the Oxygen libraries folder
(the lib subfolder of the Oxygen installation folder), set net.sf.saxon.TransformerFactoryImpl as the
property value and select JAXP as the XSLT processor in the transformation scenario associated to the transformed
XML document.
The XSLT preferences are the following:
• Value - Allows the user to enter the name of the transformer factory Java class.
• XSLT 1.0 Validate with - Allows the user to set the XSLT engine used for validation of XSLT 1.0 documents.
• XSLT 2.0 Validate with - Allows the user to set the XSLT Engine used for validation of XSLT 2.0 documents.
Saxon6
The Saxon 6 preferences panel is opened from menu Window > Preferences > Author > XML > XSLT/FO/XQuery
> XSLT > Saxon > Saxon 6 .

Figure 195: The Saxon 6 XSLT Preferences Panel

The built-in Saxon 6 XSLT processor can be configured with the following options:
• Line numbering - If checked, line numbers are maintained and reported in error messages for the XML source
document.
366 | Oxygen XML Author | Configuring the Application

• Disable calls on extension functions - If checked, external functions called is disallowed. Checking this is
recommended in an environment where untrusted stylesheets may be executed. Also disables user-defined extension
elements, together with the writing of multiple output files, all of which carry similar security risks.
• Handling of recoverable stylesheet errors - Allows the user to choose how dynamic errors will be handled. Either
one of the following options can be selected:
• recover silently - continue processing without reporting the error,
• recover with warnings - issue a warning but continue processing,
• signal the error and do not attempt recovery - issue an error and stop processing.

Saxon HE/PE/EE
The Saxon HE/PE/EE preferences panel is opened from menu Window > Preferences > Author > XML >
XSLT/FO/XQuery > XSLT > Saxon > Saxon HE/PE/EE .

Figure 196: The Saxon HE/PE/EE XSLT preferences panel

The XSLT options which can be configured for the Saxon 9.3.0.5 transformer (all three editions: Home Edition,
Professional Edition, Enterprise Edition) are the following:
• Use a configuration file ("-config") - Sets a Saxon 9 configuration file that will be used for XSLT transformation
and validation.
• Version warnings ("-versmsg") - Warns you when the transformation is applied to an XSLT 1.0 stylesheet.
• Line numbering ("-l") - Error line number is included in the output messages.
• Debugger trace into XPath expressions (applies to debugging sessions) - Instructs the XSLT Debugger to step
into XPath expressions.
• DTD validation of the source ("-dtd") - The following options are available:
• On, requests DTD-based validation of the source file and of any files read using the document() function;
• Off (default setting) suppresses DTD validation.
• Recover, performs DTD validation but treats the error as non-fatal if it fails
Note that any external DTD is likely to be read even if not used for validation, because DTDs can contain definitions
of entities.
Oxygen XML Author | Configuring the Application | 367

• Recoverable errors ("-warnings") - Policy for handling recoverable errors in the stylesheet: Allows you to choose
how dynamic errors are handled. Either one of the following options can be selected:
• Recover silently ("silent") ;
• Recover with warnings ("recover") . Default setting;
• Signal the error and do not attempt recovery ("fatal").

• Optimization level ("-opt") - Set optimization level. The value is an integer in the range 0 (no optimization) to 10
(full optimization); currently all values other than 0 result in full optimization but this is likely to change in future.
The default is full optimization; this feature allows optimization to be suppressed in cases where reducing compile
time is important, or where optimization gets in the way of debugging, or causes extension functions with side-effects
to behave unpredictably. (Note however, that even with no optimization, lazy evaluation may still cause the evaluation
order to be not as expected.)
• Allow calls on extension functions ("-ext") - If checked, the stylesheet is allowed to call external Java functions.
This does not affect calls on integrated extension functions, including Saxon and EXSLT extension functions. This
option is useful when loading an untrusted stylesheet, perhaps from a remote site using an http:// URL; it ensures
that the stylesheet cannot call arbitrary Java methods and thereby gain privileged access to resources on your machine.
• Validation of the source file ("-val") - Requests schema-based validation of the source file and of any files read
using the document() or similar functions. Validation is available only with Saxon-EE, and this flag automatically
switches on the -sa option. Available options:
• Schema validation ("strict") - This mode requires an XML Schema and determines whether source documents
should be parsed with schema-validation enabled.
• Lax schema validation ("lax") - 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.

Figure 197: The Saxon HE/PE/EE XSLT Advanced Preferences Panel

368 | Oxygen XML Author | Configuring the Application

There are some advanced XSLT options which can be configured for the Saxon 9.3.0.5 transformer (all three editions:
Home Edition, Professional Edition, Enterprise Edition):
• URI Resolver class name ("-r") - Allows the user to specify a custom implementation for the URI resolver used
by the XSLT Saxon 9.3.0.5 transformer (the -r option when run from the command line). The class name must be
fully specified and the corresponding jar or class extension must be configured from the dialog for configuring the
XSLT extension for the particular transformation scenario.
• Collection URI Resolver class name ("-cr") - Allows the user to specify a custom implementation for the Collection
URI resolver used by the XSLT Saxon 9.3.0.5 transformer (the -cr option when run from the command line). The
class name must be fully specified and the corresponding jar or class extension must be configured from the dialog
for configuring the XSLT extension for the particular transformation scenario.
XSLTProc
The XSLTProc preferences panel is opened from menu Window > Preferences > Author > XML > XSLT/FO/XQuery
> XSLT > XSLTProc .

Figure 198: The XSLTProc Preferences Panel

The options of the XSLTProc processor are the same as the ones available in the command line:
• Enable XInclude processing - If checked, XInclude references will be resolved when XSLTProc is used as transformer
in XSLT transformation scenarios.
• Skip loading the document's DTD - If checked, the DTD specified in the DOCTYPE declaration will not be loaded.
• Do not apply default attributes from document's DTD - If checked, the default attributes declared in the DTD
and not specified in the document are not included in the transformed document.
• Do not use Internet to fetch DTD's, entities or docs - If checked, the remote references to DTD's and entities are
not followed.
• Maximum depth in templates stack - If this limit of maximum templates depth is reached the transformation ends
with an error.
• Verbosity - If checked, the transformation will output detailed status messages about the transformation process in
the Warnings view.
• Show version of libxml and libxslt used - If checked, Oxygen will display in the Warnings view the version of
the libxml and libxslt libraries invoked by XSLTProc.
• Show time information - If checked, the Warnings view will display the time necessary for running the
transformation.
• Show debug information - If checked, the Warnings view will display debug information about what templates
are matched, parameter values, etc.
• Show all documents loaded during processing - If checked, Oxygen will display in the Warnings view the URL
of all the files loaded during transformation.
Oxygen XML Author | Configuring the Application | 369

• Show profile information - If checked, Oxygen will display in the Warnings view a table with all the matched
templates, and for each template will display: the match XPath expression, the template name, the number of template
modes, the number of calls, the execution time.
• Show the list of registered extensions - If checked, Oxygen will display in the Warnings view a list with all the
registered extension functions, extension elements and extension modules.
• Refuses to write to any file or resource - If checked, the XSLTProc processor will not write any part of the
transformation result to an external file on disk. If such an operation is requested by the processed XSLT stylesheet
the transformation ends with a runtime error.
• Refuses to create directories - If checked, the XSLTProc processor will not create any directory during the
transformation process. If such an operation is requested by the processed XSLT stylesheet the transformation ends
with a runtime error.
MSXML
The MSXML preferences panel is opened from menu Window > Preferences > Author > XML > XSLT/FO/XQuery
> XSLT > MSXML .

Figure 199: The MSXML Preferences Panel

The options of the MSXML 3.0 and 4.0 processors are the same as the ones available in the command line for the
MSXML processors:
• Validate documents during parse phase - If checked and either the source or stylesheet document has a DTD or
schema against which its content can be checked, validation is performed.
• Do not resolve external definitions during parse phase - By default, MSXSL instructs the parser to resolve external
definitions such as document type definition (DTD), external subsets or external entity references when parsing the
source and style sheet documents. If this option is checked the resolution is disabled.
• Strip non-significant whitespaces - If checked, strips non-significant white space from the input XML document
during the load phase. Enabling this option can lower memory usage and improve transformation performance while,
in most cases, creating equivalent output.
• Show time information - If checked, the relative speed of various transformation steps can be measured:
• the time to load, parse, and build the input document
• the time to load, parse, and build the stylesheet document
• the time to compile the stylesheet in preparation for the transformation
• the time to execute the stylesheet

• Start transformation in this mode - Although stylesheet execution usually begins in the empty mode, this default
may be changed by specifying another mode. Changing the start mode allows execution to jump directly to an
alternate group of templates.
MSXML.NET
The MSXML.NET preferences panel is opened from menu Window > Preferences > Author > XML >
XSLT/FO/XQuery > XSLT > MSXML.NET .
370 | Oxygen XML Author | Configuring the Application

Figure 200: The MSXML.NET Preferences Panel

The options of the MSXML.NET processor are the same as the ones available in the command line for the MSXML.NET
processor:
• Enable XInclude processing - If checked, XInclude references will be resolved when MSXML.NET is used as
transformer in the XSLT transformation scenario.
• Validate documents during parse phase - If checked and either the source or stylesheet document has a DTD or
schema against which its content can be checked, validation is performed.
• Do not resolve external definitions during parse phase - By default MSXML.NET resolves external definitions
such as DTD external subsets or external entity references when parsing source XML document and stylesheet
document. Using this option you can disable this behaviour. Note, that it may affect also the validation process for
the XML document.
• Strip non-significant whitespaces - If checked, strips non-significant white space from the input XML document
during the load phase. Enabling this option can lower memory usage and improve transformation performance while,
in most cases, creating equivalent output.
• Show time information - If checked, the relative speed of various transformation steps can be measured:
• the time to load, parse, and build the input document
• the time to load, parse, and build the stylesheet document
• the time to compile the stylesheet in preparation for the transformation
• the time to execute the stylesheet

• Forces ASCII output encoding - There is a known problem with .NET 1.X XSLT processor
(System.Xml.Xsl.XslTransform class): it doesn't support escaping of characters as XML character references
when they cannot be represented in the output encoding. That means that when you output a character that cannot
be represented in output encoding, it will be outputted as '?'. Usually this happens when output encoding is set to
ASCII. With this option checked the output is forced to be ASCII encoded and all non-ASCII characters get escaped
as XML character references (&#nnnn; form).
• Allow multiple output documents - This option allows to create multiple result documents using the
exsl:document extension element.
• Use named URI resolver class - This option allows to specify a custom URI resolver class to resolve URI references
in xsl:import and xsl:include instructions (during XSLT stylesheet loading phase) and in document()
function (during XSL transformation phase).
• Assembly file name for URI resolver class - The previous option specifies partially or fully qualified URI resolver
class name, e.g. Acme.Resolvers.CacheResolver. Such name requires additional assembly specification
using this option or the next option, but fully qualified class name (which always includes an assembly specifier) is
Oxygen XML Author | Configuring the Application | 371

all-sufficient. See MSDN for more info about fully qualified class names. This option specifies a file name of the
assembly, where the specified resolver class can be found.
• Assembly GAC name for URI resolver class - This option specifies partially or fully qualified name of the assembly
in the global assembly cache (GAC), where the specified resolver class can be found. See MSDN for more info
about partial assembly names. Also see the previous option.
• List of extension object class names - This option allows to specify extension object classes, whose public methods
then can be used as extension functions in an XSLT stylesheet. It is a comma-separated list of namespace-qualified
extension object class names. Each class name must be bound to a namespace URI using prefixes as when providing
XSLT parameters.
• Use specified EXSLT assembly - MSXML.NET supports a rich library of the EXSLT and EXSLT.NET extension
functions embedded or in a plugged in EXSLT.NET library. EXSLT support is enabled by default and cannot be
disabled in this version. If you want to use an external EXSLT.NET implementation instead of a built-in one use
this option.
• Credential loading source xml - This option allows to specify user credentials to be used when loading XML source
documents. The credentials should be provided in the username:password@domain format (all parts are optional).
• Credential loading stylesheet - This option allows to specify user credentials to be used when loading XSLT
stylesheet documents. The credentials should be provided in the username:password@domain format (all parts are
optional).
FO Processors
Besides the built-in formatting objects processor (Apache FOP) other external processors can be configured and set in
transformation scenarios for processing XSL-FO documents.
Oxygen has implemented an easy way to add two of the most used commercial FO processors: RenderX XEP and
Antenna House XSL Formatter. You can easily add RenderX XEP as external FO processor if the user has the XEP
installed. Also, if you have the Antenna House XSL Formatter v4 or v5, Oxygen uses the environmental variables set
by the XSL Formatter installation to detect and use it for XSL-FO transformations. If the environmental variables are
not set for the XSL Formatter installation, you can browse and choose the executable just as you would for XEP.
The FO Processors preferences panel is opened from menu Window > Preferences > Author > XML >
XSLT/FO/XQuery > FO Processors .
372 | Oxygen XML Author | Configuring the Application

Figure 201: The FO Processors Preferences Panel

The options for FO processors are the following:

• Use built-in Apache FOP - Instructs Oxygen to use its built-in Apache FO processor.
• Use other Apache FOP - Instructs Oxygen to use another Apache FO processor installed on your computer.
• Enable the output of the built-in FOP - All Apache FOP output is displayed in a results pane at the bottom of the
Oxygen window including warning messages about FO instructions not supported by Apache FOP.
• Memory available to the built-in FOP - If your Apache FOP transformations fail with an Out of Memory error
select from this combo box a larger value for the amount of memory reserved for FOP transformations.
• Configuration file for the built-in FOP - You should specify here the path to an Apache FOP configuration file,
necessary for example to render to PDF a document containing Unicode content using a special true type font.
• Generates PDF/A-1b output - When selected PDF/A-1b output is generated.
Note: All fonts have to be embedded, even the implicit ones. More information about configuring metrics files
for the embedded fonts can be found in Add a font to the built-in FOP.

Note: You cannot use the <filterList> key in the configuration file because FOP would generate the
following error: The Filter key is prohibited when PDF/A-1 is active.

The users can configure the external FO processors for use in transformation scenarios in the following dialog:
Oxygen XML Author | Configuring the Application | 373

Figure 202: The External FO Processor Configuration Dialog

• Name - The name displayed in the list of available FOP processors on the FOP tab of the transformation scenario
dialog.
• Description - A textual description of the FO processor displayed in the FO processors table and in tooltips of UI
components where the processor is selected.
• Output Encoding - The encoding of the FO processor output stream displayed in a results panel at the bottom of
the Oxygen window.
• Error Encoding - The encoding of the FO processor error stream displayed in a results panel at the bottom of the
Oxygen window.
• Working directory - The directory where the intermediate and final results of the processing is stored. Here you
can use one of the following editor variables:
• ${homeDir} - The path to user home directory.
• ${cfd} - The path of current file directory. If the current file is not a local file, the target is the user's desktop
directory.
• ${pd} - The project directory.
• ${oxygenInstallDir} - The Oxygen installation directory.

• Command line - The command line that starts the FO processor, specific to each processor. Here you can use one
of the following editor variables:
• ${method} - The FOP transformation method: pdf, ps or txt.
• ${fo} - The input FO file.
• ${out} - The output file.
• ${pd} - The project directory.
• ${frameworksDir} - The path of the frameworks subdirectory of the Oxygen install directory.
• ${oxygenInstallDir} - The Oxygen installation directory.
• ${ps} - The platform-specific path separator. It is used between the library files specified in the class path of the
command line.

XPath
The XPath preferences panel is opened from menu Window > Preferences > Author > XML > XSLT/FO/XQuery
> XPath .
374 | Oxygen XML Author | Configuring the Application

Figure 203: The XPath Preferences Panel

The XPath options are the following:

• Unescape XPath expression - When checked, the entities are unescaped in the XPath expressions entered in the
XPath toolbar. For example the expression
//varlistentry[starts-with(@os,'s')]
is equivalent with:
//varlistentry[starts-with(@os,'s')]

• No namespace - If checked, Oxygen will consider unprefixed element names in XPath 2.0 expressions evaluated
in the XPath console as belonging to no namespace.
• Use the default namespace from the root element - If checked, Oxygen will consider unprefixed element names
in XPath expressions evaluated in the XPath console as belonging to the default namespace declared on the root
element of the queried XML document.
• Use the namespace of the root - If checked, Oxygen will consider unprefixed element names in XPath expressions
evaluated in the XPath console as belonging to the same namespace as the root element of the document.
• This namespace - The user has the possibility to enter here the namespace of the unprefixed elements used in the
XPath console.
• Default prefix-namespace mappings - Associates prefixes to namespaces. These mappings are useful when applying
an XPath in the XPath console and you don't want to define these mappings in each document separately.
Custom Engines
You can configure and run XSLT and XQuery transformations with processors other than the ones which come with the
Oxygen distribution. Such an external engine can be used in the Editor perspective and is available in the list of engines
in the dialog for editing a transformation scenario.
The Custom Engines preferences panel is opened from menu Window > Preferences > Author > XML >
XSLT/FO/XQuery > Custom Engines .
Oxygen XML Author | Configuring the Application | 375

Figure 204: Custom Transformation Engines

The following parameters can be configured for a custom engine:

Figure 205: Parameters of a Custom Engine

• Engine type - Combo box allowing you to choose the transformer type. There are two options: XSLT engines and
XQuery engines.
• Name - The name of the transformer displayed in the dialog for editing transformation scenarios
• Description - A textual description of the transformer.
• Output Encoding - The encoding of the transformer output stream.
• Error Encoding - The encoding of the transformer error stream.
• Working directory - The start directory of the transformer executable program. The following editor variables are
available for making the path to the working directory independent of the location of the input files:
• ${homeDir} - The user home directory in the operating system.
• ${cfd} - The path to the directory of the current file.
• ${pd} - The path to the directory of the current project.
• ${oxygenInstallDir} - The Oxygen install directory.
376 | Oxygen XML Author | Configuring the Application

• Command line - The command line that must be executed by Oxygen to perform a transformation with the engine.
The following editor variables are available for making the parameters in the command line (the transformer executable,
the input files) independent of the location of the input files:
• ${xml} - The XML input document as a file path.
• ${xmlu} - The XML input document as a URL.
• ${xsl} - The XSL / XQuery input document as a file path.
• ${xslu} - The XSL / XQuery input document as a URL.
• ${out} - The output document as a file path.
• ${outu} - The output document as a URL.
• ${ps} - The platform separator which is used between library file names specified in the class path.

Data Sources
The Data Sources preferences panel is opened from menu Window > Preferences > Author > Data Sources .

Configuration of Data Sources

Here you can configure data sources and connections to relational databases as well as native XML databases. You can
check the list of drivers (http://www.oxygenxml.com/database_drivers.html) available for the major database servers.

Figure 206: The Data Sources Preferences Panel

• New - Opens the Data Sources Drivers dialog that allows you to configure a new database driver.
Oxygen XML Author | Configuring the Application | 377

Figure 207: The Data Sources Drivers Dialog

The fields of the dialog are the following:

• Name - The name of the new data source driver that will be used for creating connections to the database
• Type - Selects the data source type from the supported driver types.
• Help - Opens the User Manual at the list of the sections where the configuration of supported data sources is
explained and the URLs for downloading the database drivers are specified.
• Driver Class - Specifies the driver class for the data source driver.
• Add - Adds the driver class library.
• Remove - Removes the selected driver class library from the list.
• Detect - Detects driver class candidates.
• Stop - Stops the detection of the driver candidates.

• Edit - Opens the Data Sources Drivers dialog for editing the selected driver. See above the specifications for the
Data Sources Drivers dialog. In order to edit a data source, there must be no connections using that data source
driver.
• Delete - Deletes the selected driver. In order to delete a data source, there must be no connections using that data
source driver.
378 | Oxygen XML Author | Configuring the Application

Figure 208: The Connections Preferences Panel

For performance issues, you can set the maximum number of cells that will be displayed in the Table Explorer view
for a database table. Leave the field Limit the number of cells empty if you want the entire content of the table to be
displayed. By default this field is set to 2,000. If a table having more cells than the value set here is displayed in the
Table Explorer view, a warning dialog will inform you that the table is only partially shown.
In Oracle XML and Tamino databases a container can hold millions of resources. If the node corresponding to such a
container in the Data Source Explorer view would display all the contained resources at the same time the performance
of the view would be very slow. To prevent such a situation only a limited number of the contained resources is displayed
as child nodes of the container node. Navigation to other contained resources from the same container is enabled by the
Up and Down buttons in the Data Source Explorer view. This limited number is set in the option Maximum number
of children for container nodes. The default value is 200 nodes.
The Show warning when expanding other database schema option controls if a warning message will be displayed
when expanding another database schema and there are tables selected in the current expanded one. This applies for the
dialog Select database table when invoking the Convert DB Structure to XML Schema action.
The actions of the buttons from the Connections panel are the following:
• New - Opens the Connection dialog which has the following fields:
Oxygen XML Author | Configuring the Application | 379

Figure 209: The Connection Dialog

• Name - The name of the new connection that will be used in transformation scenarios and validation scenarios.
• Data Source - Allows selecting a data source defined in the Data Source Drivers dialog.
Depending upon the selected data source, you can set some of the following parameters in the Connection details
area:
• URL - The URL for connecting to the database server.
• User - The user name for connecting to the database server.
• Password - The password of the specified user name.
• Host - The host address of the server.
• Port - The port where the server accepts the connection.
• XML DB URI - The database URI.
• Database - The initial database name.
• Collection - One of the available collections for the specified data source.
• Environment home directory - Specifies the home directory (only for a Berkeley database).
• Verbosity - Sets the verbosity level for output messages (only for a Berkeley database).

• Edit - Opens the Connection dialog, allowing you to edit the selected connection. See above the specifications for
the Connection dialog.
• Duplicate - Creates a duplicate of the currently selected connection.
• Delete - Deletes the selected connection.

Download Links for Database Drivers

You can find below the locations where you have to go to get the drivers necessary for accessing databases in Oxygen.
• Berkeley DB XML database - Copy the jar files from the Berkeley database install directory to the Oxygen install
directory as described in the procedure for configuring a Berkeley DB data source.
• IBM DB2 Pure XML database - Go to the IBM website and in the DB2 Clients and Development Tools category
select the DB2 Driver for JDBC and SQLJ download link. Fill the download form and download the zip file. Unzip
the zip file and use the db2jcc.jar and db2jcc_license_cu.jar files in Oxygen for configuring a DB2
data source.
380 | Oxygen XML Author | Configuring the Application

• eXist database - Copy the jar files from the eXist database install directory to the Oxygen install directory as described
in the procedure for configuring an eXist data source.
• MarkLogic database - Download the Java and .NET XCC distributions (XCC Connectivity Packages) from
MarkLogic. You find the details about configuring a MarkLogic data source in the procedure for creating a MarkLogic
data source.
• Microsoft SQL Server 2005 / 2008 database - Both SQL Server 2005 and SQL Server 2008 are supported. For
connecting to SQL Server 2005 you have to download the SQL Server 2005 JDBC driver file sqljdbc.jar from
the Microsoft website and use it for configuring an SQL Server data source. For connecting to SQL Server 2008 you
have to download the SQL Server 2008 JDBC 1.2 driver file sqljdbc_1.2\enu\sqljdbc.jar from the
Microsoft website and use it for configuring an SQL Server data source. Please note that the SQL Server driver is
compiled with a Java 1.6 compiler so you need to run Oxygen with a Java 1.6 virtual machine in order to use this
driver.
• Oracle 11g database - Download the Oracle 11g JDBC driver called ojdbc5.jar from the Oracle website and
use it for configuring an Oracle data source.
• PostgreSQL 8.3 database - Download the PostgreSQL 8.3 JDBC driver called
postgresql-8.3-603.jdbc3.jar from the PostgreSQL website and use it for configuring a PostgreSQL
data source.
• RainingData TigerLogic XDMS database - Copy the jar files from the TigerLogic JDK lib directory from the
server side to the Oxygen install directory as described in the procedure for configuring a TigerLogic data source.
• SoftwareAG Tamino database - Copy the jar files from the SDK\TaminoAPI4J\lib subdirectory of the Tamino
database install directory to the Oxygen install directory as described in the procedure for configuring a Tamino
data source.
• Documentum xDb (X-Hive/DB) 10 XML database - Copy the jar files from the Documentum xDb (X-Hive/DB)
10 database install directory to the Oxygen install directory as described in the procedure for configuring a
Documentum xDb (X-Hive/DB) 10 data source.
• MySQL database - Download the MySQL JDBC driver from the MySQL website and use it for configuring a
MySQL data source.

Table Filters
The Table Filters preferences panel is opened from menu Window > Preferences > Author > Data Sources > Table
Filters .
Here you can choose which of the database table types will be displayed in the Data Source Explorer view.

Figure 210: Table Filters Preferences Panel

Archive
The Archive preferences panel is opened from menu Window > Preferences > Author > Archive .
Oxygen XML Author | Configuring the Application | 381

Figure 211: The Archive Preferences Panel

The following options are available in the Archive preferences panel:

• One of the following options is the default for backup actions in the Archive Backup dialog:
• No backup - No backups are made.
• Single file backup - When you modify an archive, its content is backed up under the name
originalArchiveFileName.bak. You can find the backup file in the same folder as the original archive.
Note: The backup is done only once per application session for each archive open in the Archive Browser
view.

• Show archive backup dialog - Select this option if you want to be notified for backup when modifying in archives.
The last backup option you chose will always be used as the default one.
• Archive types - This table contains all known archive extensions mapped to known archive formats. Each row maps
a list of extensions to an archive type supported in Oxygen. You can edit an existing mapping or create a new one
by associating your own list of extensions to an archive format.

Figure 212: Edit Archive Extension Mappings

382 | Oxygen XML Author | Configuring the Application

Important: You have to restart Oxygen after removing an extension from the table in order for that extension
to not be recognised anymore as an archive extension.

• Store Unicode file names in Zip archives - Use this option when you archive files that contain international (that
is, non-English) characters in file names or file comments. If an archive is modified in any way with this option
turned on, UTF-8 characters are used in the names of all files in the archive.

Custom Editor Variables

An editor variable is useful for making a transformation scenario, a validation scenario or an external tool independent
of the file path on which the scenario / command line is applied. An editor variable is specified as a parameter in a
transformation scenario, validation scenario or command line of an external tool. Such a variable is defined by a name,
a string value and a text description. A custom editor variable is defined by the user and can be used in the same
expressions as the built-in ones.

Figure 213: Custom Editor Variables

Network Connections
Some networks use proxy servers to provide Internet services to LAN clients. Clients behind the proxy may therefore,
only connect to the Internet via the proxy service. If you are not sure whether your computer is required to use a proxy
server to connect to the Internet or you don't know the proxy parameters, please consult your network administrator.
You can open the Network Connections panel from menu Window > Preferences > Author / Network Connections
.
The Network Connections Preferences Panel
Oxygen XML Author | Configuring the Application | 383

Complete the dialog as follows:

• Enable the HTTP/WEBDAV protocols - If checked, the HTTP(S) connections go through the proxy with the host,
port, user name and password that are set in Eclipse's built-in general Network Connections preferences panel.
Important: This may affect other plugins functionality.

• Lock WebDAV files on open - If checked, the files opened through WebDAV are locked on the server so that they
cannot be edited by other users while the lock placed by the current user still exists on the server.
• Encoding for FTP control connection - The encoding used to communicate with FTP servers: either ISO-8859-1
or UTF-8. If the server supports the UTF-8 encoding Oxygen will use it for communication. Otherwise it will use
ISO-8859-1.
• Private key file - The path to the file containing the private key used for the private key method of authentication
of the secure FTP (SFTP) protocol. The user / password method of authentication has precedence if it is used in the
Open URL dialog.
• Passphrase - The passphrase used for the private key method of authentication of the secure FTP (SFTP) protocol.
The user / password method of authentication has precedence if it is used in the Open URL dialog.
• Show SFTP certificate warning dialog - If checked, a warning dialog will be shown each time when the authenticity
of the host cannot be established.

Certificates
In Oxygen there are provided two types of keystores for certificates used for digital signatures of XL documents: Java
KeyStore (JKS) and Public-Key Cryptography Standards version 12 (PKCS-12). A keystore file is protected by a
password. A certificate keystore is configured in Oxygen in the Certificates preferences panel which is opened from
menu Window > Preferences > Author > Certificates . The parameters of a keystore are the following:
384 | Oxygen XML Author | Configuring the Application

Figure 214: The Certificates Preferences Panel

• Keystore type - Represents the type of keystore to be used.

• Keystore file - Represents the location of the file to be imported.
• Keystore password - The password which is used to protect the privacy of the stored keys.
• Certificate alias - The alias to be used to store the key entry (the certificate and / or the private key) inside the
keystore.
• Private key password - It is only necessary in case of JKS keystore. It represents the certificate's private key
password.
• Validate - Pressing this button verifies the keystore configured with the above parameters and assures that the
certificate is valid.

XML Structure Outline

The XML Structure Outline preferences panel is opened from menu Window > Preferences > Author > XML
Structure Outline and contains the following preferences:

Figure 215: The XML Structure Outline Preferences Panel

• Preferred attribute names for display - The attribute names which should be preferred when displaying the element's
attributes in the Outline view. If there is no preferred attribute name specified the first attribute of an element is
displayed.
• Enable outline drag and drop - Drag and drop should be disabled for the tree displayed in the Outline view only
of there is a possibility to accidentally change the structure of the document by such drag and drop operations.
Oxygen XML Author | Configuring the Application | 385

Scenarios Management
The Scenarios Management preferences panel is opened from menu Window > Preferences > Author > Scenarios
Management and allows sharing the global transformation scenarios with other users by exporting them to an external
file that can be also imported in this preferences panel.

Figure 216: The Scenarios Management Preferences Panel

The actions available in this panel are the following:

• Import Global Transformation Scenarios - Allows you to import at global level all transformation scenarios from
a properties file created with the export scenario action. The names of the imported scenarios will appear in the
Configure Transformation Scenario dialog followed by (import). This way there are no scenario name conflicts.
If you want to work with project level scenarios you have to first switch to project level in the Configure
Transformation Scenario dialog.
• Export Global Transformation Scenarios - Allows you to export all global transformation scenarios available in
the Configure Transformation Scenario dialog.
• Import Global Validation Scenarios - Allows you to import at global level all scenarios from a properties file
created with the export scenario action. The names of the imported scenarios will appear in the Configure Validation
Scenario dialog followed by (import). This way there are no scenario name conflicts.
If you want to work with project level scenarios you have to first switch to project level in the Configure Validation
Scenario dialog.
• Export Global Validation Scenarios - Allows you to export all global validation scenarios available in the Configure
Validation Scenario dialog.

View
The View preferences panel is opened from menu Window > Preferences > Author > View and contains the following
preferences:

Figure 217: The View Preferences Panel

• Fixed width console - If checked, a line in the Console view will be hard wrapped after the maximum numbers of
characters allowed on a line.
386 | Oxygen XML Author | Configuring the Application

• Limit console output - If checked, the content of the Console view will be limited to a configurable number of
characters.
• Console buffer - Specifies the maximum number of characters that can be written in the Console view.
• Tab width - Specifies the number of spaces used for depicting a tab character.

Automatically Importing the Preferences from the Other Distribution

If you want to use the settings from Oxygenstandalone distribution in the Eclipse plugin one just delete the file with the
Eclipse plugin preferences, that is [user-home-folder]/Application
Data/com.oxygenxml.author/oxyAuthorOptionsEc12.2.xml on Windows /
[user-home-folder]/.com.oxygenxml.author/oxyAuthorOptionsEc12.2.xml on Linux, start
Eclipse and the Oxygen standalone preferences will be automatically imported in Eclipse. The same for importing the
Eclipse plugin settings in Oxygen standalone: delete the file
[user-home-folder]/com.oxygenxml.author/oxyAuthorOptionsSa12.2.xml on Windows /
[user-home-folder]/.com.oxygenxml.author/oxyAuthorOptionsSa12.2.xml on Linux, start the
Oxygen standalone distribution and the Eclipse settings will be automatically imported in Oxygen standalone.

Reset Global Options

To reset all global preferences to their default values you have to go to menu Window > Preferences > Author > Reset
Global Options . . The list of transformation scenarios will be reset to the default scenarios.

Scenarios Management
You can import, export and reset the global scenarios for transformation and validation with the following actions:
• The action Window > Preferences > oXygen / Scenarios Management > Import Global Transformation
Scenarios loads a set of transformation scenarios from a properties file that was created with the action Export
Global Transformation Scenarios.
• The action Window > Preferences > oXygen / Scenarios Management > Export Global Transformation
Scenarios stores all the global (not project-level) transformation scenarios in a properties file that can be used later
by the action Import Global Transformation Scenarios.
• The action Window > Preferences > oXygen / Scenarios Management > Import Global Validation Scenarios
loads a set of validation scenarios from a properties file that was created with the action Export Global Validation
Scenarios.
• The action Window > Preferences > oXygen / Scenarios Management > Export Global Validation scenarios
stores all the global (not project-level) validation scenarios in a separate properties file.
The options of Export Global Transformation Scenarios and Export Global Validation Scenarios is used to store
all the scenarios in a separate file which is a properties file. In this file will also be saved the associations between
document URLs and scenarios. You can load the saved scenarios using the actions Import Global Transformation
Scenarios and Import Global Validation Scenarios. All the imported scenarios will have added to the name the word
import to distinguish the existing scenarios and the imported ones.
Oxygen XML Author | Configuring the Application | 387

Editor Variables
An editor variable is a shorthand notation for a file path or folder path. It is used in the definition of a command (the
input URL of a transformation, the output file path of a transformation, the command line of an external tool, etc.) to
make a command or a parameter generic and reusable with other input files. When the same command is applied to
different files, the notation is expanded at the execution of the command so that the same command has different effects
depending on the actual file.
The following editor variables can be used in Oxygen commands of external engines or other external tools, in
transformation scenarios and in validation scenarios:
• ${frameworks} - The path (as URL) of the frameworks subfolder of the Oxygen install folder.
• ${frameworksDir} - The path (as file path) of the frameworks subfolder of the Oxygen installation folder.
• ${home} - The path (as URL) of the user home folder.
• ${homeDir} - The path (as file path) of the user home folder.
• ${cfdu} - Current file folder as URL, that is the path of the current edited document up to the name of the parent
folder, represented as a URL.
• ${cfd} - Current file folder as file path, that is the path of the current edited document up to the name of the parent
folder.
• ${cfn} - Current file name without extension and without parent folder.
• ${cf} - Current file as file path, that is the absolute file path of the current edited document.
• ${currentFileURL} - Current file as URL, that is the absolute file path of the current edited document represented
as URL.
• ${ps} - Path separator, that is the separator which can be used on the current platform (Windows, Mac OS X, Linux)
between library files specified in the class path.
• ${timeStamp} - Time stamp, that is the current time in Unix format. It can be used for example to save transformation
results in different output files on each transform.
• ${caret} - The position where the caret is inserted. This variable can be used in a code template.
• ${selection} - The text content of the current selection in the editor panel. This variable can be used in a code template
.

Custom Editor Variables

An editor variable can be created by the user and included in any user defined expression where a built-in editor variable
is also allowed. For example a custom editor variable may be necessary for configuring the command line of an external
tool, the working directory of a custom validator, the command line of a custom XSLT engine, a custom FO processor,
etc. All the custom editor variables are listed together with the built-in editor variables, for example when editing the
working folder or the command line of a custom validator, the working directory, etc.
Creating a custom editor variable is very simple: just specify the name that will be used in user defined expressions, the
value that will replace the variable name at runtime and a textual description for the user of that variable.
An editor variable can be created also from a Java system property. For example the Java system property var.name
can be inserted in any expression where built-in editor variables like ${currentFileURL} are allowed: just type
${system(var.name)} in the field where you need that Java system property.
An editor variable can be created also from an environment variable of the operating system. For example the environment
variable VAR_NAME can be inserted in any expression where built-in editor variables like ${currentFileURL} are
allowed: just type ${env(VAR_NAME)} where you need the environment variable.
The current date can be inserted at cursor location with the custom variable ${date(yyyy-MM-dd)}. The date format
is: the year with 4 digits, the month with 2 letters, the day with 2 letters.
The custom editor variables are configured in Preferences.
Chapter
18
Common Problems
Topics: This chapter presents common problems that may appear when running the
application and the solutions for these problems.
• The Scroll Function of my
Notebook's Trackpad is Not
Working
• Syntax Highlight Not Available in
Eclipse Plugin
• Problem Report Submitted on the
Technical Support Form
390 | Oxygen XML Author | Common Problems

The Scroll Function of my Notebook's Trackpad is Not Working

I got a new notebook (Lenovo Thinkpad™ with Windows) and noticed that the scroll function of my trackpad is not
working in .
It is a problem of the Synaptics™ trackpads which can be fixed by adding the following lines to the C:\Program
Files\Synaptics\SynTP\TP4table.dat file:

*,*,oxygen.exe,*,*,*,WheelStd,1,9
*,*,author.exe,*,*,*,WheelStd,1,9
*,*,syncroSVNClient.exe,*,*,*,WheelStd,1,9
*,*,diffDirs.exe,*,*,*,WheelStd,1,9
*,*,diffFiles.exe,*,*,*,WheelStd,1,9

Syntax Highlight Not Available in Eclipse Plugin

I associated the .ext extension with Oxygen in Eclipse. Why does an .ext file opened with the Oxygen plugin not
have syntax highlight?
Associating an extension with Oxygen in Eclipse 3.6+ requires three steps:

1. Associate the .ext extension with the Oxygen plugin.

a) Go to menu Windows > Preferences > General > Editors > File Associations .
b) Add *.ext to the list of file types.
c) Select *.ext in the list by clicking on it.
d) Add Oxygen XML Editor to the list of Associated editors and make it the default editor.
2. Associate the .ext extension with the Oxygen XML content type.
a) Go to menu Windows > Preferences > General > Content Types .
b) Add *.ext to the File associations list for the Text > XML > oXygen XML content type.
3. Press the OK button in the Eclipse preferences dialog.

Now when an *.ext file is opened the icon of the editor and the syntax highlight should be the same as for XML files
opened with the Oxygen plugin.

Problem Report Submitted on the Technical Support Form

What details should I add to my problem report that I enter on the Technical Support online form of the product website?
For problems like server connection error, unexpected delay while editing a document, a crash of the application, etc
for which the usual details requested on the Technical Support online form are not enough you should generate a log
file and attach it to the problem report. In case of a crash you should also attach the crash report file generated by your
operating system. For generating a logging file you need to create a text file called log4j.properties in the install
folder with the following content:
log4j.rootCategory= debug, R2

log4j.appender.R2=org.apache.log4j.RollingFileAppender
log4j.appender.R2.File=logging.log
log4j.appender.R2.MaxFileSize=12000KB
log4j.appender.R2.MaxBackupIndex=20
Oxygen XML Author | Common Problems | 391

log4j.appender.R2.layout=org.apache.log4j.PatternLayout
log4j.appender.R2.layout.ConversionPattern=%r %p [ %t ] %c - %m%n
Restart the application, reproduce the error and close the application. The log file is called logging.log and is located
in the install folder.

h19267 WP Idc Storage Reqs Digital Enterprise
No ratings yet
h19267 WP Idc Storage Reqs Digital Enterprise
17 pages
Schem SPI Administration Module PDF
No ratings yet
Schem SPI Administration Module PDF
431 pages
Schem SPI Administration Module PDF
No ratings yet
Schem SPI Administration Module PDF
431 pages
Acer Aspire v3-571 v3-571g ServiceManual
No ratings yet
Acer Aspire v3-571 v3-571g ServiceManual
233 pages
AEM6 New Features
No ratings yet
AEM6 New Features
3 pages
TeamForge 620 User Guide
No ratings yet
TeamForge 620 User Guide
336 pages
Vim For Humans
No ratings yet
Vim For Humans
49 pages
Ionic Framework
No ratings yet
Ionic Framework
6 pages
Android Fragments PDF
No ratings yet
Android Fragments PDF
9 pages
Easy Clone Copy of Oracle Database
No ratings yet
Easy Clone Copy of Oracle Database
5 pages
Ecto
No ratings yet
Ecto
63 pages
Git and Github Slides
No ratings yet
Git and Github Slides
30 pages
What Is Devops
No ratings yet
What Is Devops
3 pages
Customizing PDF Output
No ratings yet
Customizing PDF Output
23 pages
Use Case Examples - JDP
No ratings yet
Use Case Examples - JDP
2 pages
Application Development Using Heroku: Prepared By: Rupesh Sharma (1505053)
No ratings yet
Application Development Using Heroku: Prepared By: Rupesh Sharma (1505053)
12 pages
Ansible Basics PDF
No ratings yet
Ansible Basics PDF
15 pages
Microsoft SQL Server Database Command
No ratings yet
Microsoft SQL Server Database Command
5 pages
5 Steps To DevOps Success
No ratings yet
5 Steps To DevOps Success
32 pages
Enterprise Programming LAB Work Book
67% (3)
Enterprise Programming LAB Work Book
154 pages
Message Modeling With DFDL: IBM Integration Bus
No ratings yet
Message Modeling With DFDL: IBM Integration Bus
42 pages
WSO2 Identity Server 3.0: Prabath Siriwardena, Architect and Senior Manager
No ratings yet
WSO2 Identity Server 3.0: Prabath Siriwardena, Architect and Senior Manager
20 pages
Eclipse - Platform Plug-In Developer Guide
No ratings yet
Eclipse - Platform Plug-In Developer Guide
150 pages
Vertioning Number Rules
No ratings yet
Vertioning Number Rules
4 pages
Re Factoring Databases Evolutionary Database Design
No ratings yet
Re Factoring Databases Evolutionary Database Design
25 pages
Day Admin Usages
No ratings yet
Day Admin Usages
128 pages
Grid Monitoring With Nagios: Aries Hung, Joanna Huang, Felix Lee, Min Tsai Asgc WLCG T2 Asia Workshop TIFR, Dec 2, 2006
No ratings yet
Grid Monitoring With Nagios: Aries Hung, Joanna Huang, Felix Lee, Min Tsai Asgc WLCG T2 Asia Workshop TIFR, Dec 2, 2006
30 pages
Nagios 3
0% (1)
Nagios 3
11 pages
Download Quick Start Guide to Large Language Models Second Edition Sinan Ozdemir ebook All Chapters PDF
100% (6)
Download Quick Start Guide to Large Language Models Second Edition Sinan Ozdemir ebook All Chapters PDF
81 pages
Basic Use Cases
No ratings yet
Basic Use Cases
22 pages
Hands-On Azure Pipelines: Understanding Continuous Integration and Deployment in Azure Devops 1St Edition Chaminda Chandrasekara
100% (3)
Hands-On Azure Pipelines: Understanding Continuous Integration and Deployment in Azure Devops 1St Edition Chaminda Chandrasekara
62 pages
AWS DynamoDB Notes
No ratings yet
AWS DynamoDB Notes
2 pages
Reactphp For Beginners Sample
No ratings yet
Reactphp For Beginners Sample
15 pages
DITA Book PDF
100% (1)
DITA Book PDF
26 pages
Jquery JSON Interview Questions With Answers
100% (1)
Jquery JSON Interview Questions With Answers
13 pages
Css or Xsl-Fo: Which Should I Use For Producing Print Publications?
No ratings yet
Css or Xsl-Fo: Which Should I Use For Producing Print Publications?
56 pages
Learning NHibernate 4 - Sample Chapter
0% (1)
Learning NHibernate 4 - Sample Chapter
21 pages
Application Deployment in Nud
No ratings yet
Application Deployment in Nud
31 pages
Docker Container Sections
No ratings yet
Docker Container Sections
15 pages
Aks Codes
No ratings yet
Aks Codes
53 pages
Overview of Software Engineering: VIT Chennai
No ratings yet
Overview of Software Engineering: VIT Chennai
100 pages
The Node - Js Developer Roadmap For 2021
No ratings yet
The Node - Js Developer Roadmap For 2021
6 pages
SQL Server 2012 Transact-SQL DML Reference
No ratings yet
SQL Server 2012 Transact-SQL DML Reference
266 pages
Web Services With IntelliJ IDEA
No ratings yet
Web Services With IntelliJ IDEA
22 pages
REST and AJAX Reconciled
100% (1)
REST and AJAX Reconciled
48 pages
Use Case Template
No ratings yet
Use Case Template
6 pages
Advanced Git
No ratings yet
Advanced Git
86 pages
Git - Github
No ratings yet
Git - Github
29 pages
Adaptto2018 JUnit 5 and Sling AEM Mocks Stefan Seifert PDF
No ratings yet
Adaptto2018 JUnit 5 and Sling AEM Mocks Stefan Seifert PDF
32 pages
Eclipse Java Tutorial: 1. Download and Install Java
No ratings yet
Eclipse Java Tutorial: 1. Download and Install Java
4 pages
WebSphere Application Server Step by Step
No ratings yet
WebSphere Application Server Step by Step
23 pages
003 Azure Intro Management and Governance
No ratings yet
003 Azure Intro Management and Governance
36 pages
DevOps Glossary - Razorops
No ratings yet
DevOps Glossary - Razorops
17 pages
Albertsons SQL Basic
No ratings yet
Albertsons SQL Basic
36 pages
Part I: Basics: Chapter 1. Xquery: A Guided Tour
No ratings yet
Part I: Basics: Chapter 1. Xquery: A Guided Tour
61 pages
Unix / Linux FAQ: with Tips to Face Interviews
From Everand
Unix / Linux FAQ: with Tips to Face Interviews
Prof. N.B. Venkateswarlu
No ratings yet
WebSphere Application Server 7.0 Administration Guide
From Everand
WebSphere Application Server 7.0 Administration Guide
Steve Robinson
No ratings yet
Oracle VM Manager 2.1.2
From Everand
Oracle VM Manager 2.1.2
Tarry Singh
No ratings yet
Visual Studio 2013 Cookbook
From Everand
Visual Studio 2013 Cookbook
Richard Banks
No ratings yet
Eclipse Plug-in Development: Beginner's Guide - Second Edition
From Everand
Eclipse Plug-in Development: Beginner's Guide - Second Edition
Dr Alex Blewitt
No ratings yet
MySQL 5.1 Plugin Development
From Everand
MySQL 5.1 Plugin Development
Andrew Hutchings
No ratings yet
GitLab Guidebook: From Basics to Expert Proficiency
From Everand
GitLab Guidebook: From Basics to Expert Proficiency
William Smith
No ratings yet
Alfresco 3 Cookbook
From Everand
Alfresco 3 Cookbook
Snig Bhaumik
No ratings yet
Albury pdf-9 11 2019
No ratings yet
Albury pdf-9 11 2019
990 pages
Oxygen-Xml Tutorial
No ratings yet
Oxygen-Xml Tutorial
8 pages
தமிழ் குழந்தை பெயர்கள்
No ratings yet
தமிழ் குழந்தை பெயர்கள்
15 pages
Go To Bills' - Memberships The Institution of Engineers, Singapore
No ratings yet
Go To Bills' - Memberships The Institution of Engineers, Singapore
8 pages
Ambarella_CV5_Product_Brief
No ratings yet
Ambarella_CV5_Product_Brief
2 pages
SIMATIC IPC MD-57A Technical Slides
No ratings yet
SIMATIC IPC MD-57A Technical Slides
7 pages
Chapter 2-Intro To Mobile Computing
No ratings yet
Chapter 2-Intro To Mobile Computing
113 pages
DMS USB 500X 1 - User - Manual
No ratings yet
DMS USB 500X 1 - User - Manual
24 pages
Example 1.1: Map With A Single Layer: Map /ms4w/apps/tutorial/htdocs/example1-1.map&layer States&mode Map
No ratings yet
Example 1.1: Map With A Single Layer: Map /ms4w/apps/tutorial/htdocs/example1-1.map&layer States&mode Map
27 pages
2011 E 0141 Upgrading Software For V2.1 B
No ratings yet
2011 E 0141 Upgrading Software For V2.1 B
195 pages
Flex Beat - User Guide - v1.1
No ratings yet
Flex Beat - User Guide - v1.1
8 pages
SprayView-KMLtoAreaFileConversion
No ratings yet
SprayView-KMLtoAreaFileConversion
43 pages
Mes p7 - Module5
No ratings yet
Mes p7 - Module5
19 pages
Motherboard
No ratings yet
Motherboard
63 pages
FPS Creator Manual
No ratings yet
FPS Creator Manual
58 pages
Project Report Format (Mca-Ds)
No ratings yet
Project Report Format (Mca-Ds)
13 pages
Traditional Food Recipe App
No ratings yet
Traditional Food Recipe App
30 pages
ServiceNow Admin Cert Flashcards - Quizlet
100% (1)
ServiceNow Admin Cert Flashcards - Quizlet
20 pages
SENG210 Mid Term Research Based Assignment - 13971
No ratings yet
SENG210 Mid Term Research Based Assignment - 13971
21 pages
David Dabner, Sandra Stewart, Abbie Vickress (2020) - CAP - 5
0% (1)
David Dabner, Sandra Stewart, Abbie Vickress (2020) - CAP - 5
17 pages
Whitepaper EOS SAT 1
No ratings yet
Whitepaper EOS SAT 1
8 pages
Computer Organisation-Unit - III
No ratings yet
Computer Organisation-Unit - III
17 pages
3D Imaging Services Statement of Work (SOW) : The Great Lakes Region 5 Standard Template For
No ratings yet
3D Imaging Services Statement of Work (SOW) : The Great Lakes Region 5 Standard Template For
19 pages
GE LITE Generations of COmputers
No ratings yet
GE LITE Generations of COmputers
3 pages
CH18 COA9e
No ratings yet
CH18 COA9e
28 pages
XII Computer Project by Rohit
No ratings yet
XII Computer Project by Rohit
25 pages
VTESTstudio ConceptManual en
67% (3)
VTESTstudio ConceptManual en
48 pages
80es Chat Read Me
No ratings yet
80es Chat Read Me
4 pages
RSL10 Bootloader Guide
No ratings yet
RSL10 Bootloader Guide
11 pages
Highlights of Netbeans Ide 7.0 Keyboard Shortcuts & Code Templates
No ratings yet
Highlights of Netbeans Ide 7.0 Keyboard Shortcuts & Code Templates
2 pages
It201-Human Computer Interaction - Calo
No ratings yet
It201-Human Computer Interaction - Calo
14 pages
Mocha HitFilm Plugin Release Notes
No ratings yet
Mocha HitFilm Plugin Release Notes
27 pages