Inserting References

A DITA map may contain various types of references. The targets of the references can be a variety of different references, such as anchors, chapters, maps, topics, or topic sets.

You can insert references to targets such as anchors, topics, maps, topic sets, or key definitions with the Insert Reference dialog. This dialog can be opened from the DITA Maps Manager extended toolbar or with actions from the contextual menu in the DITA Maps Manager view (using the Append child and Insert after submenus).

The content of these submenus depends on the node that is selected in the DITA map tree when the contextual menu is invoked. For example, if the selected node is a topic reference (topicref), its possible child nodes include the following elements: anchorref, chapter, keydef, mapref, topicgroup, topichead, topicref, topicset, and topicsetref.

Open the Insert Reference dialog by using the Insert Reference button on the toolbar or from the contextual menu (Append child > Reference... or Insert after > Reference...).

Figure: Insert Reference Dialog

The Insert Reference dialog offers the following sections and actions:

Select the reference target: Using the browse tools, file window, and filter tool in this section, you can easily browse for and select the source target file.
Target: The URL combo box specifies the path to the target that holds the content you want to reference and the Target drop-down list shows all available target.
Element: You can use this combo box to specify the reference element.
Href: The selected target automatically modifies this value to point to the corresponding href attribute of the inserted topicref element.
Type: Allows you to select a type attribute (such as topic, task, concept, etc.) of the inserted element.
Format: This property is filled automatically, based on the selected file, and corresponds to the format attribute of the inserted element.
Scope: This property is filled automatically, based on the selected file, and corresponds to the scope attributes of the inserted element.
Collection type: Drop-down list that allows you to select the collection-type attribute to create hierarchical linking between topics in a DITA map (for example unordered, sequence, choice, family, -dita-use-conref-target).
Keys: Use this text field to define the keys attribute on the inserted reference.
Keyref: Instead of using the Href combo box to point to a location you can reference a key definition by using this text field. Use the Choose key reference button to access the list of keys defined in the currently opened DITA map.
Processing Role: This drop-down list allows you to set the processing-role attribute to one of the allowed values for DITA reference elements (for example resource-only, normal, -dita-use-conref-target).
Navigation title: This text field allows you to specify a custom navigation title for the inserted reference and to enforce it by using the Lock checkbox.

Once you click Insert or Insert and close, the selected target will be added as a child or sibling of the selected reference, depending on the insert action selected from the contextual menu of the DITA Maps view (Append child or Insert after).

Note: You can easily insert multiple topic references by keeping the dialog opened and changing the selection in the DITA Maps Manager tree. You can also select multiple resources in the file explorer and then insert them all as topic references.

Tip: Another way to easily insert a reference is to drag files from the Project view, file system explorer, or Data Source Explorer view and drop them into the map tree.