Gold Fish 1/GoldFishApril1994_CD1.img/d1xx/d149/keep/keepdoc

Text File | 1987-06-15 | 12KB | 296 lines

                               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

     [phone]

     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 17, 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 has a tiny window option, and supports Nick
               Sullivan's Tiny Window Manager . This helps conserve
               chip memory.