Tips for making the most efficient use of DITA-FMx.
The following list describes common and useful tips for working with DITA-FMx. For additional information, please visit the FrameMaker/DITA Community KB at kb.leximation.com/dfm/.
If you have tips or suggestions you’d like to share, please send them to <ditafmx-help AT leximation DOT com>.
The FM 13.0.1 update changed the default XSLT processor from XALAN to SAXON. If you’re using the latest (as of v.2.0.06) default Book app, with FM12 or earlier, you’ll need to manually switch the XSLT script to XALAN (see, Special Instructions for FM12 and Earlier). If you’re using a custom Book app on FM 2015 or later, you may need to update your XSLT import script to work with SAXON (or change the default XSLT processor to use XALAN).
The error message: Can not convert #RTREEFRAG to a NodeList!
If you’re seeing this message in the FrameMaker console window, you’ll need to modify the entfmts file that ships with FrameMaker. This file is found in the FrameMaker\Structure folder, and is a FM binary file (although it doesn’t have a “.fm” extension). To fix this annoyance, open that file in FrameMaker (make a backup first), and change the Font Family of the “FmDingbats” character style to “Adobe Pi Std”. While you’re in there you may also want to change the default font family of the “Bulleted” paragraph style from “Courier” to “Courier New” (if you’re seeing console messages about Courier). Save the file. (Make sure it remains named “entfmts” not “entfmts.fm”.)
If you’re seeing other font messages in the console, that may be due to other fonts used in that file or template files. The easiest way to locate the problem is to save the template(s) to MIF and search in the MIF file for the offending font name.
By default (in DITA-FMx), when you spell check a file and use the “Allow in Document” option, that word is stored as a processing instruction in the DITA file. For words that are common to an entire project, you might consider using the “Learn” option instead, which stores the word in a system-level location. To disable this feature (prevent creation of the dictionary PIs), change the GeneralExport/WriteDictionaryPIs parameter to “0” in the ditafmx.ini file.
To support the proper sizing and placement of image elements, certain read/write rules must be defined. If you’re using a custom or older structure application, the height and width rules may not be properly defined. Refer to the image topic for the proper rules.
If your images resize and shrink-wrap properly while authoring, but don’t for your book builds, check the Reload References setting in the Book Build Settings dialog. This setting must be enabled for images to resize and shrink-wrap in book builds.
If you want a table to extend to the full width of the text frame, set the table/@pgwide attribute to 1.
As of DITA-FMx 2.0 variables (user and system) will round trip properly if the “Convert Variables to fm-var on Save” option is selected in the Authoring Options dialog.
If you make heavy use of references (conrefs or xrefs), you may find it more efficient to open the target files first (those that are the destination of an xref or the source of a conref). If the target files are already open when you open topic files, the referencing process will go much faster.
While converting an existing set of unstructured files into DITA, you may want to disable the auto-loading of xrefs and conrefs. If auto-loading is enabled you may get a lot of referencing errors when opening files if the target of those references is not a completely valid file.
If you have titles that contain conrefs, be sure to have that file open when updating the DITA map file, otherwise the conref content will not appear in the topicref label.
FrameMaker uses the read/write rule “preserve line breaks” to allow the line breaks within code or preformatted elements to round trip between XML and the authoring view. The use of inline child elements such as b or i within a preformatted element poses a particular problem since you generally don’t want line breaks preserved for those child elements when used in non-code situations. There are a number of ways to handle this problem, but the easiest is to only apply these inline elements within a line (don’t tag multiple lines), and don’t let the child element start at the beginning of the line (allow at least a leading space before the inline element starts and ends). What appears to be a Frame bug causes the preserved line break to be lost if a child element starts or ends a line.
If you make use of the draft-comment element within running text, be sure to wrap a trailing (or leading) space within the element so that when (or if) you conditionalize these elements so they are hidden in Frame, you don’t end up with a double space.
Place the cursor anywhere in a row, press Ctrl+Enter and a new row is added after the current row.
When creating a conversion table, be sure to map Index markers to a valid element type. In the default DITA-FMx Topic app, the indexterm element is not defined as a Marker type, but a Container. Index markers should be mapped to the fm-indexterm element instead because that is defined as a Marker element type in the EDD. If you map Index markers to the indexterm element, FrameMaker will crash with an assertion failure error when saving the structured file to XML.