6.0.0-git
2024-10-15
Last Modified 2013-09-04 by Jan Schneider

Help File Format

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).