CMS DITA Versioning Functionality
The DITA dependency system, content versioning, post-publish and preview processing, and alias management functionality differ between CMS 10.6.378 and CMS 10.6.308–10.6.342.
CMS 10.6.308-10.6.342 Functionality
Both CMS 10.6.308-10.6.342 and CMS 10.6.378 account for content changes and dependencies based on the latest version of your DITA content, including any changes you have saved within checked-out DITA content but have not checked in. However, because CMS 10.6.308-10.6.342 only tracks content and dependencies based on the latest version, this means only the latest checked-in version of your DITA content can undergo DITA preview and DITA publishing pipeline processing, regardless of whether you marked a previous content version for publish.
Additionally, alias structures in the CMS 10.6.308-10.6.342 Site Tree always reflect the latest checked-in version of the DITA collection, no matter what version of the DITA content you mark for publish. When you publish the aliased DITA content to a DSS, the alias URLs will reflect this.
CMS 10.6.378 Functionality
The CMS 10.6.378 release introduces functionality that accounts for content changes and dependencies based on the latest version and marked-for-publish versions of your DITA assets, so you can run DITA preview and DITA publish processing on the whichever version of the content you want. This feature is useful for separating draft content from live publishing targets, mark different content changes for different targets, and more.
For example, if the latest version of a DITA map includes a content or dependency change that is excluded from a previous version marked for your publishing target, that change will not be included in DITA Preview, publish, etc. for that publishing target.
Feature benefits include:
- Version control and tracking. Track dependencies, map details, and other content changes based on the content version of your DITA assets directly in the CMS.
- Dependency system enhancements. Include or exclude DITA content and dependencies from individual publishing targets.
- Preview rendering. Preview DITA and raw XML content based on the latest version or based on a version marked to a publishing target.
- Flexible publishing. Run the DITA publishing pipeline only on your marked-for-publish DITA map versions instead of the latest version.
- Alias management. Create, manage, and publish DITA aliases based on marked-for-publish DITA map versions instead of the latest version.
In addition to these updates, the CMS 10.6.378 release provides a new feature to check for any unmarked dependencies before publishing your DITA content. If the latest map version has different dependencies than the version marked for publish, the CMS will only throw an unmarked asset errors on those dependencies included in the marked version.
See DITA Dependency Validity Errors for details.
Dependency Version Terminology
When working with CMS DITA versioning features, you will encounter version types in Dependency Version drop-down filters and in other CMS UI areas.
Keep the following DITA content version types in mind:
- Latest version
- The latest version of the content in a DITA asset, including any changes you have saved within checked-out DITA content but have not checked in. If you mark the latest version of the DITA asset to a publishing target, the CMS will only account for the latest checked-in changes marked to that publishing target.
The latest version always displays at the top of the content version list in the asset's History tab. If the DITA asset is checked out, then a checked-out version will be indicated in the list.
- [publishing-target-name]
- The version of the DITA asset marked to the publishing target. When running DITA-OT publishes, the publishing pipeline will account only for the content changes and dependencies within the marked version.
To see which version of a DITA asset is marked to a published target, go to the asset's History tab and review the Marked Pub Targets column.
- See Diffing Versioned Content for details to compare content versions of the same DITA asset.
- See Marking Assets for Publish to mark or unmark a particular content version of a DITA asset to a publishing target.
Dependency Version Drop-Down List
The 10.6.378 release introduces dependency version drop-down menus across CMS UI areas, where you can choose a dependency version to filter data or view DITA content and dependency structures based on the DITA asset's latest version or a version marked for a publishing target.
For details about DITA dependency features in each CMS UI area, see the sections below.
"Depends On" and "Used By" Dependencies
In the Depends On and Used By tabs of the asset's DITA Properties, use the Dependency Version drop-down menu to filter all dependencies of the DITA asset based on the latest version or a marked version.
- See DITA "Depends On" Properties for details.
- See DITA "Used By" Properties for details.
- If the DITA asset has checked-out dependency changes, these dependency lists account for those changes in the latest version of the DITA asset. However, if the latest version is marked to a publishing target, the checked-out dependencies are not included for that publishing target.
- Before running a DITA preview or publish, you can use the Dependency Version and Show
Errors Only filters in the Depends
On tab to check for any dependencies that are not marked to a publishing
target.
See Checking Dependency Errors for details.
- Dependencies part of the DITA asset's latest version and any version marked to a publishing target cannot be deleted.
Map Details
The Map Details tab in the map's DITA Properties tab provides drop-down menu to filter map data based on the latest version or a marked version.
- See DITA Map Manager's Details View for details.
- See DITA Properties Map Details View for details.
DITA Preview and XML
The DITA Preview and XML tab of DITA assets provides the Dependency Version drop-down menu in the Select DITA Preview Generation Scope dialog. Use this menu to choose whether to preview normalized DITA content and expanded XML based on the latest version of a map or based on a map version marked to a publishing target.
- See Previewing DITA Views for details.
- See Previewing DITA Raw XML for details.
- DITA Preview renders based on whether you choose the version of the map scope marked to the publishing target or based on the map scope's latest version. If you run a DITA preview directly from a DITA topic, the latest version option will preview the topic content based on latest version of the map scope and of the topic itself. If you choose a publishing target option, the preview will generate based on the map's dependency version and the topic's dependency version marked for that publishing target.
- If you run DITA Preview based on a publishing target, ensure all dependencies included in the map scope are marked to that publishing target. Otherwise, stopping "unmarked asset" errors will occur, preventing the preview from processing.
Alias Management
When you create, manage, preview, and publish alias structures in CMS 10.6.378, they will reflect the version of the DITA map's dependency structure marked to the publishing target. Generated alias URLs will also reflect this.
You can filter the dependencies included in the alias structure marked for each publishing target by using the publishing target drop-down list in the Site Tree.
See DITA Aliases for details.