Describes the abstract implementation approach for processing and producing cross-deliverable links in DITA 1.3

1. DITA 1.3 Cross-Deliverable
Addressing
• DITA publications represented by “root maps”
• Each root map establishes one or more unique “key
spaces” for addressing topics by key name (indirect
addresses)
• Each key space has one or more associated “scope names”
• Can address keys in a separate root map by assigning a key
scope to the target root map (topicref with @scope=peer)
• Cross-deliverable links in the source are unambiguous
• In general case, author cannot know potential deliverables
for target publications. Can only know location of source as
authored for target publications.
• Challenge: How to render working cross-deliverable links
from a given deliverable produced from a given root map?
W. Eliot Kimber Contrext, LLC Balisage 2014

2. Solution: Generated Deliverable-
Specific Key Definitions and Maps
1. For each root map/deliverable pair, generate a
set of key definitions that bind keys to
addressable locations in the deliverable.
2. For a given deliverable:
A. Generate an intermediate map that includes the
deliverable-specific key definitions for each target
deliverable before or in place of any original key
definitions
B. Adjust the order of key definitions as needed to bind
a given key to the appropriate deliverable
C. Process this map to produce the final deliverable
W. Eliot Kimber Contrext, LLC Balisage 2014

3. Additional Requirements
• Deliverable instance definition
– Captures a root map/deliverable pair
– Captures information about how the map is processed:
• Filtering and flagging parameters
• Rules for mapping specific keys to specific deliverables
• Any other runtime parameters
• Business rules for choosing target deliverables
• Delivered location of result deliverable (e.g., URL as delivered,
shared file system location, etc.)
• Production time and any other relevant historical details (agent
making request, server produced on, etc.)
– Can be standardized for interchange and historical tracking
W. Eliot Kimber Contrext, LLC Balisage 2014

4. Benefits
• Not dependent on use of a single all-knowing
server
• Uses standard DITA facility: keys
• Deliverable production can be done by DITA
1.2 processors. Knowledge of key scopes only
required for first pass.
• Deliverable production can be distributed
across multiple loosely-coupled servers
W. Eliot Kimber Contrext, LLC Balisage 2014

5. Implementation Challenges
• Deliverable producers must produce key-to-address
mappings
• For complete automation, need way to correlate root
maps as referenced to deliverable definitions to use for
a given deliverable generation instance.
• Author-control of key-to-deliverable mapping requires
modifying intermediate key sets
– Could be avoided through metadata on key definitions or
parameters to deliverable generation process
• How to translate key and element ID to deliverable-
specific address?
W. Eliot Kimber Contrext, LLC Balisage 2014

6. Practical Implications
• Regeneration of any given deliverable may
require regeneration of deliverables that link
to that deliverable
• In practice, requires some sort of production
management system to track and maintain
historical production details and make
production process easy and convenient
• Process simplified by imposing business rules,
e.g. “like links to like”
W. Eliot Kimber Contrext, LLC Balisage 2014

7. Addresses as authored
Map Pub1
Scope: P2=Pub2
Map Pub2
Key: A=Topic T2
Topic T1
Key ref: P2.A
Topic T2
Root Map Root MapPublication
Boundary
W. Eliot Kimber Contrext, LLC Balisage 2014

8. Pass 1: Generate deliverable-specific key definitions and maps
Map Pub2
Key: A=Topic T2
Deliverable
Producer
Deliverable
Definition
Pub2 HTML Key
Definitions
Key: A=T2.htm
Map Pub1
Scope: P2=Pub2
Deliverable
Definition
Deliverable
Producer
Pub2 PDF Key
Definitions
Key: A=Anchor A1
Pub1 HTML Key
Definitions
Pub1 PDF Key
Definitions
Map Pub1-PDF
Map Pub1-HTML
W. Eliot Kimber Contrext, LLC Balisage 2014

9. Pass 2: Produce deliverables from intermediate maps
Map Pub1-HTML
Pub2 HTML Key
Definitions
Key: P2.A=T2.htm
Pub2 PDF Key
Definitions
Key: P2.A=Anchor
A1
Topic T1
Key ref: P2.A
Pub 2
HTML
Pub 2
PDF
Anchor: A1
T2.htm
Pub 1
HTML
T1.htm
A href=T2.htm
Intermediate Source Pub 1 HTML Deliverable Pub 3 HTML Deliverable
W. Eliot Kimber Contrext, LLC Balisage 2014