HELPER--AN INTERACTIVE TEXT PRESENTER

    HELPER is a small (<2k) program that enables you to "menu" a document.  
It combines the function of programs like the TXT__ series which let you 
turn documents into .COM files with that of programs like HELP__ which let 
you divide documents into user-selectable sections.

    HELPER itself is a small .COM file which you tack on to the beginning 
of your document to create a new .COM file.  The default behavior when the 
new file is run is to display the document, pausing every 23 lines.  Two 
special characters can be embedded in the document; their default values 
(changeable by assembly-time equate are ^(known as the control prefix) and 
~(the command prefix).  The control prefix causes the following character 
to be output as its control equivalent; the command prefix causes the 
following characters to be treated as a statement in a small programming 
language.  These statements enable you to control the presentation of the 
document.  They fall into five categories:


                                SELECTIONS
~S            Select: get menu response and select section
~C            Choice: mark section corresponding to menu selection
~D            Default: mark section for choice not on menu
~E            End: mark end of menu choices

                                   LOOPS
~B            Begin: start of loop
~A            Again: end of loop
~X            Exit: break out of loop

                               TEXT SHARING
~U            Use: "call" section of text
~R            Return: return from section called by ~U

                               FLOW CONTROL
~Q            Quit: return to operating system
~T            Top: restart display from start of document
~L            Label: give internal name to section of text
~G            Goto: jump to internally-named position

                                  OTHERS
~P            Pause: force "any key" pause
~O            Output: display last selection response

                          EXPLANATION OF COMMANDS

SELECTIONS

    These commands let you divide a portion of a document into sections 
such that the user is prompted for a choice, responds, and is shown the 
appropriate section.  To create a selection section, put a list of possible 
choices in the text, and follow it with ~S.  For each possible response, 
put in a line beginning with ~C followed by the response (responses can be 
strings of up to 16 characters).  Then put in the text corresponding to 
that choice.  To display text when the user enters an invalid response, put 
in a line consisting of ~D and follow it by whatever error message you want 
(on separate lines).  At the end of all these sections, put a line 
consisting of ~E.

    The commands work as follows: when HELPER encounters a ~S, it waits for 
the user to type in a string followed by CR.  The ~S by itself does not 
cause any output, so it can be placed immediately following a prompt.  When 
the string has been typed, HELPER skips through the text attempting to find 
a ~C followed by that string.  If a match occurs, HELPER resumes displaying 
text from that point on until it sees another ~C, a ~D, or a ~E.  It then 
skips to the ~E and resumes display.  If HELPER sees a ~D while searching 
for a match, it resumes display at that point, continuing to the ~E.

    Selection sections can be nested up to 8 levels deep, allowing you to 
create submenus.  Note that HELPER never tries to assign numbers or letters 
to sections the way the HELP__ programs do: you have complete control of 
what menus look like.

LOOPS

    Frequently you want to show a menu, let the user make a choice, show 
the appropriate section, and then show the menu again.  You can do this by 
using the loop commands.  Whenever HELPER sees a ~B, it marks the current 
position in the document as the beginning of a loop.  When it encounters a 
~A, it repositions itself to the loop beginning.  If it encounters a ~X, it 
skips down past the ~A.  Normally the ~X will be part of a selection 
section for going back to a previous menu or something similar.

    Loops can also be nested up to 8 levels deep.  Selections can be nested 
within loops and vice versa.

TEXT SHARING

    If you have a portion of text that you need to display at several 
points in a document, you can turn it into a "subroutine" by labeling it 
with ~L and ending it with ~R.  Whenever HELPER sees ~U followed by a 
string, it will save the current postion and search (starting at the top of 
the document) for ~L followed by the same string.  It will then display 
until it sees a ~R, at which point it will resume display after the ~U.

    "Subroutines" can also be nested up to 8 levels deep.

FLOW CONTROL

    A ~Q causes HELPER to immediately return to the operating system (which 
also happens if HELPER "falls off" the end of the document.  A ~T sends you 
back to the top of the document, and ~G followed by a string jumps you to 
the position marked by ~L followed by the same string.

OTHER COMMANDS

    ~P forces an "any key" pause when it is encountered.  However, it will 
not cause a pause if no text has been displayed since the last pause 
(triggered either by 23 lines or by another ~P), so the user will never see 
two pauses in a row.

    ~O displays the string the user typed in response to the last ~S 
command executed.  This can be used for error messages.

                          POSITIONING OF COMMANDS

    Some of the commands can be located anywhere within a line of text; 
others need a line of their own:

~S            Must be at end of line
~C<choice>    Must stand alone
~D            Must stand alone
~E            Must stand alone
~B            Anywhere on line
~A            Anywhere on line
~X            Anywhere on line
~U<label>     Must be at end of line 
~R            Must be at end of line
~Q            Anywhere on line
~T            Anywhere on line
~L<label>     Must stand alone
~G<label>     Must be at end of line
~P            End of line or alone
~O            Anywhere in line

                        ESCAPING COMMAND CHARACTERS

    If you need to display a literal ^ or ~, simply double it, e.g. ^^ or 
~~.

                                   CASE

    Command letters are case-insensitive, as are match strings used with ~C 
and labels used with ~L, ~U and ~G.

                         APPLYING HELPER TO A FILE

1) Create the file with your favorite text editor or word processor, making 
sure to create a standard ASCII file.

2) Create a one-byte file called 0.DAT, consisting of one zero byte 
(ASCII NULL).

