Friday, December 19, 2014

Oxygen XML Editor 17's Christmas List

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

Ho, ho, ho. Merry Christmas boys and girls!

I heard you've been good little children, spreading the XML wisdom throughout the year and revealing your inner geeky nature. Santa Oxygen has read your wish lists, assigning priorities and is filling his big bag of toys for the version 17 release. As Santa is quite old and the toys need to be checked and rectified for defects, Oxygen 17 will arrive in Spring next year but if you want to test the latest toys, just drop us an email and we'll make a beta kit available for you.

Just to help you get into the Christmas spirit, here are some of the goodies we've worked on so far:
  1. The DITA Preferences page. Because we love DITA so much we decided to create a brand new DITA page in the Oxygen Preferences dialog. The most important setting in the new page allows you to change the default DITA OT directory used for validation and transformation.
  2. DITA Unreferenced Resources Finder. Use this handy new tool to find all resources (images, DITA topics) which are not referenced from your DITA Maps and topics. We've been using this check internally for years to delete unnecessary resources and not we are making it available for you.
  3. Publish DITA content to PDF using CSS and the Prince XML commercial processor. The first stable version of the new DITA Open Toolkit plugin we've also made public on GitHub will allow you to style PDF content by making CSS changes and avoid a lot of XSLT customizations.
  4. Fully re-designed DITA visual editing experience. Our head elf has been revising every element in the DITA specification and completely redesigned the CSSs used to edit DITA based on minimalism and closeness to the published XHTML and PDF outputs.
  5. CSS visual layouts for DITA editing. Besides the minimalist editing style you will be able to use the Styles drop-down to choose from a number of fun editing layouts. I'm not going to ruin the surprise, as an inside info, one of the new editing styles will be called Roboto.
  6. WebHelp output improvements. The WebHelp output obtained from DITA and Docbook content will have the search box which placed in the upper right corner for easier access. It will also feature navigation based on context IDs in order to be more easily integrated in an application contextual help system. And yes, it will also load faster.
  7. Predefined Color Themes. Speaking of enhanced visual appearance, you will have an array of predefined color schemes to choose in order to completely change the visual appearance of the application, starting with Graphite and ending with the exotic Sahara.
  8. Locking for shared files. Despite our recommendations of using version control systems or commercial CMSs, some of you are still naughty enough to collaborate on a project using shared network drives. We added a special setting (which must be enabled for everybody working on a shared network drive) to avoid overwriting other people's work when editing.
  9. Saxon 9.6 XSLT Processor. Oxygen 17 will be shipped with the latest Saxon 9.6 XSLT processor. So if you're into XSLT, XPath and XQuery 3.0, this will be a good component update for you.
The bag is almost full now but if time allows we might also have the time to look into adding these new toys as well:
  1. Better support for working with multiple selected cells in tables. Like support for multiple join and split cells, support for copy pasting of multiple cells.
  2. Auto correct support. Even Santa would find those useful to avoid teh most common editing mstakes when working on this Christmas list. Both in the Text and Author pages? I would like to have both. How about you?
  3. Toolbar Customization support. We finally want to allow you to remove the access and create the perfect toolbar layout, with only the buttons you need and use daily.
  4. Apply Batch Changes on a set of resources. A powerful engine based on XQuery will allow you to chose various change scripts to apply on a set of resources. For example remove certain attributes, add new elements and attributes, convert elements and so on. And if you are a power user, you will be able to edit your change scripts directly in XQuery.
  5. Redesigned DITA Insert Image actions. The newly redesigned Insert Image dialog should allow you to set the most common used attributes on an image like alignment, scaling, even to add directly a figure.
  6. Proper support for high DPI resolutions both on Windows and Mac OSX.

Well, that's about it. Santa's got to go and re-watch his favorite DITA OT Day Presentations then prepare for the upcoming XML Prague Oxygen Users Meetup Conference which is still opened for registration. The Oxygen office Christmas Party takes place tonight and I heard there will be lots of food and good spirits.

Happy holidays everyone. Ho, ho ho!

Wednesday, November 26, 2014

Collaboration for Documenting a Software Product using DITA

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

Besides working on an XML Editor with lots of DITA editing functionality we also use DITA internally for editing the Oxygen User's Guide.

In this article I will try to give you an overview of our entire workflow as evidence that DITA does work and that it can be used and implemented without expensive solutions.

