Wednesday, November 25, 2015

Sharing Application Settings

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
There are varios ways in the Oxygen standalone version through which a team of writers can share and use a set of common settings. Below I will try to list each of these possibilities along with useful links:
  • Save the settings at project level and have all users use the same project "projectName.xpr" file in the Project view when editing. Most of the Oxygen Preference pages have a switch radio button which allows you to pass the settings to Project level and save them in the current project configuration file opened in the Project view. If you commit that Project configuration file to a version control system like GIT or SVN, all writers can open and use that project when working with the repository content.

    For example, when we work on the Oxygen User's Manual using our common GitHub repository, we all open in the Project view the "userguide.xpr" project which comes with various fixed options (eg: enabling automatic spell checking):

    You can find out more details about sharing projects here:

  • Create and then provide a default options XML document to others. When placed in a specific place in the Oxygen installation or referenced via a specific property in the application startup script, this default options XML document will be used by the application to provide default values for certain settings. You can find out more about how default options work here:

  • Have others manually import an options XML document which you exported from Oxygen:
  • An Oxygen plugin could use our Java API to impose fixed options when the application starts using the API method: PluginWorkspaceProvider.getPluginWorkspace().setGlobalObjectProperty(key, value). In our Maven-based SDK we have a sample plugin called ImposeOptions which imposes a fixed set of options when the application starts.

If you want to share document type configurations (for editing certain XML vocabulary) you can find more details in this older blog post:

Monday, November 16, 2015

Possibilities to obtain PDF from DITA

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Lately while attending Tekom 2015 and DITA OT Day 2015 I happened to come across two more DITA to PDF solutions that I did not know about so I tried to compile below a list of all DITA to PDF possibilities that I know of, along with some details:
  • Legacy DITA to PDF editing solution. It is no longer distribute with DITA OT 2.x and is probably not compatible anymore with it.
  • Default DITA to PDF solution embedded in the DITA Open Toolkit distribution. Besides Apache FOP you can also use RenderX XEP or Antenna House for publishing. It's customization can be done either via a plugin or via a PDF customization folder:
  • DITA to PDF using CSS. This open source DITA OT plugin was developed by Oxygen as an alternative to the default PDF publishing. It allows styling the DITA content using CSS and publishing to PDF using either Prince XML or Antenna House.
  • Antenna House DITA OT plugin for producing PDF from DITA using Antenna House. There is also a DITA specialization plugin which allows you to set specific formatting attributes directly to DITA elements.
  • The TopLeaf XML Publisher commercial product allows you to produce various outputs like PDF and EPUB from XML content. The application also has a visual PDF layout formatter, it comes also with a DITA OT plugin and has installation instructions for Oxygen:
  • Miramo, again a commercial solution which recently started developing support for DITA using a DITA OT plugin. Possibly user based DITA to PDF publishing will be free and server based production will require buying a license. Like TopLeaf, it also has a visual PDF layout designer.
  • Adobe FrameMaker can also publish to PDF using its own solution.

Now the question would be, why there are so many solutions available? In my opinion all these solutions are available because the default DITA to PDF output still requires quite a lot of XSLT skills in order to customize. Jarno Elovirta's PDF plugin generator covers some of the mainstream possible customizations but not all.

What do you think?

Friday, October 30, 2015

Adding CALS-table related functionality to your custom Oxygen framework

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Oxygen comes with full support for CALS tables in DITA and Docbook documents, meaning that you can easily make selections, resize columns, and invoke special actions like insert or delete rows and columns, join, or split cells. You can also easily customize tables properties such as alignments, separators, and table borders. But what if you are editing documents from other vocabularies, containing tables with CALS structure? What you can do to obtain the same table editing features?

