Future Help System

These are Shaun's thoughts from the year 2006 on the layout of a future help system. Code samples are given in Python, because it just makes sense.

The Basics

A document is an abstract version of something that contains information. Documents can come in many formats, languages, and versions. A document instance is a particular file or set of files that can actually be read. A document instance is a particular version of a document in a particular language and particular format.

The help path is the path containing the subdirectory help of each directory in $XDG_DATA_DIRS. That is,

HELP_PATH = map(lambda dir: os.path.join(dir, 'help'), XDG_DATA_DIRS)

Each document has a document ID using reverse-DNS naming. For example, the GNOME User Guide would have the document ID org.gnome.user-guide. Each document stores its metadata files in subdirectories of one or more directory in the help path. The subdirectory must be named after the document ID. For example, the GNOME User Guide might have metadata files in the following directories:

~/.local/share/help/org.gnome.user-guide/
/usr/share/help/org.gnome.user-guide/

The set of directories where a particular document stores its metadata files is called the document path for that document.

Metadata files are key files (i.e. desktop entry files) with the extension . A very basic key file follows.

[Help Document]
DocumentID=org.gnome.user-guide
Title=Desktop User Guide
Description=The Desktop User Guide is a collection of documentation which details general use of the GNOME Desktop environment. Topics covered include sessions, panels, menus, file management, and preferences.
MimeType=application/docbook+xml
Version=2.16.0
Path=C/user-guide.xml
Icon=gnome-user-guide

Key Files and Groups

The instances of each document are identified by at least the version, mime type, and language of the instance. Implementations may introduce extension properties that are also used to identify an instance. A set of instances of a document that have all but the language in common is referred to as a document group. Each help key file may define one document group.

A help key file is considered to define the instance with language lang if it contains the key Path[lang]. All non-localizable keys in the key file apply to each instance defined in that key file. For localizable strings, key[lang] defines key for the instance with language lang. The key key (without a language) defines key for the instance with language C, as well as for any instances that don't have key set explicitly. (FIXME: there should be language chaining, like key[pt] defining key for pt_BR.)

The Actual Document File

The Path property specifies a path to the actual document file. If this is relative, it is taken relative to the document's document path. For instance, using the document path for the GNOME User Guide in the beginning, an implementation would look for the followig files:

~/.local/share/help/org.gnome.user-guide/C/user-guide.xml
/usr/share/help/org.gnome.user-guide/C/user-guide.xml

The first file found in the path is used. The actual document files may be placed under the help path, but they don't have to be. If the GNOME User Guide continued to be installed in its current location, then the Path key could be ../../gnome/help/user-guide/C/user-guide.xml. Then the following file locations would be searched:

~/.local/share/gnome/help/org.gnome.user-guide/C/user-guide.xml
/usr/share/gnome/help/org.gnome.user-guide/C/user-guide.xml

Absolute paths in the Path key use only the specified file.

Pages

Documents may contain multiple pages. Each page may be represented by an additional group in the key files. Since groups must have unique headers, the format for a page group header is [Help Page #ID], where ID is the ID of the page. For example,

[Help Page #nautilus]
DocumentID=org.gnome.user-guide
PageID=nautilus
Title=Nautilus File Manager

If the source format uses multiple input documents for each page, then each page must have a Path property, which works the same as the Page property for documents. Pages, page instances, and page groups are defined the same way as documents, document instances, and document groups. If the version or mime type are not specified for the page, they are taken to be the same as the document instance defined in the same file. Note that, if any pages are defined in a separate file, it may be necessary to duplicate parts of the document definition to clarify.

For heirarchical document structures using separate input files, some mechanism is needed to specify the heirachy. This can be accomplished with the Children property:

[Help Page #nautilus]
DocumentID=org.gnome.user-guide
PageID=nautilus
Title=Nautilus File Manager
Children=nautilus-intro;nautilus-spatial-mode;nautilus-browser-mode;

Note that the document itself is considered to be the root page, so all page properties can be provided for documents.