DITA-FMx User Guide

Filtering Content

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 as Conditions command can approximate the effect of applying a ditaval file to a topic file or book. You can also achieve filtering when generating a FM book from a DITA map by modifying the Book application’s read-write rules file.

Auto-Conditionalizing Elements

There are four options for applying conditions to elements on file open. The Conditionalize Prolog on File Open and Conditionalize Comments on File Open options apply the DITA-Prolog and DITA-Comment conditions to the respective elements each time you open a topic file. The Conditionalize data and data-about on File Open option applies the DITA-Data condition to data and data-about elements when opening a topic file or DITA map file.The Conditionalize Topicmeta and Bookmeta on File Open 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 condition 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.

Ditaval Filtering

In order to filter content in FM files based on a ditaval file, you should use the Apply Ditaval as Conditions command. Before using this command you need to 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 as Conditions command. Detailed information about using this command is available in the Using the Apply Ditaval as Conditions Command topic.

Although, not a requirement, it is best to use this command only on generated FM files, not on your DITA XML files. If you use it on the XML files, the conditions are 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).

When you generate an FM book from a DITA map, these PIs are filtered out during the import XSLT processing and 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.

Regardless of whether you have applied conditions to the XML files or not, you can still run the Apply Ditaval as Conditions command to apply conditions based on the properties in a ditaval file.

Filtering with the Read-Write Rules File

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.