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.

Managing Deliverable-Specific Link Anchors: New Suggested Best Practice for Keys

824 views

Published on

How to define and maintain publicly-linkable anchors in deliverables produced from DITA source

Presented originally at DITA North America 2015

Published in: Software
  • Be the first to comment

Managing Deliverable-Specific Link Anchors: New Suggested Best Practice for Keys

  1. 1. Managing Deliverable-Specific Link Anchors: New Suggested Best Practice for Keys How to define and maintain publicly- linkable anchors in deliverables produced from DITA source 4/29/2015 Contrext, LLC 1 Eliot Kimber Contrext, LLC DITA North America 2015
  2. 2. About the Author • Independent consultant focusing on DITA analysis, design, and implementation • Doing SGML and XML for cough 30 years cough • Founding member of the DITA Technical Committee • Founding member of the XML Working Group • Co-editor of HyTime standard (ISO/IEC 10744) • Primary developer and founder of the DITA for Publishers project • Author of DITA for Practitioners, Vol 1 (XML Press) 4/29/2015 Contrext, LLC 2
  3. 3. Agenda • What are "public anchors"? • Navigation vs resource keys • Key definition and usage best practice • Generating public deliverable anchors 4/29/2015 Contrext, LLC 3
  4. 4. Executive Summary • Use keys for everything • Principle: Exactly one URI reference to each resource across all maps • Put unique keys on each navigation topicref you want to be publicly linkable or xref to • Use navigation keys to determine deliverable anchors • Don’t change navigation keys unnecessarily 4/29/2015 Contrext, LLC 4
  5. 5. What are Public Anchors? • Anything that can be linked to from outside the deliverable: – HTML files – HTML @id values – PDF named destinations – Help topic IDs • Need to be reliably persistent • Should not change from release to release for the same logical component (topic or element) 4/29/2015 Contrext, LLC 5
  6. 6. Navigation vs Resource keys • Two types of topicrefs: – "normal": contribute to the navigation tree or to reltables – "resource-only": Establish a dependency on a resource but don’t put it in the navigation tree • @processing-role on topicref: – processing-role="normal" – processing-role="resource-only" • <keydef> is resource-only by default 4/29/2015 Contrext, LLC 6
  7. 7. Resource-Only Keys • Establish context-independent keys for topics • Can be unique across all maps if required or map- or scope-specific • Key-defining maps serve as catalogs of topics or other resources (images, etc.) • Should be used for conrefs • Not useful for cross reference targets: no navigation use context 4/29/2015 Contrext, LLC 7
  8. 8. Normal-Role (Navigation) Key • Identifies the unique uses of a given topic • Only appropriate target for cross references • By the nature of keys, are globally unique within a single root map. 4/29/2015 Contrext, LLC 8
  9. 9. Key Definition and Usage Best Practice • Define resource-only keys in standalone "key- definition" maps <keydef keys="topic-000123r5" href="topics/t-57623-934.dita"/> • Use resource-only keys from navigation topicrefs: <chapter keys="chap-01" keyref="topic-000123r5"/> • Put keys on either all navigation topicrefs or • Put keys on all navigation topicrefs you want to be publicly linkable 4/29/2015 Contrext, LLC 9
  10. 10. Exactly One URI Reference For Each Resource • For images and external Web resources: – Always define a key – Refer to the key (and only the key) from topics • For topics that are or are likely to be reused: – Define resource-only keys in a separate key- defining map • For topics that are only ever used in a single map: – Put @keys on the topicref to the topic 4/29/2015 Contrext, LLC 10
  11. 11. Keys for Single-Use Topics • A topic used only once across all maps may not justify the cost of separate resource-only key definition • Define two keys on the topicref: – One that reflects that use of the topic: "ch-01-ss-01" – One that represents the topic in any context: "topic-1235" • Example: <topicref keys="installation topic-1234" href="topics/topic-1234.dita" /> • If the topic is ever reused, create resource-only topicref and move context-independent key to that definition 4/29/2015 Contrext, LLC 11
  12. 12. NOTE: DITA OT Limitation • As of OT 2.1 and earlier: – @copy-to on navigation topicrefs that use keyref doesn't work – Copy-to processing is done before key space construction • Fixing this will require rethinking entire preprocessing approach – Rethink required for DITA 1.3 anyway – Non-trivial to implement • Workaround: Use separate keydefs for each required copy-to: <keydef keys="key-01" href="topic-01.dita"/> <keydef keys="key-01-copy-to-c01s01" href="topic-01.dita" copy-to="ch01-sec01.dita"/> … <topicref keys="ch01-sec01" keyref="key-01-copy-to-c01s01"/> 4/29/2015 Contrext, LLC 12
  13. 13. Example: Publication root map <map> <title>Prod1 Product Guide</title> <mapref href="keysdefs-01.ditamap"/> <topicref keys="pubroot" keyref="topic-ABC001" > <topicref keys="chapter-01" keyref="topic-ABC123" > <topicref keys="ch01-overview" keyref="topic-ABC456" > </topicref> … </topicref> … </map> 4/29/2015 Contrext, LLC 13
  14. 14. Example: keydefs-01.ditamap <map> <title>Keydefs for Group 1</title> <keydef keys="topic-ABC001" href="topic-ABC001.dita" /> <keydef keys="topic-ABC002" href="topic-ABC002.dita" /> … </map> 4/29/2015 Contrext, LLC 14
  15. 15. Cross Reference Example <p>See <xref keyref="chapter-01"/>… <p>See <xref keyref="chapter-01/fig-01"/> 4/29/2015 Contrext, LLC 15
  16. 16. Generating Public Deliverable Anchors • Two basic use cases: – Multi-file outputs (HTML, online help) – Monolithic outputs (PDF, EPUB, etc.) • General problem: anchors for non-topic elements – Only unique within a single topic – Not necessarily unique within result documents • Must combine keys with element IDs in some cases 4/29/2015 Contrext, LLC 16
  17. 17. Multi-File Outputs (HTML) • Use navigation keys to determine result filenames: <topicref keys="chapter-01" keyref="topic-ABC123" > becomes chapter-01.html • Use navigation key plus element ID to construct in-document anchors 4/29/2015 Contrext, LLC 17
  18. 18. Monolithic Outputs (PDF) • Use navigation key for topic anchors • Use navigation key+element ID for non-topic anchors • For PDF, need to use a separator that uses legal URL characters, e.g. "_._", "-.-" – Needs to be more than "-" or "_" to avoid accidental collisions 4/29/2015 Contrext, LLC 18
  19. 19. Preprocessing Extensions • DITA Community project • Extends base preprocessing to add @copy-to to topicrefs as required – Second and subsequent reference to a given topic – Will eventually use keys for the filename value • Some subtle complexities • Haven't had time to implement yet 4/29/2015 Contrext, LLC 19
  20. 20. Summary • Always use keys for all references – To topics – To images – To peer maps (DITA 1.3) • Put keys on navigation topicrefs • Crossrefs should point to navigation keys • Use navigation keys to generate anchors in deliverables 4/29/2015 Contrext, LLC 20
  21. 21. Resources • Paper: http://github.io/dita- community/paper-dita-keys-as-public-anchor- ids • Preprocessing extensions: https://github.com/dita-community/org.dita- community.preprocess-extensions • Me: ekimber@contrext.com, http://contrext.com 4/29/2015 Contrext, LLC 21

×