==================
Help File Format
==================
.. contents:: Contents
.. section-numbering::
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:
::
Title
[Entry content (see below)]
...
...
...
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 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 elements. The 'id' attribute identifies the view in which to show these entries (currently: basic and dynamic).|
+-----+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Each 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 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). |
+----+---------------------------------------------------------------------------------------------------------------------------------------------------------------+