www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/advanced_help/help/ini-file.html

   1 <p>The advanced help configuration file is in simple .ini file format.
   2 It has an optional section for global settings that might be inherited
   3 for each help file, followed by sections for each help file.</p>
   4
   5 <p>Global settings may be put into a section named <code>[advanced help
   6 settings]</code>.  This means that this name is reserved and it cannot
   7 be a help file in any module or theme. The following settings may be
   8 set in this section, with the default value (if any) in brackets.</p>
   9
  10 <dl>
  11 <dt><code>line break</code> (FALSE)</dt>
  12 <dd>If set, the line break filter will be applied to all help files
  13 defined by this module or theme, unless that help file specifically is
  14 set otherwise.  The line break converts line breaks
  15 into <code>br</code> and <code>p</code> tags automatically.</dd>
  16
  17 <dt><code>navigation</code> (TRUE)</dt>
  18 <dd>If set, this navigation will be displayed at the end of the topic:
  19 <em>previous topic</em>, Up (parent), <em>next topic</em>.</dd>
  20
  21 <dt><code>css</code></dt>
  22 <dd>Specify a css file that will be used for all help files (unless
  23 overridden), including the .css extension. This .css file must reside
  24 in the help directory along with the .html files, and will not be
  25 affected by translation.</dd>
  26
  27 <dt><code>name</code></dt>
  28 <dd>May be set to override the module or theme name as displayed in
  29 both the module/theme index as well as the navigation and breadcrumb
  30 trail. Usually, this is not set, but for some projects you may want to
  31 use a more friendly name than appears in the project's .info file.</dd>
  32
  33 <dt><code>index name</code></dt>
  34 <dd>This may be set to change the name of the module or theme in the
  35 module/theme index. It overrides the <code>name</code> setting above,
  36 as well as the project's name in its .info file.</dd>
  37
  38 <dt><code>hide</code> (FALSE)</dt>
  39 <dd>This may be used to hide a module or theme in the module/theme
  40 index. This is particularly useful for modules who insert their help
  41 files into the hierarchy of another module or theme, as might be done
  42 by modules that extend <strong>Views</strong> or derived themes that
  43 extend base themes like <strong>Zen</strong>. By setting this to TRUE
  44 the project will not appear as its own entry.</dd>
  45 </dl>
  46
  47 <p>Each section after that will correspond to a single help file for a
  48 single topic.  It starts with the topic name in square brackets
  49 (e.g. <code>[ini-file]</code>).  The following settings may be set for
  50 each file/topic, with the default value (if any) in brackets.</p>
  51
  52 <dl>
  53 <dt><code>title</code></dt>
  54 <dd>The title of the topic, presented to the user and used in
  55 links. If you have special characters in your title, be sure to
  56 enclose it in quotes.  (This setting is currently not optional.)</dd>
  57
  58 <dt><code>file</code> (topic name)</dt>
  59 <dd>The filename, without the .html extension, used for the file with
  60 the help text for the topic. This is optional; if not specified, the
  61 topic name wil be the file name.</dd>
  62
  63 <dt><code>weight</code> (0)</dt>
  64 <dd>The weight, used for sorting topics on the administration
  65 page. The default is 0 (zero) if unspecified. Items with the same weight
  66 are sorted alphabetically.</dd>
  67
  68 <dt><code>parent</code></dt>
  69 <dd>The topic ID to use in a hierarchy; children will be listed
  70 beneath parents in the topic list, and will have the parent in their
  71 breadcrumb trail. You may parent this topic to a topic in another
  72 module or theme by using <code>module%topic</code>
  73 or <code>theme%topic</code> as the identifier,
  74 where <code>module</code> or <code>theme</code> is the project's short
  75 name. For example if parent is set to, '<code>views%display</code>',
  76 the topic will be regarded as a child of the
  77 <code>display</code> topic in the <strong>Views</strong> module.</dd>
  78
  79 <dt><code>line break</code> (FALSE)</dt>
  80 <dd>Set the line break filter for this topic. Set to FALSE to disable
  81 the line break filter if this has been turned on in the global
  82 settings.</dd>
  83
  84 <dt><code>css</code></dt>
  85 <dd>Specify a css file that will be used for this file. This .css file
  86 must reside in the help directory along with the .html files. This
  87 will override any .css file added by the global settings.</dd>
  88
  89 <dt><code>popup width</code> (500)</dt>
  90 <dd>The width in pixels of the popup window.</dd>
  91
  92 <dt><code>popup height</code> (500)</dt>
  93 <dd>The height in pixels of the popup window.</dd>
  94 </dl>
  95
  96 <p>For example, here is a version of the <code>advanced_help.help.ini</code> file:</p>
  97
  98 <pre>
  99 [readme]
 100 title = README
 101 weight = -11
 102
 103 [using-advanced-help]
 104 title = Using advanced help
 105 weight = -10
 106
 107 [translation]
 108 title = Translating advanced help
 109
 110 [ini-file]
 111 title = Help .ini file format
 112 line break = FALSE
 113
 114 [why-advanced-help]
 115 title = Why advanced help?
 116 line break = TRUE
 117 </pre>