Taking Cross References to the Next Level: Reltables for Non-Topic Elements

Taking Cross References to the Next Level:
Reltables for Non‐Topic Elements
Adding non-topic-element
indirection to DITA.
Eliot Kimber
Contrext, LLC
DITA Europe 2014
11/24/2014 Contrext, LLC 1

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)
• More DITA 1.3 accepted proposals than any other TC
member

Agenda
• The Requirement: Use relatables to relate
non-topic elements to each other
• Limitations in key-based addressing: topics
only
• Solution
• Demonstration

REQUIREMENT: USE RELTABLES
FOR NON-TOPIC ELEMENTS

Reltables: Imposed Links
• Relatables link topics to other topics or non-
DITA resources
– “extended links” in Xlink terminology
– “stand-off” or “external” links more generally
• Avoids embedded cross references
• Can define arbitrary link types
• Defined in maps using topicrefs
• Very sophisticated linking feature of DITA

Requirement: Link Non-Topic
Elements Using Reltables
• E.g.,
– Associate figures with task steps
– Associate empty marker elements with cross-reference
targets
– Link assessment questions to related or
supporting content
• No way to do this in DITA through DITA 1.3
using DITA-defined facilities

LIMITATIONS IN DITA
INDIRECT ADDRESSING

Relatables Only Link to Topics
• Reltables only use topicrefs to define the link
ends:
<reltable>
<relrow>
<relcell>
<topicref keyref=“topic-01”/>
</relcell>
<relcell>
<topicref keyref=“topic-02”/>
</relcell>
</relrow>
</reltable>

Topicrefs Can Only Address Topics
• The semantic of <topicref> is to address
topics, maps, or non-DITA resources.
• And nothing else:
– “References to DITA content cannot be below the
topic level: that is, you cannot reference individual
elements inside a topic.” —@href attribute
description for <topicref> reference entry, DITA
1.2 specification.

Keys Provide Indirect Addressing
for Topics
• Keys provide indirect addressing to topics,
maps, non-DITA resources
– That is, the things you can point to with topicrefs
• Keys are essential for re-use of content
– Decouple references to resources from location of
those resources
– Allows different key bindings in different maps

No Indirection for Non-Topic
Elements
• Can use keys to crossref and conref to non-topic
elements:
– <xref keyref=“topic-01/fig-01”/>
• This is a reference to the element with ID “fig-01”
in the topic bound to the key “topic-01”, e.g.:
<topic id=“topicid”>
<title>Topic One</title>
<body>
<fig id=“fig-01”>…</fig>
</body>
</topic>

Implication for Non-Topic Elements
• The key reference “topic-01/fig-01” requires
that all topics bound to the key “topic-01”
have an element with the ID “fig-01”
• There is no way to say “for this topic bound to
key ‘topic-01’, treat element with ID “Xabcd”
as though it was “fig-01”
• This lack of non-topic-element indirection was
a considered decision by the TC

Implication for Reltables
• No DITA-defined way to have reltables that
relate non-topic elements to each other

THE SOLUTION

If Topicrefs Only Point to Topics…
• Use topics as the indirectors
• Define a topic type whose only non-metadata
content is a specialized crossref
• Semantic of the topic is “nothing to see here,
continue on to the crossref target”
• Specialized crossref makes it clear that the
intent is indirection
• Fallback behavior is a topic with a navigable
cross reference

Indirector Topic Type
• Specializes <topic>
• Allows only <indirectElementRef> and <data>
in its body element
• No shortdesc or abstract or nested topics or
related links
• Normal prolog

Sample Indirector Topic
<indirector id="none">
<title>Indirector to
topic-01/fig-01</title>
<indirectorBody>
<indirectElementRef
keyref="topic-01/fig-01”
/>
</indirectorBody>
</indirector>

indirectorSet Topic Type
• Convenience for managing multiple
indirectors in a single XML file
• Title, prolog, zero or more <indirector> topics
• Does not affect the interpretation of
contained indirectors

Reltable-Based XRefs
• New domain: indirector-d
• Defines one element: <indirect-xref-anchor>
– Specialization of topic/ph
– Takes an @id and allows only optional <data>
within content
• When it’s the anchor of a reltable entry, result
should be xrefs to the other ends of the
relationships

PROCESSING
IMPLEMENTATION

Reltable-based XRefs
• Extend related links preprocessing
• Generate literal xref elements for each link
end related to an <xref-anchor> via relatable
rows.
• Probably need options for how to label the
xrefs, surrounding text, etc.

MapLinks Preprocess Step
• The preprocess step maplinks processes the
resolved map
• Generates links to be added to topics (related
links)
• Could be overridden to also handle indirectors
• The move-links Java code puts the links into
topics
– Could be extended to also put generated cross
references into topics.
• The topicpull step also updates links in topics, but
uses XSLT

DEMO
• Let’s see if it works…

Resources
• Full paper: http://www.dita-community.
org/paper-dita-keys-as-public-anchor-
ids/dita-keys-as-public-ids.html
• DITA Open Toolkit: https://dita-ot.github.io
• DITA Community Resources GitHub project:
http://www.dita-community.org
• Me: ekimber@contrext.com,
http://contrext.com

Taking Cross References to the Next Level: Reltables for Non-Topic Elements

Recommended

Recommended

More Related Content

Similar to Taking Cross References to the Next Level: Reltables for Non-Topic Elements

Similar to Taking Cross References to the Next Level: Reltables for Non-Topic Elements (20)

More from Contrext Solutions

More from Contrext Solutions (20)

Recently uploaded

Recently uploaded (20)

Taking Cross References to the Next Level: Reltables for Non-Topic Elements