# Help System Specification

Version &version;
23 November 2006
Don Scorgie

    	  	DonScorgie@Blueyonder.co.uk

Roman Joost

    	    romanofski@gimp.org

Christopher Lahey James

    	    clahey@ximian.com

Shaun McCance

    	    shaunm@gnome.org

Cornelius Schumacher

    	    schumacher@kde.org

## Introduction

Providing help to the user is one of the most important functions of a user-friendly desktop system. This document specifies how desktop help systems can find, navigate, show and search documentation. This includes application manuals, context-sensitive help and documentation not associated with a specific application. Documentation can be provided in in numerous formats, for example Docbook, HTML, PDF and can also be provided over the net.

The goal of this standard is to provide the base for a unified cross-desktop documentation system.

## Goals of the help system

This help system standard aims at providing help browser developers and application authors as well as documentation creators the means to integrate and consistently handle all documentation present on a system. It doesn't mean to specify any implementation details or to impose any policies about what type of help browser to use or how exactly the documentation is organized or formatted.

These are the specific goals of the help system specification:

- Users should be able to choose the help browser of their choice.

- The help system should impose as little policy as possible on the help browser, and should expose as little policy as possible to documenters.

- It should be simple to place a document in the help system. The help system shouldn't require anything to be run to register or unregister a document. That just begs for problems.

- The help system should not assume anything about the viewing program. The viewer may not be a graphical program like Yelp or the KDE Help Center. It may be a print system, a console program, or some sort of documentation server.

- Documents should be able to supply meaningful meta data, which help viewers may be able to use. The meta data format for documents should be easily extended in a well-defined way.

- Applications should have a simple and consistent way of accessing their documentation, independent of the desktop environment.

- Documents should have a simple and consistent way of referencing other pieces of documentation, independent of the desktop environment.

- The help system should be capable of pulling information from other existing help systems. This way we can have legacy compatibility with KDE's and GNOME's current systems. Also, this can provide a consistent means for help viewers to integrate man and info, if they choose to.

## Definitions

Help System

  The framework for finding, navigating, showing and searching help. This usually includes a help browser, support for applications showing manuals and context help.

Help Browser

  An application for browsing all help content which is available on the system. This usually includes showing a, possibly hierarchical list, of available documentation, facilitates to search all documentation and a view of the selected documentation.

Document

  A self-contained piece of documentation. This can for example be an application manual, a single help page, a complete book or a website.

Section

  A document may be made up of separate sections. These may be defined within the document or externally. For more details on this, please see the Additional Sections section of this document.

## Overview

The help system accesses the documentation by making use of meta data which accompanies the documentation. This meta data is provided at a standard location as files whose content is based on the desktop entry specification.

The meta data contains information about the title of the document, where to find it, what type of format it is and to which categories it belongs. Based on this information help browsers can provide navigation, search and display of all documents known to the help system.

For making the help system aware of a certain piece of documentation it's enough to create the meta data file and put it at the appropriate location. This makes it easy for documentation creators to integrate their documentation into the help system and also provides a simple way to integrate third party documentation.

More advanced features of help browsers like hierarchical displays of documents and their content or searching documentation can implemented in a generic way using the meta data information provided by the help system. The help system specification doesn't impose any policies or restrictions how (or if) help browsers should implement these kinds of functionality.

## Documentation Meta Data

In order to provide the help system with the information of where to find individual pieces of documentation and some more meta information, each document or section is accompanied with a file containing the meta data using the desktop entry specification (aka a "desktop file"). The desktop files contain some extended attributes specific to the help system.

Individual documents or sections come with individual desktop files in order to make packaging easier and not requiring any post-installation processing.

This section describes, how the meta data files are found by the help system, what specific entries they contain and how language-specifics are handled.

### Location of meta data

The help system should read desktop files containing meta data from `$XDG_DATA_HOME/help/`, followed by `$XDG_DATA_DIRS/help/` (here, referred to together as `$LOCATIONS`) using the XDG Base Directory Specification. If a file with the same name is found at multiple locations, the first one is used and the others are ignored.

Sub-directories of `$LOCATIONS` are scanned recursively (excluding `$LOCATIONS/LOCALE`) to get all desktop files.

