DITA Open Toolkit Project

The DITA Open Toolkit project file allows you to define all your DITA map input and filter pairs and to produce the desired output formats by applying the publishing engine over this single project file: https://www.dita-ot.org/dev/topics/using-project-files.html.

Oxygen XML Author Eclipse plugin has special support for creating, editing, validating, and publishing DITA Open Toolkit project files represented in XML format. It can also use such files to detect connections between DITA resources in the entire project and to apply root map and filter pairs when editing.

Parent topic: DITA Open Toolkit Support
Previous topic: Using an External DITA Open Toolkit in Oxygen XML Author Eclipse plugin
Next topic: DITA Specialization Support

Editing DITA Open Toolkit Project Files

The New Document wizard includes a template to help you create DITA Open Toolkit project files (with an .xml file extension). The template is located in the Framework templates > DITA-OT folder. There is also a sample project file that can be found in the application samples folder: OXYGEN_INSTALL_DIR/samples/dita/mobile-phone/mobilePhoneProjectFile.xml.

When working with a DITA-OT project file in the Author visual editing mode, you can see a compact representation of the file by default. You can switch to the Edit style in the Styles toolbar drop-down menu to edit the file using form controls and inline buttons. The additional View as YAML style can be selected to see a visual representation of the same document in YAML. Content for all additional project files included in the current edited file will appear expanded in place. The included content is read-only by default but can be directly edited if the Allow referenced content to be edited checkbox is selected in the Options > Preferences > Editor > Edit Modes > Authorpreferences page.

DITA-OT Project File Content Completion

Content completion is available according to the associated schema and it is enhanced with proposals for ID references, available transformation types, parameter names, and values.

DITA-OT Project File Validation

The default automatic validation support for DITA-OT project files has enhanced Schematron rules that report invalid references to non-existing contexts. The default validation is based on a validation scenario named DITA-OT Project that in included in the DITA-OT project framework.

The DITA-OT Project framework also includes a validation scenario named DITA-OT Project Validation and Completeness Check. It contains validation units that automatically validate the project file based on the DITA-OT Project scenario and also a manual validation unit based on the DITA-OT Project Validation and Completeness Check validation engine that validates all contexts recursively.

When creating a validation scenario, or editing an existing scenario for a DITA-OT project file, you can select DITA-OT Project Validation and Completeness Check engine in the Validation engine column and clicking the Settings button for that engine opens the Configure validation engine dialog box where you can configure options for validating the DITA-OT project.

Figure 1. Configure Validation Engine Dialog Box for DITA-OT Project Validation

The options available in this dialog box include:

Batch validate referenced DITA resources
This option specifies the level of validation that applies to referenced DITA files:
  • If the checkbox is left unchecked (default setting), the DITA files will be validated using the rules defined in the DTD or XML Schema declared in the document.
  • If the checkbox is selected, the DITA files will be validated using rules defined in their associated validation scenario.
Check the existence of non-DITA references resources

Extends the validation of referenced resources to non-DITA files.

Include remote resources
Select this option if you want to check that remote referenced binary resources (such as images, movie clips, ZIP archives) exist at the specified location.
Report references to resources outside of the DITA map folder
If selected, it will report any references to DITA resources that are located outside the main DITA map folder.
Report links to topics not referenced in DITA maps
Checks that all the topics referenced by other topics are also linked in the DITA map. Also reports related links defined in relationship tables whose target topics are not referenced in the DITA Map.
Report multiple references to the same topic

If selected, it will report warnings when a topic is referenced multiple times in the DITA map, unless a unique @copy-to attribute is used on the <topicref> element for any topic that is referenced multiple times.

For example, it will not report a warning if there is a topic referenced twice, but the second <topicref> has a @copy-to attribute set:
<topicref href="topic.dita"/>
.....
 <topicref href="topic.dita" copy-to="topic2.dita"/>
On the other hand, it will report a warning if there is a topic referenced twice and none of the reference-type elements has a @copy-to attribute set or both of them have the @copy-to attribute set to the same value:
<topicref href="topic.dita" copy-to="topic2.dita"/>
......
 <topicref href="topic.dita" copy-to="topic2.dita"/>
Check for duplicate topic IDs within the DITA map context
Checks for multiple topics with the same ID in the context of the entire map.
Report duplicate key definitions

Checks the DITA map for multiple key references with the same key defined for them. This is helpful because if you have two different resources with the same value for the @keys attribute, all references will point to the first one encountered and the other will be ignored.

Note: This option takes key scopes into account. For example, if you have something like this:
<topicref href="t2.dita" keys="k2"/>
    <topicgroup keyscope="ks">
        <topicref href="t2.dita" keys="k2"/>    
    </topicgroup>
