poster: cross-document linking in dita
TRANSCRIPT
Cross-Document Linking in DITA Challenge: How to author links to targets in other topics where the topic may (or may not) be published in a separate publication?
Map 2
Topic A
Topic B
Topic B as authored has a cross reference to Topic A as authored
1
Produce publications
Publication 1
Topic D
Topic A
Publication 3
Topic B
Topic CDesired result: B as published in Pub 2 links to A as published in Pub 2. B as published in pub 3 links to A as published in Pub 1. 1
Map 3
Topic c
Map 1
Topic D
Publication 2
Topic A
Topic B
Topic B links to topic A. Topic B Is used in two maps. Topic A is used In two different maps. What does B point to?
DITA XML source documents
2
Solution Part 1.A: Indirect Addressing in Source As Authored (Single Publication)
<topic id="topic-a"> <title>Topic A</title> …</topic>
Topic_A.dita
<topic id="topic-b"> <title>Topic b</title> <body> … <p>…<xref keyref="topic-a" >Topic A</xref>… </P></topic>
Topic_B.dita
Reference to key "topic-a".
Key "topic-a" is bound to resources in the maps that use Topic B. Here, "topic-a" is resolved in the context of Map 2.
<map> <title>Map 1</title> <topicref keys="topic-a" href="Topic_A.dita" /> <topicref href="Topic_B.dita" /></topic>
Map_2.ditamap
3
Solution Part 1.B: Publication-to-Publication Relationships
<map> <title>Map 3</title><mapref keyscope="pub-1" scope="peer" href="Map_1.ditamap" /> <topicref keys="topic-a" keyref="pub-1.topic-a" /> <topicref href="Topic_B.dita" />
Map_3.ditamap
<topic id="topic-b"> <title>Topic b</title> <body> … <p>…<xref keyref="topic-a" >Topic A</xref>… </P></topic>
Topic_B.dita
Map_1.ditamap
<map> <title>Map 1</title> <topicref keys="topic-a" href="Topic_A.dita" /></map>
Target publication is represented by its root map (Map_1.ditamap). The @scope of "peer" on the map reference from Map 3 means "this is the root of a publication". Map 1 is bound to scope "pub-1" in Map 3.
In Map_3, key "topic-a" is redirected to key "pub-1.topic-a", which means "'topic-a' as defined in root map Map_1.ditamap."
<map> <keydef keys="topic-b" href="pub_3.pdf#name:topic-b" format="pdf" scope="external" /> …</map>
pub-3-pdf-keydefs.ditamap
4
Solution Part 2: Producing Cross-Deliverable Links in PublicationsPass 1: Generate Intermediate key definitions for keys in each publication, reflecting the specific deliverable, e.g.,Publication_1.pdf, Publication_2.pdf, Etc.
Map 1
Map 3
<map> <keydef keys="topic-a" href="pub_1.pdf#nameddest=topic-a" format="pdf" scope="external" /> …</map>
pub-1-pdf-keydefs.ditamap
Pub 1 (Pass 1)Topic D
Topic A
Pub 3 (Pass 1)Topic B
Topic C
Map 3
Topic B
Topic C
Pub 1 PDF
keydefs Pub 3 (Pass 2)Topic B
Topic C
Map 1
Pub 1 (Pass 2)Topic D
Topic A
Topic D
Topic A
Pass 2: Reprocess original input maps with Intermediate key definitions used.Deliverable-specific keys override keys from original maps