Inserting a Reference, a Key Definition, a Topic Set

A DITA map can contain various types of references. The targets of the references can be:

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

A reference to a topic file, a map file, a topic set, or a key definition may be inserted with the following dialog box which is opened from the actions of the Append child and Insert after submenus of the DITA Maps Manager view's contextual menu. The content of the Append child and Insert after submenus depend on the selected node of the DITA map tree on which the contextual menu was invoked. For example if the selected node is the bookmap root node the possible child nodes are:

If the selected node is a topicref the possible child nodes are:

The same dialog box can be used to insert a non-DITA file like a PDF document.

Insert Topic Reference Dialog

By using the Insert Topic Reference dialog you can easily browse for and select the source topic file. The Target combo box shows all available topics that can be targeted in the file. Selecting a target modifies the Href value to point to it which corresponds to the href attribute of the inserted topicref element. The Format and Scope combos are automatically filled based on the selected file and correspond to the format and scope attributes of the inserted topicref element. You can specify and enforce a custom navigation title by checking the Navigation title checkbox and entering the desired title.

The file chooser located in the dialog allows you to easily select the desired topic. The selected topic file will be added as a child or sibling of the current selected topic reference, depending on the insert action selected from the contextual menu of the DITA Maps view, that is an insert action from the Append child submenu or from the Insert after one. 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.

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

You can also define keys using the Keys text field on the inserted topicref or keydef element. Instead of using the Href combo box to point to a location you can reference a key definition using the Keyref text field. Use the Choose key reference to access the list of keys defined in the currently open DITA map.

The Processing Role combo box allows setting the processing-role attribute to one of the allowed values for DITA reference elements: resource-only, normal, -dita-use-conref-target.