it will not report the "k2" key as a duplicate because it is defined in a key scope on the second occurrence.
Report unreferenced key definitions
Checks the entire DITA map and reports any key definitions that are not referenced anywhere. Note that if the Use DITAVAL filters option is selected, this check will search for unreferenced key definitions based upon your selected filter.
Report unreferenced reusable elements
Checks the entire DITA map and reports any detected reusable elements that are not referenced anywhere. It looks for elements that have an ID specified in the following types of topic references:
  • Any <topicref> that contains a @processing-role attribute set to resource-only.
  • Any other referenced topic that contains elements that are reused elsewhere through a @conref or @conkeyref.
Report table layout problems
Looks for table layout problems. The types of errors that may be reported include:
  • If a row has fewer cells than the number of columns detected.
  • For a CALS table, if a cell has a vertical span greater than the available rows count.
  • For a CALS table, if the number of <colspecs> is different than the number of columns detected from the table @cols attribute.
  • For a CALS table, if the number of columns detected from the table @cols attribute is different than the number of columns detected in the table structure.
  • For a CALS table, if the value of the @cols, @rowsep, or @colsep attributes are not numeric.
  • For a CALS table, if the @namest, @nameend, or @colname attributes point to an incorrect column name.
Identify possible conflicts in profile attribute values
When the profiling attributes of a topic contain values that are not found in parent topic profiling attributes, the content of the topic is overshadowed when generating profiled output. This option reports these possible conflicts.
Report attributes and values that conflict with profiling preferences
Looks for profiling attributes and values that are not defined in the Profiling / Conditional Text preferences page (you can click the Profiling Preferences button to open this preferences page). It also checks if profiling attributes defined as single-value have multiple values set in the searched topics.
Additional Schematron checks
Allows you to select a Schematron file that Oxygen XML Author Eclipse plugin will use for the validation of DITA resources. You can specify the path by using the text field, its history drop-down, the Insert Editor Variables button, or the browsing actions in the Browse drop-down list.
Advanced Tip: Some APIs are available that retrieve information about DITA keys that are referenced within a topic. The APIs can be called from XSLT Stylesheets (including XML Refactoring operations) or Schematron schemas. For details, see API Documentation: DITAXSLTExtensionFunctionUtil.

Publishing DITA Open Toolkit Project Files

Once a DITA-OT project file is opened in the application, two predefined publishing scenarios become available in the Configure Transformation Scenario(s) dialog box:
  • Publish DITA-OT Project (all deliverables) - Runs the publishing engine and produces output for all deliverables defined in the project file.
  • Publish DITA-OT Project (select deliverable) - Runs the publishing engine and produces output for only one deliverable specified by the end-user.
Some of the allowed transformation parameters that are relevant to the DITA-OT project file include:
  • project.file - Specifies the path to the project file.
  • dita-ot.dir - Specifies the directory where DITA-OT, used in transformation is installed.
  • additional.args - Specifies the additional arguments used in transformation.
  • deliverable.id - Specifies the id of the deliverable. This parameter is only available in the Publish DITA-OT Project (select deliverable) transformation.
  • jvm.args - Specifies the JVM arguments used by the transformation for each deliverable. This can be used to increase the memory allocation used by the transformation.
    Example: To set the JVM memory allocation to 5 GB for publishing deliverables, append the following value to the existing ones: 
    -Xmx5G
    If the "pdf-css-html5" (based on Chemistry PDF CSS processor) deliverable publication fails with an Out Of Memory Error, try appending the baseJVMArgLine parameter to the "jvm.args" parameter value. For example:
    -DbaseJVMArgLine=-Xmx5G

When editing DITA OT project files in the Author visual editing mode, each presented deliverable has an inline button that can be used to individually publish it.

Main Files Support for DITA Open Toolkit Project Files

If you enable main files support at project level, you can choose to detect all top-level DITA Open Toolkit project files and to add them to the Main Files folder. You could also manually add the top-level files for your DITA-OT project in the Main Files folder. The benefit of this is that whenever you rename or move files in the Project Explorer view, the references to those resources will automatically be updated.
Tip: The Referenced/Dependent Resources view also works for DITA-OT project files.

Editing Contexts Detected from DITA Open Toolkit Project Files

Once a DITA-OT project file is added to the Main Files folder, the Context drop-down menu on the DITA Maps Manager toolbar will contain context DITA maps defined in the project file and the Profiling/Conditional Text menu will contain filter pairs gathered from the project file. When you select one of them in the drop-down menu, the application gathers the keys from the context DITA map and applies the filters specified in that context.