Commit 560aedf2 authored by gisle's avatar gisle
Browse files

Issue #1980936 by gisle: Cleaned up project's own documentation

parent 852d227b
.advanced-help-topic pre {
background: #f1f1f1;
border: 1px solid #444;
border: 1px solid #ccc;
display: block;
margin: 1em;
padding: .2em;
padding: .4em;
}
.advanced-help-topic h3,
......@@ -55,6 +55,27 @@
margin: .5em;
}
.help-block {
display: block;
clear: both;
}
.help-img-left {
margin-right: 1.5em;
border: solid 1px #ccc;
}
.ta-center {
margin: 1em;
text-align: center;
}
.help-img-center {
margin-left: auto;
margin-right: auto;
border: solid 1px #ccc;
}
.help-navigation {
border-top: 1px dotted #ccc;
}
......
<Files *>
<Files *\.html>
Order Allow,Deny
Deny from all
</Files>
\ No newline at end of file
[readme]
title = README
weight = -11
......@@ -11,8 +10,8 @@ weight = -10
title = Translating advanced help
[ini-file]
title = Help .ini file format
line break = TRUE
title = Advanced help .ini file format
line break = FALSE
[why-advanced-help]
title = Why advanced help?
......
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.
<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>
The first line of an advanced help ini file should be ;&#x24;Id&#x24; which will be a comment providing the CVS identifier for the file. The ; indicates a comment character. Anything after the ; will be ignored.
<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>
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 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 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 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 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>
<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>
Each section after that will correspond to a single help file, and each one may have the following settings:
<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><strong>title</strong></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.</dd>
<dt><strong>file</strong></dt>
<dd>The filename, without the .html extension, used for the topic. This is optional; if not specified, the topic name wil be the file name.</dd>
<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 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>
<dt><strong>css</strong></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 system.</dd>
<dt><strong>popup width</strong></dt>
<dd>The width in pixels of the popup window. Defaults to 500 if unspecified.</dd>
<dt><strong>popup height</strong></dt>
<dd>The height in pixels of the popup window. Defaults to 500 if unspecified.</dd>
<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>
For example, here is a version of the <strong>advanced_help.help.ini</strong> file:
<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"
title = Using advanced help
weight = -10
[translation]
......@@ -49,5 +109,9 @@ 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>
\ No newline at end of file
</pre>
......@@ -78,25 +78,6 @@ accompanied by patches are more likely to make it into a release.</p>
<p>The maintainer hopes that the community is willing to help out by
answering &amp; closing support requests.</p>
<h2 id="access-control">Access control</h2>
<p>As noted in the introduction, the help texts are stored as plain files
and can, unless protected, be accessed by anyone who knows their URL.
To protect them, place the following four lines in a file named
<code>.htaccess</code> in project's <code>help</code> directory:</p>
<pre>
&lt;Files *&gt;
Order Allow,Deny
Deny from all
&lt;/Files&gt;
</pre>
<p>It as the responsibility of the project author to make sure this type of protection is in place if the project's author has help files that merits protection from direct access.</p>
<p>See also issue :
<a href="https://www.drupal.org/node/1980936">#1980936 Typing complete path to .html help files in module bypasses user permissions</a>.</p>
<!--
<h2 id="project-problems">Known problems</h2>
-->
......
<p>To translate advanced help, first create a <b>translations/help/$language</b> directory
in the module directory. Then, copy the .ini file and all .html files from
the help directory.</p>
<p>To translate advanced help, first create a
directory <code>translations/help/<em>language</em></code> in the
module directory. Then, copy the .ini file and all the .html files
from the help directory into this. If you need to alter an image to
use it in a translation, you also put the altered image there.</p>
<p>The .ini file only needs to keep the titles, and if there is a 'name' or 'index name' setting in the 'advanced help settings' portion, that should be retained. Any retained settings should be translated. The rest of the data in the .ini file may be discarded or ignored.</p>
<p>The .ini file only needs to keep the titles, and if there is
a <code>name</code> or <code>index name</code> setting in the
'advanced help settings' portion, that should be retained. Any
retained settings should be translated. The rest of the data in the
.ini file may be discarded or ignored.</p>
<p>Each file should then be translated in place.</p>
<p>When translating a .html file, you will find that the <b>path</b> keyword will lead to the original directory. If you must translate items that are linked, such as images, use <b>trans_path</b> instead, which will lead to the translated directory. This will allow you to pick and choose which linked items, if any, will be translated.</p>
\ No newline at end of file
<p>When translating a .html file, you will find that
the <code>&amp;path&amp;</code> keyword will lead to the original
directory. If you must translate items that are linked, such as images
containing text, use <code>&amp;trans_path&amp;</code> instead, which
will lead to the translated directory. This will allow you to pick and
choose which linked items, if any, will be translated.</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>The <strong>Advanced help</strong> module provides a framework that
allows module and theme developers integrate help texts in a Drupal
site. 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 <strong>Advanced help</strong> should
create a subdirectory named <code>help</code> inside their own main
directory. Place the file
<em>MODULENAME</em>.help.ini (resp. <em>THEMENAME</em>.help.ini) in this subdirectory.
formatted similar to the following example:</p>
<pre>
[about-php]
title = About PHP
file = about-php
weight = -10
[history]
title = History of PHP
parent = about-php
[usage]
title = Usage of PHP
weight = 1
[security]
title = Security of PHP
weight = 2
[syntax]
title = PHP syntax
parent = usage
</pre>
<p>This file defines five help topics (inside the square brackets, and
some settings for them.
See: <a href="&topic:advanced_help/ini-file&">Advanced help .ini file format</a> for
a list of defined settings.</p>
<p>All topics are addressed by the module or theme providing the
topic, and by the topic id. To produce a themed link to popup
about a topic, use the a format similar to the following example:</p>
<!-- D6
<pre>
$output = theme('advanced_help_topic', 'help_example', 'about-php');
</pre>
-->
<!-- D7 -->
<pre>
$output = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'about-php',
));
$output .= '&nbsp;' . t('Click the help icon!');
</pre>
<p>This produces the following output:</p>
<pre>
&lt;a class="advanced-help-link" title="About PHP"
onclick="var w=window.open(this.href, 'advanced_help_window',
'width=500,height=500,scrollbars,resizable');
w.focus(); return false;"
href="/help/help_example/about-php?popup=1"&gt;
&lt;span&gt;Help&lt;/span&gt;
&lt;/a&gt;
Click the help icon!
&lt;/div&gt;
</pre>
<p>This produces a clickable help icon like the one shown below:</p>
<div class="ta-center">
<img class="help-img-center" alt="clickable icon" src="&path&click_icon.png" width="180" height="90" border="0" />
</div>
<p>Inside your help file, you may link to other help topics using this format:</p>
<pre>
&lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt;
</pre>
<p>This format will ensure the popup status remains consistent when
switching between links.</p>
<p>To reference items within the help directory, such as images you
wish to embed within the help text, use:</p>
<pre>
&lt;img src="&amp;path&amp;example.png"/&gt;
&lt;img src="&amp;trans_path&amp;example.png"/&gt;
</pre>
<p>The latter is to refer to a translated version of the image if it differs from the original.</p>
<p>To reference any normal path in the site, use:</p>
<pre>
&lt;a href="&amp;base_url&amp;admin/settings/site-configuration"&gt;anchor text&lt;/a&gt;
</pre>
<p><strong>NOTE: </strong> In previous versions <strong>Advanced
help</strong> did not require the &amp;'s to be wrapped around
<code>topic:</code>, <code>path</code>, and <code>base_url</code>.
This is currently still supported, but may be removed in a future
version. By adding the &amp;'s these tokens are now not limited
to <code>href=""</code> and <code>src=""</code> parameters.</p>
<h2 id="access-control">Access control</h2>
......@@ -15,54 +117,29 @@ permission can access the advanced help index by going to
<code>view advanced help popup</code>
enable users to access the actual help pages and popups.</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>
<p>The help texts are stored as plain .html-files and can, unless
protected, be accessed by anyone who knows their URL. To protect
them, place the following four lines in a file named
<code>.htaccess</code> in project's <code>help</code> directory:</p>
<pre>
[buses]
title = "How buses are tied into the system"
file = buses
[TOPIC_ID]
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,
either topic or module%topic.
&lt;Files *\.html&gt;
Order Allow,Deny
Deny from all
&lt;/Files&gt;
</pre>
<p>All topics are addressed by the module or theme providing the topic, and by
the topic id. To embed links, use the following format:</p>
<code>$output .= theme('advanced_help_topic', $module, $topic);</code>
<p>Inside your help file, link to other topics using the format
<strong>&lt;a href="&amp;topic:module/topic&amp;"&gt;</strong>. This format
will ensure the popup status remains consistent when switching between links.
</p>
<p>Use <strong>&lt;a href="&amp;path&amp;example.jpg"&gt;</strong> to reference
items within the help directory, such as images you wish to embed within the
help text.</p>
<p>Use <strong>&lt;a href="&amp;base_url&amp;admin/settings/site-configuration"&gt;</strong>
to reference any normal path in the site.</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
click the "Run cron manually" link.</p>
<p>It as the responsibility of the project author to make sure this
type of protection is in place if the project's author has help files
that merits protection from direct access.</p>
<p>Example: <a href="&path&nowhere.jpg">Don't click this!</a></p>
<p>See also this tracker in the project's issue queue:
<a href="https://www.drupal.org/node/1980936">#1980936 Typing complete path to .html help files in module bypasses user permissions</a>.</p>
<p>See: <a href="&topic:advanced_help/ini-file&">ini file format</a></p>
<h2 id="search">Search</h2>
<p><strong>NOTE: </strong> In previous versions Advanced Help did not require
the &amp;'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 &amp;'s these tokens are now not limited to href="" and src=""
parameters.</p>
<p>If the core <strong>Search</strong> module is enabled, the contents
of the advanced help framework will be indexed on cron. If you enable
new modules or themes and wish to immediately index their help text,
navigate to <em>Administration → Reports → Status report</em> and click the link
“run cron manually”.</p>
The advanced help system was designed to replace the original Drupal help system, which has several flaws that make it hard to create new help, hard to maintain existing help, and particularly hard to access help.
The <strong>Advanced help</strong> framework was designed to replace the original Drupal help system, which has several flaws that make it hard to create new help, hard to maintain existing help, and particularly hard to access help.
The primary goal, then, is to increase the accessibility of help, meaning the ability of both the user and the help text author to access the needed tools to use, create, maintain and translate the help.
This system is completely separate from Drupal's hook_help(). In Drupal 6, it actually co-exists with it; in the future, it is hoped that it will completely replace it allowing hook_help() to be deprecated and removed.
This system is completely separate from Drupal's <code>hook_help()</code>. In Drupal 6 and 7, it actually co-exists with it; in the future, it is hoped that it will completely replace it allowing <code>hook_help()</code> to be deprecated and removed.
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.
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.
<h2>Advanced help is organized by topic</h2>
With the <code>hook_help()</code> 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.
<strong>Advanced help</strong> 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 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.
<h2>Advanced help topics are processed HTML in their own files</h2>
This separation makes it easy to find and modify. Currently, everything is lumped together in <code>hook_help()</code> in PHP strings that are run through <code>t()</code>, 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 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.
Another benefit to not using PHP is that the files themselves are safe. They are filtered to escape malicious script code that could take over the server or do worse things. This means that these files can be used relatively easily on Drupal.org itself. It also means that descriptions of the project pulled from the project's help pages or README.txt or README.md can be made on the project's Drupal.org without the need to download the module or theme to look at the contents of these files. This also simplifies maintenance, as the files can be corrected easily by patches, which are updated by tyhe maintainer and pushed to git.
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.
By moving all docymentation into help files, 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 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>
<h2>Advanced help files are translated as a file</h2>
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 or theme to include significantly richer text without burdening the PHP code with having its help loaded unnecessarily.
<h2>Advanced help has its own navigation system</h2>
By making use of a navigation system specified in a .ini file (which is not PHP code and therefore safe to use), 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>
<h2>Advanced help is indexed by the search engine</h2>
An important goal of this system was to add searchability to the help. By being able to enter keywords into the search box and find relevant topics, we come up with a system that resembles the kind of help that comes with many operating systems. This is very valuable when searching through manuals trying to find out how to do a particular thing.
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.
<h2>Inline help can be brought in via popups</h2>
In addition to the manual-like hierarchical navigation, <strong>Advanced help</strong> 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.
Popups can be added to a page with plain text links or themed icon links.
<Files *>
<Files *\.html>
Order Allow,Deny
Deny from all
</Files>
\ No newline at end of file
......@@ -5,20 +5,16 @@ weight = -10
[history]
title = History of PHP
file = history
parent = about-php
[usage]
title = Usage of PHP
file = usage
weight = 1
[security]
title = Security of PHP
file = security
weight = 2
[syntax]
title = PHP syntax
file = syntax
parent = usage
\ No newline at end of file
......@@ -19,7 +19,7 @@ function help_example_menu() {
}
/**
* Help topic index.
* Topic index callback.
*/
function help_example_index_page() {
$output = theme('advanced_help_topic', array(
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment