Home
DITA map files
Relationship tables
Relationship tables are used to store linking relationships between topics in a collection in the ditamap, rather than in individual topics. Linking relationships are defined in a table-like structure, with rows in the table determining which topics are linked to which.
Types of relationship tables
Relationship tables can be designed to suit a variety of types of relationships, including one way links, and links associating concept, task and reference topics.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
- Purpose of ditamap files
  DITA map files are used for defining the topics of a publication, specifying the topic sequence, and controlling linking between topics.
- Topic manifest
  Any topics referenced anywhere in the ditamap will be processed into the output publication.
- Topic hierarchy
  In DITA, the sequence and hierarchy of the topics to be published are defined in the ditamap through nested topicref elements.
- Relationship tables
  Relationship tables are used to store linking relationships between topics in a collection in the ditamap, rather than in individual topics. Linking relationships are defined in a table-like structure, with rows in the table determining which topics are linked to which.
  - Types of relationship tables
    Relationship tables can be designed to suit a variety of types of relationships, including one way links, and links associating concept, task and reference topics.
  - Labels for reltable related topic links
    The headings used to label generated related topic links in the output are based on the type attribute in the referencing topicref element.
  - Link text for reltable related topic links
    To control the text displayed in links automatically-generated from the relationship table, a linktext element must be added to the topicmeta for the topicref.
  - Storing relationship tables in separate, embedded ditamaps
    Even for medium-sized documents, it is easy for ditamap files to become unwieldy due to the number and complexity of topic references. You should take advantage of the modular nature of DITA to store relationship tables in separate ditamaps, embedded within the main ditamap, as soon as the ditamap becomes too large.
- Linking relationships
  DITA encourages the linking relationships to be stored outside the topic content. Links can be generated from topic hierarchies, relationship tables, and related-links section links.
- Inheritance and cascades in ditamaps
  Properties in ditamaps sometimes cascade from parent elements to child elements. Some values in ditamaps also override the equivalent values in referenced topics.
- Embedded (or nested) ditamaps
  The technique of using embedded, or nested, ditamaps can make it easier to manage documents by separating complex collections of topics into a number of smaller, simpler collections.
- DITA map vocabulary
- The bookmap feature
  Bookmaps are a specialisation of the base DITA map information type. Like ditamaps, bookmaps are containers for structure and context metadata, and do not contain any content. Bookmaps are used to describe page layout publishing outputs such as books, articles, manuals and research papers. They contain information structures that are specific to linear publications, such as tables of figures, title pages, chapters, sections and parts.
Syntax and mark-up
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Types of relationship tables

Relationship tables can be designed to suit a variety of types of relationships, including one way links, and links associating concept, task and reference topics.

There are many different ways that you can organise relationship tables. The most common are:

source and target: The source column lists the topics in which a link will be included, and the target column lists the topics that the source will be linked to (from source, to target). Target topics do not have links back to the source topic.

task, concept, and reference: Topics are organised into columns by information type. Each topic in a cell will be linked to all other topics that are in other cells in the same row. Topics in the same cell will not be linked to each other unless that cell's collection-type attribute is set to family.

task, concept, reference, and external: Topics are organised into columns by information type, with an extra column for link targets that are external to the ditamap collection. Each topic in a cell will be linked to all other topics that are in other cells in the same row, and all URLs listed in the external cell in the same row. Topics in the same cell will not be linked to each other unless that cell's collection-type attribute is set to family.

Some people have found that a four column arrangement of sourceonly task, targetonly concept, targetonly task, and targetonly reference is effective.

The arrangement of the reltable is defined by the following attributes in the relcolspec or relcell elements of the table:

linking: defines the rules by which links are generated
type: defines the information type (concept, task, reference, specialised)
scope: defines whether the related information is external to the collection (typically, a Web resource)

A setting in the relcolspec element will cascade down to the relcell element.

You can also choose to have a number of relationship tables of different designs in the same ditamap. You can use the reltable's title attribute to label the different reltables in a map; this title is not used in any output, so it is only an aid to authors.