dita cross-deliverable-addressing-poster

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

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


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


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


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?


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”


Addresses as authored

Map Pub1

Scope: P2=Pub2

Map Pub2Key: A=Topic T2

Topic T1

Key ref: P2.ATopic T2

Root Map Root MapPublication Boundary


Pass 1: Generate deliverable-specific key definitions and maps

Map Pub2Key: A=Topic T2

Deliverable Producer

DeliverableDefinition

Pub2 HTML Key Definitions

Key: A=T2.htm

Map Pub1

Scope: P2=Pub2

DeliverableDefinition

Deliverable Producer

Pub2 PDF Key Definitions

Key: A=Anchor A1



Map Pub1-PDF

Map Pub1-HTML


Pass 2: Produce deliverables from intermediate maps

Map Pub1-HTML


Key: P2.A=T2.htm


Key: P2.A=Anchor A1

Topic T1

Key ref: P2.A

Pub 2HTML

Pub 2PDF

Anchor: A1

T2.htm

Pub 1HTML

T1.htm

A href=T2.htm

Intermediate Source Pub 1 HTML Deliverable Pub 3 HTML Deliverable


dita cross-deliverable-addressing-poster

Software