Context-sensitive help

For the most complete integration of Mallard with an application, context-sensitive links can be added to the application that link to pages or sections in documentation. For example, a preferences dialog might have a help button which, when clicked, would open a guide page that links to topics about changing the application preferences.

Implementing context-sensitive help implies certain requirements, such as being able to address specific sections in Mallard documentation and a documentation viewer that is able to understand the addressing scheme.

Help URIs

A linking scheme is required in order to reference specific sections or pages of documentation from an external resource. Mallard does not prescribe a linking scheme, so it is a feature that is dependent on the documentation viewer. Yelp is the principal Mallard documentation viewer, and conforms to the draft freedesktop.org help system specification. An example of a link to the index for the hypothetical myproject project looks as follows:

help:myproject

Link URIs assume that the documentation is installed to the system-wide help directory. While it is possible to override this directory locally, it is not recommended. Refer to the help system specification for more information.

To link to a specific page, add a Unix path separator '/' and the page ID to the URI:

help:myproject/mypage

No file extensions are required, as Yelp identifies the extension automatically. Additionally, sections on a page can be linked to by adding the section ID to the end of the URI, prefixed with a '#':

help:myproject/mypage#mysection

You can test the URI by running Yelp with the URI as an argument. For example:

$ yelp help:myproject/mypage

The above command would run Yelp and show the mypage page in the myproject documentation.

Modifying applications to launch help

Given a linking scheme, applications can link from a specific context to the corresponding part of the documentation. An obvious example is linking from a help button in a hypothetical export dialog to documentation about exporting. Assuming an application myproject, with a Mallard page export, the URI might look as follows:

help:myproject/export

Application support for the linking scheme depends on the underlying toolkit. For applications using GTK+, the gtk_show_uri() function accepts a URI as an argument, and opens Yelp with the given URI. For example, the following line of code launches the default help viewer, generally Yelp, with the URI given above:

gtk_show_uri (gdk_screen_get_default (), "help:myproject/export", GDK_CURRENT_TIME, NULL);

Other toolkits should have a similar function for opening URIs, but the details are outside of the scope of this document. Consult the reference documentation of your toolkit for details.

Example preferences dialog, with help button