wek cross-publication-linking

DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com

1

1

Cross-Publication Linking:

Using Generated Keys To

Link Between Root Maps

Eliot Kimber

Senior Solutions Architect


2

About me

Founding member of the DITA Technical

Committee—currently working on DITA 1.3

Creator of the DITA for Publishers project

Technical writer by training

Been doing SGML and XML analysis, design, and

implementation for 20+ years

Been working with Publishers for most of the last

10 years


3

Agenda

What is cross-publication linking?

The technical challenge

One solution: shared generated key definitions

Demonstration: the process in action


4

WHAT IS CROSS-

PUBLICATION LINKING?


5

General Definition:

Cross-Publication (Deliverable) Linking

A cross-publication link is a link from one standalone deliverable to another:

see “some section” in Some Other Book …

By standalone deliverable I mean a publication produced from a single root map and delivered as a separate thing:

Separate PDF

Separate EPUB

Separate set of Web pages

By link I mean a machine-readable navigable reference to a specific place in the target deliverable.


6

Cross-Deliverable Linking Requires

A way to point to the deliverable as a whole:

Pub-01.ditamap

Pub-01.pdf

Pub-01.epub

Pub-01.html

A way to point to a specific location in the

publication:

Topic ID/element ID pairs (DITA source)

PDF anchors

HTML IDs or <a @name> elements

Whatever a given delivery format provides for addressing


7

Linking and Addressing

Addressing is distinct from linking

A link is a relationship among two or more things:

Map A includes Topic B

Reference Topic C is the supporting reference topic for Task

Topic D

Links in DITA:

<topicref>, <xref>, <reltable>, etc.

An address is a pointer to a specific thing:

Topic: “topics/tasks/task-0001.dita”

Element: “topic-a.dita#topic-a/fig-01”

Image: “../common/assemblies/axle-assembly-12345.svg”


8

Links Use Addresses

Links use addresses to point to the things the links relate

The form of the address is unimportant as long as it can be resolved

You should be able to change the addressing details without changing the meaning of the link as long as the things pointed to are the same: href=“topic-01.dita” === href=“topic-01.dita#topic-id” ===

keyref=“topic-01” (assuming the key “topic-01” is bound to topic “topic-01.dita”)

Linking is semantics or rhetoric

Addressing is plumbing


9

Two Domains of Addressing

Addressing within the content as authored:

Defined by the source format, e.g., DITA XML

For XML source, should be independent of any given

output format

DITA defines the rules for addressing within DITA XML

Addressing from the publication as delivered:

Defined by the delivery format: PDF, HTML, EPUB, etc.

No single standard

Details may be proprietary

Not necessarily a one-to-one relationship between

content as authored and publication as delivered.


10

DITA Addressing: URIs and Keys

DITA provides two forms of address:

URI references: @href, @conref

Key references: @keyref, @conkeyref

URI references are direct references to a resource

E.g. <xref href=“../concepts/concept-002.dita”/>

No DITA-defined indirection

Cannot indicate or reflect a specific use context

Key references are indirect references to a resource:

Defined only in maps

Establish a specific use context

Keys are global to a given root map

Keys point to topics, maps, or non-DITA resources, not to

elements within topics


11

Definition: Root Map

A root map is a DITA map that is the input to a process that produces a deliverable.

A root ditamap document is the root of a map tree consisting of all the ditamaps referenced directly or indirectly from the root map.

For processing purposes, the map tree represents a single map, meaning a single collection of topic references, e.g., the “resolved map” in DITA Open Toolkit terminology.

When I say “root map” I mean the logical map or “resolved map”


12

Root Maps, Publications, and

Deliverables

In DITA, publications are represented by root maps

A root map is a map used as input to a process that produces a deliverable.

No formal definition of “publication” or “deliverable” in DITA, but in practice we produce PDFs, EPUBs, HTML, online help (.CHM), Eclipse Infocenters, etc.

Being a “deliverable” is a function of your business rules

To point to a deliverable you must know the identifier of the deliverable and where it is published


13

Definition: Use Context

All DITA content is held in topics (maps only have links to submaps and topics)

Thus linking is ultimately relating topics to topics or elements within topics to elements within topics

Topics are used from maps: maps do one thing: point to topics

A map that points to a topic establishes a use context for that topic

A given topic may be used by any number of maps

Topics do not know where they are used

Topics are always processed in terms of a specific use context


14

THE TECHNICAL CHALLENGE


15

Challenge 1: Direct URI References

You can address maps and topics by URI (@href)

From maps you use <topicref>

From topics you use <xref>

From a topic, a direct URI reference tells you nothing about the use context of the target topic

The only possible interpretation is that the target topic’s use context is the referencing target’s use context, meaning the same root map

DITA allows you to ignore topics that are not directly referenced by the map you are processing

