
SHRINKIT FOR THE APPLE II

Program by Andy Nicholas
Documentation by Karl Bunker

Send comments/suggestions on ShrinkIt to:
Andy Nicholas
1180 Reed Ave., Apt. 12
Sunnyvale, CA 94086

Electronic Addresses:
GEnie or America-Online: shrinkit
CompuServe: 70771,2615
Internet: shrinkit@apple.com

Send comments/suggestions on this documentation to:
Karl Bunker
GEnie: k.bunker

What is ShrinkIt?
-----------------
     ShrinkIt is a utility program for archiving files and disks.
"Archiving", in this usage, refers to the process of placing files or
disks "within" another file -- the archive file. Archiving is usually
done to prepare the files/disks for transmission via modem, or for
storage purposes. Thus, an archive file, whether created with ShrinkIt
or another archiving utility, will be a file which serves as an
envelope, containing one or more other files, or complete disks. There
are a number of reasons for archiving files before transmitting them
with a modem. The principal reason is that an archive provides a means
of sending the "attributes" of a file -- its filetype and other
information -- along with the file itself. An archive also allows
several related files (or an entire disk) to be packed together into a
single file. True archiving utilities will also have the capability of
compressing the files they contain to minimize the transmission time
and disk space the archive requires.
     ShrinkIt uses a highly efficient compression algorithm known as
Ziv-Lempel compression, and creates archive files with a format called
NuFX. ShrinkIt and ShrinkIt-GS are currently the standard archiving
utilities for Apple II telecommunications. ShrinkIt can unpack files
which have been archived with ShrinkIt, as well as those which have
been packed with certain other file-packing utilities, such as BLU and
ACU.

About These Instructions
------------------------
     Most users of ShrinkIt will be interested in unpacking files they
have downloaded from a Bulletin Board Service or Information Service.
Others will also be using it to pack files that they want to upload to
such a service. In these instructions I will first describe how one
uses ShrinkIt to unpack archives, and then how to create a new archive
file. Finally I will give an explanation of each of the options
available in ShrinkIt's Main Menu, and fill in certain other details
about ShrinkIt's functioning. If you are ONLY interested in how to
unpack a file which you have downloaded, you can just read the section
entitled "Unpacking an Archive", and skip the rest of this file. I
will attempt to make these instructions understandable to the
relatively new computer-user; if you are unfamiliar with any of the
terms used, or become generally confused, you may want to consult the
instruction manual to your telecommunications software, or a magazine
article on telecommunicating with the Apple II.

System Requirements
-------------------
     ShrinkIt requires a 128K enhanced IIe, a IIc, IIc+ or IIgs.
Versions of ShrinkIt for the Apple II+ and unenhanced IIe are also
available. Shrinking and UnShrinking functions have been split into
two different programs for these older machines. These programs are
called IIPLUS.SHRINKIT and IIPLUS.UNSHRINK, and they will run on any
64K Apple II, using the 40-column screen. More information on these
alternate versions of ShrinkIt will be given towards the end of these
instructions.

ShrinkIt-GS
-----------
     These instructions are for the 8 bit version of ShrinkIt. A IIgs
version of ShrinkIt is also available. Archives that have been created
with ShrinkIt-GS can be unpacked with version 3.0 or later of the 8
bit ShrinkIt, providing that none of the files being extracted from
the archive is an "extended" GS/OS file (also know as files with
resource forks). Since ProDOS-8 can't handle extended GS/OS files,
someone who doesn't own a IIgs would probably have no reason to
extract such a file. If you open an archive containing extended files
with the 8 bit ShrinkIt, these files will be marked "forked" in the
file list.

Distribution and Copyright Info
-------------------------------
     ShrinkIt is a Freeware program. This means that you are under no
obligation to pay the author anything for it, but the copyright is
retained by him. You are encouraged to distribute this program to
whomever you please.

Launching ShrinkIt
------------------
     ShrinkIt can be launched using standard program selectors such as
