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