A short introduction to DITA keys and key references, using the parallels with martial arts, and Aikido in particular, as thematic metaphor.

1. Ki, Qi, Key:
The Way of DITA Harmony With
Keys and Key References
Eliot Kimber
Contrext, LLC
TC Dojo 2018

2. About the Author
• Independent consultant focusing on DITA analysis,
design, and implementation
• Doing SGML and XML for cough 30 years cough
• Founding member of the DITA Technical Committee
• Founding member of the XML Working Group
• Co-editor of HyTime standard (ISO/IEC 10744)
• Primary developer and founder of the DITA for
Publishers project
• Author of DITA for Practitioners, Vol 1 (XML Press)
• First-degree black belt (shodan) in Aikido
TC Dojo March 2018 2

3. Agenda
• The way of harmony: why keys are essential
• Connect and redirect: how keys and key
references work
• Key-hon waza: The essential techniques for
successful use of keys
• Hai dozo: Please try
TC Dojo March 2018 3

4. THE WAY OF HARMONY
TC Dojo March 2018 4

5. Never Attack…Redirect
TC Dojo March 2018
In the Art of Peace we never attack.
An attack is proof that one is out of control. Never run away
from any kind of challenge, but do not try to suppress or
control an opponent unnaturally.
Let attackers come any way they like and then blend with
them.
Never chase after opponents.
Redirect each attack and get firmly behind it.
—Morihei Ueshiba, The Art of Peace
Morihei Ueshiba
Founder of Aikido
5

6. It’s All About Connection
• In Aikido and similar arts, we connect with our
attacker and through that connection link our center
or “ki” with the attacker’s ki, take their balance, and
help them return to harmony
TC Dojo March 2018
• In DITA we connect maps and
topics to each other in order to
create harmonious collections of
content
• Both require care, skill, and
calmness to be successful
6

7. DITA is All About Linking
• DITA is about enabling reuse
• Reuse in DITA is use by reference
• Use by reference is done through links:
– Topicrefs from maps to topics or other maps
– Content references from elements to other
elements
• Reuse brings value but also significant cost
TC Dojo March 2018 7

8. Reuse Is The Enemy
• Reuse adds significant complexity
• If a topic is used in two places:
– How do you link to a specific use of that topic?
– Where do the links from the topic go?
– How do you know who links to (uses) the topic?
– When a new version of the topic is created, how
do users of the topic react?
• How to neutralize these attacks?
TC Dojo March 2018 8

9. CONNECT AND REDIRECT
TC Dojo March 2018 9

10. Two Ways to Connect
• Direct URI references:
<xref
href="topics/topic-01.dita"/>
• Indirect key references:
<xref
keyref="introduction"/>
TC Dojo March 2018 10

11. Direct References Are Hard and
Painful
• Creates a hard
dependency from source
to target
• Target will be the same
in all use contexts
• If target changes, must
change source
• This hurts
TC Dojo March 2018 11

12. Indirect References are Soft and
Gentle
• Indirect addresses allow
the ultimate target to
be different
TC Dojo March 2018 12
• Each map (or key scope in DITA 1.3) can
define a different target for a given key
• Changes to the target do not require changes
to the source, only changes to the key binding
• Pain is avoided

13. Indirection with Keys
• A key reference points to a key name:
• The key name is bound to a target in a
map:
• Different maps can bind the same key
name to different targets:
TC Dojo March 2018
Map 1
Key "introduction"
—> topic ABC.dita
Topic ABC.dita
"Introduction for
Beginners"
Topic DEF.dita
"Introduction for
Experts"
Map 2
Key "introduction"
—> topic DEF.dita
<xref keyref="introduction"/>
<topicref keys="introduction"
href="topics/ABC.dita"
/> (Map 1)
<topicref keys="introduction"
href="topics/DEF.dita"
/> (Map 2)
13
Topic 01
Topic with keyref to key
"introduction"
<xref
keyref="introduction"
/>

14. KEY-HON WAZA
TC Dojo March 2018 14

15. First Principle: Always Use
Keys
• All links from topics to anything else should
use keys:
– Content references (@conkeyref)
– Cross references (<xref>, <term>,
<keyword>)
– Image references (<image>)
– Object references (DITA 1.3) (<object>)
• Ensures that topics are fully reusable
TC Dojo March 2018 15
一

16. Second Principle:
Keys On All Navigation Topicrefs
• "Navigation" topicrefs are topicrefs with a
@processing-role of "normal" (the default):
<topicref keys="installation"
href="topic-02.dita"/>
• Navigation keys identify distinct uses of a given
topic in a publication's navigation structure
• Serve as targets for cross references and reltable
links
TC Dojo March 2018 16
二

17. Third Principle:
Keys on Resource-Only
Topicrefs• Resource-only topicrefs are topicrefs with a @processing-role of "resource-
only"
– <keydef> topicref type is resource-only by default
• Use for "warehouse" topics:
<keydef keys="reuse-figs" href="warehouse/figures.dita"/>
• @conkeyref points to warehouse topic key and element ID within the warehouse
topic:
<fig conkeyref="reuse-figs/fig-remove-cover"/>
• Use resource-only topicrefs for external (non-DITA resources):
<keydef keys="website-A"
scope="external" format="html"
href="http://www.example.com/A"
><topicmeta><navtitle>Web Site A</navtitle></topicmeta>
</keydef>
• Use resource-only topicrefs for images:
<keydef keys="image-cover-remove" format="jpg"
href="images/prod-01/cover/remove-01.jg"/>
• Do not use as targets of cross references
TC Dojo March 2018 17
三

18. Fourth Principle:
Use Only Keyrefs in Reltables
• All topicrefs in relationship tables should use
key references to navigation topicrefs
• Reltable links are equivalent to cross
references
• Want to link specific uses of topics to each
other
• Allows reltable itself to be reused in different
maps or key scopes
TC Dojo March 2018 18
四

19. Plenty of Perfect Practice
Always use keys for links from topics
Put keys on all navigation topicrefs
Put keys on resource-only topicrefs
Use only keyrefs in relationship tables
TC Dojo March 2018 19
一
二
三
四

20. Black Belt Techniques
• Using conditional
processing with keys
• Using key scopes (DITA 1.3)
• Cross-deliverable linking
(DITA 1.3)
• Managing sets of shared
keys
TC Dojo March 2018 20

21. Help Your Content Return to
Harmony
• Reuse is inherently difficult
• Keys allow same topic to be used in different
contexts
• Keys separate links from the details of the link
targets
– Makes the content more robust and less sensitive
to change
– Allows topics and maps to be reused in different
contexts
TC Dojo March 2018 21

22. Hai Dozo: Please Try
Like learning a martial art, using keys effectively
takes study and practice but if learned properly
and practiced consistently it will make you
powerful.
TC Dojo March 2018 22

23. Questions?
TC Dojo March 2018 23

24. Resources
• Me: ekimber@contrext.com
• DITA specification:
http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part3-all-inclusive.html
• DITA 1.3 Feature Article: Understanding
Scoped Keys in DITA 1.3, Leigh White.
https://www.oasis-open.org/committees/download.php/56472
• DITA For Practitioners, Vol. 1, Eliot Kimber.
http://xmlpress.net/publications/dita/practitioners-1/
– Chapter 8 covers keys. Predates DITA 1.3
TC Dojo March 2018 24