Friday, June 16, 2017

Checking terminology when editing in Oxygen XML Editor

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
In this blog post I will offer a general overview about the current possibilities you have available to impose your own language checking rules when working with Oxygen XML Editor.

Built-in support

Oxygen comes bundled with the popular Hunspell spell checker and along with the regular bundled dictionaries for English, German, Spanish, and French, it allows you to install new dictionaries, either for other languages or custom dictionaries (for example, dictionaries for medical terms) that you can build separately: https://www.oxygenxml.com/doc/versions/19.0/ug-editor/topics/spell-dictionary-Hunspell.html.

Besides the spell checker, Oxygen also has support for Auto-correct and you can add your own Auto-correct pairs to Oxygen.

Commercial alternatives

Acrolinx is a very popular commercial tool for checking content for consistency and terminology. The plugins that Acrolinx developed for Oxygen standalone, Oxygen Eclipse plugin and Oxygen Web Author allow you to run the Acrolinx checker directly from inside the application.

HyperSTE is another popular commercial tool for checking content and terminology. They also have a plugin for Oxygen standalone.

Open-source alternatives

LanguageTools is an open-source proof­reading program for English, French, German, Polish, and more than 20 other languages . There is an open-source plugin for Oxygen available on GitHub.

The DITA Open Toolkit terminology checker plugin from Doctales contains Schematron rules to check that various words adhere to the terminology dictionaries that are custom built using DITA.

Building your own terminology checker

The fastest and simplest way to build a simple terminology checker is by using Schematron rules. The Doctales plugin is a good example for this.

At some point, as the terminology dictionary keeps growing, you may encounter delays and slow downs when editing the documents and validating it using the custom Schematron rules. So an alternative to this is by using our Author SDK to build your own Oxygen plugin, which can use our API to check the content and then add highlights. The LanguageTools open-source plugin may be a good starting example for this.

Monday, June 12, 2017

Batch converting HTML to XHTML

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

Suppose you have a bunch of possibly "not-wellformed" HTML documents already created and you want to process them using XSLT. For example, you may want to migrate the HTML documents to DITA using the predefined XHTML to DITA Topic transformation scenario available in Oxygen. So you need to create valid XML wellformed XHTML documents from the existing HTML documents and you need to do this in a batch processing automated fashion.

