Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/104.lha/Help!.doc

Text File | 1980-07-10 | 14KB | 242 lines

*****************************************************************************
*
*  Program:  Help! V1.0 (C) 1988 The Puzzle Factory       Author: Jeff Lavin
*            Open a help window on the                   Created: 01/15/88
*            WorkBench screen.                       Last UpDate: 01/15/88
*
*      Use:  1> run Help!
*
*        Written entirely in assembly language to be small and fast.
*        Works with expanded memory, including 'sync-ram' at $C00000.
*        Also works with the C-Ltd TimeSaver(c).
*
*     Instructions
*     ------------
*     1. First of all, this version of Help! may be run from the WorkBench
*        or the CLI.  An Icon is provided for the WorkBench, but feel free
*        to change your copy.  All messages are recycled and memory
*        returned when the program closes.
*
*     2. In order to function properly, you MUST be in 640 x 200 display
*        mode, and you MUST use Topaz 8 font.  If you don't do this, don't
*        blame me if it doesn't work properly.  The purpose of this
*        restriction is so that the program doesn't have to do any size
*        checking to allow the maximum possible scrolling speed.
*
*        Also, please note that any kind of reasonable scrolling speed
*        needs to have Hayes Haugen's BlitzFonts(C) installed.  The normal
*        Amiga Text() routine is disappointingly slow.  Since Hayes has
*        already fixed the problem in a straight forward way, I decided
*        not to re-invent the wheel.  Please remember to send Hayes a
*        shareware contribution.
*
*        On the subject of scrolling speed, if it seems rather slow, check
*        your repeat speed in Preferences.  This program will scroll almost
*        as fast as the maximum setting.  If you use the maximum setting,
*        you will see the scrolling get slightly behind on files of the
*        length built into the program.  The scrolling will catch up on
*        files of this size, but what's happening is that keypress messages
*        are getting stacked up.  As the Amiga does not do memory bounds
*        error checking, it is conceivable that on a really long file, if
*        you just sat on the arrow key, you could crash the system.  So it
*        is a good idea to release the key occasionally and let the program
*        catch up.
*
*     3. When you first run Help!, you will see a window open on the right
*        side of the screen.  This is the Help! Window.  After you have read
*        the opening notice, click on the small "T" gadget in the lower
*        right corner.  The "T" stands for TINY, and it makes the window
*        small, in order to get it out of your way!  The same gadget also
*        makes the window normal size.  Anytime you want the normal size
*        window back, click on the "T" gadget again - it'll come right
*        back to normal size.  You don't have to worry about where you put
*        the tiny window meanwhile, because it checks it's location before
*        growing and moves to avoid the screen edges if necessary!
*
*     4. After the window is big again, you will find a list of all the
*        special keys the program recognizes (HotKeys).  Pressing any of
*        these keys, anytime the window is big AND active will cause the
*        action indicated.  Most of these are pretty obvious.  The case of
*        any of the alpha (letter) HotKeys is ignored.  The HotKeys aren't
*        recognized when the Help! Window is inactive, so they won't
*        interfere with your other programs.
*
*     5. Two HotKeys that may need explanation are the "C" and HELP keys.
*        When you press the "C" HotKey at any time, the previous HelpFile
*        will be cleared and the Calculator will be displayed (See below
*        for more info on the Calculator).  Anytime the HELP key is pressed
*        the previous display will be replaced with the list of HotKeys.
*        This is also true when the Calculator is displayed.
*
*     6. When you make the Help! Window tiny, and then make it big again,
*        it will display the list of HotKeys when you first see it.
*        However, you don't have to start over at the beginning of a
*        HelpFile you have been browsing, whether it's built-in or a user
*        file.  Just press the UpArrow key, and the HelpFile will be
*        redisplayed in the Help! Window one line down from where it was
*        before you made the window tiny.  This feature works the same when
*        you have been looking at a HelpFile and need to use the Calculator.
*        Just press HELP, to get back to the HotKey list, and then press
*        UpArrow to get the HelpFile back where you left it.
*
*     User Files
*     ----------
*     1. There is a separate file named "Example.txt" that will explain
*        how to write your own HelpFile.  All HelpFiles MUST be in
*        either the current directory or SYS:S or Help! won't be able to
*        find them.  Your HelpFile may be any length you like, limited only
*        by available memory.  Please follow directions in "Example.txt".
*
*        Suggestion:  If you put Help! in your 'C' directory, then you can
*        put general HelpFiles in SYS:S that you always want to access, and
*        specific HelpFiles about a program, for example, in a directory
*        with that program.  This will keep your system disk from getting
*        full too fast, and still keep all your HelpFiles handy!
*
*     2. After you have created a HelpFile ("Example.txt" may be used if
*        you want to see how it works), pressing "G" (<G>et User File) will
*        cause a string requester to appear.  Type in the name of the
*        HelpFile you want to display, and press Return.  If Help! found
*        your file, it will be displayed.  If Help! couldn't find your
*        file, it will say so.  Help! looks for your file first in the
*        current directory, and then in SYS:S.  To scroll back and forth
*        through the file, use the UpArrow and DownArrow keys.
*
*        Note:  Help! looks in the current directory using the exact
*        filename you type in to the requestor.  If the file is not found,
*        it the appends "SYS:S/" to the front of the filename and looks
*        again.  If you like you may type an entire pathname into the
*        requestor, but no other directories will be searched if the file
*        is not found.  Help! loads the entire User File into memory in
*        order to speed up scrolling; NO disk buffering is done.  This
*        means that if you have limited ram, don't write 100K HelpFiles!
*
*     3. Now that your file is loaded into memory, you may view any of the
*        built-in help files at any time by using the proper key, and
*        redisplay your file by pressing "F" (Display User <F>ile).
*        The "F" key will continue to display your file until you load
*        another file using "G".  The "F" key will be ignored if there is
*        not a valid User File in memory.
*
*     Calculator
*     ----------
*     1. This is an 8 function, 2 base, 31 bit signed integer Calculator.
*        It uses standard algebraic number and function entry format.
*        Please read this again if it isn't clear.
*
*     2. For any of the functions, you may enter any 31 bit signed numbers
*        ($7FFFFFFF to $800000001 Hex or 2147483647 to -2147483647).
*        The answer MUST also be within this range.  This does not present
*        a problem for subtraction or division, but when doing addition or
*        multiplication, if the sum or result is greater than 31 bits
*        signed, you will get an overflow error.  You may not, of course,
*        add two positive numbers and create a sum larger than $7FFFFFFF,
*        or two negative numbers for a sum smaller than $80000001.  In the
*        same vein, you may not multiply positive or negative numbers with
*        corresponding results ouside this range.
*
*     3. When using division, all the same rules apply.  It should also be
*        noted that because this is an INTEGER calculator, any remainder
*        is simply discarded, so 8 / 3 = 2 (not 2 and change).  For the
*        same reason, any division that results in a quotient of less
*        than 1, will display 0; thus 2 / 4 = 0 (not .5).  Also note that
*        divide by zero errors are trapped by the program, not the CPU, so
*        you should never meet the Guru that particular way.
*
*     4. The normal way to represent negative numbers in a computer is by
*        using their 2's complement.  This is the way numbers are
*        represented in this program.  We know a number is negative if the
*        most significan bit for that data size is set (1).  All numbers
*        in this program are represented as 31 bit signed integers.  Sorry,
*        but there are no selectable data sizes in this version.  This
*        explains the limits on value, but one more point needs to be made.
*        Consider the number $80000000.  Because there are no 1s in 31 bits,
*        we know the number is zero.  And because the sign bit is set (1),
*        we know that this number is negative.  Negative zero is obviously
*        a nonsensical quantity.  Motorola, and others have treated this
*        particular value as a special case.  In this program, so do I.
*        If you attempt to enter this value, you will get an overflow error.
*        You cannot create this value as a result, and the program will
*        ignore you if you try to negate zero.
*
*     5. The HEX and DEC keys should be reasonably obvious.  The calculator
*        comes up in hex.  All numbers entered are interpreted as
*        hexadecimal while in this mode.  If you click on the DEC gadget,
*        the boolean gadgets, as well as the numbers A-F will be ghosted,
*        and all input will be interpreted as decimal numbers.  If you need
*        a negative number in decimal calculations, you will have to subtract
*        from zero, as you cannot use NEG in the decimal mode.
*
*     6. The NEG gadget will negate either the number you have just input,
*        or the result after you have clicked on <=> or a function.  Note
*        that NEG means 0 - <num> (2's complement.  This isn't the same as
*        NOT (1's complement).
*
*        All the other boolean gadgets work on the principle
*        <num1> <gad> <num2> = <result>, just like <+> <-> <*> </>.
*
*     7. The CLR gadget works in the following way:
*        If used while entering a number, that number will be cleared.
*        If clicked again, the stored result will also be cleared.
*        If clicked as the first key after <=>, the result will be cleared.
*
*     8. All functions may be chained.  That is:
*          (n + m = * o = / p =), is equivalent to (n + m * o / p =).
*
*     9. This is my first effort at a SIGNED algebraic calculator.  At
*        the time it seemed like adding a calculator to the Help! program
*        would simply be increasing the value for the user.  It turned out
*        to be anything but simple.  Just look at the number of unsigned
*        calculators running around.  Compared to this, writing Help! was a
*        piece of cake.  The point of this is, that I've tried very hard to
*        make this calculator conform to accepted conventions.  If it turns
*        out that there is an esoteric bug lurking somewhere, please contact
*        me so that I can improve the program.
*
*        * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
*     I hope you enjoy using Help!  If you like it, please send me $10.
*     If you don't like it enough not to send the $10, don't use it.  It's
*     all between you and your concience.  If shareware ceases to be viable,
*     there won't be any more shareware.  'Nuff said.
*
*     If you have any comments or suggestions, I would like to hear them.
*     Leave a message on the board listed below, or write me a letter via
*     US Snail.  If you have problems with Help!, please try to document
*     them as thoroughly as possible, so as to facilitate bug hunting.
*
*                                                              The Author
*
*     >> No warrantee of any kind whatsoever expressed or implied! <<
*
*     This program is shareware, NOT public domain, and is copyrighted
*     by the author.  All rights are reserved.  This program may be freely
*     distributed if the following conditions are observed:
*
*       1. This notice must be distributed intact with the program.
*       2. The following files must be distributed intact with the program.
*
*                   Help!        -    Executable
*                   Help!.info   -    Icon (for you WorkBench folks)
*                   Help!.doc    -    Documentation
*                   Example.txt  -    Example user HelpFile
*
*       3. Only a reasonable distribution fee may be charged, such
*          as by User Group PD Libraries.
*       4. Commercial use is prohibited without the author's written
*          consent.
*
*     The assembly source for this program, Help.asm, may be obtained
*     by sending either a 3 1/2" disk and $15.00, or $20.00 to the address
*     listed in the opening notice of the program.
*
*       I can be reached at:     The Symposium
*                             Amiga Development BBS
*                        1 Meg Memory - 33 Meg Hard Drive
*                     300/1200, 8-N-1, 24 hr, [phone]
*                           Another Citadel-68K BBS
*
*     (This BBS is devoted to Amiga software and hardware development, and
*      all users are required to register.  Just follow the instructions.)
*****************************************************************************