@@
Help files      HE100000 (name)


A. Overview


Function:  Help files are text files used to describe things to the
user at run time.

Details:  Help files are text files stored as "members" of a logical
area called HELP.  On the VAX, this area is a separate logon.  On the
MODCOMP, this area is a SEDIT file called HE100000.  The text in each
help file is displayed on the user's terminal upon request.

Names:  Each Help file is named with the name of the verb, task,
adverb, pseudoverb, or procedure which it describes.


B. File structure and contents


     The Help files are text files prepared by the local text editor.
Thus, the details of their structures and their relationship to the
operating system are machine dependent.  On the VAX, they are separate
physical, FORTRAN files in a logon area called HELP.  On the MODCOMP,
they are members of a directoried source editor (SEDIT) file called
HE100000.

     Since help files are used only to provide run-time assistance to
users, they may contain anything the programmer feels is relevant.
Three general guidelines should be followed in order to obtain pleasing
displays:

   (1) Text should occupy only card columns 1 - 64.
   (2) Text should be typed in lower case.
   (3) The file should not contain too many lines.  23 lines will fit
       on almost every terminal while 32 or more are ok on our 4025's.

Most help files have been typed following a general pattern.  To
illustrate this pattern, consider the example

PRTMSG
Type: verb
Use:  Prints contents of message file including log of input
      commands and messages produced by AIPS and by tasks shed
      by AIPS.  Normally deletes the printed messages from
      the file.  Please use this at the end of your session.
Adverbs:
  USERID   If > 0, messages for the specified user number are
           printed and deleted.  If = 0 (the null value), the
           user number given in logging in is used.  If < 0,
           the messages are not deleted.
  PRIORITY Limits print to messages having priority >= PRIORITY.
           All priorities of messages are deleted, however.
           Message priorities range from 0 for user input to 5
           for requested answers to 10 for severe errors.

All help files are listed in alphabetical order in Volume I of this
manual.


C. Usage notes


     Help files are an important part of AIPS.  They are the means by
which users can find out how to use AIPS without leaving the terminal
or leafing through thick manuals.  Every task, verb, adverb, and
pseudoverb must have a help file.  Additional help files may also be
created to explain special details.  The existence of such files should
be mentioned in the appropriate normal help file.


D. Routines and commons for reading Help files


     Help files are opened and the member is located by the subrou-
tine ZTOPEN.  They are read sequentially by ZTREAD and closed by
ZTCLOS.  By convention, the logical unit number used for this is 11.
These text file I/O routines are described elsewhere in this volume.

     The subroutine which displays these files is called HELPS.  The
routine looks for special names which cause the symbol table to be
examined and printed.  Any other name is assumed to be a help file name
and the file is opened (ZTOPEN), read (ZTREAD), printed (MSGWRT), and
closed (ZTCLOS).


E. Routines and commons for writing Help files


     Help files are prepared by programmers using their local source
editors (e.g. SOS on VAX and SEDIT on MODCOMP).  No routines are to
write such files at run time.
