DITA referencing (also known as DITA addressing) provides the capability to reference or link among DITA elements and between DITA elements and non-DITA resources.
The DITA specifications define two types of referencing:
Direct referencing (URI-based addressing)
References are established by pointing direct to the target. For example, in FrameMaker, when you create a conref using direct referencing, you navigate to and choose the DITA topic (.xml file). Similarly, you point directly to the DITA topic (.xml file) to create a DITA link or a DITA cross-reference. Direct referencing requires authors to explicitly choose the file containing the content to reference or link. This can be cumbersome and confusing if you have a large set of related content. Direct referencing is preferred if you do not have a large set of documents that reference or link to.
See the specifications on.
Indirect referencing (key-based addressing)
References are established globally at the DITA map level using keys. For example, in FrameMaker, when you create a conref using indirect referencing, you do not point directly to the DITA topic. Instead, you point to a key that is defined . Indirect referencing requires authors to choose user-defined keys when creating references or links. When setting up the keyspaces, a well defined nomenclature should be used to name keys. Indirect referencing is recommended if you are authoring in a large set of related content.
See the specifications on.
To create a conref in your DITA topics, you first need to create a DITA topic (direct referencing) or a DITA map (indirect referencing) that contains the content (elements) that you plan to reuse. For example, say you plan to reuse a table, an ordered list, and an image across multiple topics. You will need to add these elements to the source topic. If you are using indirect referencing, the topic is then added to the DITA map. For details, see .
To make an element reusable, you need to assign a unique identifier to the element. For details, see . FrameMaker uses this unique identifier to differentiate the conref elements. For example, if you update the source element, FrameMaker uses the unique identifier to identify the elements in the container topics that need to be updated.
The DITA ID attribute provides a method to uniquely identify content (topics or elements) to reference.
In a DITA topic, you can assign a unique ID to an element to use the element when you are creating a conrefs () or cross-references (Cross-references) to the element from another topic. By default, FrameMaker assigns a unique ID to the topic, when you .
See the specifications on.
1)In the Structure View, select an element in the source topic.
2)From the DITA menu, select Assign ID to Element.
Alternatively, right-click on the element and choose Assign ID to Element from the pop-up menu.
To check if an element has an ID assigned to it, in the Structure View, click the + (plus) sign to the right of the element.
Unique ID assigned to entry (table cell) element
If you assign a unique ID to an element to which an ID is previously assigned, you will be prompted to replace the existing ID.
1)Select an instance of the element for which you want to assign IDs.
2)Select DITA > Assign ID to Elements.
a)If necessary, select the element name in the drop-down. By default, the element selected before selecting Assign ID to Elements is selected in the drop-down.
b)Select Include specialization to assign IDs to specializations of the selected element. If you are in a DITAMAP, select Process Topicrefs in Ditamap to assign IDs to all instances of the selected element in the topics in the ditamap.
c)If you have multiple files open, select All Open Files to assign IDs to all the instances of the selected element in all the open files.
In a DITA topic, you can directly reference content by specifying the DITA topic file (.xml). For example, to add links in the related links section, of a DITA topic, you can choose the topic files to reference (see ).
However, DITA also provides the specifications for using keys to indirectly reference content. See the specifications on.
Using keys, adds a degree of indirection to the referenced content. When working with keys, the author does not reference topic files directly. The author is provided with a keyspace, a collection of user-defined keys to reference. The keyspace internally references any number of topics. The author is then concerned only with the keys in the provided keyspaces. Also, since the keys are user-defined, they can be named appropriately to allow author to easily recognize them.
Theare used to create keymaps since, by default, these elements are not generated in DITA output.
A keyspace is created using a DITA map. To create a DITA map to use as a keyspace, you need to add keydef elements to the DITA map.
The keys attribute is used to identify a specific keydef in a keyspace. Since the keys attribute is mandatory for a keydef element, you can specify the attribute value in the Attributes for New Elements dialog or in the Key Name field in the Insert Element dialog.
An author using the keyspace then will only refer to the key names and not directly to the associated DITA topics. For this reason, you should specify key values that are clearly indicative of the referenced (underlying) topic content.
3)Save the DITA map.
An author uses keyspaces to create indirect references to content. If multiple keyspaces are loaded in the FrameMaker environment, you need to specify the default keyspace to use for the current or all the open documents.
1)Open the Set Keyspace dialog (DITA > Keyspace > Set Keyspace).
Set Keyspace dialog
2)In the Keyspace drop-down, select from the list of keyspaces.
3)Choose to apply the selected keyspace to the current topic or to all the currently opened documents.
4)To set the selected keyspace as the default, click OK.
1)Open the DITA Keyspace Manager dialog (DITA > Keyspace > Manage Keyspaces).
DITA Keyspace Manager dialog
If the required DITA map is not available in the list, click Load Keyspace and select the DITA map file.
The key references defined in the keyspace are displayed in the Defined Keys list.
If you make changes to the keyspace (DITA map) after loading the keyspace in the current environment, click Refresh to view changes to the key references.
3)To specify the default keyspace, click Set as Default.
You can create references in DITA topics or map, by any of the following methods:
•Cross-references (See Cross-references)
If you update the referenced content, the references in the current topic are not immediately updated. For example, if a DITA map references a specific topic and the title of the topic is changed, the updated title does not immediately display in the DITA map.
To update the references in a selected topic or map, use the DITA Update References dialog:
1)Choose DITA > Update References.
The DITA Update References dialog is displayed:
DITA Update References dialog
2)To update the references in the current topic or map, check the specific options and click OK.
You can search through a document or recursively through multiple files in a folder for links such as conref, topicref, link, or xref. By default, the Find References dialog box populates the ID of the current topic and element, if any is selected. Typically, you select the element which is referenced elsewhere, and then call this option.
1)Select DITA > Find References. Or, to find the reference of the current element, right-click within the element, and select Find References. The element ID is populated automatically.
2)On the Find References box, enter the ID of the element, if necessary.
3)Optionally, to limit the search within a keyspace, select the keyspace for the current document.
4)Set the search scope. If you select a folder, you can recursively search for references to the element in all the files in the folder.