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 KimberContrext, LLC
DITA North America 2015
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
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
Executive Summary
• Use keys for everything
• Principle: Exactly one URI reference to each resource across all maps
• Put unique keys on each navigation topicrefyou 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
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
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
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
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
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
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
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:
<topicrefkeys="installation topic-1234"href="topics/topic-1234.dita"
/>
• If the topic is ever reused, create resource-only topicrefand move context-independent key to that definition
4/29/2015 Contrext, LLC 11
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
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
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
Cross Reference Example
<p>See <xref keyref="chapter-01"/>…
<p>See <xref keyref="chapter-01/fig-01"/>
4/29/2015 Contrext, LLC 15
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
Multi-File Outputs (HTML)
• Use navigation keys to determine result filenames:
<topicref keys="chapter-01"
keyref="topic-ABC123"
>becomeschapter-01.html
• Use navigation key plus element ID to construct in-document anchors
4/29/2015 Contrext, LLC 17
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
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
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
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: [email protected], http://contrext.com
4/29/2015 Contrext, LLC 21