Context hooks and window metadata for user assistance

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

version
1.3
author
OASIS DITA Technical Committee

Context hook information specified in the resourceid element in the DITA map or in a DITA topic enables processors to generate the header, map, alias and other types of support files that are required to integrate the user assistance with the application. Some user assistance topics might need to be displayed in a specific window or viewport, and this windowing metadata can be defined in the DITA map within the ux-window element.

Context hook and windowing information is ignored if the processor does not support this metadata.

User interfaces for software application often are linked to user assistance (such as help systems and tool tips) through context hooks. Context hooks are identifiers that associate a part of the user interface with the location of a help topic. Context hooks can be direct links to URIs, but more often they are indirect links (numeric context identifiers and context strings) that can processed into external resource files. These external resource and mapping files are then used directly by context-sensitive help systems and other downstream applications.

Context hooks can define either one-to-one or one-to-many relationships between user interface controls and target help content.

The metadata that is available in resourceid and ux-window provides flexibility for content developers:

  • You can overload maps and topics with all the metadata needed to support multiple target help systems. This supports single-sourcing of help content and help metadata.
  • You can choose whether to add resourceid metadata to topicref elements, prolog elements, or both. Context-dependent metadata might be best be kept with maps, while persistent, context-independent metadata might best stay with topics in prolog elements

Context hook information is defined within DITA topics and DITA maps through attributes of the resourceid element.

In some help systems, a topic might need to be displayed in a specifically sized or featured window. For example, a help topic might need to be displayed immediately adjacent to the user interface control that it supports in a window of a specific size that always remains on top, regardless of the focus within the operating system. Windowing metadata can be defined in the DITA map within the ux-window element.

The ux-window element provides the top, left, height, width, on-top, features, relative, and full-screen attributes.