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.
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 <strong>[advanced help settings]</strong> -- 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:
Global settings may be put into a section named <strong>[advanced help settings]</strong> -- 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:
<dl>
<dt><strong>line break</strong></dt>
<dd>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.</dd>
<dd>If set to any value, 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. By default, the line break filter is not applied; however, help files can be much easier to write with the line break filter on.</dd>
<dt><strong>navigation</strong></dt>
<dd>If set to true, the navigation will be displayed at the end of the help topic: previous topic, next topic, and child topics.</dd>
<dt><strong>css</strong></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><strong>name</strong></dt>
<dd>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.</dd>
<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. In general this does not need to be set, but a few modules or themes may want to use a more friendly name than appears in the .info file.</dd>
<dt><strong>index name</strong></dt>
<dd>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.</dd>
<dd>This may be set to change the name of the module or theme in the module/theme index. It overrides the 'name' setting above, as well as the module or theme name in its .info file.</dd>
<dt><strong>hide</strong></dt>
<dd>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.</dd>
<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 Views or CCK or derived themes that extend base themes like Zen. By setting "hide = TRUE" the module will not appear as its own entry.</dd>
</dl>
Each section after that will correspond to a single help file, and each one may have the following settings:
...
...
@@ -27,7 +27,7 @@ Each section after that will correspond to a single help file, and each one may
<dt><strong>weight</strong></dt>
<dd>The weight, used for sorting topics on the administration page. Defaults to 0 of unspecified. Items with the same weight are sorted alphabetically.</dd>
<dt><strong>parent</strong></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 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.</dd>
<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 module%topic (resp. theme%topic) as the identifier. For example, 'views%display' will make this a child of the 'display' topic in the 'views' module.</dd>
<dt><strong>line break</strong></dt>
<dd>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.</dd>
<p>The <em>Advanced help</em> system is a pluggable system that provides advanced help facilities for Drupal and its modules. Although the advanced help does not provide general help by itself, it provides a powerful and easy framework that modules may use to provide their own help.
</p>
<p>
Modules utilizing <em>Advanced help</em> should create a 'help' subdirectory inside their
module's directory. Place the file MODULENAME.help.ini in this subdirectory, formatted
similar to the following example:
</p>
<p>The <em>Advanced help</em> system is a pluggable system that provides
advanced help facilities for Drupal and its modules and themes. Although the
advanced help does not provide general help by itself, it provides a powerful
and easy framework that modules and themes may use to provide their own help.
</p>
<p>Modules and themes utilizing <em>Advanced help</em> should create a 'help'
subdirectory inside their own main directory. Place the file
MODULENAME.help.ini (resp. THEMENAME.help.ini) in this subdirectory, formatted
similar to the following example:</p>
<pre>
[buses]
title = "How buses are tied into the system"
...
...
@@ -15,31 +18,38 @@ file = buses
title = "Title of topic".
file = filename of topic, without the .html extension.
weight = How important the topic is on the index page.
parent = The optional topic parent to use in the breadcrumb,
parent = The optional topic parent to use in the breadcrumb,
either topic or module%topic.
</pre>
<p>
All topics are addressed by the module providing the topic, and by the topic
<p>If the search module is enabled, the contents of help system will be indexed on cron. If you enable new modules and wish to immediately index its help text, visit the "Administration -> Reports -> Status report" and click the "Run cron manually" link.</p>
<p>If the search module is enabled, the contents of help system will be indexed
on cron. If you enable new modules or themes and wish to immediately index
their help text, visit the "Administration -> Reports -> Status report" and
<p><strong>NOTE: </strong> In previous versions Advanced Help did not require the &'s wrapped around the topic:, path:, and base_url: links. This
is currently still supported, but may be removed in a future version. By adding the &'s these tokens are now not limited to href="" and src="" paramaters.</p>
<p><strong>NOTE: </strong> In previous versions Advanced Help did not require
the &'s wrapped around the topic:, path:, and base_url: links. This is
currently still supported, but may be removed in a future version. By adding
the &'s these tokens are now not limited to href="" and src=""
@@ -7,30 +7,30 @@ This system is completely separate from Drupal's hook_help(). In Drupal 6, it ac
Messages added to the top of a page are not really "help". Often these messages are an introduction to a form or a short blurb telling a user what to do with a particular page. The problem is, these messages are always there, they are easily ignored, and they come before the actual page. In general, when users are learning, they want to see the page first, then ask questions. The reverse order is much less conducive to actually teaching a user how to use something. By allowing help to be available on request, the system conforms more naturally to how most people work.
<h3><strong>Advanced help is organized by topic</strong></h3>
With the hook_help() method, help text is organized by URL path. This is fine if you have help text describing how to use a particular page or what a particular page does, but ultimately is limiting because manuals and documentation are usually grouped by topic, and those topics are determined by the material itself.
With the hook_help() method, help text is organized by URL path. This is fine if you have help text describing how to use a particular page or what a particular page does, but ultimately is limiting because manuals and documentation are usually grouped by topic, and those topics are determined by the material itself.
Advanced help allows the documentation author to organize topics as he or she sees fit; the only restriction, really, is that each individual chunk of text needs to stand on its own as a discrete topic.
What's more, modules can insert their topics into another module's hierarchy. This would allow the Drupal core to create a task based help navigation system which allows modules insert topics into that navigation fluidly. This allows modules to continue to keep their systems separate, yet integrate into the main system.
What's more, modules and themes can insert their topics into another's hierarchy. This would allow the Drupal core to create a task based help navigation system which allows modules and themes to insert topics into that navigation fluidly. This allows modules and themes to continue to keep their systems separate, yet integrate into the main system.
<h3><strong>Advanced help topics are processed HTML in their own files</strong></h3>
This separation makes it easy to find and modify. Currently, everything is lumped together in hook_help() in PHP strings that are run through t(), and there is a fair amount of PHP code necessary in this system that actually gets in the way of writing good, explanatory text.
In fact, requiring a documentation author to understand PHP at all is a detriment. The idea that documentation writers need to have PHP development as a skill seriously reduces the number of available contributors. HTML, on the other hand, is a much more common skill, is relatively easy to learn, and the amount of HTML needed to write documentation is only a little bit more than the HTML used in forum posts.
Another benefit to not using PHP is that the files themselves are safe. They are unlikely to include malicious PHP code that could take over the server or do worse things. This means that these files can be used relatively easily on the drupal.org hardware so that a module's help files can be made immediately available without needing to download the module. It also means that descriptions of the module can be made on drupal.org that are version aware, can be corrected easily in CVS with patches, but can also be made available with the module so that drupal.org is not required.
Another benefit to not using PHP is that the files themselves are safe. They are unlikely to include malicious PHP code that could take over the server or do worse things. This means that these files can be used relatively easily on the drupal.org hardware so that a module's or theme's help files can be made immediately available without needing to download the module or theme. It also means that descriptions of the moduleor theme can be made on drupal.org that are version aware, can be corrected easily in CVS with patches, but can also be made available with the module or theme so that drupal.org is not required.
This also means that we could, if we wanted, package the drupal.org handbooks, or a subset of them, directly into a drupal distribution, or a drupal add-on, so that Drupal administrators can have Drupal help without needing to visit drupal.org. This can be valuable in locked down corporate environments and on planes. But more importantly, the handbooks can be made version aware much more easily than the current method on drupal.org.
The downside to this method is that these books can't easily be made dynamic. Though the use of alter hooks could allow a module to make modifications to the help as needed, doing this could make the help files less useful when you take them out of context.
The downside to this method is that these books can't easily be made dynamic. Though the use of alter hooks could allow a module or theme to make modifications to the help as needed, doing this could make the help files less useful when you take them out of context.
<h3><strong>Advanced help files are translated as a file</strong></h3>
It is actually not easy to translate documents as strings, particularly when the language being used is very much unlike English. In fact, when translating a document, the organization of the sentences may change drastically. It is also a burden on the CPU to do this, as you are indexing on very long strings.
It is actually not easy to translate documents as strings, particularly when the language being used is very much unlike English. In fact, when translating a document, the organization of the sentences may change drastically. It is also a burden on the CPU to do this, as you are indexing on very long strings.
Translators have a much better time translating a document as a unit, because of the presence of the entire context.
<h3><strong>Advanced help has its own navigation system</strong></h3>
By making use of a navigation system specified in a .ini file (which is not PHP code and therefore safe to use on *.drupal.org sites), the help can be structured like a book, which is typical of online manuals. This is familiar to users, can be organized (and re-organized) and allows a module to include significantly richer text without burdening the PHP code with having its help loaded unnecessarily.
By making use of a navigation system specified in a .ini file (which is not PHP code and therefore safe to use on *.drupal.org sites), the help can be structured like a book, which is typical of online manuals. This is familiar to users, can be organized (and re-organized) and allows a module or theme to include significantly richer text without burdening the PHP code with having its help loaded unnecessarily.
This book can be navigated hierarchically as well, making it easy to keep related topics together.
<h3><strong>Advanced help is indexed by the search engine</strong></h3>
...
...
@@ -39,6 +39,6 @@ An important goal of this system was to add searchability to the help. By being
This search is specific to the help, meaning that the help will not be mixed in with the global node search. This can be considered both an advantage and a disadvantage. For the most part, this help system is meant to provide help to site administrators, and content searches should not find it. The disadvantage, of course, is when you want to use it for end user help, you will not be able to.
<h3><strong>Inline help can be brought in via popups</strong></h3>
In addition to the manual-like hierarchical navigation, advanced help can also provide context-sensitive additional help through a popup. While popups are controversial, the argument for using them is that when getting help while on a form, <i>a popup will not throw away a user's data.</i> Browsers are not very friendly to input forms if they are not submitted, and navigating away from the form can be dangerous. There are various other solutions to this problem, but each one has a drawback. The drawbacks to popups are well known, but mostly it is the irritation of having new windows. When getting help, though, a popup is usually invited. Help should not interfere with what the operation the user is trying to complete. It differs greatly from the uninvited popup, which are usually ads or popups meant to prevent users from navigating away from a site.
In addition to the manual-like hierarchical navigation, advanced help can also provide context-sensitive additional help through a popup. While popups are controversial, the argument for using them is that when getting help while on a form, <i>a popup will not throw away a user's data.</i> Browsers are not very friendly to input forms if they are not submitted, and navigating away from the form can be dangerous. There are various other solutions to this problem, but each one has a drawback. The drawbacks to popups are well known, but mostly it is the irritation of having new windows. When getting help, though, a popup is usually invited. Help should not interfere with what the operation the user is trying to complete. It differs greatly from the uninvited popup, which are usually ads or popups meant to prevent users from navigating away from a site.
These popups can be added to a page with text links or icon links.