Let's suppose that you already created an Oxygen framework for your documents vocabulary (if you need further information about frameworks, see What we want to obtain next is to extract all the CALS tables related support from Docbook framework and add it to your custom framework. Why Docbook and not DITA as reference? Because the DITA customization is based on the "class" attribute checking while the Docbook one is more general (element-name oriented).

  1. Table rendering
    1. copy [oXygen_install_dir]\frameworks\docbook\css\cals_table.css in your framework css directory
    2. in the Document Type edit dialog, Author tab, CSS sub-tab, add the ${framework}/css/cals_table.css entry to the list of the CSSs

    In this way the table will be rendered properly in Author mode and the following features will be available:

    • select cells (CTRL+click), rows (click before the row), columns (click on top of the row), tables (click in the left-up corner of the table)
    • resize table column
  2. Create table actions

    Here are the table-related actions implemented in Docbook that you can implement also in you framework:

    • Expand colspecs
    • Insert/Delete Rows
    • Insert/Delete Columns
    • Table Properties
    • Join cells
    • Split cell
    1. Copy [oXygen_installation_dir]\frameworks\docbook\docbook.jar in your framework directory (this jar contains all the table operations classes needed to create table actions). In Document type edit dialog go to Classpath tab and add the docbook.jar from your framework directory to the list of paths. In this way you have access to all table operations from your framework.
    2. For every table action you have to define a corresponding action in the Document type configuration dialog. Here are the details: You can look at the corresponding Docbook action to see the properties (id, name, icons, the conditions that enables it, the specific operation for CALS tables).
      Once you created these actions you can add them to the UI.
  3. Add table actions to menu, toolbar and contextual menu
    1. To add an action to the menu go to Document Type configuration dialog, Author tab, Menu sub-tab, select the action from Available actions section and add it to the Current action section.
    2. To add an action to the contextual menu go to Document Type configuration dialog, Author tab, Contextual menu sub-tab, select the action from Available actions section and add it to the Current action section.
    3. To add an action to the toolbar go to Document Type configuration dialog, Author tab, Toolbar sub-tab, select the action from Available actions section and add it to the Current action section.
If all goes well, your custom framework which uses the standard CALS table naming mechanism will properly handle tables, both for display and for table-related operations.

Wednesday, October 28, 2015

How Special Paste works in Oxygen

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

If you've worked with one of the XML vocabularies for which Oxygen has out of the box support like DITA, Docbook, TEI, XHTML you've probably already used the support Oxygen has for converting content pasted in the application from external applications like Microsoft Word, Excel or from any web browser. This is a very useful feature for converting various types of content to XML because it preserves and converts styling, links, lists, tables and image references.

The feature relies on the fact that when copying content in the applications mentioned above, they set in the clipboard the HTML equivalent of the copied content. So all Oxygen has to do is clean up that HTML, make it wellformed XHTML and apply conversion XSLT stylesheets over it.

This support is not hardcoded and anybody who is developing an Oxygen framework customization for a certain XML vocabulary can provide conversion stylesheets for external pasted HTML content.

