All links can be seen as having a human-facing component and a computer-facing component. Computers need only the name of a resource in order to form a fully qualified URL or link to it. But human readers obviously need to know something about that resource in order to decide whether to navigate to it. This hint can be an icon that represents the nature of the link, but more commonly it is link text that describes or names the linked resource.

For DITA linking constructs that do not have other text available for use as this link text, the linktext element provides the situational context that human readers need for deciding whether to follow the reference. The DITA structures that contain linktext are the link child of linklist and the topicmeta child of topicref.

BenSpark / Foter / CC BY-NC-SA

In both cases, the link with linktext is a data structure rather than an inline link:

• Data structure links can stand alone or be reused in other contexts as independent representations of the target resource. The linktext element is a formal part of an address/linktext/description data model.
• Inline links are designed to allow contextually-dependent discourse as the link text. Because of this possible dependence on their surroundings, inline lines (xrefs) are not universally equivalent to the links represented by the link and topicref elements.

Did you know?

When you do an online search, the search engine is actually maintaining a linklist-like data structure of results which are rendered to your browser as inline links in groups of 10 or so. Computers love to manage data structures, but they need to present that data structure in a human-readable form. For each item that you see in the list, the target URL is usually wrapped in an HTML link as the human-readable “linktext” while a short extract from the target resource is pulled across as the effective “shortdesc” for that resource. Another name for this data/rendition relationship is the Model/View pattern in user interactions.

DITA’s linking elements make use of this Model/View pattern for selectively-applied progressive disclosure publishing strategies. This pattern is comprised of the address of the target resource, some form of link text, and a more complete description.

In all cases, if the target resource is a DITA topic or map, the constructed link in the result format (HTML for example) may make use of the title and shortdesc of the target item for a progressively disclosed linking experience. For non-DITA resources (or perhaps DITA resources that lack their own progressive disclosure elements), the link processing depends on information provided in the linking element itself for creating the progressively disclosed experience. This table shows those relationships:

Within a DITA topic, captioned elements also have descriptions that can be referenced using a progressive disclosure policy.

Note: Although the object element has a desc element and the image element has a longdescref element, the concept of linktext and direct linking is undefined for these media objects, and they are usually referenced via a containing fig element.

And although the data element has a title element, it is not considered a captioned element because normally it is not displayed; the title may be used as a field label in a property dialog in an editor, but by default the data element is never rendered as content.

Deep Dive

• DITA 1.2 Spec: The linktext element
• Progressive Disclosure, a discussion from the Interaction Design Foundation