First here's an overview of our needs:
  • Offline Help which is available inside the installed application. Oxygen is a multi-platform application so we need to generate both HTML Help (CHM) for Windows and JavaHelp for the Mac OSX and Linux installations. Also for the Oxygen Eclipse Plugin we need to generate Eclipse Help.
  • Online Help which is available as WebHelp with Feedback on our web site and allows users to add comments to each topic. Those comments can then be used by us to rephrase and improve our documentation.
  • PDF containing the entire contents of the user's manual. Nowadays most our users use the online WebHelp because it can be used much easier for finding certain topics so in our case at least the PDF output is not popular anymore along users.

We have two main distributions (Standalone and Eclipse plugin) and three main products (Editor, Developer and Author). So we need to produce about six (6) different publications from the same DITA content depending on the shipped product.

And here's an overview of the tools we use:

Oxygen XML Editor

This may not come as a surprise but we use our own product to edit DITA content, partly because it's ours and partly because it is a very good tool. During the last couple of years this has been a good opportunity to improve our product based on our own feedback (feedback coming from our technical writers).

Oxygen is used in two ways:
  1. By the technical writers to write DITA content.
  2. By the reviewers to review documented issues by adding comments, making changes with change tracking enabled.

DITA Open Toolkit + WebHelp plugin

We use the DITA Open Toolkit to publish DITA content to the outputs we are interested in. The WebHelp and WebHelp with Feedback outputs are our own additions to the DITA Open Toolkit. But we do not use any special customizations for the other outputs.

Jenkins integration server

We have an automated script which builds all the user manual outputs every night.

Automated DITA Content Validation

There is a script which runs on a test server and does three types of checks on the DITA content:
  1. Validate and check for completeness, check for broken links, images, broken web links and so on.
  2. Check and report topics, resources and images which are no longer referenced anywhere.
  3. Spell check the entire DITA content.

Git as a version control system

For a long time we used Subversion for version control. Recently we moved our DITA content to a private GitHub repository and we also made a public GitHub repository containing a copy of our user manual's DITA content:https://github.com/oxygenxml/userguide. We use the SourceTree application to work with Git and we are quite happy with it.

Atlassian Jira for workflow

We use Atlassian Jira to provide a workflow both for the issues which are related directly to our software product and for the issues which are related exclusively with our user's manual. The JIRA is integrated with both our SVN and GIT repositories so it shows for a certain issue all resources which have been modified to fix it.

More details about how with work with DITA can be found in these slides I presented at DITA Europe 2014:http://www.oxygenxml.com/forum/files/usingDitaForOxygenUsersManual.odp.

Video demonstration showing how collaboration on a technical publication with Subversion can be achieved: http://www.oxygenxml.com/demo/Collaborative_Authoring_Using_Subversion.html.

Saturday, November 15, 2014

Alternate sales pitch

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

This year was my first participation at Tekom Europe, we had lots of discussions with interested potential customers and one of them asked me to give him my sales pitch of why he should buy my product instead of a competitor's one. I'm not a salesman. I've always wanted to work for a product which is so good that it sells itself. And I do.

So here's my alternate sales pitch:

Ideally whenever you choose between any two software products which will be used daily by people in your company you should make a pilot test project with two user groups made of the people who will be actually using the product after it is bought. Ask them to use the product for a month performing tasks similar to what they will do after the purchase. Ask the two user groups at some point to switch products and see how that goes. And in the end let most of the decision to be made by these people who will actually be using the product in their work.

Working for an extended period of time with the product will also show how stable the product is, if it crashes often, if it has small annoying bugs and if it sometimes behaves unpredictable.

We are a productivity application and in my opinion the goals of such a type of application would be these ones:
  • shorten the amount of time users spend doing their daily tasks
  • allow users to fulfill their tasks with the least amount of frustration, let them concentrate on what should be done and not on the tool which is used in that process, be intuitive and easy to use

Look what types of operating systems are used in your company, can the tool run on all of them?

Read the product's End User License Agreement, I know it's a boring task but you might find some gems in there. For example does the user based license allow the user to install the product on multiple computers as long as he/she is the only one using it?

During the trial period ask questions on the technical support email address.
  • Are they responsive?
  • Are they helpful?
  • Do they know what they are talking about?
  • Do they go that extra mile to help you?
  • Is there a public forum available? Is it well kept, does it have a lot of activity?
  • Is there an user's list available? Register on it, see how questions are answered.

Find out how long the company which makes the product has been in business. Google the product online, read blogs and look for opinions on it.

In the end it will come down to two things: quality and price. But you need to make sure you are listening to the people who will actually use the application.

Tuesday, November 04, 2014

Public hosted Oxygen Plugin and Framework Projects

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

