/Help4_Overview
HELP4 is a useful tool utilized in accessing user built help files.

Useage:

       HELP4 [option] fname
              or
       HELP4 [topic] [subtopic] [subtopic] [subtopic]

where option is one of the following:

-i{:x} = INDEX - indexes the text file that the HELP4 System uses.
               - the index file can be created on the drive specified in x.
               - the 'fname' parameter can be used to switch the default file
                 name that HELP4 uses.

-t = TOPICS    - scans through the already created help index file and
               - displays the topics available in their hierarchical structure.

-d = DEFAULT   - displays the default help file that the HELP4 System will
               - utilize.

-n = NAME      - 'fname' specifies the new help text file that the HELP4
               - System will utilize.

If you specify topics on the command line, The HELP4 System will display those
topics, however, any subtopics specified must be related to the previous topic
or subtopic. This allows for quick access to known help topics without having
to manually enter the new topic at each prompt.

Topic names may be entered in either upper or lower case. The HELP4 System
converts each name entered into uppercase for comparison purposes. Thus,
the topic 'Help' is the same as the topic 'HELP'.

The user may also enter only partial topic names. For example, the following
topics could be available in a help file:

 Help_Overview   Dos Functions  Do loops

If the user wanted to look under 'Help_Overview', just 'H' or 'h' could be
typed. However, if the user wanted to look under 'Do loops', at least
'DO L' must be typed to distinguish the entry from the 'Do' in 'Dos Functions'

A topic may be selected by just typing part of its name. For example, the topic
'Help_on_Commands'  can be selected by any of the following:
        Help
        on
        Commands
        elp_on
        ommands

As can be seen, even partial words can be entered! If there had been a second
topic called 'Help_on_Help' and just 'Help' was typed, the first match in
sequential order of the topics would be chosen.
#end
/Index

Useage:
       help4 -i fname
        
If the -i (INDEX) option is chosen on the command line, the HELP4 System will
read through the default text file and create an index file with the same
name and an extension of '/IDX'. If a drive is specified in the format '-i:x',
where x may be any value from 0 through 7, the index file will be created
on the specified drive.

If the user has created a text file called DOS/TXT and HELP4's default text
file name has not been changed from 'HELP4', the user may type:

                             HELP4 -i DOS.

This command will index the DOS/TXT file and then re-NAME the default HELP4
text file name to DOS. (See NAME for additional information on this topic).

The command HELP4 -i will cause the HELP4 System to look for and index the
file specified by the internally stored default text file name.

Indexing may also automatically take place under the following conditions:

1. The fname/IDX file does not currently exist on any enabled drive.

2. The fname/TXT file is either a different size or has a different 
modification date/time than what is stored in the existing fname/IDX file.
#end
//Errors
If an error occurs while indexing, the HELP4 System will report the
sequential topic number where the error occurred along with the kind of
error experienced. See the Error_Messages topic.
#end
//Structure
The /IDX file is organized as a linked list or more specifically,
a generalized list.  It is organized in the same way as the topics are
organized i.e.,:

     Topic1 <-------> Topic2 <-------> Topic3 <-------> Topic(n)
       Subtopic(x)(n)   Subtopic(x)(n)   Subtopic(x)(n)   Subtopic(x)(n)

Each main topic is linked to the next both forwards and backwards. Under each
main topic there may be up to 3 levels of subtopics (x). There may be as many 
subtopics (n) at each of the three levels as is desired and that will fit in
available memory.

Since this is a linear linked list type organization, the flow of topics is
presented as set-up within the /TXT file. Some thought should be given to
whether organization of the file would be presented in a more useful manner
if the topics were written in an alphabetical order or in some other logical
structure. This help file could be considered the extreme of the opposite
kind of thought pattern!
#end
/Topic
Useage:
       help4 -t

TOPIC will display the topic tree in its hierarchical format.

For example:

  Help_Overview
  Index
     Errors
     Structure
  Topic
  Dos Commands.

This example 'tree' reveals that there are four main topics - 'Help_Overview',
'Index', 'Topic', and 'Dos Commands'.  Also, it shows the hierarchy of the
subtopics of any main topics.  'Index' has two subtopics related to it called
'Errors' and 'Structure'.
#end
/Default
Useage:
       HELP -d

The DEFAULT command will display the internally stored default file name that
the HELP4 System utilizes for both the /TXT and the /IDX files. If the user
types HELP4 -d, the screen might display:

                   Default help file name: HELP4

This means that the HELP4 System uses the HELP4/TXT and HELP4/IDX files.

For information on how to change the default file name, examine the topics
INDEX or NAME.
#end
/Name
Useage:
       HELP4 -n fname

