Help Systempart of the ArsDigita Community System by Philip Greenspun |
glossterm
tag that saves a doc author from
having to hard-code in a link to the ACS glossary module:
/glossary/one?term=film
.
The page-level documentation is stored in conventionally named files underneath the Web server root. Support is provided for multi-lingual documentation.
The standard ACS /glossary module is used to provide word and phrase definitions.
ns_register_adptag
. These special
tags help enforce site-wide style conventions as well as providing a
mechanism that will act as a switch for a particular section. For
instance, the code run by the special tag may check whether or not the
user is a member of a particular user group. If the user is in the
group, then the procedure returns the string between the tags with the
appropriate font and formating. If the user is not in the group, then
the procedure returns the empty string.
We place a call to help_link
on every page that could
potentially have a help file. This procedure determines whether or
not there actually is a help file associated with the given file. If
a help file exists, help_link
returns a string containing
a link to a page that will serve the requested help file. If no help
file exists then the empty string is returned.
We name all page-level help files with the same filename as the page that they document, with a .help extension. For instance, if we have a URL named foo, the help file will be named foo.help. If a multi-lingual help system is in place then the help file in english will be foo.en.help (the help file in french will be foo.fr.help, etc.). Language encoding and the sorting out of user preferences are as described in /doc/style.
These help files reside in a directory hierarchy mirroring that of the files that they document, rooted at a location specified by the HelpPageRoot parameter in the ns/server/servername/acs/help section of the server's auxiliary .ini file. This parameter specifies the root of the help file's directory hierarchy as a relative path from the server's page root, so HelpPageRoot=/help would specify that all help files lived under /web/servername/www/help. Leaving it blank specifies that the help page root is the same as the server's page root, so .help files reside in the same directories as their corresponding files.
.help files are registered to be interpreted as ADP files so that they can be viewed directly, in order to aid in their development.
To faciliate this style of programming, we've defined
help_upper_right_menu
which takes an arbitrary number of
optional args, each of which is a list of URL and anchor (similar to the
ad_context_bar
args). These are extra options on the menu
and they will be displayed in the order supplied, followed by a help
link (if the .help file is found in the file system).
<workflow>
tag).
help_link
in your scripts and .adp
templates