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.

They Worked Before, What Happened? Understanding DITA Cross-Book Links

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.

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

They Worked Before, What Happened? Understanding DITA Cross-Book Links

  1. 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. 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. 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. 4. A LEGACY MIGRATION STORY 11/13/2015 Contrext, LLC 4
  5. 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. 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. 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. 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. 9. BEFORE DITA: NO REUSE 11/13/2015 Contrext, LLC 9
  10. 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. 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. 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. 13. DITA INTRODUCES REUSE 11/13/2015 Contrext, LLC 13
  14. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 24. DITA 1.3 CROSS- DELIVERABLE LINKS 11/13/2015 Contrext, LLC 24
  25. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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!

×