Login
Home CMS Documentation Home CMS 10 DITA Processing Pipeline DITA Preview and XML Previewing DITA Views

Previewing DITA Views

Users can preview DITA content views within the DITA Preview tab.

Version Notes: CMS 10.6.378 vs. CMS 10.6.308–10.6.342
Versioning functionality differs between CMS 10.6.378 and CMS 10.6.308–10.6.342.

  • In CMS 10.6.378, dependencies and content changes are accounted for based on the DITA asset's latest content version and versions marked to publishing targets. To preview DITA content based on map version, you can use the Dependency Version drop-down list in the Select DITA Preview Generation Scope dialog.

  • In CMS 10.6.308–10.6.342, dependencies and content changes are only accounted for based on the current version of the DITA asset item. If you make and save changes to an asset item's content and dependencies, the DITA preview is generated to reflect the new changes, no matter if the asset is checked in or out. If you mark an older version of the DITA asset item for publish, the DITA preview will not account for the content and dependencies in that version.

See CMS DITA Versioning Functionality for more details about CMS 10.6 versioning functionality changes.

To preview DITA content:

  1. Navigate to Assets > Assets Tree.
  2. Select a DITA map or topic in the Assets Tree.
    The DITA content displays in the main Assets pane.
  3. Select the DITA Preview tab.
    The Select DITA Preview Generation Scope dialog displays.

    Select DITA Preview Generation Scope Dialog

  4. Choose one of the following options from the Dependency Version drop-down list:
    Version Notes: CMS 10.6.378

    The Dependency Version drop-down list is exclusive to CMS 10.6.378. If you have CMS 10.6.308–10.6.342, skip this step.

    In CMS 10.6.378, you can preview DITA content based on the latest version or based on a publishing target.

    OptionDescription
    Latest VersionThe DITA preview will be generated based on the latest content version of the DITA asset.
    Note
    This option includes any content or dependency changes that have been saved but have not been checked in to the DITA asset.
    Name of Publishing TargetThe DITA preview will be generated based on the version of the asset item marked to the publishing target you select from this drop-down list.

    In the drop-down list, the publish icon displays next to publishing target options.

    Also, keep in mind that if the latest version of the DITA asset is marked to a publishing target, the CMS will only account for the latest checked-in changes marked to that publishing target.
    Troubleshooting
    The Dependency Version drop-down list only displays the publishing target selected in the Site Tree or Assets Tree. If your publishing target is not in this drop-down list, ensure the target is selected in the tree and then return to this dialog.
  5. Select a DITA map scope option for your preview.

    This selection determines which maps that the DITA-OT includes in the transformation process for the DITA preview generation. The DITA map scope list includes the following details.

    Data Type

    Description

    Map Scope

    The top-level map that will undergo the DITA-OT process for the preview generation. The DITA-OT executes the transformation process on all descendent content dependencies referenced within this map.

    Important
    Generating the preview from the top-level DITA map will generate the most accurate preview, as the top map covers the most dependencies. However, the completion time for the DITA-OT process takes longer.

    If you generate the preview from ancestor maps closer (in dependency distance) to the currently selected asset, the process will take less time.

    Coverage

    The total amount of dependencies within the respective DITA map. When the map undergoes the DITA-OT preview transformation, the system processes all the descendent content referenced within this map.

    Distance

    The dependency distance between the currently selected DITA item and the respective DITA map entry.

    Pre-Rendered

    If a check mark displays, then the respective DITA map has an existing, up-to-date preview cache. This indicates that the system will load the cached preview rather than running a new DITA-OT transformation.

    See Clearing DITA Preview Cache for details to clear the cache.

  6. Optional: Select a DITAVAL to include in the DITA-OT preview transformation via the Select DITAVAL drop-down list.
    Note
    Select the No DITAVAL option to exclude DITAVALs from the DITA-OT preview transformation.

    See DITAVAL Management for details about DITAVALs.

  7. Select Preview in the dialog.
    Note
    Keep the following in mind:

    • The DITA-OT transformation process takes time to generate the DITA preview.

    • You can select Cancel Preview to cancel the DITA-OT transformation process at any time in the Generating DITA Preview... pop-up message that displays.

    If the map scope does not have an available up-to-date preview cache, then the DITA-OT transformation process runs, and the real-time DITA-OT process details display in the Log screen.

    DITA Preview > Log Screen

  8. Keep the DITA Preview tab open, and wait for the preview to generate.
    When the process completes, the system displays the Preview generated message along with the total build time for the DITA-OT transformation. Also, the DITA Preview tab switches to the Content screen, where the completed DITA content preview displays.

    DITA Preview > Content Screen

    Troubleshooting
    If the DITA-OT transformation starts but the process does not successfully complete, then the DITA Preview tab remains in the Log screen view, and the Errors navigation tool displays in the DITA Preview tab toolbar.

    Use the toolbar Error arrows to navigate errors within the log. Select the left arrow to navigate to the previous error, and select the right arrow to navigate to the next error.

    To download the log, follow the step directly below.

    DITA-OT Log Errors

  9. Optional: If the system ran the DITA-OT transformation process instead of using an existing cache for preview generation, you can download the transformation log details by completing the following steps.
    1. Select the Log option in the DITA Preview tab toolbar.
      The Log screen displays.
    2. Select Download Log in the DITA Preview tab toolbar.

Task Troubleshooting: If you encounter errors or other issues with DITA Preview, see Troubleshooting DITA Preview Issues for troubleshooting information.

Version Notes: CMS 10.6.378
If you run the preview based on a publishing target and an error displays indicating unmarked dependencies, then mark the dependencies to the publishing target (or remove the dependencies from the appropriate version of the dependency structure). The preview will not process until all map scope dependencies are marked for publish.

See DITA Preview Unmarked Dependency Error for details.

Next Steps (optional):

  • You can adjust the DITA map scope settings and regenerate the DITA preview as needed. Select the Preview button in the DITA Preview tab toolbar, and follow the steps above to repeat the preview process.
  • You can use the DITA Preview tab toolbar to emulate previews for individual hardware devices, set advanced preview settings, and perform other actions. See DITA Preview and XML Toolbar for details.
  • You can view details about previous DITA-OT transformation processes in the DITA logs. See Publishing Monitor for details.