Your SlideShare is downloading. ×
0
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Wek cross-publication-linking
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Wek cross-publication-linking

69

Published on

Describes the DITA 1.3 cross-deliverable linking facility.

Describes the DITA 1.3 cross-deliverable linking facility.

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

  • Be the first to like this

No Downloads
Views
Total Views
69
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
5
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 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. 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. 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. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 4 WHAT IS CROSS- PUBLICATION LINKING?
  • 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. 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. 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. 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. 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. 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. 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. 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. 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. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 14 THE TECHNICAL CHALLENGE
  • 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. 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. 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. 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. 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. 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. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 21 PROPOSED SOLUTION
  • 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. 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. 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. 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. 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. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 27 DEMONSTRATION
  • 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. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 29 The Demonstration
  • 30. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 30 Questions?
  • 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. DITA North America 2013 | ©2013 Eliot Kimber | RSI Content Solutions, rsicms.com 32 Thank You Contact Info: Eliot Kimber ekimber@rsicms.com

×