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 know
what 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
ekimber@rsicms.com

Wek cross-publication-linking

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie Wek cross-publication-linking

Ähnlich wie Wek cross-publication-linking (20)

Mehr von Contrext Solutions

Mehr von Contrext Solutions (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Wek cross-publication-linking