 
SHRINKIT FOR THE APPLE IIGS

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, America-Online: shrinkit
           Compuserve: 70771,2615
             Internet: shrinkit@apple.com
Note: In online discussions, GS-ShrinkIt is often abbreviated "GSHK".

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

What is GS-ShrinkIt?
--------------------
     GS-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. This is usually done
to prepare the files/disks for transmission via modem, or for storage
purposes. Thus, an archive file, whether created with GS-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.
     GS-ShrinkIt uses a highly efficient compression algorithm known
as dynamic LZW, and creates archive files with a format called NuFX.
GS-ShrinkIt and the 8-bit version of ShrinkIt are currently the
standard archiving utilities for Apple II telecommunications.
GS-ShrinkIt can unpack files which have been archived with
GS-ShrinkIt, as well as those which have been packed with certain
other Apple II file-packing utilities, such as BLU and ACU. One of
GS-ShrinkIt's most exciting features is that it can also unpack a
variety of non-Apple II archives. This will be discussed in more
detail later in these instructions.

About These Instructions
------------------------
     Most users of GS-ShrinkIt will be interested in unpacking files
that 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 GS-ShrinkIt to unpack archives, and then how to create a
new archive file. Then I will give an explanation of each of the
options available in GS-ShrinkIt's pull-down menus. If you are ONLY
interested in how to unpack a file which you have downloaded, you can
read as far as the end of the section entitled "Unpacking an Archive",
and skip the latter sections. 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
-------------------
     GS-ShrinkIt requires a IIgs with System Disk 5.02 or later, and a
minimum of 768K of RAM. If you are using a GS/OS program launcher
other than the Finder, it's possible that your system (boot) disk
doesn't have an "Icons" folder. GS-ShrinkIt requires that you have
this folder on your system disk, and that it contain (at least) the
file "FType.Main".

GS-ShrinkIt and ShrinkIt
------------------------
     GS-ShrinkIt is (of course) for the Apple IIgs. There are also
versions of ShrinkIt available for 8 bit Apple II's. Archives created
with GS-ShrinkIt can be unpacked with version 3.0.3 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.

Distribution and Copyright Info
-------------------------------
     GS-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.

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"). The following is a list 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. GS-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 GS-ShrinkIt) files within a Binary II envelope.
      Created with the utility BLU, these files can be unpacked with
      GS-ShrinkIt.
.QQ:  If you remove the Binary II envelope from a .BQY file, the
      squeezed files it contains will have the suffix .QQ. These files
      can be unsqueezed with GS-ShrinkIt.
.ACU: The archive format used by America Online (formerly
      AppleLink Personal Edition); these files can be unpacked with
      GS-ShrinkIt. (America Online currently uses .SHK format for new
      uploads.)
.SHK: NuFX format; can be created and unpacked with GS-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 GS-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 wrapper, this file will automatically be
      given the correct name and filetype.

Unpacking an Archive
--------------------
     GS-ShrinkIt uses the standard Apple Desktop interface commonly
found in IIgs programs, with the familiar pull-down menus and dialog
boxes.
     When you have downloaded a file with one of the suffixes given
above, you will want to process this file through GS-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; GS-ShrinkIt will
automatically recognize the format and handle the file accordingly. To
unpack an archive, you select "Open Archive..." from the "File" menu.
This will give you an "Open which Archive?" file-selection dialog box.
In addition to the usual "Disk", "Open", "Close" and "Cancel" mouse
buttons, there are also two radio buttons labeled "Show Only Archives"
and "Show All Files". GS-ShrinkIt uses two methods to decide whether a
file is an archive file: 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 a suffix that GS-ShrinkIt recognizes,
GS-ShrinkIt won't be able to identify that file as an archive. If you
don't see your archive file listed in the window (after you've opened
the appropriate folder), try clicking the "Show All Files" button.
     (A bug in System 5.0.2 sometimes causes the file dialog to hang
if it can't find a disk which it expects to be online. To avoid this,
you should only swap disks in your drives AFTER the file dialog is
on-screen.)
     When you click the "Open" button with your file highlighted, a
