The advanced help configuration file is in simple .ini file format, divided into sections for each help file, plus an optional section for global settings that might be inherited for each help file.
The first line of an advanced help ini file should be ;$Id $ which will be a comment providing the CVS identifier for the file. The ; indicates a comment character. Anything after the ; will be ignored.
Global settings may be put into a section named [advanced help settings] -- this means that this name is reserved and it cannot be a help file in any module. The following settings may be set in this section:
- line break
- If set to any value, the line break filter will be applied to all help files defined by this module, unless that help file specifically is set otherwise. By default, the line break filter is not applied; however, help files can be much easier to write with the line break filter on.
- navigation
- If set to true, the navigation will be displayed at the end of the help topic: previous topic, next topic, and child topics.
- css
- Specify a css file that will be used for all help files (unless overridden), including the .css extension. This .css file must reside in the help directory along with the .html files, and will not be affected by translation.
- name
- May be set to override the module name as displayed in both the module index as well as the navigation and breadcrumb trail. In general this does not need to be set, but a few modules may want to use a more friendly name than appears in the .info file.
- index name
- This may be set to change the name of the module in the module index. It overrides the 'name' setting above, as well as the module name in its .info file.
- hide
- This may be used to hide a module in the module index. This is particularly useful for modules who insert their help files into the hierarchy of another module, as might be done by modules that extend Views or CCK. By setting "hide = TRUE" the module will not appear as its own entry.
Each section after that will correspond to a single help file, and each one may have the following settings:
- title
- The title of the topic, presented to the user and used in links. If you have special characters in your title, be sure to enclose it in quotes.
- file
- The filename, without the .html extension, used for the topic. This is optional; if not specified, the topic name wil be the file name.
- weight
- The weight, used for sorting topics on the administration page. Defaults to 0 of unspecified. Items with the same weight are sorted alphabetically.
- parent
- The topic ID to use in a hierarchy; children will be listed beneath parents in the topic list, and will have the parent in their breadcrumb trail. You may parent this topic to another module's topic by using module%topic as the identifier. For example, 'views%display' will make this a child of the 'display' topic in the 'views' module.
- line break
- If set to true, linebreaks will be converted into br and p tags automatically. If unspecified, will default to off. Set to 0 to disable the filter if this has been turned on in the global settings.
- css
- Specify a css file that will be used for this file. This .css file must reside in the help directory along with the .html files. This will override any .css file added by the global system.
- popup width
- The width in pixels of the popup window. Defaults to 500 if unspecified.
- popup height
- The height in pixels of the popup window. Defaults to 500 if unspecified.
For example, here is a version of the advanced_help.help.ini file:
[using-advanced-help]
title = "Using advanced help"
weight = -10
[translation]
title = Translating advanced help
[ini-file]
title = Help .ini file format
line break = TRUE