Oakland CPM Archive/oakcpm.iso/cpm/help/helper.lbr/HELPER.DZC/HELPER.DOC

Text File | 1988-08-30 | 14.1 KB | 361 lines

                   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  [phone]
...
Jane Roe      13 Plymouth Ct.     Providence, RI ?     [phone]

    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