Unexpected DITA Publishing Output Results
When users execute a DITA-OT publish on a DITA asset collection, the system generates unexpected output file results in the CMS pub folder.
Unexpected output results may include but are not limited to the following:
- The DITA output files do not reside in the expected DITA output file architectural structure.
- The DITA output files contain other asset files not included in the publish.
- The DITA output files have missing content. This can include missing asset files or missing content within asset files.
- The views associated with the DITA output do not display the content correctly.
- The JSON associated with the DITA output did not process correctly.
A spectrum of issues can cause the DITA-OT transformation to generate unexpected output file results. 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 the unexpected output generation.
Output Issue Diagnosis
To diagnose the issue:
- Double-check your DITA publishing setup. Also, if applicable, double-check your
views setup and JSON processor setup.Ensure the appropriate settings were in place when the system executed the DITA publish.
See the DITA Publishing Pipeline Troubleshoot Checklist to double check your DITA administration settings and DITA publishing settings.
- Run debug mode to include debugging details in the next DITA publish log.
See Running DITA Debug Mode for details.
- Apply the same DITA publishing settings used when you encountered the unexpected
output, and run the DITA publish process again. Check the DITA log for errors.
These errors may provide details about where the conflict resides and what the conflict entails.
See Checking DITA Publish Logs for Errors for details.
- Check the CMS publishing log for errors and to review the output files generated
during the DITA publish post processing.
See Running the DITA-OT Locally Outside the CMS for details.
- Check the DITA output directory to review the output files within the CMS site
directory.See Checking DITA Publishing Output Directory for details.NoteIf the DITA logs indicate the DITA-OT transformation process failed in the Has Errors column, then skip this step.
- Review the DITA temp folder for discrepancies within the temporary files that may
relate to the issue.
See Checking DITA Temp Folders for details.
- If you discover errors within the logs, decipher them to determine what the
See Deciphering DITA Log Errors for details.
Address Output Issues
Use the information you gathered from troubleshooting to resolve output issues.
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 setup, views setup, or JSON processor setup, then make adjustments to 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 output
format, then do one of the following:
- Choose another output format provided by the standard DITA-OT that resolves the issue.
- Provide your own custom output format 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, republish the DITA asset collection, and then review the DITA logs and output files to see if the output files generate as expected. If you still encounter issues, try another solution or contact Ingeniux Support.