Evergreen DokuWiki

The trunk version of Evergreen has re-instated the top-level Help menu in the upper right of the staff client, next to the Admin menu. It has one menu entry, For Active Tab, which will look for help files based on the URL of the interface loaded in the active tab (the tab currently being displayed beneath the menu system). If no files are found, it will display an alert, No Help Found. The idea is that you can define a hierarchy of help files, with the Help menu looking for the most specific (context-sensitive) help file first, and then gradually working its way up to more generic help files. So, we could define a global "catch-all" help file to prevent the No Help Found alert.

The help menu will look for canonical/stock help files (none of which currently exist), and for custom/localized help files, with the local files displaying first.

To determine which files are being looked for for a given interface, perhaps the easiest thing to do is to invoke the Help menu with the debug console enabled.

Let's consider this example, using the acq.open-ils.org server and staff client, which have been built using a snapshot of the trunk version of Evergreen (this server is publicly accessible, just use the information and client listed here, and be sure to enable the debug console).

If we bring up the Check In interface, we will see a line like this in the debug console:

set_help_context: {"protocol":"http:","hostname":"acq.open-ils.org","port":"","pathname":"/xul/acq_20100513/server/circ/checkin.xul","src":""}

This lets us know that the context for the Help->For Active Tab menu entry has changed, and that it will look for help files revolving around the source file server/circ/checkin.xul.

If we activate that menu entry these lines will appear in the console, and we should receive a No Help Found alert:

help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/checkin.xul.custom_help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/checkin.xul.help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/custom_help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/custom_help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/custom_help.html>
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/help.html>
help widget: testing <http://acq.open-ils.org/xul/custom_help.html>
help widget: testing <http://acq.open-ils.org/xul/help.html>
help widget: testing <http://acq.open-ils.org/custom_help.html>
help widget: testing <http://acq.open-ils.org/help.html>

The first line is telling us the Help menu is looking for the file server/circ/checkin.xul.custom_help.html. This is the most specific help file we could create currently for Check In, and the custom_ part indicates that it should only exist locally for a given Evergreen installation, and not in the stock distribution of the source code. If checkin.xul.custom_help.html is not found, it then looks for checkin.xul.help.html. This is one we could add as a part of the stock version of Evergreen. The custom version may contain information about library policies specific to the installation, but the stock version should be generic. If the Help menu finds neither of those files, it then starts walking up the directory tree, looking first for custom_help.html, and then for help.html.

We could implement the local help files in such a way that they augment or pull in the stock help files, but there are no templates or infrastructure currently to make that easy for us. We could also rework the Help menu code so that it loads all located help files in a tabbed interface, rather than just stopping at the first (and most specific) one that it finds. In the long term, such Help displays may include functionality for displaying indexes and for searching all documentation in its entirety.

For now, it's simply looking for HTML files, which may be merely text with simple mark-up, or dynamic interfaces using Javascript. Depending on how we want to do things, the files may not even directly contain content, but may instead load documentation from elsewhere based on locale and the version of Evergreen.

If you would like to contribute to this feature (with documentation, code enhancements, feedback, suggestions, etc.), please give us a hollar on the public mailing list, OPEN-ILS-DOCUMENTATION, or if you're shy, you could contact the facilitators for Evergreen's user-driven Documentation Interest Group more directly at docs@evergreen-ils.org.

Thanks!