DITA Processing Pipeline in Ingeniux CMS

Overview of the DITA Processing Pipeline in Ingeniux CMS | Describes how DITA content moves through authoring, normalization, synchronization, and other downstream processes.


The Darwin Information Typing Architecture (DITA) is not only a powerful open standard for writing, editing, and reviewing content. It also offers a high-level of versatility in how content can transform to meet the needs of your organization and its information consumers. Ingeniux CMS provides an end-to-end DITA solution for customers who exclusively author, manage, and publish DITA content and for customers who integrate DITA content with non-DITA document types.

The figure below provides a visual demonstration of how customers work in DITA and how the DITA processing pipeline works within Ingeniux CMS.

DITA Processing Pipeline in Ingeniux CMS

  1. DITA Assets reside in AssetsAssets Tree and are checked into and out of Ingeniux CMS.
  2. Writers create and update DITA content within their preferred XML Editor.
  3. Writers execute the normalization build on DITA maps and referenced DITA topics in the CMS.
  4. The DITA Open Toolkit (DITA-OT) normalizes map references, keys, content references, code references, etc.
  5. The system executes automatic page creation and synchronization processes.
  6. Pages containing DITA content continue through standard CMS tracking, tagging, and workflow operations to their publication.

Migrating Content to DITA

Ingeniux CMS provides DITA solutions for customers who already author and publish DITA and for those customers who first need to migrate their current content to DITA. If your content is in a non-DITA format and your organization plans to migrate to DITA, the Ingeniux Services team can help you with the transformation process. For customers who already author in DITA, you can upload your DITA content to the CMS Assets Manager.

Managing DITA Assets

Once uploaded to Assets Manager, your DITA topics, ditamaps, and associated files receive unique identifiers. These IDs help Ingeniux CMS to keep track of your DITA objects and their life cycles within the CMS, no matter if you rename your files or move them to different locations in the Assets Tree. Once in Assets Manager, the CMS help you manage version histories, access level permissions for users and groups, life-cycle workflows, translation projects, and other essential source management operations.

Editing DITA

Ingeniux CMS integrates with the following XML editors for a seamless authoring experience:

  • Fonto Editor: Fonto is a highly configurable structured-content editor with a clean user interface similar to Microsoft Word. Fonto displays within the Assets Manager as an integrated tab. Writers check out DITA assets and begin working on DITA content from this Authoring tab.
  • Oxygen XML Web Author: Like Fonto, Oxygen XML Web Author is a web-based XML editor that resides within the CMS Assets Manager. It too can be accessed through the Authoring tab. This editor provides a user-friendly experience and may benefit customers who do not require the full suite of authoring and development tools of its desktop cousin, Oxygen XML Editor.
  • Oxygen XML Editor: This desktop XML editor benefits customers who require the full compliment of authoring and development tools or who prefer to work more closely with the DITA markup. From Oxygen XML Editor, writers connect to the Ingeniux CMS Assets Manager for a tightly-integrated authoring experience.

Normalization

Before DITA source enters the Ingeniux CMS publishing pipeline, map references, keys, content references, code references, etc. must resolve. CMS pages are created to contain the resolved DITA content.

The DITA Open Toolkit (DITA-OT) is an open-source publishing engine for content written in DITA. Ingeniux CMS incorporates the DITA-OT to preprocess DITA content on its way through the Ingeniux CMS publishing pipeline. This preprocessing step called normalization results in normalized DITA. The DITA-OT documentation provides a summary of how the normalization build transforms the source DITA to its intermediate form:

  • References from one DITA map to another are resolved.
  • Map-based links, such as those generated by map hierarchy and relationship tables, are added to the topics.
  • Link text is resolved.
  • Map attributes that cascade are made explicit on child elements.
  • Map metadata such as index entries and copyrights are pushed into topics.
  • Topic metadata such as navigation titles, link text and short descriptions are pulled from topics into the map.
  • XML comments are removed.

Writers execute the normalization build on the root DITA map of documentation sets from the Assets Manager. As long as the root DITA map and all child maps and topics are valid, DITA source can be normalized. Moreover, normalization is a repeatable process, so DITA source that is continually updated can be pushed forward at any point in authoring cycle.

Note: Keep in mind that the normalization build is a DITA-to-DITA transformation, which results in fully resolved and expanded XML. It is not the final presentation rendition.

Page Creation and Synchronization

When the incoming DITA source normalizes, Ingeniux CMS automatically creates new pages as needed to contain the new normalized content and also updates normalized content within existing pages (i.e., content that already underwent normalization and page creation during a previous build). After this page creation/sync process completes, the normalized DITA content resides in a dedicated field within pages in SiteSite Tree.

DITA Content Integration

Once DITA content integrates into the Site Tree, content creators and CMS administrators can conduct any further downstream processes (e.g., taxonomy categorization, publishing to website, etc.) just as they would for any pages in Ingeniux CMS.