Topics referenced from another topic must either be processed as part of the same same map or ignored.


16

Challenge 2: Mapping Addresses as

Authored to Addresses as Delivered

A reference to topic-02.dita must become a reference to topic-02.html in HTML or EPUB or anchor “1235” in PDF or whatever the addressing mechanism is in a particular output

The details of addresses as delivered are always processor dependent—the DITA standard does not and cannot mandate delivered address details.

It is up to the output processor to create and maintain this mapping

At the time you author the content you cannot knowwhat the address as delivered will be for anything.

Thus, you must depend on the processor to do the mapping for you


17

Challenge 2 (cont.): Addressing elements

within topics

You can address elements within topics using keys:<xref keyref=“topic-02/fig-01”/>

Here, “fig-01” is the ID of an element within the

topic bound to the key “topic-01”.

Keydefs do not provide any indirection for element

IDs, only to topics

Need some way to map element IDs in the DITA

source to anchors in deliverables


18

Challenge 3: Multiple Outputs

A given root map may be used to produce multiple

different published deliverables

For a given cross-publication reference, which

published form do you want the published link to

point to?

All of them?

The same format as the reference (e.g., HTML-to-HTML,

PDF-to-PDF, EPUB-to-EPUB)?

Some of them?

It depends?

There is no single rule that will work for all cases


19

Challenge 4: Generating Links for All

Possible Targets

For a given publication you can’t know what other

publications might be linking to that publication

Therefore, if you are using generated key

definitions, must generate a key for each possible

target.

That means at least one key definition for each

topic for each published form

However, for a set of publications processed in

concert, after pass 1 you can know who links to

what


20

Challenge 5: Reflexive Dependencies

Publication A links to Publication B

Publication B links to Publication A

From A, you can’t know what the published addresses

in B will be without first publishing B

But B can’t be published without having published A

Must have some type of 2+ pass process:

Publish A and B to determine the addresses as published

Publish A and B again to reflect the addresses of A used

from B and of B used from A

Implies need to maintain knowledge of addresses as

published across publishing process instances


21

PROPOSED SOLUTION


22

Solution: Intermediate Key Sets

Use keys for all addressing from topics

On first pass, generate a set of key definitions that replace the original URIs with URIs reflecting the target as published

As needed, modify the generated keys to reflect your decision about which published form to link to for a given target publication

On second pass, use the generated keys to point to targets as published

Also generate element-to-deliverable-anchor mapping tables


23

Solution: Element-to-Deliverable Anchor

Mapping

To resolve references to elements within topics, must

have a mapping from source elements to their

deliverable-specific locations

Requires information like:

Deliverable ID Topic Key Element ID Deliverable Address

Map-a-pdf Topic-01 Fig-01 Map-a.pdf#anchor-123456

Map-a-pdf Topic-01 Fig-02 Map-a.pdf#anchor-986434

Map-b-pdf Topic-01 Step-00A Map-b.pdf#anchor-543234


24

Requirements

Must have some way to indicate that a given key is a cross-publication address New addressing syntax?

Metadata on the keydef?

@scope=“peer”?

Must have a way of defining publications as a combination of: Input map

Published form (PDF, EPUB, HTML, etc.)

DITAVAL (filtering)

Processor-specific parameters that may affect publication details


25

Requirements (cont.)

Way to automatically select the appropriate

intermediate key set for a given processing

instance


26

Open Issue for DITA 1.3: Explicit Cross-

Map Key References

In DITA 1.2 no way to explicitly address a key in a

separate root map

Means you have no DITA-defined way to indicate a

given key reference is in fact cross-publication

For DITA 1.3: Proposal to add new feature for

addressing root maps (key spaces) explicitly.

Without this, no automatic way to map key-based

addresses of elements within topics

Keys only point to topics or maps, not elements within topics

The element ID is part of the key reference, not key definition

Thus, simply changing the key definition is not sufficient,

must also map element IDs to target locations


27

DEMONSTRATION


28

Prototype Implementation using Open

Toolkit Mocked Up Documents

Implements multi-pass process

Uses new pre-processor to generate intermediate key definitions and element to anchor mapping tables

Defines metadata for describing result publication details

Output format

Published location

Processing details: DITAVAL and runtime options.

Element to anchor mappings

On second and subsequent passes, uses generated key definitions and element to anchor mappings to produce cross-deliverable links


29

The Demonstration


30

Questions?


31

References

DITA proposals (https://www.oasis-

open.org/committees/documents.php):

Scoped keys: Proposal 13004

Cross-deliverable addressing: Proposal 13041

Vocabulary for publishing process details: Proposal 13120

Processor implementation:

Project on github: https://github.com/drmacro/dita13-xpub-

linking


32

Thank You

Contact Info:

Eliot Kimber

[email protected]

mailto:[email protected]

wek cross-publication-linking

Software