3) Use PIP as follows:
    PIP <yourname>.COM=HELPER.COM,<yourname>,0.DAT

                               EXAMPLE FILE

    The following is a (partially complete) documentation file for the 
SEARCH program.  It illustrates how to use commands.  Lines that begin with 
";" are comments which are not part of the actual file (which is included 
in this library as SRCHHELP.TXT).

;the ^Z is used to clear the screen on a Kaypro
^Z                              SEARCH topics:
;here's the text of the top-level menu
1)  Files, items and separators
2)  Search phrases
3)  Specifying arguments
4)  The search process
5)  Sending output to a file
6)  Customizing SEARCH

;we put a label here for use later
~l0
;now here's the actual prompt for selection
Which would you like help with (Q to quit)? ~s
;come here if response was "1"
~c1
;we have a submenu, so put a loop around it
~b
^z                        Files, items and separators

    SEARCH works with line-oriented ASCII text files.  SEARCH treats the 
file as being made up of ITEMS, where an item is one or more lines that 
"logically" belong together.  An item could be a single line, a paragraph, 
or some other grouping.  A file is broken up into items by a SEPARATOR; 
this is a line that occurs at the end of each item in the file.  An example 
would be a blank line between paragraphs.  A separator is always a whole 
line.

                   More information is available about:

1)  File types
2)  Examples of items
;"call" the piece of text labeled "choose"
~uchoose
;this is a nested selection command
~s
;choice 1 in this submenu
~c1
^z    To be usable with SEARCH, a file must be pure ASCII (no embedded word 
processor codes) and have a CR/LF pair at the end of each line.

    Squeezed and crunched versions of such a file are also usable.  SEARCH 
determines whether a file is plain-text, squeezed or crunched by looking at 
the first few bytes of the file rather than by looking for a C or Q in the 
filename extension.  This means that a plain-text file called MYPROG.AZM 
would be correctly read, and a crunched file called RCPM.LST would be 
correctly identified.

    SEARCH can also read files out of libraries.
;second choice in this submenu
~c2
    An item can be a single line:

John Doe      1221 Main St.       Hometown, IL  60000  (312)555-1988
...
Jane Roe      13 Plymouth Ct.     Providence, RI ?     (800)111-1111

    It could be a paragraph:

       Text retrieval software can be divided into two categories: programs 
based on directly searching the text and programs based on preparing an 
index to the text..........

       SEARCH falls into the first category.  Like all such programs, it is 
slower than an index-based program, but it requires no setup.....

    Or it could be a sequence of lines separated by an arbitrary line:

