Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Wek cross-publication-linking

337 views

Published on

Describes the DITA 1.3 cross-deliverable linking facility.

Published in: Software
  • Be the first to comment

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

×