This presentation briefly outlines the challenges of using keys in DITA 1.2, and then explains the new scoped keys functionality of DITA 1.3. It offers examples of the keyscope attribute used at different levels in a map, as well as examples of parallel and nested key scopes. It illustrates how to use a key in a different key scope and how to create cross-deliverable references using scoped keys.

1. Scoped Keys in
DITA 1.3
(Finally!)
Leigh White
DITA Specialist
leigh.white@ixiasoft.com
Presented at CIDM/DITA NA
April 2015

2. Me
• Writer, Information Architect
• DITA user since 2007
• Implements and supports the DITA CMS
• Author of DITA for Print
• Contributor to Language of Content Strategy
• Member of
DITA Adoption TC

3. DITA 1.2: Once upon a time
“The DITA 1.2 key reference facility provides an
indirect addressing mechanism that allows authors
to create references to things without having to
know exactly where or what those things are or will
be in the future.” (from an OASIS DITA Adoption TC
white paper)
WHAT?

4. Unscoped key (simple) example
<map>
<keydef keys="ot-version">
<topicmeta>
<keywords>
<keyword>1.8</keyword>
</keywords>
</topicmeta>
</keydef>
<topicref href="introduction.xml"/>
</map>
From introduction.xml:
<p>This book was … formatted using the DITA Open Toolkit <ph
keyref="ot-version"/> using some of the same techniques you’ll learn
about here.</p>
GREAT, huh?

5. But…there was trouble in the key-ngdom
<map>
<title>Using the Widget</title>
<keydef keys="module-name">
<keyword>Widget</keyword>
</keydef>
<topicref href="get_started.xml"/>
</map>
get_started.xml
<p>Now that you have integrated the <ph keyref="module-name">, many new
options are available to you.</p>
<map>
<mapref href="widget.ditamap"/>
<mapref href="gadget.ditamap"/>
</map>
<map>
<title>Using the Gadget</title>
<keydef keys="module-name">
<keyword>Gadget</keyword>
</keydef>
<topicref href="get_started.xml"/>
</map>

6. There can be only one…
• In DITA 1.2, there can be only one
definition/resolution of a key for an entire
processing scope
• The definition used is the “first” one that the DITA-
OT encounters when processing the map.
• What does “first” mean?
 Long story. Read about it here:
http://dita.xml.org/resource/dita-tc-faq-about-keys.
• The bottom line is you can’t use a topic multiple
times in a deliverable and have a different value
for a given key each time.

7. The people were angry
And the full promise of keys lay tantalizingly out of
reach

8. The years passed…

9. …and DITA 1.3 keyscope appeared

10. Scoped keys!
• DITA 1.3 supports key definitions at different
locations within a map structure
 Good for deliverables that are comprised of lots of sub-
maps; each map can have its own set of key definitions
 If a topic is re-used in a deliverable, you can specify
different key values depending in which sub-map the
topic appears
 Fully backwards-compatible with DITA 1.2. Existing
maps function exactly as before; they don’t contain any
keyscope attributes

11. How do they work?
• New attribute “keyscope”
• Used to define a key space
• Can be used on <mapref>, <topicgroup>,
<topichead>, <topicref>
Let’s look at some examples

12. Example 1: Parallel key spaces
Nested standalone maps:
<map>
<title>Training Courses</title>
<mapref href="widget.ditamap" keyscope="widget"/>
*<keydef keys="module-name"> = Widget
<topicref href="get-started.xml"/>
<mapref href="gadget.ditamap" keyscope="gadget"/>
*<keydef keys="module-name"> = Gadget
<topicref href="get-started.xml"/>
</map>
get_started.xml:
<p>Now that you have integrated the <ph keyref="module-name">, many new options are
available to you.</p>

13. Multiple instances?
• “If a topic that contains key references is reused in multiple
key scopes within a given root map such that its references
resolve differently in each use context, processors MUST
produce multiple copies of the source topic in resolved
output for each distinct set of effective key definitions that
are referenced by the topic. In such cases, authors can use
the [copy-to] attribute to specify different source URIs for
each reference to a topic.” (From DITA 1.3 spec as of
4/4/2015)
• force-unique build parameter generates copy-to attributes
to duplicate topicref elements. The allowed values are true
and false; the default value is false.

