DITA Preview and XML


Prerequisites:


Users can apply the installed DITA-OT to generate previews and associated XML content. Each DITA asset contains a DITA Preview tab and an XML tab.

This topic includes:

DITA-OT Transformation Process

The DITA Preview and XML tabs share similar transformation processes. Each tab uses the DITA-OT for preview generation.

When users select the DITA Preview or XML tab on a DITA asset item, the system automatically displays DITA map options that users can choose to determine the map scope for the DITA preview generation. This "map scope" specifies the top-level DITA map from which the DITA-OT will run the transformation process.

The system also provides optional DITAVALs that users can apply to the DITA-OT transformation for conditional processing. See DITAVAL Management for details about DITAVALs.

When the DITA-OT transformation process executes, the process automatically uses the normalized DITA transformation output format. Other factors include:

  • The user's map scope selection.
  • The user's DITAVAL selection.
  • The administrator's DITA-OT parameter settings.

    See DITA Open Toolkit Parameters for details.

  • The administrator's chosen page schema that renders the DITA asset content.

    See the prerequisite above.

As the process runs, users can view the log details and DITA-OT transformation commands in the Log screen.

Note
If errors occur, users can navigate to the errors directly within the log. These errors display with red text.

When the process completes, the tab switches to the Content screen where users can view the generated preview.

DITA Preview Tab

Similar to the Preview tab for site pages , the DITA Preview tab renders a visual preview of the views associated with the currently selected DITA asset. The preview provides context for how the content will display when the DITA asset is published to the DSS. In this view, all navigation and links within the map scope display and work as they will when the DITA asset and nested dependencies are published to the live site.

See Previewing DITA Views for details to generate previews for DITA asset views.

XML Tab

Rather than rendering a visual preview like the DITA Preview tab, the XML tab renders the raw preview XML that correlates with the DITA asset views and content. The system generates the preview XML after the DITA-OT transformation process completes.

See Previewing DITA Raw XML for details to generate preview XML content for DITA assets.

Preview Cache

The CMS automatically caches generated previews after DITA preview transformation processes complete in the DITA Preview and XML tabs. When users generate another preview for the same DITA asset file, then the system automatically loads the cached preview instead of processing a new one.

If map scope option's Pre-Rendered column displays a checkbox in the Select DITA Preview Generation Scope dialog, then the map scope has an existing preview cache.

Note
Administrators can configure DITA Advanced Options to manage the maximum amount of cached previews that the CMS stores.

By loading pre-rendered previews, users bypass the DITA-OT transformation process load times. If the preview cache becomes outdated, use the Clear Preview Cache feature to delete all cached previews associated with individual DITA assets.

See Clearing DITA Preview Cache for details to delete cached DITA previews.