Home CMS Documentation Home CMS 10 DITA Processing Pipeline Troubleshooting DITA Collections DITA Preview Issues Unexpected DITA Preview Output Results

Unexpected DITA Preview Results

Condition

When users execute a preview on a DITA asset, the system generates unexpected preview views or XML content in the DITA Preview and XML tabs.

Unexpected preview results may include but are not limited to the following:

The DITA preview has missing content in the rendered view.
The DITA preview does not display the content correctly.
The dependency links within the DITA preview do not resolve to the appropriate target.

***Troubleshooting Unexpected DITA Preview Results***

Cause

A spectrum of issues can cause the DITA-OT transformation process to generate unexpected DITA preview output results in the DITA Preview and XML tabs. These issues can vary depending on factors involved. Keep in mind that these steps provide general guidelines and direction for pinpointing and resolving a wide range of issues that may cause unexpected DITA preview output.

Error Issue Diagnosis

Administrators can double-check the DITA publishing pipeline setup and run debug mode. Users with asset editing permissions can execute DITA preview, view the results, and review log and temp entries.

Identify the issue that causes the unexpected DITA preview results.

To diagnose the issue:

Double-check your DITA publishing setup.
Ensure the appropriate settings were in place when you executed the DITA preview.
See the DITA Publishing Pipeline Troubleshoot Checklist to double check your DITA administration settings and DITA publishing settings.
Important
Check these settings in particular:
Ensure all Normalization Output Format settings are configured. Ensure the Rendering Schema for DSS field references the correct page schema. See Configuring DITA Open Toolkit Output Formats for details.
Ensure the DITA processor includes the normalized DITA output format, and ensure the normalized DITA output format has a partial match string in place for rendering the normalized DITA on the DSS.
Run debug mode to include debugging details in the next DITA preview log.
See Running DITA Debug Mode for details.
Execute the DITA preview in the DITA Preview or XML tab, and check the DITA log to see if you run into errors.
These error entries may provide details about where the conflict resides and what the conflict entails.
See Checking DITA Preview Logs for Errors for details.
Check the DITA Preview or XML tab to review the output results.
Note discrepancies, errors, or missing content that display in the preview. If no errors display in the DITA logs, then the issue may relate to the view stylesheet associated with the DITA page rendering schema.
See Checking DITA Preview Output for details.
Review the DITA temp folder for discrepancies within the temporary files that may relate to the issue.
See Checking DITA Temp Folders for details.
Interpret the log entry errors to determine what the conflicts entail.
See Interpreting DITA Log Errors for details.

Address Error Issues

Administrators can modify the DITA publishing pipeline setup and settings related to the DITA-OT. Users with asset editing permissions can resolve conflicts with DITA asset content and their dependencies, and they can modify settings applied at DITA preview time.

Use the information you gathered from troubleshooting to resolve DITA log entry errors.

The following list provides potential solutions to address your issue. Keep in mind that you may uncover alternative solutions not provided in this list.

If your issue relates to the DITA publishing pipeline setup, then adjust your setup settings as needed.
If your issue relates to a dependency error, where you can resolve the issue by restoring a missing file or by modifying the dependency reference in your DITA asset content, then apply fixes to the affected DITA assets as needed.
If your issue relates to a DITA specification validation error, where you can resolve the issue by making changes to your DITA asset content, then check out the affected DITA assets and apply fixes as needed.
If your issue relates to DITA-OT output formats, where you can resolve the issue by changing the normalized DITA output format, then choose another normalization output.
Note
The DITA-OT provides only one normalized DITA output format per version. You may need to provide your own custom normalization output plugin that resolves the issue.
If your issue relates to DITA-OT parameters, where you can resolve the issue by changing parameter settings, then modify parameters for the CMS DITA-OT as needed.
If your issue relates to the DITA-OT version, then do one of the following:
- Install a different DITA-OT version that better suits your organization's needs than the currently installed version.
- Install a custom DITA-OT engine that suits your organization's needs.
- If your issue is an unresolved DITA-OT bug, report the issue via GitHub: DITA-OT Issues.
If your issue relates to something else, or if the solutions above do not suffice, then contact Ingeniux Support.

After implementing your solution, preview the DITA asset again, and then review the DITA logs to see if the DITA preview logs contain errors. If issues persist, try another solution, or contact Ingeniux Support.

Unexpected DITA Preview Results

Table of Contents Release Notes Search

Table of Contents