As per the Base Directory Specification, if $XDG_DATA_HOME is empty or undefined, a path of `$HOME/.local/share` is used. If `$XDG_DATA_DIRS` is empty or undefined, a default path of `/usr/local/share/:/usr/share/` should be used.

The filename for document meta data files consists of a basename and the ".document" suffix.

### Desktop Entry Fields

The help system specification uses several standard fields. They are described in the desktop entry specification.

All entries below belong to the group header "Document". The "Required?" field states whether the key is required or option. If it is optional, sane defaults must be provided by the help system (identified in footnotes).

Standard Desktop Entry Fields used by Help System

Key | Description | Value Type | Required?
--- | --- | --- | ---
`Name` | Title of document. | localestring | Yes
`Comment` | Short description of document. | localestring | No Defaults to empty
`Icon` | Name of icon for document. As per the desktop entry spec, this may be either an icon name or a filename. If the icon is named (i.e. no path), the icon is found using the algorithm defined in the icon naming spec | string | No Defaults to empty
`Categories` | Categories the document belongs to. For possible values see the menu entry specification. Help browsers can base a hierarchical view on the categories. | semi-colon separated strings | Yes

In addition to the standard fields the meta data files uses several extensions to the desktop entry standard within this group, which contain meta data specific to the help system. The keys of all help system specific entries in this group are prefixed with "Doc".

Extended Desktop Entry Fields used by Help System

Key | Description | Value Type | Required?
--- | --- | --- | ---
`DocPath` | Location of document. In addition to the standard URI schemes like http: and file: the help system can support non-standard URI schemes to access specific kinds of documentation which aren't accessible by a standard URI. In particular the following non-standard URI schemes can be supported: help: KDE manual identified by app name, ghelp: GNOME manual identified by app name, man: man page, info: info page | URI (locale-dependent) | Yes
`DocType` | Mime type of document. | string | Yes
`DocWeight` | A number indicating the position of the document within the list of siblings. A greater weight indicates that the document is 'heavier', thus shown below 'lighter' documents. The default weight is 0. Negative values are legal. When assigning weights to documents it should be made sure that enough room is left to make it possible to put other documents before or after the documents. | int | No Defaults to 0
`DocIdentifier` | Unique identifier for document. Entries should be an R-DNS style, for example "org.gnome.user-guide" or "org.kde.konqueror". If this isn't present, it defaults to "org.other.<basename>" | string | No Defaults to org.other.<basename>
`DocLang` | Language of document. This entry is only considered if multiple locale strings are not defined within the file. | language code | No Defaults to "en"
`DocHeritage` | The scrollkeeper seriesid, used for backwards compatibility. If the document is new or does not have a current scrollkeeper seriesid, this field is not required. Should be of the R-DNS form "org.scrollkeeper.<seriesid>". | string | No Defaults to empty

Fields defined in a document meta data file, other than those defined here, are invalid and should be ignored.

### Language-specific documentation

All desktop file fields can be language-specific (e.g. "Name[fr]"). This is especially useful for the `title` and `comment` fields to provide translations of the meta data. It can also be used for the `DocPath` field, to reference translated versions of documents. An alternative to language-specific fields is to provide a separate desktop file for each translated version of the document. Which alternative is the best one is often determined by packaging requirements.

Language-specific desktop files are read from `$XDG_DATA_DIRS/help/LOCALE/LC`, where LC is a two-letter ISO language code (TODO: reference language code specification). The files in language-specific directories are read according to the same rules as non-language-specific files. Locale specific files take priority over regular entries within the same base directory.

If there are multiple versions of the same document in different languages, there can be multiple desktop files with the same name, located within `$XDG_DATA_DIRS/help/locale/LC`. It is up to the help system to decide which file is to be used based on the preferences of the user. This preference is defined by the `$LANGUAGE` environment variable.

### Additional Sections

In addition to "full" documents described previously, documents can be made up from one or more "sections".

These sections may either be specified within the document desktop file, or in their own desktop file. These section files are stored in the $XDG_DATA_DIRS/help (sub-)directories and have filenames consisting of a basename and the ".section" suffix.

As before, the first entry found is used and subsequent entries are ignored. In the special case where a ".section" file defines a section already found in a document file and both files are in the same directory, the new section overloads the previously defined section.

