*****************************************************************************
*
* 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, (503) 935-7883
* 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.)
*****************************************************************************
