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.

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


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: [email protected], http://contrext.com


http://www.dita-community.org/paper-dita-keys-as-public-anchor-ids/dita-keys-as-public-ids.html

https://dita-ot.github.io

http://www.dita-community.org

mailto:[email protected]

http://contrext.com

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

Software

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