Bird's Better Bye, Squirt, ProSel, or the IIgs Finder. (Some versions
of ProSel 16 can't launch ShrinkIt; an update to the latest version of
ProSel fixes this.) ShrinkIt is too large to be directly launched from
the BASIC prompt ("]"). However, a small SYS file called
SHRINKIT.SYSTEM is distributed with ShrinkIt. SHRINKIT.SYSTEM can be
launched from BASIC, and it, in turn, will launch ShrinkIt.

Some Terms Defined
------------------
     In the Apple II telecommunications community, there are a number
of different file- and disk-packing formats which have been used over
the years. Most of these formats have been superseded by ShrinkIt and
its NuFX format; others are still used. These various formats are
usually denoted with a three-letter suffix appended to the file's name
(as in "MY.FILE.BNY"). Here are some of the suffixes you are likely to
encounter, with brief descriptions of their related file formats:

.BNY: Binary II format. Though not a true archive format, a Binary II
      "envelope" will preserve a file's attributes through a download
      or upload. ShrinkIt can unpack .BNY files, and they can
      also be automatically unpacked during downloading by many
      telecommunications programs.
.BQY: "Squeezed" (i.e., compressed with a different algorithm than the
      one used by ShrinkIt) files within a Binary II envelope.
      Created with the utility BLU, these files can be unpacked with
      ShrinkIt.
.QQ:  If you remove the Binary II envelope from a .BQY file, the
      squeezed files it contains will have the suffix .QQ, or
      sometimes .SQ. These files can be unsqueezed with ShrinkIt.
.ACU: The archive format used by America Online (formerly
      AppleLink Personal Edition); these files can be unpacked with
      ShrinkIt. (America Online currently uses .SHK format for new
      uploads.)
.SHK: NuFX format; can be created and unpacked with ShrinkIt.
.BXY: A NuFX archive within a Binary II envelope. This is the format
      currently required for new uploads to the Apple II libraries of
      GEnie and Compuserve. .BXY files can be created and unpacked
      with ShrinkIt. Although this "envelope within an envelope"
      format may seem redundant, it has several advantages. Ideally,
      the Binary II envelope will be entirely "transparent" to end
      users -- it will be automatically added by telecommunications
      software during uploading, and automatically removed during
      downloading. As more telecommunications programs come to support
      automatic Binary II packing and unpacking, this ideal will be
      increasingly realized. Thus, if your telecommunications software
      supports automatic Binary II unpacking during downloading, you
      can turn this option on when downloading a .BXY file. Doing this
      will give you a downloaded file which is a "bare" NuFX archive.
      Thanks to the Binary II envelope, this file will automatically
      be given the correct name and filetype.

Unpacking an Archive
--------------------
     ShrinkIt starts up with a display of its Main Menu. The options
in this menu are selected by using the arrow keys to highlight an
option and pressing <return>, or by pressing the letter associated
with the option you want.
     When you have downloaded a file with one of the suffixes given
above, you will want to process this file through ShrinkIt to unpack
it and get at the files or disks it contains. It doesn't matter which
of the packing formats your download is in; ShrinkIt will
automatically recognize the format and handle the file accordingly.
     To unpack an archive, you select "O-Open Archive" from the Main
Menu. This will send you to a display called the File Dialog. Similar
File Dialog displays are used for many of ShrinkIt's functions; the
one you see after selecting Open Archive will show the title "Open
Which Archive?" across the upper screen. The File Dialog is used in
this case to select which archive file to "open", or unpack.
     Most of the File Dialog screen is used to display a list of the
files in the currently open folder. On the right side of the screen
are a list of the key-commands you can use at this point:

TAB     to change disk drives.
RETURN  to open a highlighted folder, or open a highlighted file.
ESC     to close the current folder.
OA-.    (Open Apple-period) to cancel this operation.
SPACE   to select a file for opening.

     Below this list of key-commands you will see this notation:

OA-G or RETURN does function
? does tree search

     Thus, if you only want to select a single file in the File
