parson AGPublish DITA content at the click of a button: the DITA Open Toolkit
Corresponding parson service: DITA-XML for technical documentation
Do you write and publish technical documentation in DITA-XML? It sounds easy: At the click of a button, an XML authoring tool or a web application magically creates a PDF, HTML documentation or WebHelp. But is it really that simple? What happens under the hood? And what if you want to customize the output formats?
The answer is the DITA Open Toolkit (DITA OT). In this article, we will introduce you to this small but powerful tool that converts your DITA XML documentation into the output format of your choice.
DITA XML and DITA Open Toolkit
DITA is an XML standard with a defined syntax or element structure that is supported by many XML authoring tools, such as Oxygen XML Author/Editor. Many organizations use XML authoring tools to write, edit, and review technical documentation. Although you can write DITA XML without such a tool, an XML authoring tool provides so many useful features, such as authoring support and automatic validation, that it is not worth it.
However, the DITA XML standard does not define how to convert the created content into a format that customers expect, that web applications can render, or that is easy to read. This is where the DITA OT comes in.
What is the DITA Open Toolkit?
DITA OT is a toolkit that allows you to transform DITA content into various output formats. DITA OT also provides a technical implementation of the DITA architecture in the form of Document Type Definitions (DTDs), XML Schemas (XSD) or Relax NG (RNG). These schemas guide the authors and ensure that their content is valid DITA.
Many authoring tools and content delivery portals support the DITA OT out-of-the-box. That means you can use the DITA OT to customize your output formats and schemas and then integrate the DITA OT with your customizations in the authoring tool or content delivery portal. Here are the key features of the DITA OT:
- Free and vendor-independent. The DITA OT can be used anywhere and by anyone.
- Open source. The DITA OT is maintained and developed by a small, independent group and a larger community on GitHub.
- Supports multiple output formats including HTML, PDF, Markdown, and WebHelp.
- Includes the core technologies Java, ANT and XSLT. PDF can be generated out-of-the-box using the free XSL-FO processor Apache FOP.
- Scalable. New or customized output formats and schemas can be integrated via the plug-in mechanism.
DITA OT as a command-line tool
DITA OT is a pure command-line tool. You can run it, interact with it, and generate output without using an XML authoring tool – even though this method lacks convenience features. The only requirement is an existing Java runtime environment.
Integrating DITA OT with XML authoring tools like Oxygen
One of the most common DITA authoring tools is Oxygen XML Author or Oxygen XML Editor. The tool comes with a DITA framework with integrated DITA OT that lets you create and publish your DITA documents directly in the Oxygen environment.
For the different output formats, Oxygen offers so-called transformation scenarios that allow you to adapt the output of DITA content to the requirements of a project. Transformation scenarios can be configured directly in Oxygen using various parameters and stylesheets. There is also a transformation type that accesses the plug-ins in DITA OT. In addition to the standard output formats of the DITA OT, Oxygen provides a number of custom formats, such as a WebHelp.
Some authoring tools and component content management systems provide their own publishing pipelines for DITA to PDF, such as Adobe FrameMaker, IXIA CCMS or Tridion Docs. Because these authoring tools cost money and the pipelines are designed specifically for that tool, they are not as widely used as the DITA OT.
How do I customize the DITA OT output formats?
Depending on the transformation type and use case, you can customize the output formats directly in Oxygen or in the corresponding DITA OT plug-in. The latter makes sense, for example, if you want to use DITA OT outside of Oxygen too.
To customize your output formats in the DITA OT, you need to configure separate plug-ins. Within these plug-ins, you can customize the formats and layout of your output format such as colors, column widths, font size or spacing in PDF or HTML. Depending on the format, you need to know XSLT, XSL-FO, or CSS.
Such a plug-in makes you system-independent. Once integrated into the DITA OT, you can generate the appropriate output format directly.
Customize the DITA architecture with the DITA Open Toolkit
The DITA standard provides elements and structures for topic-based authoring. It provides support for semantic elements and topic types from various domains. Authors are often overwhelmed when it comes to selecting the right structure and markup elements because there are so many options to choose from. The DITA standard makes it possible to limit the number of available options or to define new elements and attributes.
Also for customizing the DITA architecture, DITA OT plugin-ins are used. First, you select one of the following document definition types:
- DTD offers the broadest tool support, but is a bit cumbersome to customize.
- Relax NG is the normative grammar of the DITA standard and is relatively easy to learn, but is still not supported by many tools.
- XML Schema is about as simple as Relax NG, but is no longer supported as of DITA 2.0.
You then create your own plug-in for your custom schemas, similar to the output formats, and override the standard schemas in that plug-in. The greatest challenge here is to understand the complex DITA architecture and not accidentally break it.
Example of a DITA OT plug-in implementation
parson has helped many customers to create and implement their own DITA OT plug-ins. These projects often include not only the initial setup, but also ongoing customization, such as layout or CI changes, technical updates, or functional enhancements. One of our customers is Nexperia, a semiconductor manufacturer, who writes documentation in DITA-XML and publishes the data sheets as PDFs.
Learn more in the customer reference.
We are experts for DITA-XML and DITA OT
Would you like to use DITA-XML for your technical documentation or do you need plug-ins for the DITA Open Toolkit? We will find your individual DITA solution!
Add new comment