Tips for migrating from FrameMaker
8/9 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.
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.