ini-file.html 4.58 KB
Newer Older
gisle's avatar
gisle committed
1
<p>The advanced help configuration file is in simple .ini file format.
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
It has an optional section for global settings that might be inherited
for each help file, followed by sections for each help file.</p>

<p>Global settings may be put into a section named <code>[advanced help
settings]</code>.  This means that this name is reserved and it cannot
be a help file in any module or theme. The following settings may be
set in this section, with the default value (if any) in brackets.</p>

<dl>
<dt><code>line break</code> (FALSE)</dt>
<dd>If set, the line break filter will be applied to all help files
defined by this module or theme, unless that help file specifically is
set otherwise.  The line break converts line breaks
into <code>br</code> and <code>p</code> tags automatically.</dd>

<dt><code>navigation</code> (TRUE)</dt>
<dd>If set, this navigation will be displayed at the end of the topic:
<em>previous topic</em>, Up (parent), <em>next topic</em>.</dd>

<dt><code>css</code></dt>
<dd>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.</dd>

<dt><code>name</code></dt>
<dd>May be set to override the module or theme name as displayed in
both the module/theme index as well as the navigation and breadcrumb
trail. Usually, this is not set, but for some projects you may want to
use a more friendly name than appears in the project's .info file.</dd>

<dt><code>index name</code></dt>
<dd>This may be set to change the name of the module or theme in the
module/theme index. It overrides the <code>name</code> setting above,
as well as the project's name in its .info file.</dd>

<dt><code>hide</code> (FALSE)</dt>
<dd>This may be used to hide a module or theme in the module/theme
index. This is particularly useful for modules who insert their help
files into the hierarchy of another module or theme, as might be done
by modules that extend <strong>Views</strong> or derived themes that
extend base themes like <strong>Zen</strong>. By setting this to TRUE
the project will not appear as its own entry.</dd>
</dl>

<p>Each section after that will correspond to a single help file for a
single topic.  It starts with the topic name in square brackets
(e.g. <code>[ini-file]</code>).  The following settings may be set for
each file/topic, with the default value (if any) in brackets.</p>

<dl>
<dt><code>title</code></dt>
<dd>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.  (This setting is currently not optional.)</dd>

<dt><code>file</code> (topic name)</dt>
<dd>The filename, without the .html extension, used for the file with
the help text for the topic. This is optional; if not specified, the
topic name wil be the file name.</dd>

<dt><code>weight</code> (0)</dt>
<dd>The weight, used for sorting topics on the administration
page. The default is 0 (zero) if unspecified. Items with the same weight
are sorted alphabetically.</dd>

<dt><code>parent</code></dt>
<dd>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 a topic in another
module or theme by using <code>module%topic</code>
or <code>theme%topic</code> as the identifier,
where <code>module</code> or <code>theme</code> is the project's short
name. For example if parent is set to, '<code>views%display</code>',
the topic will be regarded as a child of the
<code>display</code> topic in the <strong>Views</strong> module.</dd>

<dt><code>line break</code> (FALSE)</dt>
<dd>Set the line break filter for this topic. Set to FALSE to disable
the line break filter if this has been turned on in the global
settings.</dd>

<dt><code>css</code></dt>
<dd>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 settings.</dd>

<dt><code>popup width</code> (500)</dt>
<dd>The width in pixels of the popup window.</dd>

<dt><code>popup height</code> (500)</dt>
<dd>The height in pixels of the popup window.</dd>
</dl>

<p>For example, here is a version of the <code>advanced_help.help.ini</code> file:</p>

<pre>
[readme]
title = README
weight = -11

[using-advanced-help]
title = Using advanced help
weight = -10

[translation]
title = Translating advanced help

[ini-file]
title = Help .ini file format
line break = FALSE

[why-advanced-help]
title = Why advanced help?
line break = TRUE
</pre>