Dialog, you can just press <return> with that file highlighted. If you
want to select several files to be opened in sequence, you can select
the files you want with <space>, and then press either <return> or
OA-G (Open Apple-G).
     The "tree search" function is a very powerful feature which will
be especially useful to hard disk owners. By pressing "?", you will be
sent to a "directory tree display" -- a display of all the folders
within the currently open folder. You can then select the folder you
would like to open simply by pressing the arrow keys to highlight that
folder. Press <return> and you will be back at the File Dialog screen
with your selected folder open. The tree search will not function on
volumes which are on an AppleShare network.
     At the bottom of the "Open Which Archive?" File Dialog, there is
the prompt:

Showing ARCHIVES  (OA-S)

This indicates that ShrinkIt is currently displaying only folders and
files that it has identified as archive files. ShrinkIt uses two
methods to decide whether a file is an archive: It checks the
attributes of the file (its filetype and auxtype), and it checks to
see if the filename has an appropriate suffix. When a file is
downloaded, its attributes may not be preserved through the download.
If your archive doesn't have EITHER the appropriate attributes, OR one
of the suffixes listed above, ShrinkIt won't be able to recognize that
file as an archive. If you don't see your archive file listed (after
you've opened the appropriate folder), try pressing OA-S. The prompt
will change to "Showing ALL FILES (OA-S)", and indeed, the File Dialog
will now show all of the files in the current folder.
     Press <return> to open the archive file you have selected, and
ShrinkIt will display a list of the "items" -- the packed files or
disks -- within that archive. At this point you have to select which
items you want to extract. Usually you will want to extract all of
them, but you have the option of extracting only one or a few. You can
select individual items by pressing <space>, or all of them with OA-A.
     When the items you want are selected, press <return>. Another
File Dialog screen will be displayed, this one entitled "Destination
Folder?" You use this to choose which disk and folder you want to put
the new, unpacked files in. With this variation of the File Dialog,
only folder (DIR) files will be displayed, and the words "<Select
Current>" will be seen at the top of the list of files in each folder
you open. Open the folder you want, and then press <return> with
<Select Current> highlighted. The archived files will now be unpacked
and saved to your disk.
     Occasionally, you may want to have the different files within an
archive unpacked into different destination disks or folders. If you
press OA-<space> to select an item, that item will be unpacked "with
prompting"; before the item is extracted, you will be prompted again
to select a new destination folder for it. You can select ALL of an
archive's items to be extracted with prompting by pressing OA-P.
     If the archive file contains a packed disk (or disks), ShrinkIt
will prompt you to select a "device" (disk drive) for the archived
disk to be unpacked to.

Creating an Archive
-------------------
     As you might expect, creating an archive is somewhat more
involved than unpacking one. However, in many ways the procedure is
similar to unpacking. First you will select "N-New Archive" from
ShrinkIt's main menu. You will be prompted with:

Archive What?
Files   Disk     Cancel

     Archiving files will be examined first. Press <return> with
"Files" highlighted, and you will be sent to the File Dialog display
described above. This File Dialog screen is entitled "Archive Which
Files?" and naturally, is used to select what files you want to
archive. Again, you use <space> to select the files you want, and when
done, press <return> or OA-G to go to the next step in creating the
archive. If you press <space> with a folder (directory) highlighted,
then that folder and all of its contents will be archived.
     When you press <return> or OA-G, yet another File Dialog screen
will appear, this one entitled "Name of Archive to Create?" At the
bottom of this File Dialog screen you will see a prompt for
"Filename:_______________". Using the key-commands described above,
you can first open the disk and folder you want your new archive to be
saved to. Then type in a filename for the archive file you are about
to create. To avoid confusion, be SURE to add the correct suffix to
your filename: Straight NuFX archive should have the suffix ".SHK",
and NuFX-within-Binary-II archives should be suffixed ".BXY". After
entering the filename, press <return>, and the archive will be
created.
     There is one very important point to note at this stage: If you