There are a couple of interesting Oxygen plugins and frameworks which are developed as separate public projects (and maintained either by us or by our users). I will try to compile a list below:

  1. Besides being bundled with Oxygen the TEI framework is also available as a project partly maintained by the TEI community: https://code.google.com/p/oxygen-tei/
  2. HisTEI: An Oxygen framework for historical documents encoded in TEI.

    More details: https://github.com/odaata/HisTEI, http://www.oxygenxml.com/pipermail/oxygen-sdk/2014-November/000182.html

  3. Ediarium is an extension package for TEI editing within Oxygen.

    More details:http://www.bbaw.de/en/telota/software/ediarum, https://github.com/telota/ediarum

  4. TEI Facsimile Plugin offers a side view in which users can load an image and see the marked areas (all the zone elements from a TEI document), draw new areas over the image and copy them into the editor:https://github.com/oxygenxml/TEI-Facsimile-Plugin.
  5. Framework which adds JATS/NLM support for Oxygen developed by Wendell Piez: https://github.com/wendellpiez/oXygenJATSframework
  6. Automatic builder for Oxygen frameworks which allows user to describe framework's behaviour by using only XQuery, HTML, and CSS, and automatically generate the framework archive ready to be deployed (developed by Claudius Teodorescu):http://kuberam.ro/oxygen-addon-builder/
  7. LanguageTool plugin for Oxygen: https://github.com/danielnaber/oxygen-languagetool-plugin
  8. Framework which adds Daisy support in Oxygen: https://github.com/oxygenxml/Daisy
  9. Framework which adds STRATML support to Oxygen: https://github.com/oxygenxml/stratml
  10. S1000D Framework which adds some limited support to edit S1000D documents in the Author visual editing mode:https://github.com/oxygenxml/S1000D.

If anyone else wants to add something else to the list, just drop us an email.

All resources, Frameworks and Plugins which we make publicly available to contributors can be found on the oxygenxml GitHub group:https://github.com/oxygenxml/.

Wednesday, September 10, 2014

Cool Stuff to Look for in future DITA publishing

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

First of all a big thank you to all you Oxygen XML users who have been from the very beginning the driving force behind many of the improvements we have added into the application.

In my opinion of all the people who try an application for the first time only a few of them will ever bother to write to the application's producers and give feedback about things which do not properly work. Most of them probably suffer in silence and maybe end up abandoning the application alltogether. So feedback received from people using a trial license of Oxygen and who still bother to report a problem instead of giving up is quite valuable and we are grateful for it.

We have many Oxygen DITA users and this leads to many requests to improve the DITA Open Toolkit publishing. Our policy so far has been to contribute these improvement suggestions back to the DITA Open Toolkit so that they benefit others as well. Also we should all be grateful to Jarno Elovirta, the main DITA OT contributor, guru and developer who makes all of this possible for all of us.

So here are some of the DITA publishing improvements I'm looking forward to see in the future:
  1. The Oxygen team is actively working on a DITA Open Toolkit plugin which will use CSS to render PDF output from DITA content. The plugin could be used with commercial rendering engines like Prince XML and Antenna House which support obtaining PDF from XML and CSS. Initially the plugin will provide support only for the Prince XML engine This would mean that most PDF customizations which are currently being done using XSLT could instead be done via CSS styling which is far easier for users who are not experienced XSLT developers. I will present the general architecture of the plugin on the DITA OT Day in Munich this year. And if it proves to be succesfull we are willing to make this plugin available as an open source project or part of a future DITA OT distribution. Oxygen 16.1 which will be released in a few weeks will have an experimental version of the plugin included with its bundled DITA Open Toolkit.
  2. DITA Open Toolkit 2.0 will probably generate HTML 5 compatible output by default.
  3. DITA Open Toolkit 2.0 will generate the Index page for PDF output even when using the Apache FOP processor. The changes are already incorporated in the DITA OT distribution which comes with Oxygen, you can also incorportate them quite easily in your DITA OT by modifying an XSLT stylesheet: https://github.com/dita-ot/dita-ot/pull/1587.
  4. Using the DITA Open Toolkit 2.0 you will also be able to pass profiling attributes and values from the DITA content to the generated HTML content: https://github.com/dita-ot/dita-ot/issues/1739. This means that instead of profiling the content before it is published, you will be able to profile it at publishing time by using Javascript to show/hide parts of the content depending on the user role for example.
  5. Besides lots of bug fixes Jarno Elovirta made lots of memory and processor optimizations which also will be included in the next DITA Open Toolkit 2.0 release.

I'm also looking forward for the support for the DITA 1.3 specification which will slowly begin to be implemented in future DITA Open Toolkit releases.

So what are your ideas for future DITA OT publishing enhancements?

Tuesday, August 05, 2014

The Oxygen SDK (Part 2: Frameworks)

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
This is the second part of a blog post I started some time ago:

