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.

Tuesday, August 23, 2016

Converting Subject Scheme Map Values to a DITAVAL

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

Let's say you already have a Subject Scheme Map in your project and you use it to control attribute values: http://blog.oxygenxml.com/2015/07/controlled-attribute-values-for-your.html.

In the Oxygen Colors and Styles Preferences page you can also assign various colors and styles to each profiling attribute (name, value) combination. One option for this is to manually re-add attributes and values in that list. Another option would be to create an XSLT stylesheet to gather all profiling attribute names and values from the Subject Scheme map and create a DITAVAL file. The stylesheet would look like this:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    exclude-result-prefixes="xs"
    version="2.0">
    <xsl:output indent="yes"/>
    <xsl:template match="/">
        <val>
            <xsl:for-each select="subjectScheme/enumerationdef">
                <!-- For each attribute name -->
                <xsl:if test="subjectdef/@keyref and attributedef/@name">
                    <xsl:variable name="attrName" select="attributedef/@name"/>
                    <xsl:variable name="keyref" select="subjectdef/@keyref"/>
                    <!-- For each key value -->
                    <xsl:for-each select="//*[@keys=$keyref]/*//@keys">
                        <xsl:variable name="attributeValue" select="."/>
                        <prop action="flag" att="{$attrName}" val="{$attributeValue}"/>
                    </xsl:for-each>
                </xsl:if>
            </xsl:for-each>
        </val>
    </xsl:template>
</xsl:stylesheet>

After you obtain the DITAVAL, you can import it directly in the Colors and Styles preferences page. If the DITAVAL file has flagging information, that information will be directly used to style each attribute value.

A possibility to enhance this workaround is to specify profiling styles for each attribute value directly in the Subject Scheme map using the <data> element like:
<subjectdef keys="linux">
    <data name="color" value="yellow"/>
</subjectdef>
in which case the XSLT stylesheet would create the DITAVAL by picking colors directly from the Subject Scheme Map:
….….…....
<prop action="flag" att="{$attrName}" val="{$attributeValue}">
    <xsl:choose>
        <!-- Here you can also set flagging colors depending on the profiling attribute value -->
        <xsl:when test="data[@name='color']">
            <xsl:attribute name="color" select="data/@value"/>
        </xsl:when>
    </xsl:choose>
</prop>
….….….….
In this way your Subject Scheme Map will keep both the controlled attribute values and various colors and styles which can later be used to create a DITAVAL and either publish with those styles or import the DITAVAL in Oxygen in order to highilight various elements with various colors:https://www.oxygenxml.com/demo/Colors_and_Styles_for_Profiled_Content.html.

Monday, June 27, 2016

Guided DITA Authoring Solution Overview

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

We've had past blog posts about how Oxygen can be used to impose various editing behaviors for your team. In this blog post, we are going to try to bring all of these solutions together in a comprehensive overview.

Learning to Work with DITA and Oxygen

You can find useful links for learning to edit DITA using Oxygen in this previous blog post: http://blog.oxygenxml.com/2016/03/resources-for-learning-dita-with-oxygen.html.

Migrating to DITA

There are multiple reasons why you would want to migrate from unstructured content to structured: http://blog.oxygenxml.com/2015/12/migrating-to-structured-standards-based.html.

This older blog post details some possibilities of migrating Word documents to DITA: http://blog.oxygenxml.com/2016/05/how-to-migrate-from-word-to-dita.html. You also have ways to migrate from XML-based standards (like DocBook or XHTML to DITA) using a set of predefined transformation scenarios.

Implementing Your own Style Guide

Let's say you are a team of technical writers collaborating on a DITA-based project and suppose that you have your own various best practices in regards to which elements to use and when to use them. So, at some point you gather a set of HTML resources that explain how various DITA elements should be used, you store them on an internal server, and you want all your team members to have access to that set of HTML resources directly from Oxygen. This blog post provides more details and useful links to help you get started: http://blog.oxygenxml.com/2016/03/implementing-your-own-style-guide.html

Imposing Controlled Attribute Values

If you want to impose DITA attribute values that need to be set for profiling or general use, this blog post should cover all you need to know about this: http://blog.oxygenxml.com/2015/07/controlled-attribute-values-for-your.html

Restricting the Visual Editing Experience

The entire visual editing experience using the Author editing mode in Oxygen is CSS driven. Oxygen has support for defining various CSS layers that can be applied when editing DITA content. For example, if you choose to create a Lightweight DITA topic in Oxygen, it has a special editing layer that allows it to be edited with a combination of buttons, hints, and form controls.

Imposing Business Rules and Structure Restrictions to the DITA Content

In most cases, instead of relying on people to memorize numerous internal documentation style rules, you can convert many of these rules to Schematron and allow the application to automatically signal the content author when a rule is violated. You can also add quick fixes to show authors various ways to rectify the problem. This blog post contains more details about this: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.

Running Batch Validation Checks on all of Your DITA Content

