Tuesday, February 14, 2017

Customizing Oxygen XML Editor (Overview)

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

Let's assume you just bought Oxygen and want to customize it in order to better suit your team's workflow or to add support for your custom XML vocabulary. I will attempt to provide a set of use cases along with indications and useful links about what customization should be done in order to cover each use case:

Add support for editing a specific XML vocabulary

This kind of support usually should include:
  • New file templates.
  • Validate opened XML documents according to a custom schema.
  • Provide custom CSS to be used in the Author visual editing mode.
  • Provide custom toolbar, menu, and contextual menu actions to be used in the Author visual editing mode.
Such support is done using a document type/framework configuration: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

Customize the existing support for a specific XML vocabulary

Oxygen comes with pre-configured framework configurations for the most commonly used XML standards such as DITA, Docbook, TEI, or XHTML. You may want to customize the existing configuration for one of these vocabularies and share the customization with others. Such customizations may include: All of these customizations can be done by extending the existing framework configuration and then sharing the extension: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.

Provide custom settings

You may want to provide all members of the team with a fixed set of options: http://blog.oxygenxml.com/2015/11/sharing-application-settings.html.

Modify the application appearance or behavior using plugins

Oxygen plugins can be used to:
  • Contribute custom views and toolbars for the entire application.
  • Filter out existing views or toolbar actions.
  • Contribute a fixed set of options/settings to the application.
  • Register various listeners and be notified when a document is opened, closed, saved, and so on.
  • Use the existing API to make changes to the opened documents.
A more detailed overview of Oxygen plugins can be found here: http://blog.oxygenxml.com/2013/11/the-oxygen-sdk-part-1-plugins.html.

The most popular plugin extension is the Workspace Access plugin extension: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/concepts/workspace-access-plugin.html. This extension is notified when the application starts and can contribute custom views, custom main menu items, custom main toolbar actions, or add listeners for various document-related changes.

There is also a JavaScript-based workspace access plugin extension that can use JavaScript to call our Java API: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/concepts/workspace-access-plugin-js.html.

A set of sample plugins built with the JavaScript-based extension can be found here: https://github.com/oxygenxml/wsaccess-javascript-sample-plugins.

Our Maven-based SDK can be used to develop both plugins and framework Java customizations: https://www.oxygenxml.com/oxygen_sdk_maven.html.

Tuesday, February 07, 2017

Sharing Schematron Validation Rules

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

Custom Schematron rules are a great way to ensure consistency for the edited XML structure, especially when there is a large team working on the same set of documents. You can use Schematron for numerous use cases. For example, to make sure that certain elements are not used at all, to impose restrictions on the amount of text for an element, or to impose restrictions on certain elements based on various attribute values or text content set in other elements. Furthermore, you can define quick fixes for each Schematron rule to give the technical writer proposed solutions for the reported problem. In a previous blog post, I described how we use Schematron rules for our Oxygen User's Manual to impose restrictions when editing DITA content: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.

Once you define the Schematron rules, they can be shared with the other members of your team via a document type framework configuration: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

In this post, I'm going to provide some precise steps to share a set of Schematron rules with a DITA framework extension.

Instead of making changes directly to the DITA framework configuration folder (located in OXYGEN_INSTALL_DIR\frameworks\dita) and distributing it, you can choose to extend the DITA framework and distribute the extension. This way, you will benefit from new functionality added to the base framework in newer versions of Oxygen and you can still use your customizations.

The following steps describe how you can extend a DITA framework that contains an additional Schematron rules file:

  1. Create a folder structure (for example, custom_frameworks/dita-extension) somewhere on your local disk, in a place where you have full write access.
  2. In that new folder structure, create another folder (custom_frameworks/dita-extension/rules) that will contain all of your custom Schematron files.
  3. Create a new ISO Schematron file (for example, additionalRules.sch) that contains the additional rules you want to impose. For example, the following Schematron rule reports an error if the @scale attribute is used on an image:
    <schema xmlns="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
        xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
        <pattern>
            <rule context="*[contains(@class, ' topic/image ')]">
                <assert test="not(@scale)">
                    Dynamically scaled images are not properly displayed, you
                    should scale the image with an image tool and keep it within
                    the recommended with and height limits.
                </assert>
            </rule>
        </pattern>
    </schema>
  4. In the Document Type Association / Locations preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list.
  5. In the Document Type Association preferences page, select the DITA document type configuration and use the Extend button to create an extension for it.
  6. Give the extension a custom name (for example, DITA - Custom), then change its Storage option to External, and then save it to a path such as: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
  7. Make whatever changes you desire to the extension, go to the Validation tab, edit the default DITA validation scenario, and add an extra validation stage to it (a stage that uses your custom Schematron schema). More details about validation scenarios can be found here: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/tasks/dg-validation-scenarios.html.
  8. Click OK to close the dialog box and then either OK or Apply to save the preferences changes.

