DITA 1.2, currently in the final stages of development by the OASIS DITA Technical Committee, provides a number of important new features. Of the new features in DITA 1.2, it can be argued that the key reference (keyref) feature is the most important. The keyref feature provides the ability to do indirect, context-dependent linking, something that is required in any application that supports re-use of content across multiple publications.
Because keyref is so important and because it also has inherent, unavoidable complexity, I will be posting short examples of how keyref can be used to solve specific business problems. This is the first in an occasional series of such examples.
This example shows one particular application of the keyref feature to a real-world problem faced by one of Really Strategies' clients. The data and the business requirements are real.
This is is a real-world example of using the new DITA 1.2 keyref feature to make existing
content with topic-to-topic cross references reusable, using keyref, where without keyref is
it not reusable.
The scenario comes from real publications: test preparation manuals for primary education
standardized tests. For this client, one business goal was to define an XML solution that
produced, as much as possible, publications that reflected their current, pre-XML presentation
practices.
Each test prep manual publication consists of a set of lessons, pointed to by topicrefs
within a publication-specific map.
Each publication also includes a glossary, where each glossary entry contains a cross
reference to the lesson or lessons in which in the term is defined or explained. With DITA
1.1, these glossary entries use a normal
<xref> element to point from the
glossary entry to the topic for the appropriate
lesson:
<glossentry
id="action">
<glossterm>action</glossterm>
<glossdef>what a character does in a story
(<xref href="../lessons/lesson_12.xml"/>)</glossdef>
</glossentry>
This works to the degree that the cross reference will resolve to topic lesson_12.xml but it can only ever resolve to lesson_12.xml. This lesson is specific to a particular test prep manual, e.g.,
Texas TAKS Language Arts Grade 7.
However, the business requirement is that the glossary entries be re-usable across different
publications. With the cross reference, the topic cannot directly be re-used in different
publications (different maps) because the crossreference is a direct topic-to-topic reference:
regardless of the map that uses the glossary entry, it will always point to lesson_12.xml.
In the DITA 1.1 the only DITA-defined options are:
- Have publication-specific glossary entries that conref the definition text and contain
publication-specific cross references.
- Replace the cross references with reltable links.
Option 1, per-publication glossary entries with conref, requires many publication-specific
glossary entry topics as well as the base glossary entries as well as the conrefs themselves.
It works, but it's complication and duplicated data. It also requires explicit per-publication
authoring of the cross references.
Option 2, reltable links, works, but either produces a presentation result that is not
consistent with the pre-DITA publication practice (that is, the legacy presentation that we
are attempting to replicate as closely as possible) or requires custom processing to make the
presentation result look like a normal cross reference. The relationship tables eliminate the
need for per-publication glossary entries, but do require separate per-publication authoring
of the relationship tables, one or more rows for each glossary entry.
With DITA 1.2, there is a third solution that avoids both the need for per-publication
glossary entries and the need for per-map relationship tables: keyref.
The keyref features provides an indirect addressing mechanism that allows a single reference
to resolve to different concrete targets in different maps. Keys are defined on <topicref> elements. Linking elements, such as <xref>, refer to
the keys using the new keyref= attribute rather than href=.
In the case of the glossary entries for the test prep manual, it is a business rule that
every glossary entry have at least one corresponding lesson in which the glossary entry is
defined or explained. This means that glossary entries can blindly point to the key for the
lesson for the entry without knowing which lesson that will be in a given map. Within a
publication-specific map, the topicref for each lesson simply defines the keys for those terms
it defines or explains.
Using the approach, the glossary entry gets modifed to replace the
href= on
the
<xref> element with a
keyref=:
<glossentry
id="action">
<glossterm>action</glossterm>
<glossdef>what a character does in a story
(<xref keyref="action_Lesson"/>)</glossdef>
</glossentry>
Note that instead of pointing to a key like "lesson_12", the key reflects the term itself,
"action_Lesson", reflecting the requirement that there must be a lesson for the terms
"action". In fact, you can take the uttering of the key as a demand that there be a
lesson that defines "action." At a minimum, a keyref-aware processor will report any keys that
can't be resolved, providing a built-in completeness check on the correlation of glossary
entries to lessons.
Within the map for a given publication, the topicrefs to lesson topics are modified to add
the keys for the terms they define or
explain:
...
<topicref
navtitle="Chapter 2. Literary Elements">
<topicref
navtitle="Character"
href="ELA/TX_ELA_G7/lessons/lesson_13.xml"
keys="action_Lesson"
/>
<topicref
navtitle="Setting"
href="ELA/TX_ELA_G7/lessons/lesson_14.xml"
keys="clause_Lesson setting_Lesson"
/>
...
Note that a given topicref can define any number of keys. In the case of the lessons, a given
lesson might define or explain a number of different terms.
Because keys are defined within maps, a given key reference can resolve to different targets
when resolved in the context of different maps.
For example, having created the Texas TAKS Language Arts Grade 7 test prep publication, we
decided to create the Ohio Grade 8 Language Arts test prep publication. It's the same subject
so most, if not all, of the glossary terms are appropriate, but the specific lessons will be
different for this new publication.
By defining the same keys in the map for the Ohio publication, the same glossary entries can
be re-used
without modification in the new publication. The new map might look
something
like:
...
<topicref
navtitle="Chapter 3. Literary Devices">
<topicref
navtitle="Plot"
href="ELA/OH_ELA_G8/lessons/lesson_21.xml"
keys="clause_Lesson"
/>
<topicref
navtitle="Character"
href="ELA/OH_ELA_G8/lessons/lesson_22.xml"
keys="action_Lesson"
/>
<topicref
navtitle="Setting"
href="ELA/OH_ELA_G8/lessons/lesson_23.xml"
keys="setting_Lesson"
/>
...
Here, the same keys are defined, but linked to different lesson topics.
Now there is exactly one glossary entry for each term, with no need to have
publication-specific versions of each glossary entry. The cross references are just normal
cross references, so they require no special processing. Likewise, there is no need for
relationship tables.
The author of the publication-specific map still has to figure out which terms are defined in
which lessons in the publication and declares the keys appropriately, but that work has to be
done regardless: the only variable is how the results of the analysis are captured in the DITA
markup.
For this particular use case, the keyref feature provides the simplest solution, in terms of
data complexity while also allowing the use of xref, reflecting the legacy practice we need to
preserve for this particular client.
