Using Linking with DITA Documents
DITA topics have two different types of links. In the body of the topic, you can use the xref element to insert cross reference or inline links. In the related-links part of the topic, you can use the link element to insert links. Related links are also generated from a relationship table when you publish a DITA map. An xref can link to a topic, elements inside of a topic, and external documents. A link can only reference topics and external documents, not elements inside of a topic.
The Resource Manager contains a Link/Xref tab that enables you to browse for documents in a files system, in a CMS, or on the internet to use as the target for a link. The tab also enables you to browse within a document to locate specific elements to which you want to link. An undocked version of the Link/Xref tab is available from the Modify Attributes dialog box, the Document Map, and Column view that enables you to modify existing links.
When you insert a cross reference or link into a DITA topic,
Arbortext Editor retrieves both the title and short description for the target, if available, and displays that information in the Edit view. This enables you to determine whether generated text will be sufficient for the link, or if you need to manually author text for the link. The displayed link text is preceded by a brown diamond and has a gray background (
). If no title is available for the link target, the message
No title at target; link text should be authored is displayed as the preview text.
If you want to author the text for a cross reference or link instead of using generated text, you can easily delete the preview text. When you click the mouse pointer on the preview text or move the cursor into the preview text, all of the preview text is selected. When the preview text is selected, you can delete it or just begin typing to enter authored link or description text. You can also use the Edit window shortcut menu choices Use Authored Link Text and Use Generated Link Text to switch between the two types of text. You can use the update references feature to redisplay deleted preview text or to update preview text.
Preview text is only available for local references to DITA documents. Arbortext Editor tries to retrieve title information first from the navtitle element, then from the title element, and finally from the searchtitle element in a DITA topic. Description text is retrieved from the shortdesc element.
Note that the link preview text displayed in the Edit view is not used when you publish a document. The publishing process uses either authored link text or obtains title and description information from link targets at publishing time.
Related information