I will describe how this works for the DITA framework and you can do the same for yours. You can also use this information to modify the way in which smart paste works for the bundled framework configurations.
  1. In the Preferences->Document Type Association page you can choose to edit (or extend) the DITA document type association.
  2. In the Extensions tab the Extensions bundle implementation is set to DITAExtensionsBundle which resides in the DITA Java extensions archive dita.jar.
  3. The DITAExtensionsBundle is an extension of the ExtensionsBundle API and it provides its own external object extension handler:
       * @see ro.sync.ecss.extensions.api.ExtensionsBundle#createExternalObjectInsertionHandler()
      public AuthorExternalObjectInsertionHandler createExternalObjectInsertionHandler() {
        return new DITAExternalObjectInsertionHandler();
  4. The DITAExternalObjectInsertionHandler extends the base class AuthorExternalObjectInsertionHandler and provides a reference to its specific conversion stylesheet:
       * @see ro.sync.ecss.extensions.api.AuthorExternalObjectInsertionHandler#getImporterStylesheetFileName(ro.sync.ecss.extensions.api.AuthorAccess)
      protected String getImporterStylesheetFileName(AuthorAccess authorAccess) {
        return "xhtml2ditaDriver.xsl";
    Note: The Extensions tab also allows you to specify the external object insertion handler as a separate extension.
  5. In the same Document Type edit dialog in the Classpath tab you will see that there is a reference to a framework-specific resources folder like:${framework}/resources/
  6. If you look on disk in the DITA framework resources folder: "OXYGEN_INSTALL_DIR\frameworks\dita\resources" you will find the xhtml2ditaDriver.xsl stylesheet there. The stylesheet imports various other stylesheets which you could probably fully reuse and which apply various cleanups on HTML produced with MS Word. It also handles the conversion between the pasted HTML content and DITA so it is a good starting point, you can copy the entire set of XSLT stylesheets to your framework and use those as a starting point.

Friday, October 23, 2015

DITA-related improvements and goodies in Oxygen 17.1

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

I'm happy to announce this autumn the release of Oxygen 17.1. We've been quite buzy in the last months working on it and we hope you'll enjoy it in your daily XML-related activities.

Oxygen 17.1 comes with official support for the latest operating systems, Windows 10 and Mac OSX OS X El Capitan (10.11).

It also comes with a new user interface color theme called "Light" that makes the entire application interface look crisp and clean. Besides this, you now have the support to define custom color themes and share them with your team.

As always we also have lots of DITA-related improvements:
  1. The dialogs for inserting conkeyrefs, conrefs and keyrefs to metadata have all been merged in one intuitive to use toolbar action called "Reuse content".
  2. The dialog used to insert or to edit properties for a topic reference now also allows you to:
    1. Set profiling attributes.
    2. Define metadata content.
    3. Set any other valid attribute on the topic reference.
  3. Experimental support for DITA 1.3. You can enable DITA 1.3 support (using the latest DITA Open Toolkit 2.1.2 bundled with the application) from the "Preferences->DITA" page. This support includes support for editing and validation, scoped keys and branch filtering.
    1. Scoped Keys Support. You can establish key scopes and insert references to keys inside or outside key scopes. oXygen will also takes key scopes into account when it validates and checks for completeness, resolves key and content key references, and publishes.
    2. Branch Filtering Support. The DITA 1.3 branch filtering mechanism makes it possible to reuse the content of topics multiple times within the same map, each time using different filters.

    You can find out more about DITA 1.3 support from our user's manual:

    or by watching this video demo:

  4. The oXygen WebHelp system was also improved to enhance your published output. Google Search, Google Analytics, and some popular social media widgets can now be integrated into your WebHelp system and search features are now available in offline mode.
  5. Oxygen 17.1 comes bundled with an experimental new plugin developed by Jarno Elovirta for generating MS Word output (OOXML) from DITA content.
  6. Once you decide in the "Preferences->DITA" page to use the bundled DITA Open Toolkit 2.1.2, you will also enable the ability to create Lightweight DITA topics and maps so you can experiment with this exciting new standard in the making:

Monday, September 07, 2015

A Short Story of Reuse

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Give the smartest human in the world a piece of wood and ask him/her to make paper. Give him/her no prior tools and it will take years to come up with a decent process which would result in some brown almost usable thick piece of paper.

This blog post is about reuse, not necessarily reuse of tools and materials, but reuse of knowledge. Humanity has evolved not because each generation is smarter than the last one but because we learned to reuse and pass knowledge to larger and larger audiences and from one generation to another.

Almost all tools that we use today are made up of quite a complex set of components which interact with each other. There is no one person in a car assembly factory who still knows all the pieces and how they come together.

Although using the tool is easier than interacting with all components which make it up, you still need knowledge to operate it and in this day and age having enough people to teach how a certain tool can be used is no longer an option. You need to pass knowledge in other forms, on paper or in some kind of digital form. So I would define technical communication as a means of passing knowledge about using tools to a larger audience.

Reuse in technical communication can be structured on many levels:
  • Reuse written content by publishing it to more than one format (PDF, HTML, EPUB, MS Word).

    It turns out that XML is perfect for publishing content in more than one format. XML is not designed to be consumed directly by end users and its benefit lies directly in this. Your XML content should contain all the data necessary for obtaining all the output formats. So if you are using XML in your technical content, no matter what standard or custom vocabulary, you can safely check the first and most important level of reuse.

  • Create larger publications from existing ones.

    Either using an XML standard like XInclude or using standards with their own diverse and powerful methods of reuse like DITA, or by performing custom techniques you can merge XML content in larger publications.

  • Reuse content written for a certain tool to document the functionality and behavior of a very similar tool.

    In most mature XML standards like DITA and Docbook there is this implemented concept of profiling which allows you to dynamically filter at publishing time content marked with certain attributes from your original XML project. In this way from the same XML content you can publish documentation for multiple similar tools.

  • Reuse smaller pieces of common content in more than one publication.

    Again, using XML standards like XInclude or DITA specific standards like content references you can create and maintain small libraries of reusable XML content, then reuse these components across various publications.

  • Reuse images and other binary resources in multiple publications.

    Because XML content does not embed binary resources, these resources are stored separately and thus they can be reused in multiple places.

So these are what I consider to be the main selling points for using XML in technical documentation. As usual any feedback is welcomed.

Wednesday, September 02, 2015

DITA 1.3 Branch Filtering - Next Generation of Reuse

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Thanks to the hard working OASIS DITA TC Group the DITA 1.3 standard is quite close to being released. Oxygen 17.1 which will be released probably in September this year will have experimental DITA 1.3 support. This will include publishing using a custom build of the latest DITA Open Toolkit 2.x engine in which the main developer Jarno Elovirta has already added incipient support for key scopes and branch filtering.

In this blog post I'm going to give you a small example of how branch filtering can benefit two cases of reuse which could not be done previously. You can read more about branch filtering in the DITA 1.3 specs.

Case 1 - Combine Two Profiles in the Same Publication

Let's say you have a DITA Project about preparing and cooking vegetables. And your DITA Map looks like this:
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
 <title>Cooking vegetables</title>
 <topicref href="cleaningTableArea.dita" audience="novice"/>
 <topicref href="preparingVegetables.dita"/>
 <topicref href="addingExtraFlavor.dita" audience="expert"/>
You have some content common both for expert and novice users but you also have content which is specific for a target audience. You do not need to teach expert chefs how to clean the table and you do not want to teach novice cooks about enhanced flavoring techniques.
All is fine until at some point you decide to produce a publication which contains merged inside both the novice and the expert map contents. And here's where branch filtering comes for help. You can create a main DITA Map which reuses your current DITA Map with two profiling contexts:
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
 <title>Cooking Vegetables.</title>
 <topichead navtitle="Cooking for Beginners" keyscope="novice">
  <topicref href="vegetables.ditamap" format="ditamap">
   <ditavalref href="novice.ditaval"/>
 <topichead navtitle="Cooking for Experts" keyscope="expert">
  <topicref href="vegetables.ditamap" format="ditamap">
   <ditavalref href="expert.ditaval"/>

Case 2 - Reusing Common Topics with Different Product Names

Let's say you have a simple DITA task in which you have described how a certain task can be performed for a certain product. In our case, the task describes peeling potatoes:

The task works and at some point in your Vegetables Soup publication you realise you need to write a similar task about peeling cucumbers. The task is exactly the same, except the product name. So naturally you want to reuse the existing written task. For this we re-write the task so that instead of of the product potatoes it contains two consecutive profiled product names:
Peeling <ph product="potatoes">potatoes</ph><ph product="cucumbers">cucumbers</ph>
and include the task in the main DITA Map in two places with different ditaval filters applied:
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
 <title>Peeling Vegetables.</title>
 <topichead navtitle="Potatoes">
  <topicref href="peeling.dita">
   <ditavalref href="potatoes.ditaval"/>
 <topichead navtitle="Cucumbers">
  <topicref href="peeling.dita">
   <ditavalref href="cucumbers.ditaval"/>

This kind of usage will produce in the HTML output folder two topic HTML files from the single peeling.dita, one for each filter context.

The DITA samples for this post can be downloaded from

As usual any feedback is welcomed.

If you would like to beta test Oxygen XML Editor 17.1 with experimental DITA 1.3 support please contact us: