1) The document discusses using keys to define and maintain publicly linkable anchors in deliverables produced from DITA source. 2) It recommends putting unique keys on each navigation topicref that should be publicly linkable or cross-referenced, and using navigation keys to determine deliverable anchors. 3) The keys ensure anchors are reliably persistent and do not change from release to release for the same logical component.

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
9/24/2015 Contrext, LLC 1
Eliot Kimber
Contrext, LLC
DCL Learning Series, Sept 24 2015

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)
9/24/2015 Contrext, LLC 2

3. Agenda
• What are "public anchors"?
• Navigation vs resource keys
• Key definition and usage best practice
• Generating public deliverable anchors
9/24/2015 Contrext, LLC 3

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
9/24/2015 Contrext, LLC 4

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)
9/24/2015 Contrext, LLC 5

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
9/24/2015 Contrext, LLC 6

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
9/24/2015 Contrext, LLC 7

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.
9/24/2015 Contrext, LLC 8

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
9/24/2015 Contrext, LLC 9

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
9/24/2015 Contrext, LLC 10

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
9/24/2015 Contrext, LLC 11

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"/>
9/24/2015 Contrext, LLC 12

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>
9/24/2015 Contrext, LLC 13

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>
9/24/2015 Contrext, LLC 14

15. Cross Reference Example
<p>See <xref keyref="chapter-01"/>…
<p>See <xref keyref="chapter-01/fig-01"/>
9/24/2015 Contrext, LLC 15

16. Generating Deliverables
• Links in the source need to become links in the
deliverable
• E.g., <xref keyref="ch01-ss02"/> becomes <a
href="ch01.html#unique-0345">
• "ch01.html#unique-0345" is an "anchor" in the
deliverable
– That is, a thing you can point to to create a link to that
place in the deliverable
• Generating the links is easy if you don't care what
the anchor values are
• Generating the links is harder if you do care.
9/24/2015 Contrext, LLC 16

17. We Do Care About Anchors
• If you are publishing your books to the Web
• Then people will link to or bookmark HTML
pages
• For PDF, you may want to have PDF-to-PDF
links
• Changing the anchors breaks links others have
created to your publications
9/24/2015 Contrext, LLC 17

18. 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
9/24/2015 Contrext, LLC 18

19. 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
9/24/2015 Contrext, LLC 19

20. 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
9/24/2015 Contrext, LLC 20

21. 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
• OT 1.8 only at this time (2.x support is
planned)
9/24/2015 Contrext, LLC 21

22. 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
9/24/2015 Contrext, LLC 22

23. 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
9/24/2015 Contrext, LLC 23