want the new archive to be a .BXY (NuFX-within-Binary-II) archive, you
must press OA-<return> (Open Apple-<return>), rather than simply
<return> after typing in the filename. There is a brief notation to
the right of the "Filename:" prompt to remind you of this.
     The best way to create a .BXY file is to use ShrinkIt to make a
.SHK file, and then let your telecommunications program add the outer
Binary II envelope during uploading. However, not all
telecommunications programs can do this. ShrinkIt does not allow you
to add new items to a .BXY archive after it has been created. This can
only be done with "bare" NuFX archives. For this reason, if you are
using ShrinkIt to make a .BXY file, you must start out with all of the
files you want to archive in the same folder, so you can select and
pack them all at once.
     If the archive is simple NuFX, you can add a packed file or disk
to it after it has been created. This is done by selecting "A-Add to
Archive" from ShrinkIt's main menu. You will first be prompted to
select the files (or disk) you want to add, and then to select which
archive you want the new items added to.
     To create a new archive from an entire disk, select "N-New
Archive" from the main menu, and then select "Disk" from the "Archive
What?" prompt. Disks to be archived may be either 800k 3.5" or 140k
5.25" disks, and may be ProDOS, DOS 3.3, CP/M or Pascal.  Some
non-standard, "customized" operating systems can also be handled. For
most purposes, creating archives from individual files will be more
efficient, and preferable. Disk packing is intended primarily as a
means of handling data on the older operating systems.

ShrinkIt's Main Menu
--------------------
     The above instructions describe ShrinkIt's two main functions:
creating and unpacking archives. ShrinkIt can perform a number of
other functions, however. This section reviews each of the options
available in ShrinkIt's main menu, in the order in which they are
listed.

Q-Quit:
     Exits you from ShrinkIt and returns you to your program selector.
N-New Archive:
     Create a new archive.
O-Open Archive:
     Open an existing archive to unpack it, or simply to see a list
     of its contents.
A-Add to Archive:
     Add new items -- either packed files or a packed disk -- to an
     existing archive.
C-Catalog:
     Display a catalog of a disk or folder. The folder or disk to be
     cataloged is selected using the File Dialog screen described
     above.
R-Rename Files:
     Allows renaming of files.
X-Copy Files:
     Copy files from one disk or folder to another. After selecting
     this function, two File Dialog screens will appear. The first
     will ask "Copy Which Files?", and the second "Destination
     Folder?"
D-Delete Files:
     Deletes files.
T-Type Files:
     This option allows you to read TXT (ASCII text), AWP (AppleWorks
     Word Processor), and WPF (WordPerfect Word Processor) files. A
     File Dialog is used to select the file or files to be "Typed",
     and then the contents of the file are displayed on-screen.
     Pressing <space> moves you through the file a page at a time;
     <return> will exit you from the current file and display the next
     one you selected (if any). Either <esc> or OA-. (Open Apple-
     period) will return you to the main menu.
/-Create Folder:
     Allows you to create a new folder. A File Dialog is used to
     choose where to put the new folder and what to name it.
F-Format Device:
     Format (initialize) a 5.25" or 3.5" disk. If you are using a IIgs
     and an Apple 3.5 drive, you will be prompted for an option called
     "Fast-Format and Skew 2:1". This is a high-speed disk formatter
     which forgoes a little error checking for the sake of rapidity.
     If you'd rather do a slower, safer formatting, select "Cancel" at
     this prompt.
E-Erase Device:
     Erase the contents of a ProDOS disk.
Z-Zero ProDOS Disk:
     If you are planning to create an archive from a ProDOS disk, you
     should perform this operation on the disk first. It will "zero
     out" all the unused blocks on the disk, making the disk archive
     smaller.
?-About ShrinkIt:
     Displays information about the programmer, gives distribution and
     copyright information, credits those who helped out, and displays
     a list of "short cut keys".

Key-Commands and Short Cut Keys
-------------------------------
     This section describes the key-commands which are available
