Taking Cross References to the Next Level:
Reltables for Non‐Topic Elements
Adding non-topic-element indirection to DITA.
11/24/2014 Contrext, LLC 1
Eliot KimberContrext, LLC
DITA Europe 2014
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
11/24/2014 Contrext, LLC 2
Agenda
• The Requirement: Use relatables to relate non-topic elements to each other
• Limitations in key-based addressing: topics only
• Solution
• Demonstration
11/24/2014 Contrext, LLC 3
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
11/24/2014 Contrext, LLC 5
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
11/24/2014 Contrext, LLC 6
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>
11/24/2014 Contrext, LLC 8
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.
11/24/2014 Contrext, LLC 9
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
11/24/2014 Contrext, LLC 10
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>
11/24/2014 Contrext, LLC 11
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
11/24/2014 Contrext, LLC 12
Implication for Reltables
• No DITA-defined way to have reltables that relate non-topic elements to each other
11/24/2014 Contrext, LLC 13
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
11/24/2014 Contrext, LLC 15
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
11/24/2014 Contrext, LLC 16
Sample Indirector Topic
<indirector id="none">
<title>Indirector to
topic-01/fig-01</title>
<indirectorBody>
<indirectElementRef
keyref="topic-01/fig-01”
/>
</indirectorBody></indirector>
11/24/2014 Contrext, LLC 17
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
11/24/2014 Contrext, LLC 18
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
11/24/2014 Contrext, LLC 19
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.
11/24/2014 Contrext, LLC 21
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
11/24/2014 Contrext, LLC 22
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: [email protected], http://contrext.com
11/24/2014 Contrext, LLC 24
Top Related