Documentation of online HELP system in PLOT3D Version 3.5.
Pieter G. Buning   4/13/87


The online HELP system included in PLOT3D (version 3.5) is based on the
VAX/VMS HELP facility in two ways.  First, the behavior of the interactive
HELP command is very similar to the VAX/VMS $HELP command, and second, the
input file (xxx.HLP) is in the same form as described in the VAX/VMS
documentation, including level numbers, keywords, and special handling of
qualifier-type entries.

The basic system is as follows: the HELP utility reads a FORTRAN unformatted
(and therefore generally unreadable) direct access file which includes text and
database pointers.  This file will be referred to as the HELP Library file and
has the file type ".HLB".  It is originally created from one or more text files
referred to as HELP Files which have a ".HLP" file type.  A utility, CREHLPLIB
is supplied to generate the .HLB file from .HLP files.  (The capability of
CREHLPLIB to merge more than one .HLP file is limited: additional files cannot
add entries under nodes generated by previous input files.)

Formats of the two files are discussed below.


HELP File format:

HELP Files are formatted (text) files, and should be less than or equal to 80
characters per record.  Some records are "nodes" in the (inverted) HELP tree
data structure.  These have a level number starting in column 1, followed by
the keyword identifying this node.  The level number and keyword are separated
by at least one blank.  (Keywords may contain blanks, but this is generally
avoided because it complicates the parsing of a HELP request, which is of the
form "HELP keyword1 keyword2 keyword3 ...", or simply "keyword1 keyword2
keyword3 ..." in resonse to a "Topic?" prompt.  Keywords with blanks CAN be
distinguished by enclosing them in double quotes ("), which forces the parser
to treat them as single character string entities.)  The first record in a
HELP File must be a level 1 node.

Following each node there may be multiple lines of associated text.  These
generally start in column 3 for form's sake; they must avoid placing a number
in column 1, so as to be distinguishable from node records.

Additional nodes and text may follow.  Nodes with level one greater (i.e., one
lower on the inverted tree) than the current node are treated as descendents
of the current node.  A node with the same or higher level signals the end of
any descendents of the current node.  (Thus levels must increase
consecutively: a level n node may only have level n+1 nodes as direct
descendents.)

There must be a level 1 node with the keyword "HELP"; this entry is treated as
the "level 0" node and printed in response to a HELP request with no keywords,
as well as a level 1 node with the keyword "HELP".

In VMS (and in PLOT3D), commands may have qualifiers, denoted as
"command/qualifier".  Qualifier entries are denoted in the HELP File not by a
level number, but by a "/" in column 1.  These should be included in the HELP
File with an auxiliary keyword "Qualifiers", which refers to all qualifiers
for that command (or entry).  Thus the HELP file section

	1 COMMAND
	  Command description.
	2 Qualifiers
	/QUALIFIER_1
	  Qualifier 1 text.
	/QUALIFIER_2
	/QUALIFIER_3
	  Qualifier 2 and 3 text.

could be interrogated by typing "HELP COMMAND /QUALIFIER_1", producing the
response

	COMMAND
	
	  /QUALIFIER_1
	
	    Qualifier 1 text.

or "HELP COMMAND Qualifiers", which would list the following:

	COMMAND
	
	  Qualifiers
	
	    /QUALIFIER_1
	      Qualifier 1 text.
	    /QUALIFIER_2
	    /QUALIFIER_3
	      Qualifier 2 and 3 text.

Thus "/QUALIFIER_1" is considered a level-2 node, but is also treated as text
under "COMMAND Qualifiers".  As long as the form above for the HELP File is
followed, CREHLPLIB will generate a suitable HELP Library file.

Another special case to be considered is where several qualifiers constitute a
"set" of mutually exclusive options, such as /FORMATTED and /UNFORMATTED.  If
entered in the HELP File in a manner such as /QUALIFIER_2 and /QUALIFIER_3
above, querying either node will print the text

	COMMAND
	
	  /QUALIFIER_2
	  /QUALIFIER_3
	    Qualifier 2 and 3 text.

The key here is that no text records come between the /QUALIFIER_2 and
/QUALIFIER_3 entries.  Any number of qualifiers may be associated in this
manner.


HELP Library file format:

HELP Library files are direct access, unformatted* files.  Each record
contains 80 columns of text, followed by seven integers, providing a linked
list through the (inverted) HELP tree.  The seven numbers are LEVEL,IUP,IDOWN,
IPREV,INEXT,ITEXT,NTEXT.  Each node in the tree has one record associated
with it, with complete level and pointer information.  Associated with each
node, there may be multiple records of text, for which the integers do not
apply (and are set to zero).

LEVEL gives the depth of the node, and corresponds to the level
starting in column 1 in the HELP File.  LEVEL=1 is the highest level in the
tree; LEVEL=2 is the next level down.  LEVEL may be negative, in which case the
absolute value of LEVEL is the node depth.  A negative LEVEL indicates that the
node is a qualifier-type node.  

IUP gives the record number of the next node up in the tree, while IDOWN
points to the first node that is one level down.  IUP is set to zero for all
level 1 nodes, and IDOWN is zero for all nodes which have no descendant nodes.

IPREV and INEXT give the record numbers of previous and next nodes at the same
level; IPREV=0 for the first node at this level with the same parent, and
INEXT=0 for the last.

INEXT points to the first record of text associated with this node, and NTEXT
gives the number of text records.  These records are assumed to be
sequentially numbered.  In fact, CREHLPLIB arranges the entire HELP Library
file to be a sequentially numbered file.

A FORTRAN OPEN statement for the HELP Library file is in the utility CREHLPLIB,
as well as in the routine HELP.  The record length (specified by the
"RECL=record_length" keyword) is interpreted differently on different systems:
on the Silicon Graphics IRIS workstation (under Unix), the record length is
specified in bytes, while under VAX/VMS FORTRAN it is in (4-byte) words.  Using
CFT77 on the CRAY 2 (Unicos 1.x), the record length measure is unclear for
unformatted (direct access) files; the form of the HELP Library file has been
changed to FORMATTED until the CFT77 compiler is improved*.


*The HELP Library file may be formatted to avoid FORTRAN direct access
peculiarities of certain systems (e.g., the CRAY 2).  A format of (A80,7I10) is
adequate, and needs to be included in routines CREHLPLIB, HLPINF, HLPTRV, and
HLPTXT.  The OPEN statement needs to be changed from FORM='UNFORMATTED' to
FORM='FORMATTED' in CREHLPLIB and HELP.
