Context-Sensitive Help (CSH)

Note: CSH is new as of version 3.3 and is not yet fully implemented. It is bugged and may not behave exactly as described here. Jaime Prilusky provided the explanation on which this section is based.

Online Help in ACEDB has been restructured to make it possible for curators to document tags, fields and classes. Users access this information in a context-sensitive way from within a text display. The standard display-oriented Help distributed with the offical release has been integrated into this system. The original help system is also still available.

How it works

Each help topic is now a separate file in $ACEDB/whelp and is formatted using HTML (Hypertext Markup Language). When help is requested via menu selection or button, ACEDB looks in whelp/ for the appropriate file and then loads it into Mosaic, the html viewer developed by the National Center for Supercomputing Applications. The process requires a file called Mosaic.csh in $ACEDB/wscripts:

#!/bin/csh -f
exec /home/mosaic2.2/Mosaic-sun $*
exit
The script should point to a valid Mosaic executable (or a link to one). The script must be executable. Mosaic can be obtained from ftp.ncsa.uiuc.edu and other sources via anonymous ftp. If Mosaic is not running, ACEDB will launch it. Subsequent calls for help will reuse the same Mosaic window. The user may kill Mosaic if desired. If the script is missing, ACEDB will try to use the original help mechanism (which relies on wspec/help.wrm).

CSH also uses another "fallback" mechanism to insure that help of some kind is always available. This is useful because many curators will document only a small subset of possible classes, fields and tags. If a user asks for help for an undocumented item, ACEDB searches back along the branch containing that item until it locates help. The fallback may be help for another field, tag or the class itself. If the class is undocumented, ACEDB will fallback to help for Text displays.

Users obtain help for tags and fields by selecting them first, then requesting help via the pop-up menu in the Text window.

Adding help files

ACEDB will be distributed with a set of *.html files in whelp/ which document the ACEDB environment. If you are unfamiliar with hypertext markup language, you might take a look at these.

To document classes, tags, and fields, you need to add new files to whelp/. These are named according to a simple scheme. For example, to document certain items in class ?Paper you would create the following files:

Tree_Paper.html               documents class ?Paper
Tree_Paper_Author.html        documents tag Author
Tree_Paper_Author_Data.html   documents field following Author
The documentation can be as simple or elaborate as you want. Since html gives you the ability to make links to other documents, you can extend your help by referencing other help files, ancillary information not directly called by ACEDB, and even files at remote sites. The latter however will not work unless the host is attached to the Internet and should be done sparingly.

Troubleshooting

After every request for CSH, ACEDB tests for different whelp/*.html files until it finds a suitable one. Since the names of the files that ACEDB expects depend on the model structure and Tags names, you may need to confirm the proper names to provide adequate help.

ACEDB will store the names of the files it tests for in the database/log.wrm file if ACEDB_HTML_DEBUG_MODE is active. To use this feature, before starting ACEDB enter the following line:

% setenv ACEDB_HTML_DEBUG_MODE
The debug mode will remain active for the entire session. You may deactivate this mode by entering

% unsetenv ACEDB_HTML_DEBUG_MODE
In database/log.wrm file you will find groups of lines like the following. . . 

/home/ace3/whelp/Tree_Clone_Links_Data.html
/home/ace3/whelp/Tree_Clone_Links.html
/home/ace3/whelp/Tree_Clone.html
/home/ace3/whelp/Tree.html
. . . assuming you are using this model:

?Clone Links ?Fragment XREF Link
The log indicates that help was requested for the data field following the "Links" tag in a Clone object. ACEDB first attempted to find help for that specific item, i.e. the file Tree_Clone_Links_Data.html.

Since that was not present, it searched for Tree_Clone_Links.html, which is the closest "enclosing" description. It traversed the Clone class tree until it located the Tree display help available in Tree.html.

Do not leave this DEBUG option enabled when it is not needed. The log.wrm file may grow rapidly.

Additional Notes

The fallback mechanism, which uses the underscore character to interpret the tag hierarchy, is confused when tags contain one or more underscores.

The help mechanism is confused when more than one text display is open.

Back to Table of Contents