Types of Topic references in DITA

What are the various types of Topic references in DITA

DITA provides many types of reference links that you can use to insert topics into maps. Each reference link type has specific processing results.

 

What is a Topic Reference?

The <topicref> element is a link to a topic (concept, task, or reference) or other resource. A <topicref> can contain other <topicref> elements, allowing you to express navigation or table-of-contents hierarchies, in addition to implying relationships between a containing (parent) <topicref> and its children. You can set the collection-type of a parent <topicref> to determine how its children are related to each other. You can also express relationships among <topicref> elements by using group and table structures (<topicgroup> and <reltable>). Relationships are expressed as links in the output (with each participant in a relationship having links to the other participants by default).

 

What is a Map Reference?

The <mapref> element is a convenience element that has the same purpose as a <topicref> element except that it explicitly sets the format attribute to “ditamap”. The hierarchy of the referenced map is merged into the container map at the position of the reference, and the relationship tables of the child map are added to the parent map.

 

What is a Topic Group?

The <topicgroup> element is designed for grouping <topicref> elements without affecting the hierarchy, as opposed to nesting <topicref> elements, which does imply a structural hierarchy. The <topicgroup> element can group <topicref> elements and so provide linking relationships and shared, inherited attributes without affecting the resulting table of contents or navigation.

The <topicgroup> element is meant as a non-titled grouping element, so adding a <navtitle> element to the <topicgroup> element has no defined purpose, and processors are required to ignore the title.

 

What is a Topic Head?

The <topichead> element provides a title-only entry in a navigation map, which appears as a heading when the map is rendered as a table of contents. In print contexts, it also appears as a heading in the rendered content.

 

What is a Topic Set?

The <topicset> element defines a complete unit of content that can be reused in other DITA maps or other <topicset> elements. The <topicset> element can be especially useful for task composition in which larger tasks are composed of a number of smaller tasks. The <id> attribute on a <topicset> is required, which ensures that the complete unit is available for reuse in other contexts.

A <topicset> is similar to a source file that contains nested topics in that the combination of topics constitutes a complete, self-contained unit. That unit of content can stand independently of the containing, prior, and following content within the original map context.

 

What is a Topic Set Reference?

The <topicsetref> element references a <topicset> element. The referenced <topicset> element can be defined in the current map or in another map.

 

What is a Glossary Reference?

The <glossref> element is a convenience element for creating a reference to a glossary topic. It has a required keys attribute, which forces the author to create a key by which inline terms may reference their definition. For example, when glossentry topics are used to define acronyms, this will remind authors to create a key, which <abbreviated-form> elements may use to reference the short and expanded versions of that acronym.

Note: Only a <map> element can contain a <glossref> element. The bookmap

element allows the <glossarylist> element.