window will be displayed showing what type of archive file you have
selected, and listing the "items" (the packed files or disks)
contained within the archive. This window will also show several
buttons: "Extract", "Info", "Delete", "Sort", "Add Files", and "Add
Disk". If you simply want to unpack this archive, only "Extract" and
"Info" need concern you.
     If the archive is NuFX format, there may be a brief message
included within the archive by the person who put it together and
uploaded it. Items which have space set aside for an attached message
will have a small document icon to the right of the item's name. If
there is an actual message, this icon will be yellow; if the message
space is blank, it will be gray. You can read the message by
highlighting the item and then clicking the "Info" button. This will
display a window with various pieces of information about that item,
and the message text, if there is any.
     To unpack an archive, you must first highlight those items which
you want to extract. Usually you will want to extract all of the items
listed, but you also have the option of extracting only one or a few
items. To highlight all of the items, press Apple-A. You can select
several individual items by holding down the Apple key while you click
on those items you want. You can select a group of items by holding
down the shift key and clicking on the first item in the group you
want, and then on the last of the group.
     When the items you want are highlighted, click the "Extract"
button. Another file-selection dialog box will be displayed allowing
you to choose which disk and folder you want to put the new, unpacked
files in. Open the appropriate folder, and click the "Accept" button.
If there is a file in the folder with the same name as the file you
are about to unpack, GS-ShrinkIt will ask if you want to overwrite the
existing file, rename the unpacked file, skip that file, or cancel.
You can set GS-ShrinkIt to automatically overwrite any existing
same-name files by turning off the "Prompt before overwriting" check
box which appears in the file-selection dialog.
     If the archive file contains a packed disk (or disks),
GS-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, the process is quite
straightforward.
     If you are going to be archiving files (rather than a disk),
select "New File Archive..." from the "File" menu. A file-selection
dialog box will be displayed, allowing you to select the files to be
archived. There are two check boxes in this file-selection dialog box;
these let you choose whether to "Use Compression" (usually you will
want to compress the files you archive) and to "Delete after
archiving".
     As when selecting items to be extracted from an archive,
GS-ShrinkIt gives you several ways to highlight files in this dialog
box. You can select all the files in the open folder by clicking the
"Select all" button, you can select several individual files by
holding down the Apple key while you click files, and you can select a
group of files by holding down the shift key and clicking on the first
and last files of the group.
     When the files you want to archive are highlighted, click the
"Accept" button. A new file-selection dialog box will appear,
prompting you for a "Destination Name" -- a filename for the archive
file you are about to create. After opening the disk and folder you
want your archive to be saved to, enter a name for the archive in the
text box. To avoid confusion, be sure the filename has the correct
suffix: Straight NuFX archive should have the suffix ".SHK", and
NuFX-within-Binary-II archives should be suffixed ".BXY". After
entering the filename, press <return> or click the "Save" button, and
the archive will be created.
     There is a check box in the "Destination Name?" dialog box
labeled "Save as '.BXY' file". This box must be checked if you want
your archive to be saved to disk in the NuFX-within-Binary-II format.
     The best way to create a .BXY file is to use GS-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. GS-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 GS-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.
     After creating a new archive, you can perform a number of
