When migrating content to DITA there are often links from one book to another. These links work in their legacy environment but don’t work when migrated to DITA 1.2 or earlier. Why not? This talk presents why it is that cross-book links that work in legacy environments don‘t work when migrated to DITA 1.1 or 1.2 and how to make those links work using the new DITA 1.3 crossdeliverable linking feature. It also presents challenges faced by a major software vendor as they migrate their manuals to DITA from FrameMaker through DocBook to DITA and how to solve those challenges with DITA 1.3.

1. They Worked Before, What Happened?
Understanding DITA Cross-Book Links
11/13/2015 Contrext, LLC 1
Eliot Kimber
Contrext, LLC
Tekom 2015, Stuttgart, Germany

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)
11/13/2015 Contrext, LLC 2

3. Agenda
• A story about migration to DITA
• Cross-book links in legacy content
• DITA introduces reuse, which breaks cross-
document linking
• DITA 1.3 adds cross-deliverable linking support
11/13/2015 Contrext, LLC 3

4. A LEGACY MIGRATION STORY
11/13/2015 Contrext, LLC 4

5. A Story Part 1: Legacy Days
• Big company has DocBook documents for
their publications
• These books have cross-document links to
other books ("olink" in DocBook)
• These links work in the HTML and PDF
generated from the DocBook
11/13/2015 Contrext, LLC 5

6. Note on DocBook
• Focusing on DocBook here because it is a
typical pre-DITA legacy XML format
• Other non-DITA XML applications may have
similar cross-book linking features
• May have done similar linking in unstructured
formats (e.g., FrameMaker)
• Not picking on DocBook specifically
• Point is going from low-reuse to high-reuse
content
11/13/2015 Contrext, LLC 6

7. Part 2: But then DITA Happened
• The DocBook books are converted to DITA
• Now the writers have lots of nice topics and book
maps
• They produce their HTML and PDF
• Suddenly the cross-book links stop working
• The tools support people don't understand why
• The writers say to them "it worked in DocBook,
you broke it!"
11/13/2015 Contrext, LLC 7

8. What Happened?
• Why did the links work in DocBook?
• Why did they stop working in DITA?
• What can we do to fix it?
11/13/2015 Contrext, LLC 8

9. BEFORE DITA: NO REUSE
11/13/2015 Contrext, LLC 9

10. DocBook: No Reuse
• In DocBook every book is a single XML document
• There is no reuse
• For each DocBook source document there is a small set
of deliverables
• DocBook <olink> points to a target DocBook XML
document
– Can include application-specific details for resolving the
link
• Works because there is no re-use
• Depends on non-standard application processing
("magic")
11/13/2015 Contrext, LLC 10

11. DocBook Cross-Book Links
11/13/2015 Contrext, LLC 11
Book 1
<book>
…
<olink
targetdoc="book2.xml"
targetptr="sect-04"
/>
Book 2
<book>
…
<section id="sect-04">
…
</section>
…
</book>

12. In DocBook,
As Authored ≈ As Delivered
• For a given link out of a document, the link
exists in exactly one publication
• For a given target in a document, the target
exists in exactly one publication
• Thus direct URI references from one DocBook
document as authored to another DocBook
document as authored are unambiguous for
those documents as delivered.
11/13/2015 Contrext, LLC 12

13. DITA INTRODUCES REUSE
11/13/2015 Contrext, LLC 13

14. DITA Reuse Breaks Cross-
Document Linking
• In DITA the same topic may be used in multiple
publications
• One-to-many relationship between topics and
deliverables
• For a link from a topic to another topic, what is
the target topic as delivered?
• The target topic does not know where it is (or will
be) used
• A direct URI reference to a topic does not
establish any use context for the topic
11/13/2015 Contrext, LLC 14

15. Direct Topic-to-Topic Links
11/13/2015 Contrext, LLC 15
Topic 1
<topic id="topic-01">
…
<xref href=="topic-02.dita#topic-02/sect-04"
/>
Topic 2
<topic id="topic-02">
…
<section id="sect-04">
…
</topic>Where are
the maps?

16. Wait, What?
• Yes, DITA just broke cross-document linking
• Simple approaches to addressing are not
going to work
• Seriously?
• Seriously.
• In particular, the direct URI references used in
no-reuse applications like DocBook will not
work in DITA
11/13/2015 Contrext, LLC 16

17. In DITA,
As Authored ≠ As Delivered
11/13/2015 Contrext, LLC 17
Topic 1
<xref
href="topic-02.dita#t1/fig1"
/>
Topic 2
<topic id="t1">
…
<fig id="fig1">
…
</topic>
Map 1
Map 2
Map 3

18. Same Topic: Multiple Deliverables
• Topic 1 is used in two maps: Map 1 and Map 2
• Topic 2 is used in two maps: Map 1 and Map 3
• Topic 1 points directly to Topic 2
• Which use of Topic 2 should Topic 1 as
delivered point to?
– The use in Map 1?
– The use in Map 3?
• No way to know given only information in the
DITA source
11/13/2015 Contrext, LLC 18

19. DITA 1.2: Keys
• DITA 1.2 introduced indirect addressing: Keys
and key references
• A key is defined in a map
• Binds a key name to a resource (e.g., a topic)
• The same key can be bound to different
resources in different maps
• Now possible to have use-context-specific links
from re-used topics
11/13/2015 Contrext, LLC 19

20. 1.2 Keys Handle Reuse of Links
Within Publications
• Given a topic with a link where the topic is
used in two different maps…
• …map author can define the key-to-target
binding so link resolves to the appropriate
target within the same publication
11/13/2015 Contrext, LLC 20

