STScI Logo

gethelp README


Introduction

This directory contains Perl scripts which implement a "just in time" iraf help to html converter. There are four main scripts:

apropos.pl : Dislay tasks which match a list of keywords
gethelp.pl : Convert iraf help to html
helpdbase.pl : Build a database of help files
helpindex.pl : Create index of packages and tasks

Apropos.pl and gethelp.pl are designed to be run as cgi scripts, though they can also be run from the command line. Command line mode is mostly intended for debugging.

Apropos

Apropos.pl creates an html page containg the names of tasks and their descriptions for all tasks whose description contains a specified keyword. The task names are linked to the corresponding help pages. The argument to apropos is a blank or comma separated list of keywords. The task displays a list of tasks where the one line description contains at least one of the keywords. The list is sorted so that tasks that match the most keywords are listed first. Within groups matching the same number of keywords tasks are sorted in alphabetical order. Keyword matching is case insensitive, but keywords must match the entire word. There is no prefix or suffix stripping done before matching. Normally, apropos.pl will be called from a form.

Gethelp

Gethelp.pl converts help files from their native format into html. It sends the converted file to STDOUT, so the task can be used as a cgi script to display iraf help in a web browser. The argument to gethelp is the name of the task whose help is to be displayed. Different kinds of help can be found by adding a suffix to the task name. "Task.hlp" retrieves the ordinary help, "task.men" retrieves the package menu, "Task.sys" retrieves the system level help and "task.src" retrieves the source code. If the task name passed to gethelp does not have a suffix, it assumes a suffix of ".hlp". If more than one task has the same name, gethelp will retrieve the help for the task in the first package in alphabetical order.

Helpdbase

Helpdbase.pl builds several databases of help information. These databases speed the operation of gethelp. The databases are helpdb, which associates the help file name with the task name, envdb, which stores the values of the iraf environment variables, and worddb, which contains task names that are also common words. This last database is used in automatic link generation, to prevent generating spurious links. Helpdbase is run from the command line and not as a cgi script. It should be run every time a new task is added to iraf or the location of a task is changed. In order to ensure that the help is up to date, you can add an entry to crontab to run helpdbase at regular intervals. Helpdbase takes no command line arguments, all information is read from iraf files.

Helpindex

Helpindex.pl builds the static pages used by the html version of the iraf help system. These pages are the top level search form, the html version of this file, pages containg an alphabetical index of all tasks, and pages containg a hierarchical index of all packages. The top level search form links to the task and package indices and contains forms to run the apropos and gethelp scripts. Helpindex is run from the command line and not as a cgi script. It should be run whenever the package menus are changed. You can run the task at regular intervals with crontab to make sure the pages it generates are up to date. It should be run after helpdbase, as it uses the databases created by this task. Helpindex takes no arguments. It reads the package menu files to generate its information. In order for helpindex to work, packages must be set up so that the directory structure and names correspond to the package structure and names.

Directory and File Structure

The code is contained in a top level directory and two subdirectories, images and src. Images contains the images displayed in the web page. Currently it contains three images displayed at the top of each page. If additional images are added to the html pages, they should be placed in this directory. Src contains source code for the various tasks. All code is written in Perl 5. Code shared between the different tasks are stored in Perl modules, with the extension .pm.

The top level directory contains the databases and html pages generated by helpdbase.pl and helpindex.pl, as well as the templates used to generate the html pages. The code uses template files to simplify modifying the html files generated by the tasks. The template files support two commands: $include, which includes the contents of another template in the generated html file and $(var), which substitutes the value of a variable for the variable name in the template. The purpose of include files is to factor out common code from the various templates. The included files provide a common header and footer to the html pages and forms for the gethelp and apropos tasks.

Installation

Installing the software requires unpacking the tar file in a directory that can be accessed by your web server. The you should:

The variables %field, $HTML_DIR and $IRAF, at the top of Configure.pm, will need to be modified for each installation. Other variables in Configure.pm can probably stay the same.

If you have any questions or problems, please contact me
(mailto:bsimon@stsci.edu).


Help Form · STSDAS