The command line option NAME will change the internally stored default file
name to the file name specified on the command line as 'fname'. The HELP4
System will then index the /TXT file, if neccessary, and then load the
/IDX file and begin execution. The new default file name is actually
written to the HELP4/CMD file so it is not necessary to NAME unless a new
help text file will be utilized.

This function is also covered under the topic INDEX.
#end
/Creating_Help
Help files can be created with any available text editor that will create
ASCII files. The TED program provided with TRS/LS-DOS will do just fine.
The file name must be a legal DOS file name and have the extension '/TXT'.
Each help file may consist of many topics and subtopics. The subtopics under
each topic must logically progress in level from one to the next, i.e., the
LEVEL of subtopic under a topic may not be a '3' if there is no '2'.
#end
//Levels
Each topic starts with a '/' and the number of slashes you put in front of
that topic will decide its LEVEL. All HELP4 System text files must start with
a topic utilizing a single '/'. This topic must start at the first line of the
text file and in the first column. If any additional characters or lines are
placed before this first topic, the HELP4 System will not function properly
There may be as many topics or sub-topics that memory can hold but there may
not be any subtopics beyond the fourth level. If the INDEX function encounters
any topic greater than the fourth level, the program will abort and an error
message will be displayed.

In other words, you may only have:
   TOPIC
     SUB-TOPIC
       SUB-TOPIC
         SUB-TOPIC


The levels must be in ascending order i.e., Level 1, if it has a subsidary
level, must be followed by level 2, etc.

Example:
 /Main topic
    topic definition.
 #end
 //Main sub topic
    topic definition.
 #end
 ///Sub subtopic
    topic defintion.
 #end
 /Next main topic
    topic definition
 #end

As can be seen, each subtopic is NESTED within its main topic. 

Note that subtopics are associated with and must follow the previous topic
associated with that subtopic.

Subtopics, like main topics, may be placed all on the same associated level.
For instance, the main topic 'DOS', could have 10 subtopics at level 2
(2 slashes '//') because each of the 'main' subtopics may have no need for
their own subtopics.
#end
//Topics
Topic names may be up to 15 characters in size. If more than 15 characters are
encountered, the remaining characters will be ignored and the entry will be
truncated in the INDEX file but not in the TEXT file. The topic name
should not contain any spaces, however the program will accept them.

A topic name is not allowed to start with a '-', '?'.

There must be a topic name provided after the slashes.

After the topic definition has been completed, the index directive '#end' must
be placed at the end of the definition on a single line starting in the first
column.

Anything between the topic name and the '#end' become part of the topic
definition even if a '/' is in the first column. The next topic must start
immediately after the previous '#end' command.

A topic definition can be up to a maximum of 65534 lines long. There is no
minimum. In fact, the user does not have to have any descriptive text:

                                /TOPIC
                                #END

is a valid topic to the program. Of course, no descriptive text will be
displayed in this situation, just an entry in the topics or subtopics
available list will be displayed.
#end
///Messages
The message 'No further subtopics available under this topic/subtopic' will
be displayed when the topic the user requested has no sub-topics to select.

If the message 'Requested topic was not found' is displayed and the general
help screen is presented, an entered topic was not found. This will also
happen if several topics were typed on the command line and one of the
subtopics was not found. For example:

Topic? Help_Overview Creating_help

In the above example, 'Help_Overview' is valid, 'Creating_help' is also valid
but is not a subtopic of 'Help_Overview'. The whole command line is ignored
because 'Creating_help' was not a valid choice and the topic not found message
will be displayed.
#end
//File_Name
The /TXT file can have any legal dos name and does not have to be called
HELP4/TXT. If a help file is created called DOS/TXT, the HELP4 System can
be informed of the new default name by utilizing the NAME command.

The HELP4/CMD file name may be changed by the user to some other name if so
desired. The user should be aware that the HELP4 System is smart enough to
recognize its own program name so that it can properly store the default file
name for the /TXT and /IDX files even if the /CMD file name was changed.
#end
/Program_Info
The HELP4 System is the copyrighted property of Kachina Software Group and is
distributed as "shareware". You are granted a limited license to use the
HELP4 System and to copy and further distribute it, provided the following
conditions are met:

1) No more than $5.00 may be charged for such copying and distribution.

2) Distribution of the HELP4 System may only occur if it is provided in its
original archive and only in its un-modified state.

3) The HELP4 System may not be used in commercial ("shareware" is commercial)
applications or in governmental organizations unless a license fee of $35.00 is
paid.

This software is being offered as "shareware". Shareware relies on the inherent
honesty of the users of a product to voluntarily contribute money to offset the
cost of producing the software if, and only if, the user finds the product
useful.

The user supported software concept allows the end-user to receive a quality
product at very low cost after being able to put it to practical use in the
end-user's own computer environment. The author benfits by being able to enter
the commercial software market without needing large amounts of venture
capital.

Shareware - it only works with your support!