There are two ways of customizing the application, by implementing a plugin or by implementing a framework:

A framework configuration provides validation, content completion and editing support for a certain XML vocabulary. 

If you are already using Oxygen for editing DITA, Docbook, XHTML or TEI documents you may notice that Oxygen knows how to validate these vocabularies and that it can propose content completion entries while you are editing. Also when you are editing in the Author visual editing mode you have lots of custom vocabulary-specific toolbar buttons which can be used to insert links, images, to manipulate tables and so on. This happens because each Oxygen installation comes with pre-bundled framework configurations for certain XML vocabularies that we consider to be more important for our users.

Knowing how to create and modify a framework/document type association configuration will benefit you in two ways:
  1. Create your own framework which adds editing support to Oxygen for certain specific XML vocabularies and then distribute it to your team.
  2. Customize an existing framework bundled with the installation (DITA, Docbook, etc) and change certain behaviors in it.
Our user manual contains a special step by step tutorial which explains how a new framework configuration (document type association) can be created and configured:
The Oxygen Preferences->Document Type Association page lists all detected frameworks (document type associations). Usually looking inside one of the pre-configured document type associations (eg: DITA) is a good place to start exploring what such a customization contains:
  1. Association rules - when one of these rules matches the opened XML document, Oxygen will associate it with the current document type association. The rules are pretty simple to compose, they refer to a certain root name, namespace, certain attributes set on the root and so on.
  2. Schema - specifies a grammar to be used to providing validation and content completion if the opened XML document does not refer directly to any particular gramar.
  3. Classpath - a list of JAR libraries which contain Java extensions for this specific framework.
  4. Author - contains all necessary support for editing the XML in the Author visual editing mode:
    • CSS - one or more CSS files to be used when rendering the XML. If you define alternate CSSs, you will be able to switch between them when editing. The user manual contains a list of supported CSS features and additional available extensions.
    • Actions - a list of actions specific for modifying the edited content. An action has a name, description, icons and shortcut key. It also has one or more activation contexts which depending on an XPath expression enable a certain operation be be executed. A fair amount of basic operations are already available but you can create your custom operations.
    • Menu, Contextual menu and Toolbar - you can easily mount defined actions to the main document type menu, to the contextual menu or to the special Author toolbar(s).
    • Content Completion - add defined actions to the content completion window (shown when ENTER is pressed in the Author editor mode) or remove existing entries from the content completion window. You can for example replace some of the insert suggestions given by the association grammar with your own custom actions.
  5. Templates - points to folders which contain new file templates for this particular framework. These new file templates will be shown in the New wizard dialog.
  6. Catalogs contains a list of XML catalogs which will be used to indirectly solve various references (like references to schemas or other XML documents).
  7. Transformation may contains a predefined list of transformation scenarios which are available when you want to publish your opened XML document to various output formats.
  8. Validation may contain a predefined list of validation scenarios which are used to add complex multi-stage validation (with multiple engines) for the XML documents matching the document type association.
  9. Extensions - contains implementations of the available Java extensions which are used to provide further functionality for editing in the Author visual editing mode. Here's what some of the extensions do:
    • AuthorExtensionStateListener - provides a way to be notified when the XML was opened in the Author editing mode. You can then add all kinds of listeners and react to edit events done by the user. For example add a modification listener, send the edited content to an external spell checker engine and then add highlights in the content on invalid constructs.
    • AuthorExternalObjectInsertionHandler - reacts to drag and drop and copy/paste events containing with HTML content or resources. In the case of DITA for example this handler is responsible of the automatic conversion of HTML pasted from the browser to DITA content.
    • SchemaManagerFilter - filter and modify the insertion items detected from the associated grammar when editing XML content. For example even if the schema proposes certain elements as valid insertions at the caret offset, you can filter out and restrict the suggestions given by the associated schema (grammar).
    • StylesFilter - take control over the rendering styles for each node by adding this layer of Java customization over the styles provided by the associated CSSs.
    • AuthorSchemaAwareEditingHandler - handle special editing cases and provide fallbacks which keep the document in a valid state. For example if the user starts typing text between two paragraphs, the handler can automatically create a new paragraph.
You can create automated tests for your frameworks:

and even debug their functionality:

Thursday, June 26, 2014

Webinar: New in oXygen XML Editor 16 - XSLT Quick Fixes

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
This webinar presents the XSLT Quick Fixes functionality in detail and then go through some of the other important new features in the new oXygen release including:

  • new XSLT refactoring actions
  • support for developing XSLT stylesheets for Saxon CE
  • XPath execution over multiple files
  • the new Ant editor
  • and more.