Using Keyspaces in DITA-FMx

In DITA-FMx, a keyspace consists of all keys defined in a root map and all submaps, optionally filtered by an associated ditaval file.

The implementation of keyspaces in is a bit different than that in default FM-DITA (and perhaps other tools as well).

Each registered key space is stored as a “.keyspace” file in the user’s DITA-FMx folder (DITA-FMx > Open DITA-FMx Folder). The format of this file is XML, and contains all of the necessary data (normalized and filtered) to insert and display key references for that key space. This is not a DITA file, so don’t try to open it using a FrameMaker DITA structured application. If you’re curious, take a look by opening it in a text editor; the structure will be apparent.

When you create a map and start adding key definitions to it, use the Keyspace Manager to register the root map. Consider making use of the Keyspace Generation feature (see Keyspace Options) so that the keyspace file is kept in sync with the key definitions in the map.

If you are using submaps, remember to register the root map, not the submap; the key space should always be defined by the root map. As a convenience feature, DITA-FMx will automatically update the keyspace, even when working on a submap, if the submap includes an “fmx-root-map” othermeta element. This feature is described in Keyspace Options.

If you are working with multiple projects and thus multiple keyspaces, consider using the Keyspace Resolution feature (also described in Keyspace Options) to automatically change the default keyspace when the root map or an associated submap is opened.

When registering a keyspace, you have the option to assign an associated ditaval file. If you are setting up key definitions that are modified by ditaval filtering, you may want to select one of the filtering scenarios as the default for editing. You can always change the ditaval file associated with a keyspace to switch filtering schemes if needed. If no ditaval is assigned to a keyspace, all key definitions are included in that keyspace (duplicate keys are ignored; first key wins).

Only registered ditaval files are available to be assigned to a keyspace. Use the Ditaval Manager to register a ditaval file.

When publishing through the DITA-FMx Generate Book from Map command, the ditaval file selected in the Book-Build Options dialog or specified in the book-build INI file will be applied to the keyspace regardless of the current default keyspace configuration.

Important: In order to use keys, you must be using DITA 1.2 or greater. This is determined by the ditaarch:DITAArchVersion attribute on the “topic” element. The DITA version is not typically assigned explicitly, but has a default value that will affect the availability of these features in DITA-FMx.