Migrating from FM-DITA to DITA-FMx

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

In general, there should be minimal effort required to migrate from the default DITA support in FrameMaker (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 FrameMaker DITA 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 DITA-FMx Specific Element Definitions topic.

If you want to just “give it a try” to see what breaks, that’s fine (you’re not going to hurt 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 an earlier version of FM-DITA, which may support DITA 1.0 or 1.1, keep in mind that because DITA-FMx 2.0 supports DITA 1.2, there will be significant differences in the EDDs. You can continue to use older DITA apps in DITA-FMx 2.0 as long as you provide certain element definitions (described below).

One significant difference between FM-DITA and DITA-FMx (since FM8) is that DITA-FMx relies on a separate “Book” structure application for publishing. The “Topic” application is for authoring topics, the “Map” application is for authoring maps, and the “Book” application is for publishing. While this does add a bit more effort to maintain one more structure application, it provides far greater control over your publishing process. Also keep in mind that while you may be tempted to do so, there’s really no reason to customize the “Map” or “Topic” apps (unless you’re adding specialized elements). You shouldn’t need to see the published view of the content while authoring, so you really just need to customize the Book app to align with your publishing styles.

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

The fm-indexterm element is required (if you use an index).

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

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 and the fm-figuretitle element if you use the “Move fig/title” 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 DITA-FMx Specific 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 different 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 uses a slightly different structure than FM-DITA. The base table name is the root element, which contains “fm-TABLENAMEhead” and “fm-TABLENAMEbody” elements, which in turn contain the standard head and row elements.

For more information, refer to the simpletable-Based Tables topic.