There are lots of open source projects that deliver processors that can convert HTML to its wellformed XHTML equivalent. For this blog post, we'll use HTML Tidy. Here are some steps to automate this process:
  1. Create a new folder on your hard drive (for example, I created one on my Desktop: C:\Users\radu_coravu\Desktop\tidy).
  2. Download the HTML Tidy executable specific for your platform (http://binaries.html-tidy.org/) and place it in the folder you created in step 1.
  3. In that same folder, create an ANT build file called build.xml with the following content:
    <project basedir="." name="TidyUpHTMLtoXHTML" default="main">
        <basename property="filename" file="${file}"/>
      <target name="main">
          <exec command="tidy.exe -o ${output.dir}/${filename} ${file}"/>
      </target>
    </project>
  4. In the Oxygen Project view, link the entire folder where the original HTML documents are located.
  5. Right-click the folder, choose Transform->Configure Transformation Scenarios... and create a new transformation scenario of the type: ANT Scenario. Modify the following properties in the transformation scenario:
    1. Change the scenario name to something relevant, like HTML to XHTML.
    2. Change the Working Directory to point to the folder where the ANT build file is located (in my case: C:\Users\radu_coravu\Desktop\tidy).
    3. Change the Build file to point to your custom build.xml (in my case: C:\Users\radu_coravu\Desktop\tidy\build.xml).
    4. In the Parameters tab, add a parameter called file with the value ${cf} and a parameter called output.dir with the value of the path to the output folder where the equivalent XHTML files will be stored (in my case, I set it to: C:\Users\radu_coravu\Desktop\testOutputXHTML).
  6. Apply the new transformation scenario on the entire folder that contains the HTML documents. When it finishes, in the output folder you will find the XHTML equivalents of the original HTML files (XHTML documents that can later be processed using XML technologies such as XSLT or XQuery).

Tuesday, April 25, 2017

DITA Inheritance Hierarchy

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

The DITA standard is based on this concept of inheritance which allows extending or restricting the vocabulary while allowing the XML content to still be regarded as valid DITA. Even in the DITA standard there are various element which are specializations of others (for example "b" is a specialization of ph"). The XSLT styesheets which are used for publishing match all DITA elements by the value of their @class attribute so knowing how elements may extend each other may be useful when customizing the DITA XSLTs.

A DITA inheritance hierarchy list for the base DITA specification is presented below. Would you consider it useful if a future version of Oxygen would have some kind of a tool to show such hierarchies even for custom DITA specializations?

  • topic/copyryear
  • topic/foreign
    • mathml-d/mathml
    • svg-d/svg-container
  • topic/author
  • topic/example
  • topic/unknown
  • topic/titlealts
  • topic/linktext
  • topic/category
  • topic/data
    • relmgmt-d/change-request-reference
    • relmgmt-d/change-person
    • relmgmt-d/change-request-id
    • relmgmt-d/change-request-system
    • relmgmt-d/change-completed
    • relmgmt-d/change-started
    • ut-d/sort-as
    • relmgmt-d/change-item
    • relmgmt-d/change-organization
    • relmgmt-d/change-summary
    • concept/data
      • glossentry/glossPartOfSpeech
      • glossentry/glossProperty
      • glossentry/glossStatus
    • relmgmt-d/change-revisionid
  • topic/longdescref
  • topic/audience
  • topic/abstract
    • concept/abstract
      • glossentry/glossdef
  • topic/related-links
  • topic/body
    • task/taskbody
    • concept/conbody
      • glossentry/glossBody
    • troubleshooting/troublebody
    • reference/refbody
  • topic/ph
    • hi-d/overline
    • hi-d/line-through
    • hi-d/sub
    • pr-d/sep
    • equation-d/equation-inline
    • pr-d/repsep
    • equation-d/equation-number
    • hi-d/tt
    • task/cmd
    • pr-d/synph
    • sw-d/userinput
    • ut-d/coords
    • pr-d/oper
    • hi-d/sup
    • pr-d/var
    • sw-d/msgph
    • pr-d/codeph
    • ui-d/uicontrol
    • hi-d/i
    • hi-d/u
    • sw-d/filepath
    • sw-d/systemoutput
    • pr-d/delim
    • hi-d/b
    • ui-d/menucascade
  • topic/object
  • topic/fig
    • ut-d/imagemap
    • pr-d/syntaxdiagram
    • equation-d/equation-figure
  • topic/featnum
  • topic/lines
  • topic/brand
  • topic/state
  • topic/source
  • topic/link
  • topic/vrm
  • topic/sli
  • topic/navtitle
  • topic/figgroup
    • pr-d/synblk
    • pr-d/fragment
    • ut-d/area
    • pr-d/groupcomp
    • pr-d/groupseq
    • pr-d/groupchoice
  • topic/note
    • hazard-d/hazardstatement
    • concept/note
      • glossentry/glossScopeNote
      • glossentry/glossUsage
  • topic/ol
    • task/substeps
    • task/steps
  • topic/stentry
    • task/choption
    • reference/propvalue
    • reference/propvaluehd
    • reference/propdeschd
    • reference/propdesc
    • reference/proptype
    • reference/proptypehd
    • task/choptionhd
    • task/chdesc
    • task/chdeschd
  • topic/dlentry
    • pr-d/plentry
  • topic/vrmlist
  • topic/entry
  • topic/fn
    • pr-d/synnote
  • topic/xref
    • mathml-d/mathmlref
    • svg-d/svgref
    • concept/xref
      • glossentry/glossAlternateFor
    • pr-d/synnoteref
    • pr-d/fragref
    • pr-d/coderef
  • topic/component
  • topic/series
  • topic/bodydiv
    • reference/refbodydiv
    • troubleshooting/troubleSolution
    • concept/conbodydiv
  • topic/data-about
  • topic/tgroup
  • topic/keywords
  • topic/boolean
  • topic/critdates
  • topic/strow
    • task/chrow
    • reference/property
  • topic/simpletable
    • reference/properties
    • task/choicetable
  • topic/linklist
  • topic/revised
  • topic/table
  • topic/dt
    • pr-d/pt
  • topic/image
    • hazard-d/hazardsymbol
    • concept/image
      • glossentry/glossSymbol
  • topic/ul
    • hazard-d/messagepanel
    • task/choices
    • task/steps-unordered
  • topic/p
    • concept/p
      • glossentry/glossSurfaceForm
    • troubleshooting/responsibleParty
  • topic/q
  • topic/linkinfo
  • topic/dd
    • pr-d/pd
  • topic/lq
  • topic/prodinfo
  • topic/dl
    • pr-d/parml
  • topic/prolog
  • topic/indextermref
  • topic/copyright
  • topic/div
    • equation-d/equation-block
  • topic/sthead
    • task/chhead
    • reference/prophead
  • topic/tbody
  • topic/searchtitle
  • topic/colspec
  • topic/created
  • topic/tm
  • topic/text
  • topic/cite
  • topic/li
    • hazard-d/howtoavoid
    • task/step
    • task/substep
    • hazard-d/consequence
    • hazard-d/typeofhazard
    • task/choice
    • task/stepsection
  • topic/permissions
  • topic/no-topic-nesting
  • topic/dlhead
  • topic/prodname
  • topic/index-base
    • indexing-d/index-sort-as
    • indexing-d/index-see
    • indexing-d/index-see-also
  • topic/indexterm
  • topic/copyrholder
  • topic/longquoteref
  • topic/required-cleanup
  • topic/ddhd
  • topic/sl
  • topic/draft-comment
  • topic/section
    • task/postreq
    • task/result
    • troubleshooting/remedy
    • task/tasktroubleshooting
    • concept/section
      • glossentry/glossAlt
    • task/context
    • troubleshooting/cause
    • task/steps-informal
    • reference/refsyn
    • task/prereq
    • troubleshooting/condition
  • topic/pre
    • sw-d/msgblock
    • pr-d/codeblock
    • ui-d/screen
  • topic/topic
    • troubleshooting/troubleshooting
    • concept/concept
      • glossgroup/glossgroup
      • glossentry/glossentry
    • reference/reference
    • task/task
  • topic/platform
  • topic/alt
  • topic/keyword
    • ui-d/shortcut
    • markup-d/markupname
      • xml-d/parameterentity
      • xml-d/xmlatt
      • xml-d/numcharref
      • xml-d/xmlpi
      • xml-d/textentity
      • xml-d/xmlnsname
      • xml-d/xmlelement
    • pr-d/parmname
    • pr-d/option
    • sw-d/cmdname
    • ui-d/wintitle
    • ut-d/shape
    • sw-d/varname
    • pr-d/apiname
    • pr-d/kwd
    • sw-d/msgnum
  • topic/thead
  • topic/publisher
  • topic/desc
  • topic/term
    • abbrev-d/abbreviated-form
  • topic/title
    • concept/title
      • glossentry/glossShortForm
      • glossentry/glossAbbreviation
      • glossentry/glossSynonym
      • glossentry/glossterm
      • glossentry/glossAcronym
  • topic/itemgroup
    • task/steptroubleshooting
    • task/tutorialinfo
    • task/info
    • task/stepxmp
    • task/stepresult
  • topic/row
  • topic/linkpool
  • topic/param
  • topic/shortdesc
  • topic/resourceid
  • topic/dthd
  • topic/metadata
    • relmgmt-d/change-historylist
  • topic/othermeta
  • topic/prognum
  • topic/sectiondiv

Wednesday, March 08, 2017

Useful DITA OT plugins

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

The DITA Open Toolkit is the most commonly used engine for publishing DITA content to various output formats. It has a plugin-based architecture and it comes bundled by default with plugins for publishing to XHTML-based and PDF formats. There are other useful open-source plugins which can be installed in the DITA Open Toolkit and provide various publishing or reporting capabilities. I will try to compile below a list with my favorite open source plugins, many of which are bundled by default with Oxygen XML Editor:

DITA to MS Word

This very useful plugin developed by Jarno Elovirta (the main DITA OT developer) can be used to publish DITA to MS Word (OOXML): https://github.com/jelovirt/com.elovirta.ooxml. The plugin is robust and can handle quite large DITA projects.

Convert MS Word to DITA

The DITA For Publishers project developed by Eliot Kimber contains a plugin which can convert MS Word (OOXML) documents to DITA topics: http://www.dita4publishers.org/d4p-users-guide/user_docs/d4p-users-guide/word2dita/word-to-dita-plugin.html. Useful advice and other ways to migrate from MS Word to DITA can be found here: http://blog.oxygenxml.com/2016/05/how-to-migrate-from-word-to-dita.html.

DITA to EPUB

The DITA For Publishers project developed by Eliot Kimber contains a plugin which can convert DITA content to EPUB3: http://www.dita4publishers.org/d4p-users-guide/user_docs/d4p-users-guide/epub-plugin/generating-epubs.html. There are also plugins which can take the EPUB3 output and generate Kindle or Mobi formats.

Use Markdown content directly in DITA Maps

This plugin developed again by Jarno Elovirta can be used to publish hybrid DITA projects containing both DITA and Markdown topics to any output format: https://github.com/jelovirt/dita-ot-markdown.

Embed video and audio resources in DITA topics

This handy little plugin developed by Oxygen allows you to embed audio, video, or Youtube resources in DITA topics and properly display the embedded content in the XHTML-based outputs: https://github.com/oxygenxml/dita-media-support.

Publish RelaxNG-based DITA topics

RelaxNG is the default schema type in which the DITA vocabulary is described by the specification developers. But the DITA Open Toolkit does not allow publishing RNG-based DITA content by default. Installing this plugin developed by Oxygen will make this possible: https://github.com/oxygenxml/dita-relaxng-defaults.

Present Oxygen track changes in the PDF output

This useful plugin developed by Oxygen allows you to preserve Oxygen change tracking highlights in the PDF output: https://github.com/oxygenxml/dita-classic-pdf-review.

Publish DITA to PDF using CSS

The hard thing about the default PDF output is the customization which involves modifying XSLT scripts and having knowledge of both XSLT and XSL-FO. This plugin developed by Oxygen allows you to use CSS to customize the PDF obtained from DITA content: https://github.com/oxygenxml/dita-css. The plugin needs a commercial license of RenderX XEP or Antenna House in order to produce the PDF: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/ditamap-pdf-css-x-dita2.html. But for Oxygen XML Editor 19 we are actively working on a PDF CSS engine which will allow the plugin to work from Oxygen without any additional licenses: http://archive.xmlprague.cz/2017/files/presentations/css2pdf-xslfo.pdf.

A list with all open-source DITA OT plugins developed and shared by Oxygen XML Editor can be found on GitHub: https://github.com/search?q=topic%3Adita-ot-plugin+org%3Aoxygenxml&type=Repositories. My DITA OT Day 2016 presentation covers most of these: https://www.oxygenxml.com/events/2016/dita-ot_day.html#Seven_Open-Source_DITA-OT_plugins.

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.