Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Ki, Qi, Key:
The Way of DITA Harmony With
Keys and Key References
Eliot Kimber
Contrext, LLC
TC Dojo 2018
About the Author
• Independent consultant focusing on DITA analysis,
design, and implementation
• Doing SGML and XML for c...
Agenda
• The way of harmony: why keys are essential
• Connect and redirect: how keys and key
references work
• Key-hon waz...
THE WAY OF HARMONY
TC Dojo March 2018 4
Never Attack…Redirect
TC Dojo March 2018
In the Art of Peace we never attack.
An attack is proof that one is out of contro...
It’s All About Connection
• In Aikido and similar arts, we connect with our
attacker and through that connection link our ...
DITA is All About Linking
• DITA is about enabling reuse
• Reuse in DITA is use by reference
• Use by reference is done th...
Reuse Is The Enemy
• Reuse adds significant complexity
• If a topic is used in two places:
– How do you link to a specific...
CONNECT AND REDIRECT
TC Dojo March 2018 9
Two Ways to Connect
• Direct URI references:
<xref
href="topics/topic-01.dita"/>
• Indirect key references:
<xref
keyref="...
Direct References Are Hard and
Painful
• Creates a hard
dependency from source
to target
• Target will be the same
in all ...
Indirect References are Soft and
Gentle
• Indirect addresses allow
the ultimate target to
be different
TC Dojo March 2018 ...
Indirection with Keys
• A key reference points to a key name:
• The key name is bound to a target in a
map:
• Different ma...
KEY-HON WAZA
TC Dojo March 2018 14
First Principle: Always Use
Keys
• All links from topics to anything else should
use keys:
– Content references (@conkeyre...
Second Principle:
Keys On All Navigation Topicrefs
• "Navigation" topicrefs are topicrefs with a
@processing-role of "norm...
Third Principle:
Keys on Resource-Only
Topicrefs• Resource-only topicrefs are topicrefs with a @processing-role of "resour...
Fourth Principle:
Use Only Keyrefs in Reltables
• All topicrefs in relationship tables should use
key references to naviga...
Plenty of Perfect Practice
Always use keys for links from topics
Put keys on all navigation topicrefs
Put keys on resource...
Black Belt Techniques
• Using conditional
processing with keys
• Using key scopes (DITA 1.3)
• Cross-deliverable linking
(...
Help Your Content Return to
Harmony
• Reuse is inherently difficult
• Keys allow same topic to be used in different
contex...
Hai Dozo: Please Try
Like learning a martial art, using keys effectively
takes study and practice but if learned properly
...
Questions?
TC Dojo March 2018 23
Resources
• Me: ekimber@contrext.com
• DITA specification:
http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part3-all-i...
Upcoming SlideShare
Loading in …5
×

Ki, Qi, Key: The Way of DITA Harmony With Keys and Key References

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

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all
  • Be the first to comment

  • Be the first to like this

Ki, Qi, Key: The Way of DITA Harmony With Keys and Key References

  1. 1. Ki, Qi, Key: The Way of DITA Harmony With Keys and Key References Eliot Kimber Contrext, LLC TC Dojo 2018
  2. 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. 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. 4. THE WAY OF HARMONY TC Dojo March 2018 4
  5. 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. 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. 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. 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. 9. CONNECT AND REDIRECT TC Dojo March 2018 9
  10. 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. 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. 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. 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. 14. KEY-HON WAZA TC Dojo March 2018 14
  15. 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. 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. 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. 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. 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. 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. 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. 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. 23. Questions? TC Dojo March 2018 23
  24. 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

×