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):
DITA 1.3 is not currently supported by DITA-FMx. We are assessing which features to support; if you have specific needs, please contact us.
While no support is provided out of the box, there is no reason that DITA-FMx would not support the DITA 1.3 model if an appropriately defined structure application were developed. The aspects of DITA 1.3 that will not currently work, involve new methods for ditaval filtering, scoped key resolution, and cross-deliverable linking.
The following DITA 1.2 features are not currently supported:
keyrefs to topicref-based elements are not supported
key element references to fm-indexterm, indexterm, and indextermref are not supported
key element references will provide the defined content but will not currently provide a hyperlink to a provided href target
inline elements within key element references are unwrapped; the content will remain, but the markup is deleted
text from conrefs and keyrefs within a map will not be passed to the book-build process
the conaction attribute is not supported
a “Learning” structure application (based on the Learning and Training specialization) is provided for testing purposes only and is not considered to be production-ready; an update will be provided in a future release
a “SubjectScheme” structure application is not currently provided
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.
For the Apply Ditaval command, only the prop ditaval element is supported. Other elements may be recognized in a future release if that is seen as beneficial.
The as conditions option of the Apply Ditaval command does not necessarily result in 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 that used by the OT. When using the as conditions option, it is best to use ditaval files that only use the “exclude” action attribute; this will provide more reliable results. Due to the nature of conditional tagging, this option cannot remove components from a book. If this is needed, use the by deletion option.
The by deletion option of the Apply Ditaval command, more closely emulates the filtering done by the DITA-OT. However, the by deletion option only supports the “include” and “exclude” action attributes; the “flag” action is not supported (if “flag” is needed, use the as conditions option).
Because a graphic object in FrameMaker cannot have children, the alt and longdescref elements are not fully supported. The text of the alt element will round-trip and can be edited through the Object Properties (Object Attributes) dialog, but any attributes on the alt element will be discarded on file open. The longdescref element will be discarded on file open.
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 href attributes that include references to topic IDs will be stripped down to just the file name for processing and creation of related links. This may change in a future update.
DITA-FMx does not support the “use by reference” feature of DITA footnotes. This is where the footnote reference number only shows up at the referenced (via xref) location but not at the location of the fn element. In all cases, there will be a reference number generated by the fn element. You may add references to that footnote with a formatted reference (fm-xref).
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 element 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).
When generating a book from a map, any attributes on topicref-based elements that reference a submap are lost during the XSLT import process. The “merge” process replaces the referencing topicref with the referenced topicref (the root topicref in the referenced map). Therefore, any filtering (or other) attributes intended to affect the generated book, should be placed on the referenced topicref rather than the referencing topicref.
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, 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 2020 and 2022:
The structure application auto-install feature seems to not work consistently on FM 2020 and FM 2022. If you’re running into trouble, please use the manual install instead. See, Manual Installation of the Structure Applications.
Issues that relate to using DITA-FMx with FrameMaker 2017:
FM version 14.0.2 or later is required for use with DITA-FMx due to FDK library updates with that update.
The FM 2017 “welcome screen” has no API, so the DITA-related links and buttons will not work when DITA-FMx is installed.
Issues that relate to using DITA-FMx with FrameMaker XML Author (FM 12 and 2015):
DITA-FMx does not work well with FrameMaker XML Author. Many commands work fine, but due to the inability to open FM binary files, you cannot create new DITA files through the DITA-FMx interface and the publishing features will also not work. You can work around this limitation by opening an existing XML file and saving it to a new name (remember to recreate the topic ID). You can also use DITA-FMx to author files that are stored in a CMS such as XDocs or easyDITA.
Issues that relate to using DITA-FMx with FrameMaker 11:
Due to changes in the FrameMaker 11 API, the “Open Maps in Document View” option does not work on the initial open of a map. It will however, work when opening a supmap from a topicref in a map. If a solution is found it will be provided in a future update.
Be aware that using the FrameMaker 11 Code View can strip leading spaces from preformatted elements (i.e., codeblock, lines, msgblock, pre). This is a core FM bug, that will hopefully be fixed soon. Unfortunately, there’s nothing that DITA-FMx can do about this (other than to warn you about it).
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:
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:
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>.