A registration fee of $10.00 for the use of this program in a non-commercial
or non-governmental environment is requested and should be sent to:

                        Kachina Software Group
                        9112 Dempsey Dr. NE
                        Albuquerque, NM 87109

If you don't already have a copy of the HELP4 System, send a formatted
diskette along with a return address label and the registration fee to the
above address. If no diskette is provided, an additional $5.00 should be added
to the registration fee for postage and handling.
#end
//Revision_History
Version 01.00.00 07/23/89 of the HELP4 System was released on 7/23/89.
Version 01.01.00 07/24/89 of the HELP4 System was released on 7/24/89 
shortly after the first release. This release corrects a problem associated
with the NAME function caused by failure to update the default name and
the writing of the new name into a critical area of the /CMD file. It also
corrects a failure to properly terminate a topic name when it is equal to
or greater than 15 characters.
#end
///Version_Numbers
The version number of the HELP4 System is given as follows:

                           XX.YY.ZZ

XX = a major revision.

YY = an essential revision to correct minor "bugs" or a minor enhancement
was added.

ZZ = an extremely minor revision considered non-essential.

A change in compile date without a corresponding change in version number
indicates a trivial revision such as correcting a spelling error.
#end
/Using_Help4
The HELP4 system is very easy to use. Because the text file may be easily
updated without any special tools, it provides a help system with a great
versatility and flexibility.

To be able to effectively utilize the HELP4 System, the user should have some
idea what topic to look for. By providing for both a command line and
interactive mode that function in conjunction with each other, the user is
provided with all of the necessary information to make effective use without
a large amount of instruction. Once the basics have been mastered, rapid
selection of topic and subtopics of interest are able to be done directly
from the command line.
#end
//Examples
Examples of selecting a topic:

         Command line mode
              help4 dos format errors

         Interactive Mode
              Topic? dos format errors

                Either of these methods will display the ERRORS descriptive
                text under the main topic DOS and as a subtopic of FORMAT,
                skipping the descriptive text of both DOS and FORMAT.

        Command line mode
             help4 help_on_help

        Interactive Mode
             Topic? help_on_help

                This will select just one topic.  Notice that this topic has no
                spaces so that when 'Help_on_Help' is typed, it is considered a
                single topic and not a series of three topics.

Note that an underline character is made by pressing and holding down the
<CLEAR> key and then pressing the <ENTER> key.
#end
//Display
When a selected topic's descriptive text is being displayed, it is scrolled
upward on the CRT one page at a time. When the page is full, a prompt of
[ MORE ] in reverse video is displayed in the lower left corner of the CRT.
Pressing any key but the <BREAK> key will cause the program to display
another page. Pressing the <BREAK> key will cause an exit from the program.
#end
//Memory_Use
In a Model 4 with no high memory reserved, there will be approximately
26800 bytes available for storage of the index file containing the topic
names and their location within /TXT file. This should be enough room for
slightly more than 400 separate topics/subtopics.
#end
//Text_File
The text file (help file) may be created with any text editor. There are
only a few requirements. One is that the text file must be a straight ASCII
file. Another is that the line length should not exceed 80 characters. And,
the last is that each line should be terminated with a carriage return
(the <ENTER> key). See the topic Creating_Help as well as its subtopics
for additional information
#end
/Error_Messages
The following are some of the error messages that may be encountered when
utilizing the HELP4 System. They are intended to be self-explanatory and
are provided here as a reference.

The index file (/IDX) was not found. Use the '-i' or the '-n' option
to index/re-index the text file and/or name the file to be utilized.

The index file (/IDX) is either corrupt or incompatable with this
version of the HELP4 System.

The help (/TXT) file was not found. You must create a text file for the
HELP4 System to work. This information is detailed in the HELP4 System
on-line help file provided in the original archive.

There is insufficient internal memory available to accomodate the
index (/IDX) file. Reduce the number of topics and re-index.

The help (/TXT) file contains more than 4 nested levels of topics.
A topic may have up to 3 levels of sub topics in this version of the
HELP4 System.

While indexing the help (/TXT) file, a topic was encountered that did
not progress in the appropriate sequence.

This topic text size exceeded the limit of 65535 lines.

The help (/TXT) file has apparently been modified since it was last
indexed.

An error has occurred while writing the new file name to the /CMD file.

A '-' or a '?' is an illegal character for the beginning of a topic.

There is insufficient memory available to accomodate the variable
argument print function. Reduce the number of topics and re-index.

More than 1 of the primary available command line options was selected
at one time. Only select ONE of the 'ITND' options.

An invalid command line option was entered on the command line. The only
choices available to follow a '-' are one of 'ITND'.

A command line option was entered that is not recognized by the HELP4
System. The only choices to follow a '-' are one of 'ITND'.
#end
