DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
1
1
Cross-Publication Linking:
Using Gene...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
2
About me
 Founding member of the DITA ...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
3
Agenda
 What is cross-publication link...
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 (...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
6
Cross-Deliverable Linking Requires
 A ...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
7
Linking and Addressing
 Addressing is ...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
8
Links Use Addresses
 Links use address...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
9
Two Domains of Addressing
 Addressing ...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
10
DITA Addressing: URIs and Keys
 DITA ...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
11
Definition: Root Map
 A root map is a...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
12
Root Maps, Publications, and
Deliverab...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
13
Definition: Use Context
 All DITA con...
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
 Y...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
16
Challenge 2: Mapping Addresses as
Auth...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
17
Challenge 2 (cont.): Addressing elemen...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
18
Challenge 3: Multiple Outputs
 A give...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
19
Challenge 4: Generating Links for All
...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
20
Challenge 5: Reflexive Dependencies
 ...
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 ...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
23
Solution: Element-to-Deliverable Ancho...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
24
Requirements
 Must have some way to i...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
25
Requirements (cont.)
 Way to automati...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
26
Open Issue for DITA 1.3: Explicit Cros...
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
To...
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://w...
DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com
32
Thank You
Contact Info:
Eliot Kimber
e...
Upcoming SlideShare
Loading in …5
×

Wek cross-publication-linking

276 views
189 views

Published on

Describes the DITA 1.3 cross-deliverable linking facility.

Published in: Software
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
276
On SlideShare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
8
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Wek cross-publication-linking

  1. 1. 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. 2. 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
  3. 3. 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
  4. 4. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 4 WHAT IS CROSS- PUBLICATION LINKING?
  5. 5. 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.
  6. 6. 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
  7. 7. 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”
  8. 8. 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
  9. 9. 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.
  10. 10. 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
  11. 11. 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”
  12. 12. 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
  13. 13. 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
  14. 14. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 14 THE TECHNICAL CHALLENGE
  15. 15. 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.
  16. 16. 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 know what the address as delivered will be for anything.  Thus, you must depend on the processor to do the mapping for you
  17. 17. 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
  18. 18. 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
  19. 19. 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
  20. 20. 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
  21. 21. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 21 PROPOSED SOLUTION
  22. 22. 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
  23. 23. 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
  24. 24. 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
  25. 25. 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
  26. 26. 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
  27. 27. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 27 DEMONSTRATION
  28. 28. 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
  29. 29. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 29 The Demonstration
  30. 30. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 30 Questions?
  31. 31. 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
  32. 32. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 32 Thank You Contact Info: Eliot Kimber ekimber@rsicms.com

×