21. DITA 1.2 Key References
11/13/2015 Contrext, LLC 21
Topic 1
<xref keyref="topic-02"
/>
Topic 2
…
<fig id="fig1">
…
Map 1
<keydef
keys="topic-02"
href="topic-02.dita"/>

22. DITA 1.2 Keys Don't Help Cross-
Deliverable Links
• Key-to-resource binding limited to a single root map
• No way to say "this key binds to that topic as used in
that other root map"
• Could bind key to topic as delivered
<keydef key="topic-02"
href="http://mycorp.com/pubs/pub-02/topics/
topic-02.html"
format="html"
scope="external"/>
• Only works for a single deliverable
• Not interchangeable or generally reliable
• Same problem as DocBook olink
11/13/2015 Contrext, LLC 22

23. Wait, What?
• Yeah, DITA 1.2 didn't address cross-book
linking
• Seriously?
• Seriously.
• But we fixed it in DITA 1.3
11/13/2015 Contrext, LLC 23

24. DITA 1.3 CROSS-
DELIVERABLE LINKS
11/13/2015 Contrext, LLC 24

25. DITA 1.3: Scoped Keys
• DITA 1.3 adds key scopes
• A key scope establishes a distinct key space
within a root map and gives it a prefix:
<map>
<topicgroup keyscope="scope-01">
<topicref keys="key-01" …/>
</topicgroup>
…
</map>
• Can refer to scope-qualified keys from outside the
scope:
<p>See <xref keyref="scope-01.key-01"/> …
11/13/2015 Contrext, LLC 25

26. Relating Root Maps Together
• DITA 1.3 defines a new meaning for
@scope="peer" on map references
– Target map is an independent root map
– That is, the source for one or more deliverables
• If you put a scope on the map reference…
• …you can refer to keys defined in the target
map
• Enables unambiguous cross-document links
11/13/2015 Contrext, LLC 26

27. Ambiguity Resolved
• Topic 1:
<xref keyref="topic-02"/>
• Map 1:
<topicref keys="topic-02"
href="topic-02.dita"/>
• Map 2:
<keydef keys="topic-02"
keyref="map-03.topic-02"/>
<mapref keyscope="map-03"
scope="peer"
href="map-03.ditamap"/>
• Map 3:
<topicref keys="topic-02" href="topic-02.dita"/>
11/13/2015 Contrext, LLC 27

28. DITA 1.3 Cross-Deliverable Links
11/13/2015 Contrext, LLC 28
Topic 1
<xref keyref="topic-02"
/>
Topic 2
…
<fig id="fig1">
…
Map 1
<keydef
keys="topic-02"
href="topic-02.dita"/>
Map 2
<keydef
keys="topic-02"
keyref="map-03.topic-02"/>
<mapref scope="map-03"…/>
Map 3
<keydef
keys="topic-02"
href="topic-02.dita"/>

29. Ambiguity Resolved (cont.)
• When topic 1 is used in Map 1, key reference
"topic-02" resolves to topic-02 as used in
Map 1
• When topic 2 is used in Map 2, key reference
"topic-02" resolves to topic-02 as used in Map
3
• Map authors get to decide what the binding
for any key is, including redirecting a key to a
key defined in a different root map
11/13/2015 Contrext, LLC 29

30. Producing Deliverables
• DITA 1.3 enables unambiguous links as
authored
• Still a challenge to produce deliverables
• A given root map may result in many
deliverables
• For a given map-to-map link, which
deliverable should the link get bound to?
• No simple answer
11/13/2015 Contrext, LLC 30

31. Production Challenges
• Requires either consistent business rules or a way
for authors to control deliverable linking details
• Obvious business rule is "like links to like"
– E.g., links from HTML go to HTML, links from PDFs go
to PDFs
• Not always possible or practical to impose this
rule
– May need PDFs to link to HTML or HTML to link to
PDFs, for example.
11/13/2015 Contrext, LLC 31

32. Generic Solution: Use Intermediate
Key Definitions
• Two passes:
– Pass 1: Generate deliverable-specific key
definitions for all anchors in all documents that
link to each other
– Pass 2: Documents include the intermediate key
definitions for the other documents they link to
• Effect is to replace key definitions that point to
source XML with key definitions that point to
deliverables
11/13/2015 Contrext, LLC 32

33. Author Control of Deliverable-
Specific Links
• In theory, authors could manually adjust the
intermediate key definitions
• In practice, probably use private conventions
in links or key definitions as authored to
indicate deliverable linking policy
• This starts to look a lot like the @type and
@targetptr attributes on DocBook <olink>
11/13/2015 Contrext, LLC 33

34. Summary
• If there's no re-use, cross-book linking is relatively easy:
source ≈ deliverable
• Re-use breaks this simple model: direct references become
ambiguous when re-used
• DITA 1.2 doesn't solve the problem for cross-book links
– No way to explicitly address keys in other root maps
• DITA 1.3 solves the problem:
– Provides a way to explicitly address other root maps
– Key scopes enable redirecting key references to keys in other
root maps
• Processing is still a challenge: requires more complicated
data processing and configuration management
11/13/2015 Contrext, LLC 34

35. Resources
• DITA 1.3: https://www.oasis-
open.org/news/announcements/dita-version-
1-3-committee-specification-01-is-published
• Me: ekimber@contrext.com,
http://contrext.com
11/13/2015 Contrext, LLC 35

36. Your opinion is important to us! Please tell us what you thought of the
lecture. We look forward to your feedback via smartphone or tablet under
http://IN24.honestly.de
or scan the QR code
The feedback tool will be available even after the conference!