poster: cross-document linking in dita

4
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 Top ic A Top ic 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 C Desired result: B as published in Pub 2 links to A as published in Pub 2. B as published in pub 1 Map 3 Top ic c Map 1 Top ic 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

Upload: contrext-solutions

Post on 15-Jan-2017

590 views

Category:

Technology


0 download

TRANSCRIPT

Page 1: Poster: Cross-Document Linking in DITA

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

Page 2: Poster: Cross-Document Linking in DITA

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

Page 3: Poster: Cross-Document Linking in DITA

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

Page 4: Poster: Cross-Document Linking in DITA

<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