G'day! And welcome to... c Keep v1.2 Copyright Notice: Keep v1.2 is copyright (c) 1987, 1988 by Tim Grantham. It may not be sold for profit, nor altered in any way, without the permission of the author. Keep is an example of the latest in freely distributable programs: Bonusware. That means that you can copy this software as much as you want -- no donation is required or requested (I won't send them back if I get them, though. ;-) ) However, should you wish to have a copy of the source code, send me $10 and a blank disk and I will happily oblige. It's ugly code but it's only about the 15th program I've ever written, in any language on any computer, and I'm damn proud of it. I would appreciate any feedback users have about the program. I can be reached at: 55 Sorauren Ave. Toronto, Ontario Canada. M6R 2C9 (416) 535-1721 or on: PeopleLink: AMTAG BIX: dispatcher GEnie: t.grantham CIS: 71426,1646 Keep those cards and letters coming, folks! What you are reading is the documentation for version 1.2. Those of you who simply wish to see what has been added to version 1.1 can jump to the end where the changes are listed. I still recommend that you peruse the entire file: some of the changes require a little explanation. The new features are preceded by an asterisk (*). Keep is a utility program for BBS and network junkies like myself who download messages in one large file and then read them off-line. Using only the mouse, you can drive through such files a message at a time, examine each at your leisure and tag those you wish to keep. When the entire file has been examined, keep goes through the file once more and stores those messages that have been so tagged. The original source file is left intact. *If a file with the same name as the current output file is found, Keep will give you the option of overwriting that file, appending to it (useful when building a file from several source files) or renaming the current output file. If no messages have been tagged for saving, the source file will be closed and the program will simply restart. Once running, Keep is (or should be) self-explanatory. A possible source of ambiguity is the gadgets at the top of the window. Selection of the arrows pointing up and down permit the user to page through the text of each message. The KEEP and DUMP gadgets tag the message and advance to the next message. You can select the left-pointing arrow to back up to the previous message. Here you can change the fate of that message by selecting the appropriate KEEP or DUMP gadget. However, you must return to the current message by selecting the right-pointing arrow before you can move on to the next message in the file. *The `ghosted' slider indicates how far into the file you've gone. I call it the file gauge. :-) You can invoke Keep in a number of ways. If you are using the Workbench, you can simply click on the icon provided. If you are using the CLI, the recommended command is as follows: run keep Charlie Heath's excellent file requester is put up as soon as the program starts so that you can pick the file to be examined. In this case, the output file containing the kept messages will be stored by default in the current directory. However, you can specify the source file from the CLI thusly: run keep message_file This will examine the file message_file and store the messages to be kept in the file message_file.kpt, in the current directory. If you wish to cross directories, you can enter, for example run keep df1:message_file to df0:file_name The .kpt extension will be automatically appended to the destination file name. You should specify a destination file name. Simply entering, for example, run keep df1:message_file to df0: will cause the kept file to appear simply as .kpt on df0:. Keep opens its own screen to the same size as the front-most screen. This is almost always the Workbench screen. Thus, if you are using morerows or interlace to get a larger display area, Keep will inherit it. Keep assumes that message files consist of lines of no more than 120 characters, ending with a carriage return (CR) and/or linefeed (LF). Any non-text character contained in the line before the CR/LF will be displayed, usually as a rectangle. CRs or LFs do not appear. They are, however, left intact. You can at any time change the directory and name of the destination file by selecting To... under the Project menu. Skip terminates examination of the current file and saves what messages had been tagged up to that point. *It then saves all of the unread messages into another file in the same directory with a .splt extension, e.g. message_file.splt. (I'm afraid there is no option to change the name of this file.) Skip is useful if its 3:00 am and you can't plow through another 250 messages before you have to go to work in the morning. You can use Skip to split the file into read and unread messages; later you can pick up where you left off. You can even use the To... option to append the kept messages to the original .kpt file. A couple of caveats: the storing of the unread messages is pretty slow in this version. Be patient. Secondly, make sure there is enough room for the .splt file, or the program will terminate! Abort terminates examination of the current file completely and restarts the program. About provides some speculation as to the inspiration for the Guru's meditations... *Tiny closes the Keep screen and puts up a tiny window on the Workbench screen. This conserves CHIP memory should you wish to switch to another program but still leave Keep in memory. Keep also provides support for users of the Tiny Window Manager created by Nick Sullivan of The Transactor for the Amiga. If TWM is running, it will `gather up', so to speak, Keep's tiny window into itself, along with any other tiny windows created by other programs that can make themselves clients of TWM. To bring the Keep screen back up, simply click the mouse inside the tiny window. You will then find yourself exactly where you were when you put up the tiny window. It's probably not a good idea to select the Tiny option while the program is storing the messages marked for saving. Quit exits the program. Keep does not have to be used exclusively for information services. It can work with any text database that uses a repeating header at the beginning of each record and fields of no more than 120 characters delimited with CR and/or LF. It looks for a search string of five characters or less -- the shorter the string, the faster the search. You can see which ones I have chosen: each time a network gadget is selected in the service requester, the First line search word string gadget is updated. You can click on this gadget to customize the search string. *Special note to Usenet-ers: Because the headers on Usenet/Pnet/Bitnet vary widely, the search string I have provided may not be suitable. Use the string gadget to make the program look for a string unique to your particular message header. If the program encounters a read error in the message file, it will save those messages currently tagged and offer to restart the program. If the program encounters an error during the writing of the destination file, it will close that file and save to ram: instead -- very handy if you just spent four hours going through 700+ messages. In this case, however, the default destination file name will be used. Enhancements to future versions of Keep may include: 1. Much more attractive, Image-rendered gadgets. 2. Command line and menu support for interlace. 3. More polished mutual exclude in the service requester. 4. Custom depth arrangement gadgets. The standard ones are there, although only the top two rows of pixels are visible. If you can grab those two rows, you can also slide the screen down. 5. Support for other BBSs and networks. Does anybody know what The Source uses for its message headers? 6. Support for arbitrarily large files and messages. *In this version, Keep is confined to files containing up to 4000 messages or records. In addition, it reads in no more than 1000 lines at a time. This latter aspect does not compromise the operation of the program should the message be larger than 1000 lines. It simply splits it into smaller pieces. If you want to save a complete message, save all the pieces. 7. More elegant command line parsing. 8. The ability to use the mouse to mark portions of messages for keeping. 9. Word wrap for lines longer than 80 characters. 10. Scrolling, rather than paging of text. Keep v2.0 will make use of the ARP library, including the ARP file requester. It will also most likely provide the ability to keep messages to multiple files at once and the ability to use the Pipe: device provided by some shell programs to permit a file to be kept even as it is being downloaded. The shareware program blitzfonts works with Keep and is highly recommended. I would like to thank Harvey Laser, Larry Pahlman and DARRYL H for testing the various versions of this program. I especially would like to thank the real Nick Sullivan, editor of The Transactor for the Amiga for his endlessly patient assistance. Keep is a direct descendant, several generations removed, of a program Nick wrote in CBM Basic and 6502 ML for the C64 and PET 8032. My greatest debt is to my wife Cate and my son Alex, for their love. Tim Grantham April 26, 1988. New features of Keep v1.2: 1. A proportional gadget `file gauge' that shows you how far into the source file you are. 2. The Skip menu option now will save the unexamined portion of the source file to a separate file, for later perusal. 3. Keep now checks to see if a destination file already exists and if so, it provides an opportunity to append to it, to overwrite it or to change the name of the current output. 4. Keep is now runnable from the Workbench. Check out the icon! 5. If no messages have been marked for keeping, no file will be opened -- Keep will simply restart. Before, Keep created an empty file. 6. Keep now can handle files containing up to 4000 messages. It will not recover nicely if this number is exceeded but I find it hard to imagine a file of such a size. You could always use the Skip option to gnaw on it a piece at a time. 7. Keep now has a tiny window option, and supports Nick Sullivan's Tiny Window Manager . This helps conserve CHIP memory.