within many of ShrinkIt's functions. Some of them have been referred
to before. A few of these commands are needed to perform certain of
ShrinkIt's operations, while others are just short cuts or alternate
ways of doing things. This list does not include those key-commands
whose function is explained by on-screen prompts in the File Dialog
displays.

OA-up arrow and OA-down arrow: In the File Dialog, the arrow keys
together with Open Apple will move you through the file list quickly.

OA-A: Select all files in the open folder, or all items in the open
archive.

OA-<space>: Select an archive item to be extracted (unpacked) with
separate prompting for a destination folder.

OA-P: Select all items in an archive to be extracted with prompting.

OA-E: In the File Dialog, eject the current 3.5" disk.

OA-O: In the File Dialog, display a list of online volumes.

/: In the File Dialog, instead of selecting a pathname by opening the
correct disk and folder(s), you can also type it in; just press "/" to
start the full pathname. If you type the pathname of a folder, that
folder will be opened and displayed in the File Dialog. If you type
the full pathname of a file, the operation you have selected (Type,
Open Archive, etc.) will be performed on that file.

U: If, for some reason, you want to archive a file without compressing
it, you can do so by pressing "U" to select it instead of <space>.

OA-U: You can select all of the files in the open folder to be
archived without compression by pressing OA-U.

OA-B: When scrolling through the list of items in an open archive,
this will send you to the beginning of the list. When "Typing" a file,
OA-B sends you to the beginning of the file.

 .: At most points in ShrinkIt, you can simply press "." (period) to
cancel an operation, rather than OA-. (Open Apple-period).

ShrinkIt for the ][+ and unenhanced //e
---------------------------------------
     As mentioned earlier, if you are using an unenhanced //e or a
][+, you will have to use alternate versions of ShrinkIt. ShrinkIt for
these machines is broken up into two programs: IIPLUS.SHRINKIT for
creating archives and IIPLUS.UNSHRINK for unpacking archives. To an
extent, the above instructions apply to the IIPLUS ShrinkIts, but
there are some important differences.
     In general, the IIPLUS ShrinkIts are simpler than the standard
version. The 40 column screen is used, so the on-screen information is
minimal. None of the utilities, such as copying files, are available;
these programs only create or unpack archives.
     The Open Apple (OA) key is not used. Some of the OA key commands
are replaced with Control key commands, but others, such as OA-A
(select all) are not implemented. To select an archived file to be
extracted with separate prompting, press "P" (instead of OA-<space>).
     In the File Dialogs of the IIPLUS ShrinkIts, instead of pressing
<esc> to close the current folder, you must press <return> with the
words "Parent Directory" highlighted.


For More Technical Information...
---------------------------------
     If you want to know more about data compression:

Bell, T., Cleary, J., and Witten, I. Text Compression.  Prentice-Hall, 1990.
ISBN 0-13-911991-4

Ziv, J. and Lempel, A. A Universal Algorithm for Sequential Data
Compression. IEEE Trans. Information Theory, Vol. IT-23, No. 3, May
1977, pp. 337-343.

Ziv, J. and Lempel, A. Compression of Individual Sequences via
Variable-Rate Coding, IEEE Trans. Information Theory, Vol. IT-24, No.
5, Sept. 1978, pp. 5306.

Storer, James A. Data Compression: Methods and Theory. Computer
Science Press, 1988.  ISBN 0-7167-8156-5.

Held, Gilbert. Data Compression, Techniques and Applications, Hardware
and Software Considerations.  John Wiley & Sons, 1987

Welch, T. A Technique for High-Performance Data Compression. IEEE
Computer, Vol. 17, No. 6, June 1984, pp. 8-19.

If you want to know more about the NuFX ("nu-eff-ex") archive format,
please consult the Apple Filetype Technote for $E0/$8002.


Trademarks
----------
Apple, Apple II, IIgs, GS/OS, and ProDOS are registered trademarks of
Apple Computer Inc. America Online, ACU and AppleLink are registered
trademarks of Quantum Computer Services. ShrinkIt is a trademark
of Andrew E. Nicholas.

