Migrating from FM-DITA to DITA-FMx

Tips for migrating from default FrameMaker DITA to DITA-FMx.

In general, there should be very little migration effort going from the default DITA support in FrameMaker 8 or 9 (FM-DITA) to DITA-FMx. Because both DITA authoring environments create valid DITA files, you can open and edit files created by the other environment just as you can open and edit files created in different authoring tools such as XMetaL or Oxygen.

If you’ve customized the default FM8 or FM9 structure applications and want to continue using those customizations in DITA-FMx, there may be some work required to migrate the apps since DITA-FMx provides features that do not exist in FM-DITA. For a complete listing and description of the DITA-FMx structure application requirements, refer to the Required Element Definitions topic.

You cannot migrate FM10 DITA 1.2 applications for use in DITA-FMx 1.1 (DITA-FMx 1.1 supports the DITA 1.1 specification, even on FM10). DITA-FMx 2.0 will support the DITA 1.2 specification, and should be available in the near future. If you want to migrate FM10 DITA 1.1 applications for use with DITA-FMx, you should be able to follow the suggestions for migrating the FM8/9 apps.

If you want to just “give it a try” to see what breaks, that’s fine (you’re not going to break anything). The only thing that’s absolutely required is that you change the “Use API Client” node in the application definition so it uses the “ditafmx_app” client name instead of “ditafm_app.” You’ll need to do this for any structure application that you want to use with DITA-FMx. (If you try to use these apps without changing the UseApiClient node, you will get the following error message when opening a DITA file: “Translator client (ditafm_app) was not found.”) Once this is done, change the application names in the DITA Options dialog, and give it a whirl.

If you’re migrating from FM8-DITA, which supports DITA 1.0, keep in mind that because DITA-FMx 1.1 supports DITA 1.1, there will be significant differences in the EDDs. You can continue to use DITA 1.0 apps in DITA-FMx 1.1 as long as you provide certain element definitions (described below).

If you’re migrating from FM9-DITA, the general EDD structure will be virtually identical to the DITA-FMx structure, other than the special “fm-*” elements. Some of these elements are required and others are more of a convenience.

Also, it may be useful to note that FM8-DITA provided a Book application (for building a book from a map), while the FM9-DITA does not. In FM9-DITA the book-building process uses the Topic application when building a book. DITA-FMx requires a separate Book application.

The following items are significant migration points, refer to the Required Element Definitions topic for a complete list of elements specific to DITA-FMx.

The fm-indexterm element is required.
In the DITA-FMx Topic and Book applications the fm-indexterm element is required to exist and be defined as a marker element type. You should be able to rename your FM-DITA indexterm to fm-indexterm since by default the FM-DITA indexterm is a Marker element. You’ll also need to rename all references to indexterm in the general rule of other element definitions. If you want to be able to use the DITA-FMx feature that lets you switch between an fm-indexterm Marker and an indexterm Container, you’ll need to create an indexterm element that is defined as a Container. This should be added to all general rules at the same location as the fm-indexterm.
For more information, refer to the indexterm and fm-indexterm topic.
The topic referencing label in Maps.
The DITA-FMx Map application uses the fm-reflabel element to provide a clickable label for navigation in a map or bookmap. In DITA-FMx 1.0 as well as in FM-DITA, this element is named fm-topicreflabel. Because bookmaps can contains topic referencing elements other than topicref, it was decided that this element name should be changed. DITA-FMx 1.1 is designed to work properly with either element name.
For more information, refer to the fm-reflabel and Topic References topic.
Special Book application elements.
The DITA-FMx Book application includes three required elements, fm-ditabook, fm-ditafile, and fm-bookcomponent. The fm-ditabook element makes use of href and title attributes, and the fm-ditafile element uses the href and mapelemtype attributes. The Book application will also use the fm-tabletitle element if you enable the “Move table/title” book-building option. If you plan to take advantage of the enhanced DITA-FMx book-building functionality, you should make sure your Book application includes these elements.
For more information, refer to the Special Book Application Elements topic.
The simpletable-based table structures.
All of the DITA-FMx applications make use of simpletable-based tables. In Topic and Book applications are simpletable, choicetable, and properties (table), and in the Map application is the reltable. Because tables within FrameMaker require a slightly structure than that required by the DITA specification, additional “fm-*” elements are added as wrappers to the “head” and “row” (sthead and strow in simpletable) elements. DITA-FMx 1.1 uses a slightly different structure than FM-DITA. The base table name is the root element, which contains “fm-<tablename>head” and “fm-<tablename>body” elements, which in turn contain the standard head and row elements.
For more information, refer to the simpletable-Based Tables topic.