The Validate and Check For Completeness tool available in the DITA Maps Manager view performs a lot of different consistency checks on all your DITA topics. It can also be used to apply Schematron business rules on all of your topics: http://blog.oxygenxml.com/2015/12/dita-map-validate-and-check-for.html.

Sharing DITA Editing Customizations with Your Team

Most of the custom editing behaviors, toolbar, and menu buttons that are available when editing DITA content are defined in the DITA framework configuration. A framework configuration's general anatomy is described here: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

The framework configuration can be shared with all of your team members. For example, here is a way to restrict team members from using certain DITA elements: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html. Furthermore, here is a way to distribute new DITA file templates to your team: http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html.

Sharing Global Application Settings with Your Team

Let's say you want all of your team members to enable the automatic spell checker when writing documentation, or you want all of them to use a custom term dictionary or a custom set of learned words. This older blog post offers some hints about how global Oxygen settings can be distributed to your team members: http://blog.oxygenxml.com/2015/11/sharing-application-settings.html.

Collaboration, Content Management, and Version Tracking

All major Component Management Systems (CMSs) have plugins that can be installed in Oxygen to provide access to the CMS: https://www.oxygenxml.com/partners.html#cmssolutionpartners. Even if you lack the funds to buy a commercial CMS, there are still plenty of open source version tracking solutions that allow collaboration for a single DITA project: http://blog.oxygenxml.com/2013/12/collaboration-teams-working-on-common.html. For example, the Oxygen User's Manual is written in DITA and we use a GitHub private repository to collaborate on it: http://blog.oxygenxml.com/2014/11/collaboration-for-documenting-software.html.

Allowing Subject Matter Experts to Review Content

Many technical writers are interested in having their content reviewed by the subject matter experts who are directly involved in building the tools. Oxygen has support for change tracking and adding comments directly in the edited content. Subject matter experts do not necessarily need to have the standalone version of Oxygen installed. The Oxygen Web Author is an online editing and reviewing solution that allows them to add comments and propose changes directly in the DITA content by using any device with a web browser (laptop, tablet, phone): https://www.oxygenxml.com/xml_web_author.html.

I hope this overview will help you to implement a complete guided authoring experience using Oxygen. As usual, if you have any questions or suggestions, they are welcome.

Monday, June 20, 2016

Enable Massive Contributions with oXygen XML Web Author and GitHub

Early in 2016, a new product was added to the oXygen XML set of tools - the oXygen XML Web Author. It leverages the power of oXygen XML Author (which basically runs on the server side) and provides access to XML authoring from any modern device that supports a browser capable of rendering HTML5+JavaScript, including desktops and mobile devices like your smart phone or tablet.

The real power of web-based XML authoring can be seen when it is integrated as part of a workflow, simplifying it by reducing a large number of steps to just a few. This is what the GitHub connector provides!

If you have XML content on GitHub, you can then provide a link that will open a file in the oXygen XML Web Author and anyone will be able to review or edit it just by accessing the link and saving (a GitHub account is of course required).

When you save a file, assuming you do not have commit access on that repository, the GitHub connector will automatically:
  • fork the project into your account, if it is not already
  • create a new branch from the edited branch
  • commit your changes on this newly created branch
  • create a pull request from your newly created branch to the originally edited branch
  • switch the editor to your branch so further save operations will just add new commits to your branch, thus updating the pull request with new changes
This is a great simplification of the contribution process, a contributor just follows a link and saves the file, and all the magic to create the pull request happens automatically.

If the XML source is published, then it is possible to include an "Edit this page" link on the published format that will allow immediate access to the editor. An example of such access is provided for the DITA-OT documentation project. The development branch is published at http://www.dita-ot.org/dev/ and every page contains an "Edit this page" link at the bottom that gives immediate access to the DITA topic that page is generated from.

For example, the http://www.dita-ot.org/dev/user-guide/DITA_v1-3-support.html page shows the DITA 1.3 support in DITA-OT and the "Edit this page" link will send you to the DITA_v1-3-support.dita topic. If you edit a file and then save it, a pull request with your changes will be automatically generated. Content contribution cannot be easier than this!

Next, we plan to have the "Edit this page" link available in every page of the oXygen documentation, which is also hosted on GitHub at https://github.com/oxygenxml/userguide.
Hope you find this useful!

Guided Authoring: Enforcing Editing Rules

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

Webinar - Guided Authoring:
Enforcing Editing Rules

This webinar presented a way of imposing various rules that your content authors need to follow, such as grammar rules, document structure guidelines, business requirements, style preferences, or rules for the generated output. 

When editing documents there are various rules that you want your content authors to follow, such as grammar rules, document structure guidelines, business requirements, style preferences, or rules for the generated output. To enforce these rules, companies often use grammar checking apps, custom schemas or best practice guides.

For content authors, there are usually too many rules to remember them all when writing content. The best approach for this challenge is to signal the user when a rule violation is detected and offer suggestions to help them solve possible rule problems and maintain integrity in their documentation.

A recording of the event, sample files, and slides are available on our website: 








Discover the technology behind the fix proposals for business rules by attending our next webinar: Understanding and Developing Schematron Quick Fixes - Jul 14, 2016