ini-file.html 4.56 KB
Newer Older
1 2 3
<p>The advanced help configuration file is in simple .ini file format.
It has an optional section for global settings that might be inherited
for each help file, followed by sections for each help file.</p>
4

5 6 7 8
<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>
9 10

<dl>
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
<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>

38 39 40 41 42
<dt><code>show readme</code> (FALSE)</dt>
<dd>For projects that comes with a set of HTML-files, the default is
to hide the project's <code>README</code>-file. Setting this TRUE will
show the README along with the HTML-files.</dd>

43 44 45
<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
46 47 48
files into the hierarchy of another module or theme. By setting this
to TRUE the project will not appear as its own entry.</dd>

49 50
</dl>

51
<p>Each section after that will correspond to a single help file for a
52 53 54 55 56 57
single topic.  It starts with the topic machine name in square
brackets (e.g. <code>[introduction]</code>).  The file containing the
documentation for that topic will have the same machine name with the
extension <code>html</code> (e.g. <code>introduction.html</code>) The
following settings may be set for each file/topic, with the default
value (if any) in brackets.</p>
58

59
<dl>
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
<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
78 79
breadcrumb trail. You may parent this topic to a topic
in <em>another</em> module or theme by using <code>module%topic</code>
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
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>
101 102
</dl>

103 104
<p>Take a look at the .ini-file for this project to see an
example.</p>