Keyspace Manager

Defines the current and registered keyspaces available to the author.

A keyspace is defined by all key definitions in a map and any submaps, along with any ditaval filtering applied to those key definitions. The Keyspace Manager lets you specify the root map for each keyspace and the default ditaval file to be applied to the key definitions found in that scope.

As you insert references to keys, the referenced content or files will be determined by key definitions in the current default keyspace. You should register a keyspace for each root map that contains key definitions or each root map that contains submaps with key definitions. (Do not register a keyspace for submaps unless those maps are used as a root map.)

If you have assigned filtering attributes to your key definitions, and want to author in one specific filtered “view”, assign a ditaval file to the registered keyspace. Each root map can only be registered with one ditaval file at a time. To switch the filtering to render a different ditaval file, change the existing keyspace to use a new ditaval file. The current keyspace filtering has no effect on the filtering applied to the book-build process (which uses the ditaval defined for that build).

Figure 1. Keyspace Manager

If keyspaces are registered for multiple maps, when you open one of the registered maps, the Keyspace Resolution option (in Keyspace Options) can set the default keyspace to match the map. If Keyspace Resolution is set to Auto, this switching is automatic, and if set to Prompt, you are prompted to change the default keyspace.

The Keyspace Generation option (in Keyspace Options) determines if the default keyspace is regenerated automatically when the associated root map is saved or if you are prompted to regenerate the keyspace (we suggest using “Auto”). If this option is disabled, you can regenerate the keyspace with the Rebuild button in the Keyspace Manager dialog.

A submap that contains key definitions may be associated with a root map by adding an othermeta element with the name attribute set to “fmx-root-map” and the content attribute set to the relative path and file name of the root map. When this is done, the submap is treated by the Keyspace Resolution and Keyspace Generation options as if it were the root map when saving and opening. This ensures that modifications to the key definitions in the submap are reflected in the keyspace.

Important: If the Keyspace Manager command is not available, check the “ditaver” attribute for the current file. It must be set to version 1.2 or greater. 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