topicsetref

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

Document

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

Version

1.3

Author

OASIS DITA Technical Committee

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

When possible, applications should treat the referenced topicset as an independent unit. For example, an application that renders DITA for a dynamic navigation platform might generate a reusable navigation structure for each topicset, and each topicsetref is retained as a reference to that structure. This differs slightly from the processing of the conref attribute, which results in a literal copy of the referenced content.

For situations that do not support reusing a topic set as an independent unit, such as a rendered PDF, applications MAY resolve the topicsetref element as for other topicset (or topicref) elements that have the format attribute set to "ditamap".

As with other cases where the attribute format="ditamap" is specified or used as a default, the use of topic references nested inside of topicsetref is undefined.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

+ map/topicref mapgroup-d/topicsetref

Example

The sql-tutorial.ditamap file contains a topicset element that groups together several topics that collectively comprise an overview of SQL.

Figure. DITA map that contains a topicset element

<!-- Excerpt from sql-tutorial.ditamap -->
<topicset id="sqlbasics" href="sqlOverview.dita">
  <topicref href="sqlSelection.dita"/>
  <topicref href="sqlJoin.dita"/>
  <topicref href="sqlFilter.dita"/>
  <!-- ... -->
</topicset>

Another map can include that topic set, in addition to content related to programming with JDBC.

Figure. DITA map that contains a topicsetref element

<topichead navtitle="Mastering JDBC">
  <topicsetref href="sql-tutorial.ditamap#sqlbasics"/>
  <topicref href="jdbcPrepare.dita"/>
  <!-- ... -->
</topichead>

A reader of the JDBC information will see the content integrated as a single unit.

Figure. Result of the reuse

<topichead navtitle="Mastering JDBC">
  <topicset id="sqlbasics" href="sqlOverview.dita">
    <topicref href="sqlSelection.dita"/>
    <topicref href="sqlJoin.dita"/>
    <topicref href="sqlFilter.dita"/>
    <!-- ... -->
  </topicset>
  <topicref href="jdbcPrepare.dita"/>
  <!-- ... -->
</topichead>

Attributes

The following attributes are available on this element: Universal attribute group, Link relationship attribute group (with narrowed definitions of href, format, and type, given below), Attributes common to many map elements, Topicref element attributes group, outputclass, keys, and keyref.

href: A pointer to the topicset represented by topicsetref. See The href attribute for detailed information on syntax.
format: The format attribute identifies the format of the resource being referenced. For the topicsetref element, this attribute defaults to "ditamap", because the element typically references a branch of a map. See The format attribute for details on other supported values.
type: Describes the target of a reference. For the topicsetref element, this attribute defaults to "topicset". See The type attribute for detailed information on other supported values and processing implications.