operations on it. You can delete items, you can add a file or disk
item (provided the archive isn't a .BXY file), you can sort the
archive to change the order in which its items are listed, and you can
add a short message to the archive to be read when the "Info" button
is clicked. All of these operations are performed via the "Open
Archive..." option in the "File" menu; that is, you must first select
and open the archive, just as you would if you were going to unpack
it.
     To add a message, or "comment" to an archive, you first highlight
the top item listed in the archive, and then click the "Info" button.
Enter the text of your message in the lower half of the "Info on Item"
window, and then click the "Update" button in that window.
     The other operations are performed by clicking the appropriate
buttons in the Open Archive window. The various options for sorting
items within an archive can be set in the "Preferences" dialog box,
selected from the "Special" menu. This will be described later. The
sorting operation requires an amount of free disk space equal to the
size of the archive file. If GS-ShrinkIt doesn't find sufficient space
on the currently open disk, it will report the problem and abort the
operation.
     To create a new archive from an entire disk, you would select
"New Disk Archive..." from the "Disk" menu. Disks to be archived may
be ProDOS disks, or they may use other operating systems, such as DOS
3.3, CP/M or Pascal. Some non-standard, "customized" operating systems
can also be handled. Unfortunately, due to a bug in the IIgs 5.0.2
System Disk, GS-ShrinkIt disk-archiving only functions correctly with
3.5" disks and ProDOS 5.25" disks; non-ProDOS 5.25" disks cannot be
archived or unpacked. To archive or unpack 5.25" disks, you will have
to use the 8 bit version of ShrinkIt.


Pull-down Menu Options
----------------------
     The above instructions give a fairly thorough overview of
GS-ShrinkIt. This section provides a list of each of the options
available in GS-ShrinkIt's pull-down menus. This will serve as a
reference section to the instructions, and will also fill in some
details not dealt with above.

"Apple" Menu:
     About ShrinkIt...
        Information about the programmer, distribution & copyright
        information, addresses for user support, thanks to those who
        helped out.
     Your NDA's are also under this menu.

File Menu:
     New File Archive... (Apple-N)
        Create a new archive (from files).
     Open Archive... (Apple-O)
        Open an existing archive to unpack its contents or to modify
        it.
     Close (Apple-W)
        Close the active window.
     Delete...
        Delete files from your disks.
     Quit (Apple-Q)
        Exit from GS-ShrinkIt.

Edit Menu:
     Undo
     Cut
     Copy
     Paste
     Clear
        These are provided for use when editing an archive message,
        and for possible use by NDA's.
     Select All  (Apple-A)
        Select all files in the displayed folder, or all items in
        the displayed archive.

Disk Menu:
     New Disk Archive... (Apple-D)
        Create a new archive from a disk.
     Erase...
        Erase the contents of a disk.
     Format...
        Format a disk. Due to a quirk in the ROM 03 IIgs firmware, the
        Format option will not work on this machine.

Special Menu:
     Create AppleSingle...
        AppleSingle is a relatively simple file-packing format
        designed by Apple, Inc. to provide a means by which extended
        GS/OS files can be handled on "foreign" file systems (such as
        ProDOS 8). AppleSingle files can only contain one file, and
        don't use any compression. Because NuFX archives are also
        able to store extended GS/OS files, and have many other
        capabilities as well, most users will have no need for this
        option. GS-ShrinkIt can also unpack AppleSingle files, and
        AppleSingle within Binary II files.

     Preferences...
        This option puts up a dialog box with several check boxes and
        pop-up menus, allowing you to set a number of parameters.
        These settings will be saved in an "invisible" file called
        "ShrinkIt.Prefs" in the folder containing GS-ShrinkIt.
        The check boxes are as follows:
        Show invisible files
           Show invisible files (such as "Finder.Data") in
           file-selection displays.
        Prompt on every extraction
           When multiple items are selected for extraction from an
           archive, you will be prompted to select a new disk and
           folder for each file before it is unpacked.
        Force extracted names to fit ProDOS
           When extracting a file from one of the "foreign" archive
           formats (see below), the name of the file may not fit
           ProDOS's rules for filename syntax. With this box checked,
           GS-ShrinkIt will automatically modify such a filename to
           make it legal. If the box is unchecked, you will have to
           modify such filenames manually.
        Use sessions when archiving
           "Sessions", also referred to as "cache-deferred writes",
           are a feature of GS/OS which can save considerable time
           with disk-intensive operations, such as creating large
           archives. With "Use sessions" selected, the new archive
           will be saved in memory until the entire archive-creation
           process is completed (or until memory runs out). Then it
           will be written to disk. A disadvantage of using sessions
           is that it uses up memory which GS-ShrinkIt may need for
           its file compression process.
        Use sessions when extracting
           This option corresponds to "Use sessions when archiving"
           above, but enables the use of sessions when an archives are
           being unpacked.
        Attach suffix when archiving
           With this box checked, GS-ShrinkIt will automatically add
           the appropriate suffix -- either ".SHK" or ".BXY" -- to the
           default archive name it offers you.

        To the right of these check boxes there are eight labels
        with pop-up menus; the titles of these menus are:
        Sort by:
           This allows you to set how the items in an archive will
           be sorted when you click the "Sort" button. The choices
           are:
              Name (Alphabetical order)
              Length (Of the uncompressed file)
              Percent Size (How much the file was compressed)
              Date Archived
              Filetype
              Auxtype
        Sort order:
              Ascending
              Descending
        Comment size:
           This lets you set the maximum size of the comment that
           can be added to an archive; the choices are:
              100 Bytes
              200 Bytes
              400 Bytes
              800 Bytes
              1000 Bytes
        Add Comment to:
              First File
              All Files
           With First File (the default), a message can only be
           attached to the first item in an archive. This menu
           gives you the option of adding comments to all of the
           items.
        Archive As:
              Hierarchy
              Flat File
           It is possible to select a folder for archiving with
           GS-ShrinkIt. When you do this, the entire contents of that
           folder (including the contents of any folders within the
           folder you selected) will be archived. Normally, when this
           archived folder is unpacked, GS-ShrinkIt will first create
           the folder that was archived, and then extract the folder's
           contents, placing them within the new folder. By changing
           the "Archive As:" preference from "Hierarchy" to "Flat
           File", you can change this procedure. A "Flat File" archive
           will only contain the contents of any selected folders; it
           will not contain the folders themselves. Thus, when this
           archive is unpacked, no new folders will be created, and
           the archived files will simply be placed "flat" in whatever
           disk and folder you selected.
        Extract As:
              Hierarchy
              Flat File
           This option corresponds to the "Archive As:" preference
           above, but it controls how an archive is extracted, rather
           than created. With "Flat File" selected here, an archive's
           contents will be extracted "flat", with no new folders
           being created, even if that archive contains one or more
           folders.
        Save ARC Files As:
              Binary
              Text
        Save ZOO Files As:
              Binary
              Text
           "ZOO" and "ARC" are two "foreign" archive formats supported
           by GS-ShrinkIt; this is discussed in more detail below.
           These two options in the Preferences window allow you to
           set how files which GS-ShrinkIt extracts from these
           archives will be saved on your disk. The ZOO and ARC
           archive formats don't include any internal information that
           GS-ShrinkIt can use to determine what type the files should
           be when they are extracted, so the user has to make this
           decision.


"Foreign" Archive and Compression Formats
-----------------------------------------
     This part of the instructions was left for last because it's a
little technical. However, you shouldn't feel too intimidated even if
many of the terms used here are unfamiliar. The "short version" of
this section is simply this: Thanks to the remarkable versatility of
GS-ShrinkIt, IIgs users can now unpack MOST of the files found in MOST
of the download libraries of the online services. Whether these files
are for Macs, Atari STs, Amigas, IBM PCs, or Unix systems, there is a
good chance that GS-ShrinkIt will be able to unpack them. Although
programs which were written for these other computers will not run on
a IIgs, such things as text files, programmer's source code and
graphics files (which can be converted for IIgs viewing with utilities
such as SHR.Convert) CAN be used on the IIgs. It's probable that
certain other types of non-IIgs files will become usable on the IIgs
in the future. The wide range of formats supported by GS-ShrinkIt make
it the most versatile archiving utility available for ANY personal
computer. So take advantage of this and go exploring in those other
libraries!
     What follows isn't intended to be a complete description of the
archiving and library standards used by these various other computers.
It only presents the salient points of using GS-ShrinkIt with the
archive formats it supports. The "foreign" (non-Apple II) formats
supported by GS-ShrinkIt are:

StuffIt (Used on the Macintosh)
ZOO (Used on the IBM PC, Amiga and Atari ST)
ARC (Used on the IBM PC, Amiga and Atari ST)
Compress (Used on computers running the Unix operating system)

StuffIt:
     GS-ShrinkIt can extract files from StuffIt archives, sort them,
     and delete items from them. Encrypted items can not be extracted,
     nor can HFS folders within other folders. Such items will be
     dimmed in GS-ShrinkIt's display. StuffIt archives within
     MacBinary I or II "envelopes" are supported, as are StuffIt
     archives from America Online.
ZOO:
     ZOO archives can be opened and their contents extracted with
     GS-ShrinkIt. ZOO archives can't be sorted or items within them
     deleted, however.
ARC:
     GS-ShrinkIt's unpacking of ARC archives works only for those
     created with ARC 5.0, not ARC 6.0, which are less common. Some of
     the types of compression used in ARC files are not supported, and
     archive items using these methods will appear dimmed. Sorting and
     deleting of ARC items is not supported.
Compress:
     GS-ShrinkIt should be able to unpack all types of Unix Compress
     files.

     Two fairly common archive formats which are not currently
supported by GS-ShrinkIt are ZIP and LHArc (LZH). These formats are
used on IBM PCs and other machines.

Table of Supported Formats
--------------------------
     For reference purposes, the following is a table showing all of
the file packing formats supported by GS-ShrinkIt:

Format                          |Filename
                                |Suffix
                                |      |[C]reates and
                                |      |Unpacks, or
                                |      |[U]npacks Only
                                |      |   |
                                |      |   |Computer(s) Which
                                |      |   |Use This Format
--------------------------------|------|---|--------------------------
NuFX . . . . . . . . . . . . .  | .SHK | C | Apple II
NuFX in Binary II . . . . . . . | .BXY | C | Apple II
Binary II . . . . . . . . . . . | .BNY | U | Apple II
Binary II in Binary II. . . . . | .BNY | U | Apple II
ACU (Used on America Online) . .| .ACU | U | Apple II
ACU in Binary II . . . . . . .  |  --  | U | Apple II
SQ (BLU) . . . . . . . . . . .  | .QQ  | U | Apple II
SQ in Binary II (BLU) . . . . . | .BQY | U | Apple II
AppleSingle . . . . . . . . . . |  --  | C | Apple II
AppleSingle in Binary II . . .  |  --  | U | Apple II
StuffIt . . . . . . . . . . . . | .SIT | U | Macintosh
StuffIt in MacBinary I or II. . | .SIT | U | Macintosh
StuffIt from America Online . . | .SIT | U | Macintosh
Zoo . . . . . . . . . . . . . . | .ZOO | U | IBM PC, Amiga, Atari ST,
                                |      |   | Unix systems
ARC . . . . . . . . . . . . . . | .ARC | U | IBM PC, Amiga, Atari ST
Compress . . . . . . . . . . .  | .Z   | U | Unix Systems


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

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

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

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, ProDOS, Finder and Macintosh are
registered trademarks of Apple Computer Inc. ACU and AppleLink are
registered trademarks of Quantum Computer Services, Inc. America
Online is a registered service mark of Quantum Computer Services Inc.
StuffIt is a registered trademark of Aladdin Systems, Inc. and Raymond
Lau. ARC is a registered trademark of System Enhancement Associates,
Inc. Unix is a registered trademark of AT&T. ShrinkIt is a trademark
of Andrew E. Nicholas