similarly, language-specific versions of section files may be supplied in `$XDG_DATA_DIRS/help/LOCALE/LC`. These files follow the same rules as previously outlined.

The entries within sections belong to the "Section" group header and are described below. All entries are prefixed by "Section".

Section Desktop Entry Fields used by Help System

Key | Description | Value Type | Required?
--- | --- | --- | ---
`SectionName` | The title of the section | localestring | Yes
`SectionIdentifier` | The ID of the section for referencing within the document | string | Yes
`SectionDocument` | The parent document to which the section belong. This is in the form of the parent documents "DocIdentifier" in the R-DNS style described above. For subsections (or lower), the R-DNS must include the parent section path. E.g. "org.gnome.user-guide.CDBurning" would describe a section from the GNOME user guide that is a child of the "CDBurning" section. If the section is defined within the master document meta data file, the document "DocIdentifier" may be neglected. | string | Yes This entry is only required for sections defined in a separate file from the main document. For sections defined within the document meta data file, the SectionDocument is implied to be the current document.
`SectionPath` | The path to the file containing the section. This can be either relative to the parent document's path (if no full path is given) or an absolute file path | URI (locale-dependent) | Yes

## Location of Documentation

The help standard doesn't imply any policy where the files containing the actual documentation are located. The only requirement is that the DocPath from the meta data files points to the right location.

If the DocPath is a full URI, it is taken as it is. Absolute paths are promoted to "file:" URIs.

## Identifying and Referencing help

The help system has to be able to identify and reference help documents. This is needed for applications to provide manuals or context-sensitive help or to cross-link documents. It is also needed for locating documentation from within the desktop meta data files.

### Identifiers

Each document is uniquely identified by an identifier. The identifier is defined within the meta data file as the DocIdentifier entry. The identifier has to be unique on the system. If there are multiple language versions of a document all of them are identified by the same identifier.

The unique identifier is used within the help system to determine if duplication has occurred. If two meta data files have the same identifier, first one discovered by the help system is used. In the special case of two meta data files in the same directory sharing an identifier, the first discovered by the help system is used (which may vary depending on system).

### Invoking the Help Browser

If a desktop environment provides a help browser it has to provide a program "xdg_help" in the binary search path which starts the help browser. The program should handle URIs and document identifiers as command line options. When invoked with a URI or command line option, the program should open the relevant document and section specified.

The "xdg_help" program may also be invoked through a dbus call to "org.freedesktop.help_system" on the session bus. The program must respond to two signals.

open_document (DocIdentifier: string)

  Open the given identifier

close_document (DocIdentifier: string)

  Close the given identifer, if an open window exists currently displaying the document with the given identifier

(Brackets denote required input parameters and types). Both methods are asynchronous and are not expected to return anything.

Sections of documents may be requested by extending the document identifier to include the section id. If the document has registered sections, the section identifier may point to one of these. If no registered sections are available, the section identifier is assumed to point to an internal (implicit) section within the found document / section and treated as such when the document is displayed.

In order to call the help system from within an application, several options are available:

- Issue the command "xdg_help <uri>" through system() or similar
- Issue the command "xdg_help <DocIdentifier>" through system() or similar
- Issue a dbus command of "open_document" with the associated docidentifier as an argument to "org.freedesktop.help_system" on the session bus.

In the first case, the given URI should be opened without reference to any meta data files available. In the second and third cases, the help system should find the appropriate meta data file and use the specified docpath from that meta data.

## Example Help System Meta Data Files

This appendix gives examples of meta data desktop files for use within the help system.

A basic docbook desktop file with German translation (with apologies for the translation).

    # Beanstalk manual description
    [Document]
    Name=The Beanstalk Manual
    Name[de]=Das Bohnenstange-Handbuch
    Comment=Jack likes beanstalks.  With this manual, you too can grow you're own
    beanstalk.  Who knows, you may even find a golden egg or two!
    Comment[de]=Jack mag Bohnenstangen.  Mit diesem Handbuch kannst du dich wachsen
    auch sollst Bohnenstange besitzen.  Wer weiß, kannst du ein goldenes Ei oder zwei
    sogar finden!
    DocPath=file://usr/share/help/C/beanstalk/beanstalk.xml
    DocPath[de]=file://usr/share/help/de/beanstalk/beanstalk.xml
    DocType=application/docbook+xml
    Categories=GNOME;Building;Construction
    DocIdentifier=org.gnome.beanstalk
    # Displaces a document previously registered with scrollkeeper
    DocHeritage=org.scrollkeeper.2a958241-f90e-4aca-a201-cc5d21b7b6ce