After you perform the steps above, in the dita-extension folder you will have a fully functioning framework extension that can be shared with others.

There are several methods for sharing the framework and you can read about them here: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/author-document-type-extension-sharing.html.

After your team members install the framework, they can check the Document Type Association preferences page to make sure the framework is present in the list of Document Types and that it appears before the bundled DITA framework (meaning that it has higher priority).

You can use the framework extension mechanism to customize numerous aspects of the DITA functionality in Oxygen. For example, you can remove various elements from the content completion list: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html. Or you can distribute custom new file templates: http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html.

Wednesday, January 18, 2017

Your First Oxygen Add-on

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

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

Existing framework configurations that come bundled with Oxygen can be extended and modified. For example, the DITA framework configuration that adds support for editing DITA documents can be modified to remove existing actions, add custom actions, or modify many other behaviors: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.

One way of distributing framework configurations is by using Oxygen's add-on support: https://www.oxygenxml.com/addons.html. An add-on configuration is usually composed of only two files:
  1. A ZIP file containing the zipped framework folder.
  2. An add-on XML configuration file that references the zipped framework folder and defines various properties of the add-on. A small example can be seen below:
    <xt:extensions xmlns:xt="http://www.oxygenxml.com/ns/extension"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.oxygenxml.com/ns/extension http://www.oxygenxml.com/ns/extension/extensions.xsd">
        <xt:extension id="dita-extension">
            <xt:location href="dita_extension.zip"/>
            <xt:version>1.0.0</xt:version>
            <xt:oxy_version>18.0+</xt:oxy_version>
            <xt:type>framework</xt:type>
            <xt:author>Radu Coravu</xt:author>
            <xt:name>DITA Extension which removes the bold action</xt:name>
            <xt:description xmlns="http://www.w3.org/1999/xhtml">
                This extension removes the bold action
            </xt:description>
            <xt:license>
    <![CDATA[
    Everybody's welcomed to use this
    ]]></xt:license>
        </xt:extension>
    </xt:extensions>
    In the add-on descriptor file you usually need to specify the following :
    • The ID of the extension.
    • The version of the add-on.
    • The minimum supported Oxygen version.
    • Author name.
    • Name and description of add-on.
    • Licensing details.

Changing the add-on version in the XML file will trigger notifications to the end user to install the new add-on. Therefore, you can modify the framework customization in a common location and change the add-on version to signal all end-users who have installed the add-on that a new version is available. More details about packing an add-on can be found here:https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/packing-and-deploying-addons.html#packing-and-deploying-addons.

If you want to test the small add-on I exemplified, you can find the sample add-on resources here:https://www.oxygenxml.com/forum/files/sample-add-on.zip.

Installing an add-on is straight-forward using the Install new add-ons dialog box from the Oxygen Help menu. You can add a reference to the add-on XML descriptor file that can reside either on the local hard drive or on a web server, and Oxygen will present all available add-ons: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/installing-and-updating-add-ons.html

The add-ons support can also be used to install Oxygen plugins. Some of the public hosted Oxygen plugins and frameworks are also available as add-ons: http://blog.oxygenxml.com/2014/11/public-hosted-oxygen-plugin-and.html.

In conclusion, if you want to share Oxygen customizations with others, you should try the add-on approach, it is a better approach to manually distributing frameworks and plugins.

Thursday, October 13, 2016

Replacing direct image references with key references in a DITA Project

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Let's say that you have a large DITA project and all the image references in your topics are direct, using the @href attribute like this:
<image href="../../images/Iris_sanguinea.jpg" scale="50"/>
and for better scalability and reuse you want to convert these direct references to DITA 1.2 key references:
<image keyref="Iris_sanguinea.jpg" scale="50"/>

Doing something like this manually means making replacements in hundreds of places and in addition manually building a DITA Map which maps the image file name to the image location.

