Help File Format

Help File Format
Help File Location
Help File Translation
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).                                                                                                        |
+----+---------------------------------------------------------------------------------------------------------------------------------------------------------------+