Skriftlig Info ➜ DITA publishing ➜ Indirect adressing ➜ Building blocks in indirect adressing
Indirect adressing
Introduction to indirect adressing
Why should I use indirect adressing?
Buildingblocks in indirect adressing
Illustrating the indirect adressing sequence
Use the keyref attribute to fetch an entire topic
Use the conkeyref attribute to fetch a single text element
In fact, you will only use two standard DITA building blocks: topics and topic maps. However, I have chosen to identify them with specific names. I have also chosen to use a unique name for the request that "starts" the indirect processing sequence.
These names are for practical purposes only. These names are in no way related to the official DITA specification. If you don't like them, don't use them.
The purpose of indirect addressing is to replace existing text in your publication - text created for a specific context - with a different text better suited for another context.
This new text is put to use in a topic, and I have chosen to identify this topic as a target topic. My target topic is a standard DITA topic, typically a task, a concept or a reference topic.
I define a DITA topic as follows:
A DITA topic is a stand-alone data module that contains multimodal text. The module has a title and enough information to explain a specific procedure or concept. Each topic is written in such a way that it is independent of other topics and can be reused in different publications whenever appropriate. The content of the topic is presented in a flat structure. Structure and context are established when the topic is inserted into a topic map together with other topics.
The new text I have chosen to replace my existing text is taken from a given source and placed inside this target topic.
|
The target topic is located in the bookmap. It can be a separate <chapter>, or placed inside a topic map with a <topicref> tag. |
To replace text in my target topic, I need to retrieve the text from somewhere. This "somewhere" is also a standard DITA topic, and I refer to this topic as my source topic.
|
As a source topic, it is not placed inside the bookmap like the target topic. The source topic is automatically placed inside the bookmap as a sub-element to the keymap. As you will see below, the keymap is located inside the <frontmatter> tag at the top of the bookmap. |
TipDITA topics are explained in more detail under the heading DITA topics. The DITA bookmap - and its structure - is explained under heading DITA topic maps. |
To connect the information in the source topic to the target topic, use a standard topic map. Due to its specific use, I have chosen to refer to this map as a keymap.
A DITA keymap is a stand-alone data module that contains electronic links to objects. A keymap is a standard DITA topic map that performs a specific task; it contains the links required for indirect addressing. The keymap will establish a connection using a reference from a target topic. This connection will address a specific source topic or a text element inside the source topic. The topic map "connects" these objects together. The term Keymap is not defined in the DITA specification.
The keymap uses the <keydef> element to make the connection. Two attributes are used:
You must insert the keymap into your bookmap. The correct location is inside the <frontmatter> element. Use the <mapref> element and retrieve the keymap using the correct URI. You can insert as many keymaps as you want, and you can also place keymaps inside each other.
Structure example:
<frontmatter>
<bookabstract>
<preface>
<booklists>
<toc>
<figurelist>
<tablelist>
<mapref>
</frontmatter>
The entire process of retrieving information using indirect addressing starts with an attribute in your topic map or topic. The word "key" is used in many of the elements and attributes in use. Therefore, I use "key request" as a generic term to describe the link from my target topic to the publication's keymap.
There are two types of key requests.
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.