DITA-FMx User Guide

Tips and Troubleshooting

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>.

Do you often choose the wrong application when opening a map?

Because both the Book and Map applications use the “map” doctype, it is easy to mistakenly choose the Book app when opening a map file. The applications are listed in the “disambiguator” dialog in the order that they are entered in the structure applications definitions file. If you move the Map app so it is before the Book app, you’ll reduce the chance of choosing the wrong app.

Note: The default DITA-FMx Book application no longer references the topic or map doctypes. This application is still used for book publishing, but will no longer show up in the Use Application dialog.
Supporting round-tripping of image sizes.

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 imagetopic for the proper rules.

Making use of page-wide tables.

If you want a table to extend to the full width of the text frame, set the table/@pgwide attribute to 1.

Using FrameMaker variables with DITA

User variables will round-trip properly in topic files provided the following points are observed (system variables will not round-trip):

  • Do not name your variable with other than alphanumeric, underscore, or hyphen characters, and do not use a numeric character as the first character in the name.

  • Be sure to add the variable definitions to the application’s template file, to ensure that any character formatting is properly applied. Note that this formatting will only be visible in print (or PDF) output from FrameMaker since it has no element structure.

  • Variables will not live through the map to book process. If you want to have live variables in your generated FM files, you need to use the Prepare Variables command.

  • If you use the Prepare Variables command and feel inclined to set attributes on the <ph> elements that wrap the variables, don’t do it. The <ph> wrappers are temporary and are deleted each time the Prepare Variables command is run. If you want to apply filtering or other attributes to variables, wrap them in a <ph> element and apply the attributes on that element.

Note: Using FrameMaker variables is not really considered to be a “best practice” although there may be situations where it is an ideal solution for a particular problem. The proper DITA way to use “variables” is that of a conref to a phrase element.
Heavy use of references slowing things down?

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.

Reference problems while converting unstructured content to DITA

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.

Conrefs in title elements

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.

Use of inline formatting within “preformatted” elements (like codeblock)

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.

Use of draft-comments inline

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.

Quick way to add a row to tables

Place the cursor anywhere in a row, press Ctrl+Enter and a new row is added after the current row.

Converting unstructured to structured files

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.