Tips

Tips for making the most efficient use of DITA-FMx.

The following lists of tips will be expanded in future updates.

If you have tips or suggestions you’d like to share, please send them to ditafmx-help@leximation.com.

Using FrameMaker variables with DITA

User variables will round-trip properly 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.

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.