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

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

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)

Agenda
• What are "public anchors"?
• Navigation vs resource keys
• Key definition and usage best practice
• Generating public deliverable anchors

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

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)

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

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

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.

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

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

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

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"/>

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"
>
<topicref keys="ch01-overview"
>
</topicref>
…
</topicref>
…
</map>

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>

Cross Reference Example
<p>See <xref keyref="chapter-01"/>…
<p>See <xref keyref="chapter-01/fig-01"/>

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.

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

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

Multi-File Outputs (HTML)
• Use navigation keys to determine result
filenames:
<topicref keys="chapter-01"
>
becomes
chapter-01.html
• Use navigation key plus element ID to
construct in-document anchors

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

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)

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

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

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

More Related Content

What's hot (20)

Viewers also liked (12)

Similar to Managing Deliverable-Specific Link Anchors: New Suggested Best Practice for Keys (20)

More from dclsocialmedia (7)

Recently uploaded (20)

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