This blog post will try to describe some steps that you can take in order to automate this change in your project:
  1. The first big step is the generation of the DITA Map which maps each image file name (which will be used as a key) to the image location. So the generated DITA Map will look like this:
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <map>
    ….…....
    <keydef href="Iris_sanguinea.jpg" keys="Iris_sanguinea.jpg"/>
    …...
    </map>
    We will assume that all images are placed in an images folder and we can create an ANT build file which lists all the images in a parameter and then calls an XSLT script to process the list of images further:
    <project basedir="." name="Create Image Keys Definition Map">
        <fileset id="dist.contents" dir="images/" includes="*"/>
        <property name="prop.dist.contents" refid="dist.contents"/>
        <xslt in="createKeyrefsMap.xsl" style="createKeyrefsMap.xsl" out="images/imageKeydefs.ditamap" destdir=".">
            <param name="filesList" expression="${prop.dist.contents}"/>
        </xslt>
    </project>
    The XSLT stylesheet createKeyrefsMap.xsl is responsible for creating the mapping DITA Map:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        exclude-result-prefixes="xs"
        version="1.0">
        <xsl:param name="filesList"/>
        <xsl:output doctype-public="-//OASIS//DTD DITA Map//EN" doctype-system="map.dtd" indent="yes"/>
        <xsl:template match="/">
            <map>
                <xsl:call-template name="tokenizeString">
                    <xsl:with-param name="list" select="$filesList"/>
                </xsl:call-template>
            </map>
        </xsl:template>
        <xsl:template name="tokenizeString">
            <xsl:param name="list"/>
            <xsl:param name="delimiter" select="';'"/>
            <xsl:choose>
                <xsl:when test="contains($list, $delimiter)">
                    <keydef href="{substring-before($list,$delimiter)}" keys="{substring-before($list,$delimiter)}"/>
                    <xsl:call-template name="tokenizeString">
                        <xsl:with-param name="list" select="substring-after($list,$delimiter)"/>
                    </xsl:call-template>
                </xsl:when>
                <xsl:otherwise>
                    <keydef href="{$list}" keys="{$list}"/>
                </xsl:otherwise>
            </xsl:choose>
        </xsl:template>
    </xsl:stylesheet>

    So after this step you will have a new DITA Map with all image mappings, DITA Map which you can afterwards link in your main project's DITA Map.

  2. We still need to make changes to all DITA topics and replace all image hrefs with keyrefs. Oxygen has support for XML Refactoring actions and you can define custom XSLT scripts which can be applied to modify an entire set of topics. In the OXYGEN_INSTALL_DIR/refactoring folder you can add an XSLT script along with an XML description of the refactoring action. An XSLT script which would replace @href attributes on images with @keyref would look like this:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="2.0"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:f="http://www.oxygenxml.com/ns/functions">
        <xsl:function name="f:getKeyref" as="xs:string">
            <xsl:param name="element" as="element()"/>
            <xsl:variable name="imageFile" select="tokenize(translate($element/@href, '\', '/'), '/')[last()]"/>
            <xsl:variable name="key" select="substring-before($imageFile, '.')"/>
            <xsl:value-of select="$key"/>
        </xsl:function>
        <xsl:template match="node() | @*">
            <xsl:copy>
                <xsl:apply-templates select="node() | @*"/>
            </xsl:copy>
        </xsl:template>
        <xsl:template match="image[@href and not(@keyref)]">
            <xsl:copy>
                <xsl:apply-templates select="@* except @href"/>
                <xsl:attribute name="keyref" select="f:getKeyref(.)"></xsl:attribute>
                <xsl:apply-templates select="node()"/>
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet> 
    In the DITA Maps Manager view you can right click and choose Refactoring->XML Refactoring, then use your custom refactor action to modify all resources.

A set of samples, including the build file, XSLT stylesheets and refactor action XML descriptor can be found here:https://www.oxygenxml.com/forum/files/batchImageHrefToKeyref.zip.

Thursday, October 06, 2016

Customizing the DITA Visual Editing Experience

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

The Author visual editing experience in Oxygen is CSS driven. Let's say I have a team of writers using Oxygen and they want to visually edit DITA dl elements in a table-like layout.

All the validation, editing and publishing support Oxygen has for a specific XML vocabulary is defined in a framework configuration.

Instead of copying an entire framework configuration folder (like DITA or Docbook), modify and distribute it you can choose to extend that framework and distribute the extension. In this way, you will benefit of new functionality added to the base framework by newer Oxygen versions and still use your customizations.

The steps below describe how an extension of the DITA framework which removes certain elements from the content completion list can be constructed and shared:
  1. Create somewhere on your disk, in a place where you have full write access a folder structure like: custom_frameworks/dita-extension.
  2. In that folder create a new CSS stylesheet called for example custom.css which will keep your custom CSS styles:
    dl{
        display:table !important;
    }
    dlentry{
        display:table-row !important;
    }
    dt, dd {
        display:table-cell !important;
        border: 1px solid black;
        padding: 2px;
    }
  3. In the Document Type Association / Locations preferences page add in your Additional frameworks directories list the path to your custom_frameworks folder. Then click Apply in the Preferences dialog.
  4. In the Document Type Association Preferences page select the DITA document type configuration and use the Extend button to create an extension for it.
  5. Give a custom name to the extension, for example DITA - Custom and then change its Storage to external, then save it to a path like: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
  6. Make changes to the framework configuration, in the Author tab click the CSS tab and add a reference to your custom CSS. Do not set a title for the CSS and also do not check the Alternate checkbox as you want your CSS to apply by default.
  7. Click OK to close the dialog and then either OK or Apply to save the preferences changes.

