Previous: hlptrm Up: ../plot79_h.html Next: hlptx2

HLPTX

       SUBROUTINE  HLPTX (NIN,NOUT,NHELP,QUERY,NQUERY)
 C$    (Help Text)
 C$    This  routine  provides  a  calling  program  with  a  HELP
 C$    facility for use  in interactive programs.   The caller  is
 C$    expected to  have open  a help  file and  input and  output
 C$    files (presumably directed to a user's terminal).
 C$
 C$    The help file must be specially-formatted to be usable with
 C$    this routine.  It must consist of topic headings  beginning
 C$    in column 1, with descriptive text on following lines  with
 C$    a blank or tab in column 1 of each.  Lines in the help file
 C$    should be formatted to contain no more than 72  characters.
 C$
 C$    The array QUERY(*) contains A1-format text with the desired
 C$    topic name, and will result in the printing of that  topic.
 C$    Leading and  trailing white  space  (blanks and  tabs)  are
 C$    stripped from QUERY(*), and the remaining text is stored in
 C$    an internal buffer after converting to upper-case, so  that
 C$    letter case is  ignored in  the search for  a topic  match.
 C$    QUERY(*) itself is not modified.
 C$
 C$    The topic name may be abbreviated and will match all  those
 C$    topics in the file  with those beginning characters.   When
 C$    the first  character in  the topic  (after stripping  white
 C$    space)  is  an  asterisk  (*),  a  special  pattern  search
 C$    mechanism is provided, and will result in a match with  all
 C$    topics containing  the characters  following the  asterisk.
 C$    Thus if the help file contains topic lines
 C$
 C$    LIST
 C$
 C$    NO LIST
 C$
 C$    then a query  with the  text '*LIST' will  display both  of
 C$    them.
 C$
 C$    If the first character in the topic (after stripping  white
 C$    space) is a  question mark, or  QUERY(*) is entirely  white
 C$    space (blanks and tabs), the  response will be to list  all
 C$    of the topics in the help  file, then to reprompt the  user
 C$    for a topic name.  If a topic name does not match  anything
 C$    in the file, a message will  be issued, the topics will  be
 C$    displayed, and the user will be requested to enter a  topic
 C$    string.
 C$
 C$    Only characters up to the  first character which is not  an
 C$    upper-case letter, a digit,  an alphabetic extender  (minus
 C$    sign, underscore, dollar sign), or white space in the topic
 C$    line are  displayed in  the topic  list, so  that with  the
 C$    usual convention of having the line contain a command  name
 C$    and  its  parameters,  only   the  command  name  will   be
 C$    displayed.  This allows topic lines such as
 C$
 C$    GENERAL-INFORMATION
 C$
 C$    LIST option
 C$
 C$    LIST 'option'
 C$
 C$    NO LIST
 C$
 C$    to result in display  of 'GENERAL-INFORMATION', 'LIST'  and
 C$    'NO LIST'.  However, when a topic is selected for  display,
 C$    the entire topic line will be printed with the description.
 C$
 C$    Trailing white space is stripped  from all output lines  to
 C$    speed terminal output.
 C$
 C$    The arguments are:
 C$
 C$    NIN..........Input file (terminal).
 C$    NOUT.........Output file (terminal).
 C$    NHELP........Help file.
 C$    QUERY(*).....A1-format   Hollerith  text  containing  topic
 C$                 name.  Leading  and  trailing white  space  is
 C$                 ignored.
 C$    NQUERY.......Number of characters in QUERY(*).
 C$
 C$    (02-FEB-82)