Help File Format

Table of Contents

This document is intended to help developers create/edit an application's help file.

Help File Location

The help file is located in an application's locale directory at this location:

locale/xx_XX/help.xml

Where xx_XX is the locale (country and language code), e.g. en_GB or es_ES.

The master help file is in English and is located at:

locale/en/help.xml

Any help entry additions MUST be made in the master English help file. These changes will be propagated to the translated help files through the translation build process.

Help File Translation

See Doc/Dev/Translation.

Help File Format

The help file has the following format:

<?xml version='1.0'?>
<help>
  <entry id="[id]">
    <title>Title</title>
    [Entry content (see below)]
  </entry>

  ...

  <view id="[view]">
    <entry>
      ...
    </entry>
    ...
  </view>
</help>

Help structure tags are as follows:

Tag	Description
help	Defines the help data. All other tags must live under this tag.
entry	Defines a help entry. The 'id' attribute is a unique (by application) identifier to this entry. Entries living directly under <help> are shown in all views.
title	The title of the entry. Displayed in the help topics tree to allow a user to quickly browse for the entry.
view	Defines entries only shown in this view. Children are <entry> elements. The 'id' attribute identifies the view in which to show these entries (currently: basic and dynamic).

Each <entry> tag can have one or more of the following:

Tag	Description
para	A paragraph block.
raw	A raw block. Content will be displayed in fixed format.
tip	Tip block. Used to identify the containing text as tip (i.e. useful instructions; UI shortcuts) content.
warn	Warning block. Used to identify the containing text as warning (i.e. potential issues; dangerous behavior) content.

Each <entry> block can be formatted with the following tags:

Tag	Description
b	Strong formatting of text. This tag can contain additional formatting tags in its content.
css	Outputs containing data in a CSS class. The 'class' atrribute contains the CSS class name. This tag can contain additional formatting tags in its content.
eref	Create URL link. The 'url' attribute contains the URL to link to.
i	Emphasis formatting of text. This tag can contain additional formatting tags in its content.
pre	Preformatted formatting of text. This tag can contain additional formatting tags in its content.
ref	Reference to another Help entry. The 'module' attribute should be the application id. The 'topic' attribute should be the id attribute of the entry to link to.
text	Raw text contained in this node (sub-tags are ignored).