DITA 1.2: Defining Keys and Managing Keyspace

FrameMaker 10 has integrated support for DITA 1.2. DITA 1.2 specification offers many new elements, refinement to many existing elements and newer methods of reusing/referencing content.

Referencing and reusing content has always been centric to DITA. DITA 1.2 introduces the concept of keys which creates a level of abstraction and helps the author work more logically and not worry about the location of the content.

The importance of keys has been discussed widely over popular forums, so I will not elaborate on this (links at the bottom). With the help of this blog, I want to focus on how FrameMaker helps you create keys and allows you to manage keyspace.

Defining Keys

Keys are defined inside a DITAMAP. Key definitions can be inserted in DITAMAP using the elements keydef or topicref. The Keydef element is a specialization of the element topicref where the processing-role attribute is set to resource-only by default. This will mean keydef element will only act as a resource that defines a key and will not participate in output generation.

In FrameMaker, you can insert a topicref or keydef element in a DITAMAP from the resource manager view option “Insert Child”. Here you will be prompted to insert the key name and the destination file.


Insert Topicref Dialog

An animation at the end of this blog explains, in detail, the steps involved while defining a key.

Sample xml snippet when you define a key will look something like:

Using keydef element

<keydef keys="oil" href="synthetic_oil.xml">

The above xml snippet defines a key that points to the file “synthetic_oil.xml”

Using topicref element

<topicref keys="oil" href="oil.xml">

The above xml snippet includes a topic as well as defines a key that points to the file “oil.xml”

Keyspace Management

Defining keys is just one part of indirect addressing introduced in DITA 1.2. Keys can also be defined in nested DITAMAPs and duplicate keys can also be present. So, DITA 1.2 defines the concept of effective key definitions:

For a given key there is at most one effective definition within a key space. A key definition is the effective definition for a given key if it is the first, in document order, within the map document that contains it, and is the first in the map tree in breadth-first order. It is not an error for the same key name to be defined more than once within a map or map tree, and duplicate key definitions should be ignored without warning.

For easy management of keys, FrameMaker provides you with a Keyspace Manager. Using this, for any map, you can view:

(a) list of keys
(b) file or topic the key refers to
(c) DITAMAP containing the key definition (case of nested maps)
(d) key is active or not (case of duplicate keys)

To open the KeySpace Manager, go to DITA>Keyspace>Manage Keyspaces…


Keyspace Manager

Thus, using Keyspace Manager, you can figure out where each key is pointing to and should assist in debugging when creating links and references using keys. Also, you can select any key from the list and go to its definition directly using the option “Go to Key Definition” from the dialog box.

The following animation shows how you can use FrameMaker UI to define keys and manage keyspace for a particular DITAMAP:

View video in a new browser window.

Some nice content explaining the importance and usage of keys:

(1) http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/key-based_addressing.html
(2) http://dita.xml.org/sites/dita.xml.org/files/Anderson-Eberlein-24-Feb-2010.pdf
(3) http://dita.xml.org/resource/keyref-overview-dita-12

I hope this helps in understanding creation of keys and keyspace management using FrameMaker. Once a keyspace is created, it can be used to create links, x-refs, conkeyrefs etc. In the next blog, I will discuss how you can use keys to create such links and references.

Saurabh Agrawal,
Adobe FrameMaker Team