wek cross-publication-linking
TRANSCRIPT
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
3
Agenda
What is cross-publication linking?
The technical challenge
One solution: shared generated key definitions
Demonstration: the process in action
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
4
WHAT IS CROSS-
PUBLICATION LINKING?
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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.
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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”
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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.
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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”
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
14
THE TECHNICAL CHALLENGE
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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.
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
21
PROPOSED SOLUTION
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
25
Requirements (cont.)
Way to automatically select the appropriate
intermediate key set for a given processing
instance
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
27
DEMONSTRATION
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
29
The Demonstration
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
30
Questions?
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
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
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
32
Thank You
Contact Info:
Eliot Kimber