*** TOPIK Note: Execute the file Execute.me to setup colorterm as it runs best. You need to boot on a workbench with some space. ============================================================= | | | ***** ******* | | * * * | | * * * | | * ***** * ***** ***** * ***** ***** ***** | | * * * * * * * * * * * * * * | | * * * * * * * * ***** * * * * | | * * * * * * * * * * * * | | ***** ***** * ***** * * ***** * * * | | | | | | ***** ***** | | ** ** ** ** | | ** ** *** | | **** ** * ** | | ** *** ** | | ** ** *** ** ** | | ******* *** ***** | | | ============================================================= Copyright 1988 Warren Block Release Date: November, 1988 +------------------+ | SPECIAL OFFER!!! | +------------------+ Through a special limited arrangement with the Turbo Tech Group, registered owners of ColorTerm 2.0 will receive a $100 discount coupon for Xetec C64, C128, or Amiga FastTrax hard disk drives. More information about this amazing offer is contained in the SpecialOffer text file. ============================================================= | | | This is a NEW release of ColorTerm. This document may | | look long and formidable, but the contents are very | | important, and I have attempted to make it somewhat | | amusing, too. Please read the whole thing. | | | | Please pay special attention to the Status section | | below. The future of this program depends on it. | | | | The best approach is to print out this file. Type | | | | Copy ReadMe to PAR: | | | | to obtain a hard copy for further reference. | | | ============================================================= Introduction ------------------------------------------------------------- ColorTerm is a C64 terminal program emulator; that is, it is an Amiga terminal program that accepts and correctly responds to C64 cursor moves, color codes, and graphics characters. I saw all the colors and effects on a C64 running a local BBS, and was amazed. It seemed strange that the Amiga, with all its mighty graphic power, couldn't do something like that. ColorTerm was the result. If there is a demand for it, new versions could be produced on machines like the Mac (in black and white, but with all the cursor moves and graphics characters), Atari ST, or even MS-DOS machines. Writing something like this to work on the less graphically powerful machines like the Apple II series I leave up to those who enjoy that kind of thing; of course, it's already available for the C64/128 (TouchTerm seems to be the program of choice for these machines). Installation -------------------------------------------------------------- To run ColorTerm, you must install two 8-point fonts (c64upper and c64lower) into the fonts directory on your bootup disk; the arp.library must also be added to your libs directory. To make this process simpler, just Execute the included Execute.Me file. Note that this file expects to have all the ColorTerm files in the current directory, and copies the fonts to the current SYS:fonts directory and arp.library to SYS:libs. These should be the on the disk you booted from. You did want to install ColorTerm on that one, didn't you? NOTE: Normal WorkBench disks don't have enough free space to hold ColorTerm. To remedy this, you can delete the Utilities and System drawers, and the fonts directory. The batch file was designed to work with a two- drive system. If you have only one drive, it will be faster for you to set up a RAM disk with the commands, then copy the files into place by hand. To make this easier, the first part of the Execute.Me file consists of comments that describe where the files should be relocated and what they should be called. By the way, the fonts may not be perfect. I laboriously drew them in with Fed from the 1.2 Extras disk. In their current state, they seem to be pretty close, though. At one time, I intended to edit the alpha characters so they were easier to read, but I decided against this, mainly because of the possibility that they wouldn't be entirely compatible with the C64 set. Laziness played a part, too. Memory -------------------------------------------------------------- The program will run on a 512K machine. I haven't really done any size optimization; it hasn't seemed necessary (so far, at least). There is one thing I want to clear up, though: when you run ColorTerm, it uses ROM Kernel routines to open and use two disk fonts and the arp.libary. These files are loaded into memory, and the Workbench memory meter will show that fact. The memory they occupy doesn't seem to come back when you exit the program; however, should the next program you run need more RAM space, the system will automatically throw out resources that aren't being used (and it seems doubtful that anybody else's program is going to use the fonts) and give back the memory. This is just the way the system routines were built to work. Some people seem to have gotten the idea that ColorTerm was allocating some memory and not returning it; that isn't the case. Usage Notes -------------------------------------------------------------- The function keys are implemented as the C64 color-control keys, and they follow the same patterns. For example, F3 changes text to red. You can use either CTRL or SHIFT to access the "upper" colors, like orange (shift-F1). F9 and F10 are RVS on and off, while the ESC key is used as the HOME/CLR key. The arrow keys act like, well, arrow keys, and the tilde key (under the ESC key) produces CTRL-N and shift-CTRL-N, which switch between the two C64 character sets when received by the program. Key Definitions +-------+-------+-------+-------+-------+ Shifted |Orange | Brown |Lt Red |Dk Gray|Md Gray| | | | | | | Unshifted | Black | White | Red | Cyan |Purple | +-------+-------+-------+-------+-------+ F1 F2 F3 F4 F5 +-------+-------+-------+-------+-------+ Shifted |Lt Grn |Lt Blue|Lt Gray| | | | | | |RVS On |RVS Off| Unshifted | Green | Blue |Yellow | | | +-------+-------+-------+-------+-------+ F6 F7 F8 F9 F10 (Note: RVS On and RVS OFf perform the same with or without the Shift key.) +-------+ +-------+ Shifted | CLR | | Upper | | | | | Unshifted | HOME | | Lower | +-------+ +-------+ ESC Tilde (under ESC) (Note: the tilde key can be used to switch back and forth between uppercase/graphics and lower/uppercase character sets when the characters it produces are echoed back to the computer by a modem or BBS.) When you're ready to quit ColorTerm, either select Quit from the menu, type right-Amiga-Q, or click in the invisible, secret, hidden, close gadget in the upper left corner of the screen. ColorTerm uses the Exec Wait routine to wait for characters from the keyboard or serial port; that way, it doesn't eat processor time that other programs might need. In other words, it is set up to multitask correctly. New Features For Release 2.0 -------------------------------------------------------------- * Robustness And Error Checking The initial release had some pretty nasty bugs, and some design flaws--like no error checking for memory allocation and other fun things (my favorite was the one that wiped out the Copper; neat!) Version 2.0 is very robust, with all sorts of checking going on. If you run it from CLI, it'll print error messages when something goes wrong, just like a real program 8-). You can also, of course, start it as a background task with the AmigaDOS Run or the ARP ARun CLI commands. * New Menus The menus have been reworked, with an eye to making them easier to use and more logically organized. All the new options necessitated the addition of several completely new menus and submenus. In low resolution (40-column) they will seem a bit wide; the extra width is needed to make them look acceptable on an 80-column screen. Keyboard shortcuts are available for many selections, including the Right-Amiga-4 and Right-Amiga-8 40- and 80-column selections that version 1.0 had. They don't show, but they are there. * Keymap Additions The keymap conversion has been modified a bit. Now the DEL key works just like the Backspace key, deleting characters when unshifted and inserting spaces when shifted. The tilde key (under the ESC key) now lets you produce characters to switch back and forth between the uppercase/graphics and lowercase/uppercase/minimal graphics character sets. When used unshifted, it generates a CTRL-N, which switches to the lowercase set; shifted, a (surprise!) Shift-CTRL-N is generated, which causes a switch to the uppercase set. Note that these characters have to be echoed back by a computer, or, more commonly, your modem, to make the program switch character sets. You still have to use the Shift or Caps Lock keys to generate "true" uppercase ASCII characters; this will be necessary when sending "AT" commands to most Hayes- compatible modems. No matter what you type, you'll see uppercase, but the modem knows the difference. * Secret Gadgets Another invisible, secret gadget has been hidden on the screen. It is in the upper right corner, just where the screen front/back gadgets normally are, and that's what it does: flip the ColorTerm screen to the back. There is no "screen to front" gadget; it is not as useful, and it would be difficult to tell the two apart (being invisible, you see). There are ways around this; if you think the program should have it, write or call and tell me so. * Faster Screen Scrolling Screen scrolling is substantially faster than that of Version 1.0, thanks to lots of semi-shady mucking around with Intuition structures. It's easy to get faster scrolling; it's amazingly difficult to try and get Intuition to deal with a double-buffered screen. During a No Protocol Send (see below), you will see some of the color flickering that the easy method produces, for technical reasons too detailed to describe here. It will give you some idea of why I spent so much time and effort on smooth scrolling. Don't worry: a No Protocol Send is the only place you can see the flicker. * XModem Transfers The single most-requested addition to ColorTerm is now here: XModem file transfer. These routines required a lot of sweat and blood to produce; about three-quarters of all this effort was due to my stupidly trying to port C versions, rather than just writing them from scratch in Forth. The receive routine is still dimly related to its C cousin; the send routine is entirely my own. The C versions were from the VT100 program by Dave Wecker and Steve Drew. Mine are much improved in things like handling transmission and user errors, but I would never have come up with some of the stuff I found in xmodem.c. My thanks to them. A special note of thanks to Phil Anthony, a DEC guru who (through a roundabout way) provided me with a copy of a real spec for XModem. I learned a lot from it, including just how bad most of the implementations out there really are, and tried to make mine better. To abort an XModem transfer, click on the Cancel gadget, or press the ESC key. The transfer window will display "Cancelled!," beep, and wait for five seconds. If you don't feel like waiting, just press a key or click the mouse. Auto-Chop is an added feature of these routines. When ColorTerm is first run, Auto-Chop is disabled. This means that XModem downloads will be an even multiple of 128 bytes, the XModem block size. With Auto-Chop on, XModem downloads will be automatically truncated: all of the CTRL-Z and null characters will be stripped from the end of the file, where they were presumably added to round out an XModem packet to 128 bytes. AmigaDOS won't run programs that have unnecessary padding like this, so the Auto-Chop option allows you to directly transfer executable programs without the use of archive programs like ARC, Pak, or Zoo. However, this feature will occasionally cause problems with archived files, where some of the bytes it stripped out weren't padding, but an actual part of the original file. To prevent this, just download the file with Auto-Chop disabled. WARNING: if you select an existing file as the file to Receive a transfer into, the previous contents of that file will be erased. Don't be alarmed when the block count on an XModem transfer suddenly goes from 255 back down to zero. The block count will always be a modulo 256 value. * ARP File Requester The transfer routines require the user to enter a filename, and for a while I was using my own little file requester that was very plain. As a quick and easy fix, I implemented the ARP (AmigaDOS Replacement Project) file requester, which turned out not to be quite as quick or easy as I had originally thought. Still, it is a very, very nice file requester. (Note: when you click the right mouse button, it shows a list of devices. Neat!) Thanks go to Charlie Heath and Scott Ballantyne for providing such a fine addition to AmigaDOS, which needs all the help it can get. By the way, since you'll have to add the arp.library to your boot disk to run ColorTerm, you might as well add the ARP CLI commands, too. They work better than the AmigaDOS ones and will save some disk space as well. Check your local BBS for the ARC files, or write to the address below. * Additional Baud Rates Baud rates up to 9600 may now be selected from the Baud menu. While text output can't come close to keeping up with the highest speeds, they were included so that local file transfers could be performed at a reasonable rate. * Text Capture Facility With this feature, you don't need to memorize what goes on on-line. Just capture a session into a file, then you can examine it at your leisure. Because the Amiga and most printers can only handle plain ASCII, there are two styles of text captures. The first is with the Translate option enabled, where the evil C64 cursor controls and color codes are discarded, and graphics characters are translated into asterisks. Upper and lower case are also corrected. The result is a pure ASCII file that looks surprisingly like what the screen displayed in the first place. The second option is with Translate disabled, where everything is captured with no translation whatsoever. Be warned: this file will be completely incomprehensible on an Amiga screen or ASCII printer. The reason that this option exists at all is to allow you to capture an interesting graphic screen or message, then upload it again somewhere else with No Protocol Send. Selecting Text Capture/Off will close the file and stop the capture. WARNING: like all of the other transfer protocols, Text Capture overwrites the selected file *each time* you use it. If you capture some text into a file, shut off Text Capture, then attempt to capture more text into the same file, the previous contents will be overwritten. The solution is to use two or more capture files, which you can combine into one file afterwards with the Join CLI command. * No Protocol Send Actually, this is an outgrowth of the Text Capture option; on some terminal programs, it is called ASCII Send. To me, that seemed like an inappropriate name. Anyway, it will allow you to capture a graphic or message (or a graphic message), then upload it into a text editor. Since the severely wimpy editor built into the Color 64 BBS is so painfully slow, the program pauses for .045 seconds after each character is sent. This prevents the BBS from dropping characters; it works better with wordwrap off. (The value of .045 seconds was obtained by experimentation, and was the fastest I could get reliable text uploading to work at 2400 baud on the local system.) * Fantastic Sound Well, no, not really. But now there is a beep that is sounded when a CTRL-G (BEL) is received, and at the end of file transfers. This allows you to start a long file transfer and do something else until the computer beeps to get your attention. Be sure to turn up the volume on your monitor or external amplifier so the beep can get your attention. Multitasking ColorTerm with a music program may cause some problems with the two of them fighting over the audio channels (although, in all likelihood, ColorTerm would win). I can't really bring myself to consider this much of a problem. You should be aware that the beep only comes out on one stereo channel. If you don't have a Y-cable connecting both channels of the Amiga audio output to your monitor, or a stereo amplifier of some kind, you may not be able to hear the beep. The screen can also be made to flash when a bell character is received; a new menu (Options) lets you control what ColorTerm will do when this happens. You can disable the flash, the beep, or both. Only the beep is enabled when the program is started. * New And Improved Documents But then, you already know that. You're reading them. * Hassle-Free Shareware Fee Submission A nifty and handy pre-addressed envelope and survey form are actually provided with this package! To see proof of this amazing fact: Turn on your printer, set it to the top of a fresh page, and set it to Pica or 10 CPI and six lines per inch (this is the default on most modern printers). Turn on the NLQ, bold, or double-strike mode, then type: Copy PrintMe to PAR: The printer will reconstitute the magnetic bits of the file with ink and paper molecules to form two sheets of paper. The first sheet will magically become an addressed envelope as you fold it up and stick a stamp on it. The second sheet is a survey form which I hope you'll take the time to fill out and return (using the envelope made from the first sheet, naturally). The envelope is also a convenient way to submit your shareware fee. Remaining Flaws -------------------------------------------------------------- Text output at higher baud rates can be sluggish, due to a combination of several factors. This will be especially noticeable on the 80-column screen. If you have a problem running ColorTerm from the Workbench, try it from CLI to see what the error message says. Of course, there may still be actual bugs, so if you think you've found one, find a way to reproduce it, and let me know. Function key macros: I wanted to include them with this release, but time and funding ran out. If there is enough popular support for this version of ColorTerm, count on them to be included in the next release. I've seen what a pain PC Pursuit is to use without macros, and I'm sorry. More transfer protocols: some people have tried to convince me that I should include Punter file transfers. It hasn't worked; Punter isn't a bad protocol, but it's only used on the C64. XModem (and YModem, and ZModem, and WXModem, all of which I would like to include in the next release) is a universal protocol; no matter what else is available, XModem is always there. An analogy: Punter is the Mandarin Chinese of file transfers; a lot of people speak it, but it's not a worldwide language like English (XModem). Design Credits -------------------------------------------------------------- ColorTerm was written in Amiga Multi-Forth, from Creative Solutions. Multi-Forth for $89 (list; commonly discounted to about $50) has got to be one of the best deals in Amiga programming languages. The serial communications and keymap conversion words were based on ideas I got from looking (mostly) at ATerm1.3, an early Amiga terminal program by Michael Mounier, and an early version of VT100, a VT100 emulator by Dave Wecker. The video and other stuff (yecchhh) is all my own. Special thanks for lending me equipment and books go to John Fassbender and Burt Landman, nice guys both. Everyone who wanted a new version of ColorTerm with more features owes some thanks to Burt, who constantly bugged me (but politely, of course) to keep improving it. Once you get Multi-Forth, be sure to get ConMan to use with it. ConMan gives you full command-line editing and history; since it works with all console device windows, it works with Multi-Forth. ConMan is incredibly good shareware from Bill Hawes (author of ARexx and WShell), who highly deserves a contribution from all Amiga owners. Another necessity for use with Multi-Forth: a decompiler. Mine has been supplied to Creative Solutions, and is making its way around the PD circuit about now. It has been quite a help with my Forth programming; it's also fun to snoop around with. Version 1.5 is the latest (as of this writing), and it can handle 99% of the high-level definitions listed in the Multi-Forth manual, and some that aren't listed in the manual. (Send me a blank disk and a stamped return mailer and I'll send it and some other neat programs to you. How can you lose?) I recommend Aedit for a general-purpose text and program editor. Aedit is 57K of very tight and powerful 68000 assembler by Joe Bostic, an industrial-strength editor that does just about everything anyone could want, and does it with mnemonic commands and intuitive operation. About forty bucks, but a steal at any price. The ARP (AmigaDOS Replacement Project) commands were very helpful in the creation of this program. They reduce the AmigaDOS frustration level greatly, and they're faster, smaller, and smarter than what you get with the stock AmigaDOS commands. A final note: it would have been much more difficult to complete this program without my 2M StarBoard, which is still the best RAM expansion out there. Suppliers --------- Multi-Forth: Creative Solutions 4701 Randolph Road Suite 12 Rockville, MD 20852 (800) GO-FORTH ConMan: William Hawes P.O. Box 308 Maynard, MA 01754 (617) 568-8695 Decompiler: Warren Block 1921 Fifth, Apt. 3 Rapid City, SD 57701 (605) 342-1632 Aedit: DRM Programs 1329 Arthur Ave. Las Vegas, NV 89101 (702) 457-9489 ARP: ARP Support c/o Microsmiths, Inc. P.O. Box 561 Cambridge, MA 02140 StarBoard2: MicroBotics 811 Alpha Drive, Suite 335 Richardson, TX 75081 (214) 437-5330 VT100: Fred Fish Disk #55 About Me -------------------------------------------------------------- My name is Warren Block. To try to make a living, I write articles and reviews for magazines like INFO, Amazing Computing, and (back when they still covered interesting machines) BYTE; additionally, I sometimes do consulting on the Amiga and other computers. (Note that, unlike many "reviewers," I don't work for a software company, nor do I accept "free" software from manufacturers). If you like this program or my writing, feel free to correspond with me at: 1921 Fifth, Apt. 3 Rapid City, SD 57701 (605) 342-1632 I may also be reached through the P.C. Worlds Color 64 BBS at (605) 348-2357 (not Pursuitable, unfortunately). My usercode is Wablock and I am user #24. Status -------------------------------------------------------------- ColorTerm is and always has been a "shareware" program; in other words, freely redistributable, but those people who use it are supposed to send me some money. As of this release, I have received a total of ten dollars and one disk of public domain software. This does not constitute a strong incentive to spend time developing upgrades, and that's the major reason it's been so long between releases of this program. Another factor was the amount of complaints I got. The most common was "it doesn't do lower case on CNet." As near as I can tell, this is due to lack of knowledge on the part of those complaining. (I'm not sure, because I don't use CNet, but I've been told that there is an option that needs to be selected in the CNet text editor. Contact your Sysop about that.) I don't mind constructive criticism, but I'd be more willing to listen to complaints if those registering them had contributed to the production of this program, monetarily or otherwise. I got some encouraging correspondence, too: there were letters and calls from folks from New Jersey to Canada to California. Many were enthusiastic, and that helped. A few were interested in porting the program to the other machines mentioned above. This hasn't happened so far, for two reasons: 1. I only have an Amiga, and, much as I'd like to, I can't write code as complex as this long-distance. I keep telling people that I'll work on a translation for any machine (except the Apple II series, which I leave for the masochists) if they'll give me one of the machines (in the permanent sense). The machine in question should have at least 512K and a double- sided drive, and I'll probably need development tools and serious reference books, too. Eventually somebody may take me seriously. 2. I don't know anybody locally who can program well enough to port ColorTerm to those other machines. I know only a few people who have the level of machine- specific knowledge that this requires, and none of them have Macs or Atari STs. On the other hand, if someone is interested in buying the source, I'm willing to accept offers. It won't be cheap. What all this adds up to is that the future of ColorTerm depends on you, the user. If you *use* the program, warts and all, send in a contribution (and a list of suggested improvements!). The guideline I use is to send enough money so the programmer can at least go out and get a pizza, which comes out to $15-$20, depending on quality and number of toppings. If you can't afford to send any money (and there are a *few* who really can't), don't waste time feeling guilty about it (although you could spend some time making those who *can* afford it feel guilty about it). Send me something else: a letter saying what you like and dislike about the program, how your nephew thought it was awful or your niece thought it was great, your user group newsletter, a picture of your cat, whatever. BUT SEND SOMETHING! If I know there are people using it, I'll try to keep working on improvements to ColorTerm. Legal Stuff -------------------------------------------------------------- This file and the ColorTerm program are Copyright 1988 Warren Block. Provided that the archive file containing these files is not modified, it may be freely redistributed to anyone, anywhere, subject to the laws of their country or planet of residence.