Installing the Structure Applications

It is important to install the DITA-FMx structure applications to take full advantage of the features provided.

In order for FrameMaker to properly import and export DITA files, you must have structure applications that support the authoring of topic and map files. DITA-FMx provides both of these applications as well as a structure application for book processing. If you want to customize the appearance of the templates or change the elements supported (adding through specialization or removing unwanted elements), you should clone the provided structure application folders and modify the cloned versions.

If you are upgrading from the FM7.2 DITA Application Pack, and want to continue using those structure applications (or your customized version), you’ll need to edit the “stub” files for those applications and change the “Use API Clients” element so it references the client “ditafmx_app” instead of “ditafm_app.” Or, if you want to use the new structure application that are provided with DITA-FMx, you may want to delete the old ones to eliminate possible confusion. The steps below refer to the Structure Tools menu, in FM7.2, this is on the File menu ( File > Structure Tools).

Tip: We’ve posted a video of the complete DITA-FMx installation process. If you haven’t watched this video you may want to take a moment to do so: http://blog.leximation.com/2010/03/installing-dita-fmx-1-1/

The following steps describe the installation of the structure applications provided with DITA-FMx.

Make a backup copy of your current structure application definitions file (typically found at FrameMaker\Structure\structapps.fm for FM7.2 and FM8, or <user appdata>\Adobe\FrameMaker\9 for FM9). Store this file in a safe location before making modifications.
Extract the contents of the DITA-FMx_apps.zip file to the FrameMaker\Structure\xml folder. This will create a folder named DITA-FMx_1.1 that contains folders named Book, dtd, Map, and Topic. These folders contains the three structure application as well as the DITA 1.1 DTD files used by the applications.

Note: The EDD files provided with DITA-FMx are in MIF format by default. This results in the installer application being 8 MB smaller in file size than it would be if we provided the EDDs as FM binary files. If you plan to modify the EDDs in any way, you should save them as FM binary files before making any modifications. After saving as an FM binary, feel free to delete the MIF files.
Start FrameMaker and open the structure application definitions file (Structure Tools > Edit Application Definitions). (If running FM9, this opens the structapps.fm file in your “USERNAME\AppData” area, not the one in the FrameMaker program files area).
Open the Structure View window (for FM7.2 or FM8 click the button on the upper right of the document window, in FM9 or FM10 choose Structure Tools > Structure View). In the structure application definitions file place the insertion point just after the Version element. When the insertion point is in the right location, you’ll see a black triangle pointing to the right in the Structure View window (see the following image).

Figure 1. Structure View window insertion point
Choose File > Import > File, then navigate to the structapps-stub_topic_1.1.fm file in the DITA-FMx_1.1\Topic folder created in step 2. Select the Import by Reference option and choose the Import button. In the next dialog accept the defaults and choose Import.

Note: If you see red dotted lines in the Structure View window after importing the “stub” file, it has been inserted into the wrong location. Delete the inset and try again. Make sure that the black triangle is placed as shown in Structure View window insertion point.
Repeat step 4 for the “structapps-stub” files in the DITA-FMx_1.1\Map and DITA-FMx_1.1\Book folders.
Save the file, then choose Structure Tools > Read Application Definitions.
Close the file and exit FrameMaker.
Restart FrameMaker and run the DITA-FMx > Options command and select DITA-FMx-Topic-1.1 for the DITA Topic Application, DITA-FMx-Map-1.1 for the DITA Map Application, and DITA-FMx-Book-1.1 for the DITA Book Application.

Note: If your folder structure is non-standard, you may need to modify the paths specified in the “structapps-stub” files to match the file paths on your system. To do this, just open the structure application definitions file and double-click each application’s text inset. In the dialog that displays, choose the Open Source button and make the changes in the “stub” file. When you have finished editing the stub file, save and close that file, then double-click the text inset again and choose the Update Now button.

If you plan to make use of the DITA Open Toolkit for generating output, see Setting Up to Use the Generate Output Command.

