they worked before, what happened? understanding dita cross-book links

05/01/2023 Contrext, LLC 1

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

Eliot KimberContrext, LLC

Tekom 2015, Stuttgart, Germany


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)


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


A LEGACY MIGRATION STORY


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


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


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!"


What Happened?• Why did the links work in DocBook?• Why did they stop working in DITA?• What can we do to fix it?


BEFORE DITA: NO REUSE


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")


DocBook Cross-Book Links

Book 1

<book>…<olink targetdoc="book2.xml" targetptr="sect-04"/>

Book 2<book>…<section id="sect-04"> …</section>…</book>


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.


DITA INTRODUCES REUSE


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


Direct Topic-to-Topic Links

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?


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


In DITA,As Authored ≠ As Delivered

Topic 1

<xref href="topic-02.dita#t1/fig1"/>

Topic 2<topic id="t1">…<fig id="fig1">…</topic>

Map 1

Map 2

Map 3


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


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


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


DITA 1.2 Key References

Topic 1

<xref keyref="topic-02"/>

Topic 2…<fig id="fig1">…

Map 1

<keydef keys="topic-02" href="topic-02.dita"/>


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


Wait, What?• Yeah, DITA 1.2 didn't address cross-book

linking• Seriously?• Seriously.• But we fixed it in DITA 1.3


DITA 1.3 CROSS-DELIVERABLE LINKS


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"/> …


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


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"/>


DITA 1.3 Cross-Deliverable Links

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"/>


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


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


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.


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


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>


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


Resources• DITA 1.3:

https://www.oasis-open.org/news/announcements/dita-version-1-3-committee-specification-01-is-published

• Me: [email protected], http://contrext.com





mailto:[email protected]

http://contrext.com/

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.deor scan the QR code

The feedback tool will be available even after the conference!

they worked before, what happened? understanding dita cross-book links

Software