Tips for filtering and conditionalizing content in topic files or maps.
DITA-FMx provides many ways to filter the content in your DITA files. The auto-conditionalizing options apply conditions to elements each time you open a file, and the Apply Ditaval command filters content by applying include or exclude actions (as defined in a ditaval file) based on attribute values. Ditaval filtering can be used on files while authoring (not recommended) and can be applied to the generated files in a book build. You can also achieve filtering when generating a book from a map by modifying the Book application’s read-write rules.
There are five options for applying conditions to elements on file open. The Conditionalize prolog, Conditionalize comments, and Conditionalize required-cleanup options apply the DITA-Prolog, DITA-Comment, and DITA-Cleanup conditions to the respective elements each time you open a topic file. The Conditionalize data, data-about, and area option applies the DITA-Data condition to data, data-about, and area elements when opening a topic file or DITA map file.The Conditionalize topicmeta and bookmeta option applies the DITA-Topicmeta to the topicmeta element when opening a DITA map file. On file save, these conditions are stripped (all other conditions you may apply will honor the Conditional Text setting in the structure application definition).
The term “Conditionalize” does not necessarily mean to “hide,” it just means that the associated conditional tagging will be applied to the elements. It is up to you to set the hide/show state as well as the color and style for these conditions (in the structure application template).
When any of these options are enabled, the plugin does a “show all” then a “hide” of the appropriate conditions when the XML or FM file is opened. If the file makes extensive use of conditions, this may result in the addition of blank pages at the end of the document. For XML files, this is not a problem since the blank pages are not saved, but if you’re working on generated FM files, you may end up with extra blank pages that you can’t get rid of (each time you save then reopen, the blank pages will reappear). If this is the case, you should disable the auto-conditionalizing options when doing final pagination on generated FM files.
To filter content in FM files based on a ditaval file, use the command or enable the Apply Ditaval option in the book-build process. Before using this feature you must first create the ditaval file (using the Ditaval Manager or other means), then register it with the Ditaval Manager. Once the ditaval file has been registered with DITA-FMx, you can use it with the Apply Ditaval command. Detailed information about using this command is available in the Using the Apply Ditaval Command to Filter with Conditions topic.
As of DITA-FMx version 2.0.03, this command can be run in either of two modes, filtering as conditions or by deletion. Both modes result in similar results, but filtering by deletion will more closely match the filtering done by the DITA-OT.
While not a requirement, it is best to use this command only on generated FM files, not on your DITA XML files (as is done by the book-build process). If used on XML files, when using the filter as conditions option, the conditions are typically saved to the XML as processing instructions (PIs) and will persist in the state set the next time you open the file (this persistence is dependent on the Conditional Text setting in the associated structure application definition). If using the by deletion option, it will delete content from your files, which is typically not desired while authoring.
When you generate an FM book from a DITA map, any PIs created during authoring are filtered out during the import XSLT processing and are not included in the generated FM files. However, any conditions that have been applied to content that is the source of a conref, will appear in the generated FM files because the conref source is not passed through the import XSLT processing, but pulled in by the conref resolution process which happens after the initial topic file aggregation. This results in an FM file with some conditions that appear to have survived the conversion while other have not. This confusing situation can be avoided by not applying conditions to the XML files while authoring.
Regardless of whether you have applied conditions to the XML files or not, you can still run the Apply Ditaval command to apply conditions based on the properties in a ditaval file.
If the filtering provided by the Apply Ditaval command doesn’t result in the required filtering for your documents, you can make use of FrameMaker’s Filter by Attribute build expressions when generating a book from a map.
To make use of this feature, you should start by developing (and extensively testing) the attribute build expression in a generated FM file (the result of the book-build process). When you’ve created the necessary build expression, import it into your Book template (or appropriate component templates) using and select the Filter by Attribute Settings option. In addition to the named build expression, your template must define the condition you plan to assign to the filtered content.
Use of this feature requires that you’re using a book-build INI file. In the BookBuildOverrides section, add an entry named FilterByAttribute. Assign the build expression name and the condition name (separated with a greater-than symbol) as the value to this INI entry using the syntax: BUILD-EXPRESSION>CONDITION-NAME. For example, if your build expression is named “Print-Filter” and the condition is “FilteredContent”, the INI entry would look like the following:
[BookBuildOverrides] FilterByAttribute=Print-Filter>FilteredContent ...
Because the use of this feature is a replacement for ditaval filtering, if this entry is used in the book-build INI file, any specified ditaval filtering is ignored for content filtering. When the FilterByAttribute feature is in use, ditaval filtering is still used for the filtering of key definitions, so it is important to maintain both.
In the future, DITA-FMx may provide a mapping from ditaval to attribute build expressions, but for now this is left to the user to develop.
If there are certain elements that you want to exclude from your generated FM book files, use the “drop” rule. For example, if you want to exclude the shortdesc element from your generated files, add the following rule to the Book application’s rules file:
element "shortdesc" drop;
This results in the shortdesc element being removed from the generated FM files while it remains in the source topic files.