SEARCH21.LBR (CP/M)
  A free-format text retrieval system.

  Uploaded by Eric Bohlman

----
VDE266.LBR (CP/M)
  The final version of the public-domain text editor.
----


    In the first example, there is really no separator; we call this 
"line-by-line."  In the second one, the separator is a blank line and in 
the third, the separator is a line consisting of four dashes.

    A separator is always a line by itself (except for line-by-line).  You 
cannot use a period as a separator in order to make each sentence an item; 
items must consist of whole lines.
;choice for "Q"; we simply exit
~cq
~q
;choice for "P"; we go back to top of document
~cp
~t
;end of choices for this submenu
~e
;at end of any selection, pause and repeat loop
~p~a
;now this is choice 2 from the top-level menu
;it's also a submenu
~c2
~b
^z                              Search phrases

    SEARCH can look for any sequence of characters within the text.  You 
can search for a word, a phrase, a punctuation character, or any logical 
combination of these.  You can specify whether a word must stand alone or 
whether it can be embedded in another word.  Comparison is 
case-insensitive.  SEARCH always treats a sequence of spaces in the text as 
being equal to a single space.  A line-ending is treated as a space, unless 
it's immediately preceded by a hyphen, in which case both the hyphen and 
the line end are ignored.  SEARCH also ignores leading spaces on a line.  
This means that a word will be matched even if it was hyphenated at the end 
of a line, and a multiple-word phrase will match across line boundaries, 
even if there's a left margin.

                   More information is available about:

1)  Phrases
2)  Embedding control
3)  Logical combinations
~uchoose
~s
~c1
^z
    A word or phrase is any sequence of characters that is to be searched 
for in the text.  The total length of all unique words or phrases that you 
wish to search for must be less than 256 characters, and you can use at 
most 16 unique words or phrases in a logical combination of search phrases.
~c2
^z
    By default, a word will be matched ANYWHERE in the text.  For example, 
"ion" would match itself.  It would also match "emotion," "ionic" and 
"emotionally."  Sometimes it is desirable to restrict the matching of 
embedded words.  You can do this by putting the special character "^^" at 
the beginning or end of a word or phrase.  When this character is present, 
it signifies that the match can occur only at a word boundary.  For 
example, "^^ion" would match only those words beginning with "ion" and 
"ion^^" would match only words ending with "ion."  "^^ion^^" would match 
only the word "ion."
~c3
^z
    SEARCH can do more than detect the mere presence of a single word or 
phrase.  It can also check for the presence of LOGICAL COMBINATIONS of 
words or phrases.  There are three kinds of logical combinations.  First, 
you can specify that a word or phrase must NOT be present in an item.  
Second, you can require that two or more phrases BOTH be present in an 
item.  This is known as an AND combination.  Finally, you can require that 
EITHER of several phrases be present.  This is an OR combination.

    To require that a word or phrase NOT be present, you simply precede it 
with the NOT character, which is an exclamation mark.  If you need to match 
a phrase that begins with a literal exclamation mark, you precede it with a 
backslash.  The exclamation mark has special significance only when it is 
at the very beginning of a word or phrase; otherwise it is treated 
literally.

    How you specify an AND combination or an OR combination depends on 
whether you are entering arguments by the command line or by prompt.  This 
is covered in the section on how to specify arguments, and examples of 
logical combinations are available there.
~cq
~q
~cp
~t
~e
~p~a
;the rest of the top-level choices haven't been filled in yet
~c3
~c4
~c5
~c6
~cq
~q
;this gets executed if the response didn't match one of the
;allowable top-level choices
~d
~ubadchoice
;this sends us back to the top level prompt.  Note that in the submenus,
;an invalid response simply recycled the menu with no output
~g0
;end of top-level menu
~e
;send us back to the beginning
~t
;this is a subroutine
~lchoose

Pick one or press Q to quit, P to see the previous section: ~r
;this is another subroutine.  Note the use of ~o to echo the invalid 
;response
~lbadchoice
"~o" isn't on the menu.  Try again
~r
;end of example file


                                  Eric Bohlman
                                  August 5, 1988