After you perform the steps above you will have in the dita-extension folder a fully functioning framework which can be shared with others: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.

To check that your framework extension works, you can create a new DITA topic and insert a dl element inside it. It should now be presented in a table-like layout.

In order to know which CSS styles to override for a specific DITA element, you can right click inside that element in the Author visual editing mode and use the Inspect Styles action to see all CSS styles defined for it by default. You can also define alternate CSS styles which are applied manually by the writer by using the Author toolbar Styles drop down menu.

Monday, October 03, 2016

DITA Linking Usage Survey

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

A couple of weeks ago I published a survey which was intended as an overview about DITA Linking habits. A big thank you to everyone who took it. The entire set of survey results, including the answers to open questions can be found here:

https://www.surveymonkey.com/results/SM-N8RJ6CJX/

Here are some comments I have about the results:
  • Most projects (including ours) seems to approach linking with a mixture between DITA 1.1 href's and DITA 1.2 keyrefs. In my opinion this is caused by a variety of factors among which the most important could be:
    • Technical writers who are not comfortable using indirection (keyrefs)
    • The project was started using href's and not all links have been converted to keyrefs
  • Almost everyvody using related links uses a relationship table to manage them. And that's good.
  • There are projects where related links, chunking and collection-type are not used at all. And I think this is not because the projects are not complex, but because the main output delivery format for those projects is PDF. In a DITA Reuse survey I opened last year there was a clear indication that PDF was still the most used output format: https://www.surveymonkey.com/results/SM-3WSR598S/.
Although harder to quantify I usually like answers to open questions best because you get a better idea about the difficulties of linking in DITA:
  • The large set of DITA linking possibilities make the standard harder to use. Too many options, harder for writers to understand and use keyrefs or relationship tables. There seems to be a need to have a best practice involving linking and DITA.
  • Various writers have various writing styles, leading to inconsistent projects.
  • Problems with the publishing part, even when the right DITA content is used for links (for example abbreviated-form) the publishing engine might have issues which break the link in the final output.
  • Problems with link management, with having a clear idea of outbound and inbound links and their target. Problems with broken links.
  • The tools used for editing DITA sometimes hide the complexity and even the type of link which gets created. Also the tools should help the writer easier find the target content to link to.

Wednesday, September 21, 2016

Migrating DITA Open Toolkit PDF Customizations

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

We daily encounter clients who have PDF customizations created for older DITA Open Toolkit versions and they want to migrate to a new Oxygen version (which includes a newer DITA Open Toolkit publishing engine distribution).

Most XHTML-based customizations are quite easily accomplished just by using a custom CSS. But as the standard PDF publishing obtained with the DITA Open Toolkit is XSL-FO based, it requires XSLT customizations.

As a general rule, when making a customization of any kind you should keep some kind of notes about what you achieved during the customization and through what means, this will help you migrate your customization to a new DITA Open Toolkit version.

Oxygen 18 comes with two DITA Open Toolkit distributions (1.8.5 and 2.x), you can choose which DITA OT distribution to use in the Preferences->DITA page. DITA OT 2.x is newer and it comes with DITA 1.3 support so you should try to update directly to it.

First of all, if you are happy with the output obtained using your current DITA OT distribution, you can continue using that DITA OT as an external DITA OT, you can copy it from inside the old Oxygen installation to an external location and in Oxygen 18.0 the same Preferences->DITA page allows you to choose an external DITA OT distribution to use:

https://www.oxygenxml.com/doc/versions/18.0/ug-editor/tasks/use-new-dita-ot.html

If you still want to migrate:

No proper implemented customization should modify the base "org.dita.pdf2" plugin contents. The customization folder should be either kept external to the DITA Open Toolkit distribution:

https://www.oxygenxml.com/doc/versions/18.0/ug-editor/topics/dita_pdf_output_customization.html

or it should be provided via a PDF customization plugin:

http://www.dita-ot.org/1.8/readme/dita2pdf-customization.html

In the DITA Open Toolkit documentation there is also a best practices about PDF customizations:

http://www.dita-ot.org/dev/dev_ref/pdf-customization-best-practices.html

The main idea is to have all your changes in one place.

While the DITA Open Toolkit evolves, various XSLT templates might change, they might be renamed or removed completely. There is a migration guide here:

http://www.dita-ot.org/dev/dev_ref/migration.html

Even without reading the guide, you need to determine what XSLT templates are not getting called anymore in your customization (you can add xsl:message's for this) and then try to find in the base PDF plugin the templates which need to be overridden instead.

So this is why having some notes about all aspects that your PDF customization should cover is useful in the long run, you can use the notes to see if all aspects of your customization are still applied with a newer DITA OT and for the aspects which no longer work you can easily locate the places in XSLT where the customization was done.