14. Example 2: Parallel key spaces
Single map, scope definition via topicgroup or topichead:
<map>
<title>Training Courses</title>
<topicgroup keyscope="widget">
*<keydef keys="module-name"> = Widget
<topicref href="get-started.xml"/>
</topicgroup>
<topichead keyscope="gadget" navtitle="Using the Gadget">
*<keydef keys="module-name"> = Gadget
<topicref href="get-started.xml"/>
</topichead>
</map>
*Not the actual syntax; abbreviated to save space

15. Example 3: Parallel key spaces
Single map, scope definition via topicref:
<map>
<title>Equipment Oil Change Procedures</title>
<topicref href="get-started.xml" keyscope="widget">
*<keydef keys="module-name"> = Widget
</topicref>
<topicref href="get-started.xml" keyscope="gadget">
*<keydef keys="module-name"> = Gadget
</topicref>
</map>

16. Example 4: Nested key spaces
<map keyscope="scope1">
<map keyscope="scope2">
<topicgroup keyscope="scope3">
<topicref href="topicA.xml"/>
</topicgroup>
</map>
</map>
scope1: module-name="Widget"
scope2: module-name="Gadget"
scope3: module-name="Thingy"
In topicA.xml, key "module-name" resolves to...?
Widget

17. Which key space wins?
• If a key is defined in both parent and child scopes,
parent definition takes precedence
• Always an implicit root key scope on root map
• Based on existing DITA 1.2 practice where a key
definition in a parent map takes precedence over
same key definition in child maps
 Good arguments for having key definitions in child
scopes override those from parent scopes for references
within that scope
 Could put control of this in the author’s hands via
“precedence”-type attribute but maybe confusing

18. Example 5: Keys outside of scopes
<map>
<title>Training Courses</title>
<mapref href="widget.ditamap" keyscope="widget"/>
*<keydef keys=“X"/>
*<keydef keys=“Y"/>
<mapref href="gadget.ditamap" keyscope="gadget"/>
*<keydef keys=“X"/>
*<keydef keys=“Z"/>
<topicref href=“topic1.xml”/> <!--uses keys X & Y-->
</map>
•X is redefined per gadget keyscope definition
•Y is considered undefined because it has no definition within gadget
keyscope
•Key definitions don’t carry over from parallel key spaces; they only
“trickle down” from parent key spaces*
*Let me clarify
Y

19. Example 6: Using keys from other scopes
<map>
<title>Training Courses</title>
<mapref href="widget.ditamap" keyscope="widget"/>
*<keydef keys=“module-name"/>
<topicref href=“get-started.xml"/>
<p>If you also integrate the <ph keyref=“gadget.module-name">, many new options will be
available to you.</p>
<mapref href="gadget.ditamap" keyscope="gadget"/>
*<keydef keys="module-name"/>
<topicref href=“get-started.xml"/>
<p>If you also integrate the <ph keyref=“widget.module-name">, many new options will be
available to you.</p>
</map>
•To reference a key in another scope, include that scope name in the
keyref
•If the key is many scopes deep, specify all of the scope names, from the
top down to the key, relative to the current scope

20. Scope names and reuse
• Scope names can limit reuse
 Either the context you are reusing in has to have a key
space with the specified name, or
 You have to add a key space with that name to the
context for the sake of resolving the key
• Otherwise, you have an undefined key

21. Example 7: Cross-deliverable linking
• Basic idea: define a root map as a key space and
allow a topic within another root map to link to a
key within that key space
• One use case: root map A creates a help system;
root map B creates a separate help system. You
want to create links between topics in the two help
systems.
• Whether or not a cross-deliverable reference
becomes an active link depends on processor
 DITA 1.3 spec doesn't define how cross-deliverable links
should be handled by processors

22. Example 7: Cross-deliverable linking
widget.ditamap:
<map>
<title>Widget Online Help</title>
<mapref href="gadget.ditamap" scope="peer" keyscope="gadget"/>
<topicref href="getting_started_widget.dita"/>
</map>
gadget.ditamap:
<map>
<title>Gadget Online Help</title>
<keydef keys="integ-gadget" href="integrating_gadget.dita"/>
</map>
getting_started_widget.dita:
<topic id="getstartwidget">
<title>Getting started with the Widget</title>
<body>
<p>If you choose to <xref keyref="gadget.integ-gadget">integrate the Gadget
module</xref>, many more options will be available to you.</p>
</body>
</topic>

23. Questions? Comments?
leigh.white@ixiasoft.com