DITA referencing

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.

You reference DITA content by Content references. You create links to DITA or non-DITA resources, by Using DITA cross-references to single source content. You can also use DITA links to Add links to related content.

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 URI-based (direct) addressing.

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 Using keyspaces to manage DITA key references. 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 Key-based addressing.

Set up reference content

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 Using keyspaces to manage DITA key references.

To make an element reusable, you need to assign a unique identifier to the element. For details, see DITA ID attribute. 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.

DITA ID attribute

The DITA ID attribute provides a method to uniquely identify content (topics or elements) to refer­ence.

In a DITA topic, you can assign a unique ID to an element to use the element when you are creating a conrefs (Content references) or cross-references (Cross-references) to the element from another topic. By default, FrameMaker assigns a unique ID to the topic, when you Create a DITA topic.

See the specifications on ID attribute.

Assign a unique ID to an element

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.

Assign IDs to all instances of an element

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.

d)Select Assign.

Using keyspaces to manage DITA key references

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 Add links to related content).

However, DITA also provides the specifications for using keys to indirectly reference content. See the specifications on Key-based addressing.

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.

The keydef elements are used to create keymaps since, by default, these elements are not generated in DITA output.

Create a keyspace

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.

1)Create a DITA map.

2)Add keydef elements to the DITA map. For details, see Insert topicref elements in a 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 asso­ciated 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.

Set the default keyspace

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.

To add or remove keyspaces in the environment, click Keyspaces. For details, see Manage keys­paces.

3)Choose to apply the selected keyspace to the current topic or to all the currently opened docu­ments.

4)To set the selected keyspace as the default, click OK.

Manage keyspaces

To use a key reference in your DITA topic, you need to load the container keyspaces in FrameMaker authoring environment. After you have loaded the keyspaces in the environment, you can Set the default keyspace.

1)Open the DITA Keyspace Manager dialog (DITA > Keyspace > Manage Keyspaces).

DITA Keyspace Manager dialog


2)From the Keyspace drop-down list, select a DITA map that is defined as a keyspace. For details, see Create a keyspace.

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.

After you have loaded multiple keyspaces into the environment, you can Set the default keys­pace from the Set Keyspace dialog.

Update DITA references

You can create references in DITA topics or map, by any of the following methods:

Conrefs (See Content references)

Cross-references (See Cross-references)

Topicrefs (See Insert topicref elements in a DITA map)

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.

Find References

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.

5)Click Search.

September 30, 2016

Legal Notices | Online Privacy Policy