Description of the Structure Application Files

The Structure\xml\DITA-FMx_1.1 folder contains a number of files, some are specific to the structure applications, and some are used for other purposes.

DITA-FMx_1.1\: map-from-outline_template.fm - Template file used by the New DITA File > New Map from Outline command.
DITA-FMx_1.1\Book\: book_1.1.edd.mif - The Book application EDD (in MIF format). Defines the data model structure and provides the element definitions. Save to FM format before modifying. Remember to import this into the template (below) if you make and changes to the EDD.; book_1.1.rules.txt - The Book application read/write rules file.; book_1.1.template.fm - The Book application template file. Defines the page layout and formatting as well as the character and paragraph styles used by the EDD.; bookmap2fmbook.xsl - The Book application XSL import file. Controls the process that aggregates all of the topic files into the book and chapter FM files.; expandOrig.xsl - A support file for the Book XSL import process. Performs initial aggregation of all topic files before passing control off to the bookmap2fmbook.xml file.; structapps-stub_book_1.1.fm - The Book application definition stub file. Inserted into the structure application definitions file (structapps.fm).
DITA-FMx_1.1\Book\component-templates\: gentpl~indexlist.fm - A sample template for generating an Index (indexlist). Referenced by the ditafmx-bookbuild.ini file.; gentpl~toc.fm - A sample template for generating a TOC (toc). Referenced by the ditafmx-bookbuild.ini file.; tpl~appendix.fm - A sample template for an Appendix map element. Referenced by the ditafmx-bookbuild.ini file. As of DITA-FMx 1.1.11, the EDD in this template is the default EDD; additional context rules have been added to support the alternate heading styles used for appendix and part files.; tpl~chapter.fm - A sample template for a Chapter map element. Referenced by the ditafmx-bookbuild.ini file. As of DITA-FMx 1.1.11, the EDD in this template is the default EDD; additional context rules have been added to support the alternate heading styles used for appendix and part files. The default Chapter template is actually just a copy (and rename) of the default Book template. It can be convenient to use a Chapter template to make adjustments to the output without modifying the core Book template.; tpl~part.fm - A sample template for a Part map element. Referenced by the ditafmx-bookbuild.ini file. As of DITA-FMx 1.1.11, the EDD in this template is the default EDD; additional context rules have been added to support the alternate heading styles used for appendix and part files.
DITA-FMx_1.1\dtd\: fmxbook.dtd - Custom DTD file referenced by the bookmap2fmbook.xsl file. Created from the ditabase.dtd file.; All remaining files are the default DITA 1.1 DTD files.
DITA-FMx_1.1\Map\: map_1.1.edd.mif - The Map application EDD (in MIF format). Defines the data model structure and provides the element definitions. Save to FM format before modifying. Remember to import this into the template (below) if you make and changes to the EDD.; map_1.1.rules.txt - The Map application read/write rules file.; map_1.1.template.fm - The Map application template file. Defines the page layout and formatting as well as the character and paragraph styles used by the EDD.; structapps-stub_map_1.1.fm - The Map application definition stub file. Inserted into the structure application definitions file (structapps.fm).
DITA-FMx_1.1\Topic\: new~reference~simple ref.fm - A sample “reference” element template named “simple ref”.; new~task~simple task.fm - A sample “task” element template named “simple task”.; new~topic~simple ref.fm - A sample “topic” element template named “simple topic”.; structapps-stub_topic_1.1.fm - The Topic application definition stub file. Inserted into the structure application definitions file (structapps.fm).; topic_1.1.edd.mif - The Topic application EDD (in MIF format). Defines the data model structure and provides the element definitions. Save to FM format before modifying. Remember to import this into the template (below) if you make and changes to the EDD.; topic_1.1.rules.txt - The Topic application read/write rules file.; topic_1.1.template.fm - The Topic application template file. Defines the page layout and formatting as well as the character and paragraph styles used by the EDD.