Using DITAVAL Files
Arbortext Editor provides support for conditional processing as defined in the Conditional processing (profiling) section of the OASIS DITA Architectural Specification. Conditional processing is defined in a DITAVAL file, which you can specify when publishing a DITA map or topic in the DITAVAL File option on the publishing dialog boxes. Arbortext Editor also supports referencing a DITAVAL file in a DITA map, so that the file’s conditional processing actions are applied to all or part of the map during publishing. You can use DITAVAL files and profiling configuration files (.pcf) at the same time, but DITAVAL file actions are processed before any profiling is applied.
Actions defined in DITAVAL files are based on values assigned to the following DITA conditional processing attributes:
• audience
• platform
• product
• otherprops
• rev
Note that the rev attribute can only be used for flag actions.
• props
Specialized attributes based on props can also be used in DITAVAL files. Note that the props attribute is not available in the Arbortext Editor user interface by default.
A DITAVAL file contains a series of prop elements that define conditional processing actions in an action attribute. The following actions are available:
• include — Include the elements with the specified attribute and value in processing.
• exclude — Exclude the elements with the specified attribute and value from processing.
• flag — Flag the elements with the specified attribute and value during processing.
The text in an element can be highlighted in various ways, assigned a color and background color, or have a graphic appear before or after the text.
The prop element contains other attributes to define the attribute and value to which the action applies and to provide details about the type of flagging desired. Refer to the Darwin Information Typing Architecture (DITA) Version 1.2 OASIS standard in the Arbortext Editor help for more information about DITAVAL files.
Editing a DITAVAL File
The New Document dialog box lists DITAVAL file in the DITA Technical Content category. You can edit a DITAVAL file in Arbortext Editor using Column view. However, Arbortext Editor provides the DITAVAL Editor dialog box to assist you with developing DITAVAL files.
Following is how a DITAVAL file appears in Arbortext Editor:
The DITAVAL Editor dialog box enables you to edit a DITAVAL file without knowing the specific settings required in the file. The dialog box also shows you how other values for a conditional processing attribute that are not specifically defined in the file are handled during publishing. You open the dialog box from a DITAVAL file by choosing > . You can also open the dialog box when editing a DITA map or topic from the > submenu.
Following is how the same file appears in the DITAVAL Editor dialog box:
The following additional menu choices are available when you are editing a DITAVAL file in Arbortext Editor:
• >
— Enables you to import set profile groups from an existing .pcf file into a DITAVAL file.
• >
— Opens the DITAVAL Editor dialog box for the current DITAVAL file.
• >
— Enables you to select a DITA topic or map and preview the actions defined in the current DITAVAL file.
The following DITAVAL file related menu choices are available when you are editing a DITA topic or map:
• > > — Enables you to select a DITAVAL file and preview the actions defined in the file for the current document.
• > > — Opens the DITAVAL Editor dialog box for a new DITAVAL file using the settings in any .pcf file associated with the current document.
• > > — Opens the DITAVAL Editor dialog box for an existing DITAVAL file merging the settings in the DITAVAL file with those in any .pcf file associated with the current document.
DITAVAL files are further supported in the user interface in the following ways:
• When you are using the Resource Manager to assign a value to the href attribute for a data element, DITAVAL is provided as a choice in the Type option.
• When you select a DITAVAL file for the href attribute in this case, the data element’s name attribute is also set to the value ditavalref.
• When you have a DITAVAL file assigned to a DITA map, the DITAVAL reference is labeled DITAVAL Reference in the Outline column in the Column view of the map.
• When you open the resolved document for editing for a DITA map containing DITAVAL references, any DITAVAL actions assigned to topic references in the map are done. For example, if a topic reference has an exclude action assigned to it, that topic is not included in the resolved document.
• DITAVAL references are checked as part of the enhanced completeness checking for DITA documents.
Assigning a DITAVAL File to a DITA Map
You can assign a DITAVAL file to both an entire DITA map and to individual parts of a map. DITAVAL files are referenced from the data element inside of the topicmeta element. In the data element, set the name attribute to ditavalref and the href attribute to the location of the DITAVAL file. The DITA references path is used to resolve DITAVAL file references.
To associate a DITAVAL file with an entire map, add the reference to the topicmeta element at the highest level of the map. To associate a file with just part of the map, add the reference to the topicmeta element in a topicref element (or a specialization of topicref) inside of the map. In this case, the DITAVAL file will apply to just that topic reference and any topic references contained in that topic reference.
You can have more than one DITAVAL file reference in a map. If the settings defined in multiple DITAVAL files do not conflict, then all of the actions defined in the files are performed. If the settings defined in the files do conflict, then the following rules are used to resolve the conflict:
• A DITAVAL file provided in the DITAVAL File option on a publishing dialog box always takes precedence.
• A DITAVAL file assigned to the map as a whole takes precedence over a file assigned to a part of the map.
• If two DITAVAL files are at the same level of the map, the first file referenced in the map takes precedence.
The data element also has a keyref attribute, so you can use a key reference for a DITAVAL file.
Debugging DITAVAL Files
Arbortext Editor enables you to preview the effect of actions defined in a DITAVAL file in the DITAVAL Preview Window. For a DITAVAL file, you can open the DITAVAL Preview Window by choosing > . For a DITA map or topic, you can open the preview window for the current document by choosing > > . If the current document is a DITA map, you are asked whether to open the map or the Resolved Document for Styling for the map.
How the applied DITAVAL rules are displayed is determined by the setting of the ditavaldebug advanced preference. By default, the previewed document just displays the results of applying the current DITAVAL file settings. If you set ditavaldebug to on, the following additional information is displayed in the DITAVAL Preview Window:
• A comment is inserted at the beginning of the document listing all of the DITAVAL files used to process the document.
• A comment is inserted before any affected elements describing why the content was included, excluded, or flagged. The comment includes the location of the DITAVAL file that the rule came from along with a description of the rule.
• All excluded text is displayed in strikethrough with red text and a yellow background.
You can use this information to debug any issues with your DITAVAL files.
Related information
