Known limitations in the current version of DITA-FMx.

The following list describes the currently known issues that apply to using DITA-FMx on all supported versions of FrameMaker (see below for version-specific issues):

• When generating an FM book from a map, you may get the following messages in the FrameMaker Log file:

  • XML Parser Message: “ID 'TOPICID' has already been used”

    This message is caused when your topic files contain duplicate IDs. This can happen when you clone a topic file to create a new topic file or if you include the same topic in multiple places in the map. Both of these situations are valid as far as DITA is concerned, but FrameMaker doesn’t like to see duplicate IDs in a single book. This is just a warning and can generally be ignored.

    The only situation where this duplicate ID issue will cause problems or possibly unexpected results, is when you have xrefs or related links to a topic where the ID exists in multiple places in a given chapter file. The reference will always end up pointing at the first instance of the ID in a generated FM chapter file.

  • XML Read Message: “Cannot find the file (FILENAME) containing the imported graphic.”

    This message is caused when the target location for the generated book is a different relative location to the images than that of the source DITA file. When the book files are initially created, the images may not be resolved. After the files are created, a process runs that relinks the topic files to the image files. Assuming that the image files are actually available, you should be able to ignore this message.

    This issue should no longer exist as of DITA-FMx 1.1.14.

• The Apply Ditaval as Conditions command does not necessarily result in conditional filtering that matches that of the DITA Open Toolkit. The conditions are applied properly based on the filtering attribute values, but the default hide/show logic of FrameMaker conditions is not the same as the used by the OT. We plan to provide an additional command that will apply filtering that matches the OT logic in a future version of DITA-FMx. In the mean time, it may be possible to achieve this filtering through the use of Boolean conditional expressions.

• For the Apply Ditaval as Conditions command, currently only the “prop” ditaval element is supported. Other elements may be recognized in a future release if that is seen as beneficial.

• When using TextLine graphic overlay objects, do not use a Center or Right alignment, only use the default Left alignment. Using an alignment of Center or Right will result in the text line position shifting to the left or right when the file is reopened. This will be fixed in a future release.

• In a relationship table, only @href references to files are honored. Any @hrefs that that include references to topic IDs will be stripped down to just the file name for processing and creation of related links. This may be fixed in a future update.

• Indexterms with multiple child elements that are siblings, will not round-trip properly. On import, the sibling indexterms are incorrectly converted into FM index syntax, which means the exported indexterms will be nested rather than siblings. A workaround is to disable indexterm conversion on import and export (although this will not allow you to generate a FM index). This may be fixed in a future update.

• Xrefs within the link/desc element will not resolve properly on file open. After file open, running the Update References command will resolve these references. This may be fixed in a future update.

• Backslashes used in an external xref (either in the link text or in the @href value) will not render as expected. You should use forward slashes if at all possible. This is due to a FrameMaker limitation and cannot be resolved.

• The Generate Book From Map command disallows the building of a book from a DITA map that references files on multiple disk drives. This appears to be a core FrameMaker limitation (but this probably isn’t a good idea anyway).

• If an XML file is “pretty-printed” and a line breaks after an inline element (such as a <ph>), when opened in Frame the space between that element and the following word will be lost.

• Child elements within an xref or link are lost on import if the Auto-Load Xrefs option is enabled. If your xrefs contain child elements, disable this option.

• Conrefs within titles won’t be included when you run the Update References command in a DITA map unless the target file is already open. If you have conrefs in your titles, you should open the file first before running the Update References command.

• Deleting an fm-reflabel element from a DITA map file without deleting the entire topicref, may result in the leading symbol being left in the map. This is a temporary issue and will go away the next time you open the file; it has no effect on the ability to process the files.

• The syntaxdiagram child elements should round-trip properly as of DITA-FMx 1.1.14, but the formatting of these elements may not be optimal. We will focus on providing better support for these elements in DITA-FMx 2.x.

Issues that relate to using DITA-FMx with FrameMaker 10:

• FrameMaker 10 includes a number of “Save Ditamap As” options that are not functional when DITA-FMx is installed (because the FM10 DITA support is uninstalled). The following SaveAs options are not supported:

  • Composite Document
  • Book with FM Components
  • PDF

• The two left-most buttons on the Resource Manager (map editor) toolbar are non-functional when DITA-FMx is installed. We are looking into options for enabling them, but for now you must use the element catalog to insert topic referencing elements (topicref, chapter, appendix, etc.). The remainder of the buttons seem to work properly with DITA-FMx.

Issues that relate to using DITA-FMx with FrameMaker 9:

• FrameMaker 9 includes a number of “Save Ditamap As” options that are not functional when DITA-FMx is installed (because the FM9 DITA support is uninstalled). The following SaveAs options are not supported:

  • Composite Document
  • Book with FM Components
  • PDF

• The four left-most buttons on the Resource Manager (map editor) toolbar are non-functional when DITA-FMx is installed. We are looking into options for enabling them, but for now you must use the element catalog to insert topic referencing elements (topicref, chapter, appendix, etc.).

Issues that relate to using DITA-FMx with FrameMaker 8:

• A bug exists in FrameMaker 8 (and FM7.2) that causes it to crash if more than approximately 350 XML files are opened in the same session. In normal authoring use this limitation does not cause any problems, but if you are publishing a book that contains more than 300 topics, it is very likely that you’ll run into this problem. The only workaround is to convert your maps into a book in multiple segments and assemble the final book once all of the components have been built (restarting FrameMaker in between each build). DITA-FMx displays a warning after opening more than 300 files to remind you to restart FrameMaker. This bug has been fixed in FrameMaker 9.

Issues that relate to using DITA-FMx with FrameMaker 7.2:

• In the FM7.2 version of DITA-FMx, double-byte characters are garbled in the fm-topicreflabel elements, and don’t update properly.

Using DITA-FMx for DITA authoring in binary FrameMaker files is not recommended. Many of the features of DITA-FMx rely on the files being XML (allowing them to be parsed on disk). The following are reported issues, but there may be others:

• A file that can’t be opened due to missing fonts or images and it is the target of a conref or xref, the Reference Manager won’t display when the conref or xref is double-clicked. This can be resolved by opening the referenced file before double-clicking the conref or xref.

• Double-clicking a conref then choosing Update, will delete the conref.

Please send any problems or suggestions to <ditafmx-help AT leximation DOT com>.