Another manual (with different keys), installed as a pdf. No translations.

    [Document]
    # Glermo's proprietary app.  Installed as a pdf to stop thieving.
    # Comments are lines that begin with a '#' symbol.
    Name=Glermo's Magic Beanstalk Recipes
    Comment=Tired of the semi-finished Beanstalk from Jack?  With Gelrmo,
    you don't need to worry, we're already finished!
    # Named icons don't need a path.  This assumes the system knows the icon
    # exists.
    Icon=glermo-beanstalk
    DocPath=file:///opt/glermo/help/glermo.pdf
    DocType=application/pdf
    # We want to be first on the list, dag nabbit
    DocWeight=-50
    Categories=Construction
    DocIdentifier=org.other.glermo

### Documentation with Defined Sections

In this section, one "document" is described - "GNOME User Guide", comprising of 2 sections - "Desktop Tools" and "CD Burning". I'll forgo you the agony of my translations.

    # First the document.  This would be user-guide.desktop
    [Document]
    Name=GNOME User Guide
    Comment=Learn how to use you're GNOME desktop
    DocPath=file://usr/share/gnome/help/user-guide/C/user-guide.xml
    # Made up mime type.  Do we need to define a mime type for Mallard docs?
    DocType=application/mallard+xml
    Categories=GNOME
    # We really want to be listed first.  For real reasons this time,
    # not just vanity
    DocWeight=-5
    DocIdentifier=org.gnome.user-guide

    # Define one section
    [Section]
    SectionName=Desktop Tools
    # Don't give a full path.  The full path is found using the DocPath given
    # above.  The complete path is /usr/share/gnome/help/user-guide/C/desktop-tools.xml
    SectionPath=desktop-tools.xml
    SectionIdentifier=desktoptools
    # Don't need to define section document as we're defined in the parent
    # docs meta data file

    # Now we define the second section
    [Section]
    SectionName=CD Burning
    SectionPath=cdburning.xml
    SectionIdentifier=cdburning

In the same directory, someone else has defined a new section file, defining a new "CD Burning" section. This new section contains a new subsection - "DVD Burning". This new version will overwrite the section defined above.

    # The new CD Burning section.  This would be the file cdburning.section
    [Section]
    SectionName=Burning Media
    SectionIdentifier=cdburning
    SectionDocument=org.gnome.user-guide
    # Sections defined outside the main document meta data file
    # almost certianly want to define the location with an absolute path
    SectionPath=file://tmp/testing/cdburning.xml
    SectionChildren=dvdburning

    # Define the dvd burning section here as well
    SectionName=Burning a DVD
    SectionIdentifier=dvdburning
    # Not strictly necessary as we already know the parent (above), but it won't
    # hurt to define it anyway
    SectionPath=file://tmp/testing/dvdburning.xml
    # Parent is the CD Burning section.  Add that to the Document ID as below
    SectionDocument=org.gnome.user-guide.cdburning

## Example Help System Calls

This section demonstrates various methods of requesting the help system open a particular document or section. This is intended to show how application authors would implement requests. All code here is psuedo-code.

An example of a simplistic call to help from a program requesting that the user manual for "The Beanstalk Program" be opened.

    # User requested help.  Open using dbus.
    bus = get_dbus_session_bus ()
    bus.send_signal (bus, "org.freedesktop.help_system",
                     "open_document", "org.gnome.beanstalk");

The following example shows how to request subsections and a possible example of requesting a filename be opened.

    if (installed)
      # We're running in installed mode, request help using the proper route
      bus.send_signal (bus, "org.freedesktop.help_system",
                       "open_document", "org.gnome.beanstalk.Growing"
    else
      # We're uninstalled.  The help probably isn't registered.  If it is
      # it's probably old.  Request using the filename instead.
      system ("xdg_help ../help/C/beanstalk.xml#Growing")

Finally, for the app that doesn't want to depend on dbus, we present yet another method of accessing help (same section as above)

    # Help requested.  Opening.
    system ("xdg_help org.gnome.beanstalk.Growing")