

NuPak IIgs
 Version 2.0 [ February 25, 1990 ]
Documentation File: Revision Three

        NuPak IIgs(tm) is an innovative creation in packing utilities.  Nupak IIgs offers the ability to pack and unpack not only ShrinkIT(tm) type files, but files in several other formats as well. However, the biggest advantage of Nupak IIgs is the ability to pack files with resource forks. With the onset of GS/OS(tm) 3.0, files containing both resource and data forks will become more prominent. Programs utilizing this format are following a format found in most Macintosh programs. Such programs already exist on the IIgs--most notably the CDEV files found on the IIgs System Disk and this program. Until now, there has not been a way to pack files with resource forks. One had to pack a whole disk in order to send any file with a resource fork--that is, until NuPak IIgs.  Now you will be able to pack single files and send them like any other file.

        NuPak IIgs is a full fledge 16-bit packing and unpacking program, running under GS/OS, that follows the human interface guidelines. It therefore offers an easy to use substitute for the myriad of archival programs for the Apple II series (as well as for other computers). Although, the main focus of NuPak is on NuFX(tm) archives such as those created by ShrinkIT.

        Another ability that makes NuPak unprecidented, is the promise of accessing on other operating systems when FSTs become available. It currently supports AppleShare(tm) network file servers. However, what sets NuPak off from the rest is its ability to unpack Macintosh files compressed with StuffIT(tm), the most widely used Macintosh archival program. This can be done without waiting for Apple's FSTs.

        Comments, suggestions, enhancements, and/or bug reports can be sent to the author on America Online(tm), on Internet, or via US mail.  See the end of this file for additional information.


Notes Version 2.0
_________________

        This is it folks, version 2.0!  I decided to jump the major version number because I've added along awaited feature...StuffIT support!  This program can now handle Macintosh "StuffIT" archives, with either a 32-byte header (from downloading the archives from America Online) or a 128-byte Macbinary header (used on BBSs).

        Another major development is speed.  Version 2.0 has had its decompression routines totally reworked and enhanced.  The old slowness of version 1.x is no more.

        I have changed the user interface in a few places to be more friendly.  The most major change is at points where the user is prompted to enter a device name.  All such dialogs have been replaced with a standard dialog window allowing the selection of a device from a displayed list of available devices.  This prevents the user from having to memorize the exact names of devices.

        I have also added the "View Help File" option.  This option brings up a help window containing the quick-help list describing the menu options in minor detail.

        Version 2.0 also supports User Preferences and the creation of Binary II files, a very useful option for users of services such as CompuServe and GEnie which want Binary II headers on uploaded files.

Ghost of Features Present
_________________________

        Here is a listing of what Version 2.0 can do:

o Extract files from NuFX, Binary  II, ACU, BXY, and StuffIT archives.
o Uncompress records in the above archive formats if they are packed with         Huffman, Dynamic LZW, or RLE compression.
o Add files to an archive in uncompressed format to NuFX archives, including      resource forked files.
o Unpack whole disks from a ShrinkIT archive.
o Add Binary II headers to files for uploading to information services such as    America Online, GEnie(tm), and CompuServe(tm).
o Standard disk operations (delete, rename, format, and erase).
o Save User Preferences such as compression mode and default pathname for   extraction

Ghost of Features Yet to Come
_____________________________

        The following features are planned for versions in the near future:

o Actually compress files while adding, using Huffman or Dynamic LZW.
o Add messages while adding files to NuFX archives.
o Display messages that are in NuFX archives.
o Add whole disks to NuFX archives.
o Work with even more archive types (Arc, Zip, Zoo, etc...).
o A mini-editor for composing quick text messages.

        Please do drop me a letter on America Online, on Internet, or by US Mail, especially if you find bugs.  I wish to incorporate features YOU want, so I have to be informed.  I also can't test the program in every possible machine configuration or situation, so there may be rare bugs that have yet to crop up.


Getting Started
_______________

        This program needs System Disk 5.0.2 or higher to run correctly.  If you don't have the necessary system disks, try to download them from America Online or goto your local user group to obtain them. You might also want to see your local dealer and obtain a copy.  Most dealers should let you copy it, or you can buy the three-disk set with manuals for around $40.

        Start by copying the program to where you want it.  It will run on any GS/OS-compatible device, including 3.5" and 5.25" drives, hard drives, and AppleShare file server volumes.  You absolutely *MUST* use the Finder or another GS-based copy program, since the program does have a resource fork and cannot be copied by a ProDOS 8 program.

        Please note that the NuPak IIGS program cannot be "locked" or write-protected in any way. This is because NuPak writes back to itself to save the user preferences.  If you forget and accidently lock or protect the file, NuPak IIGS will kindly tell you this and exit back to your program launcher.


Quick Help List
_______________

        After running the program from the Finder(tm) or another program selector, the NuPak IIgs desktop will pop up and the File, Edit, Archive Options, and Special menus will appear.

    Note that currently unavailable options are marked with "[ N/A ]".

**** The menu underneath the Apple contains 2 options:

"About NuPak IIGS" will bring up a series of dialogs showing some info about who contributed to this program, as well as version number you are using.

"View Helpfile" opens a window in which you can view the miniature help file.  If the help window is already open, this option brings it to the front.

 (these are followed by any NDAs you have installed.)

**** The File Menu has several options:

"New" will create a new NuFX archive, allowing you to select its filename and location before it is created.  Any current archives are not closed.

"Open" will allow you to select a file, which is then opened as an archive.  NuPak will automatically figure out what type of archive it is.  If it can't figure out what the file format is, it will tell you so.  Any current archives are not closed.

"Save" and "Save As" aren't used and are for future use.

"Close" will close the currently active window, be it an NDA, archive window, or whatever.  If it is an archive window, the archive file is closed and any data buffered in memory is flushed to disk.

"Delete" allows you to select a file, which is then deleted.  You are asked to confirm before the file is actually destroyed.

"Rename" will let you rename a file you select.  You can change the entire path of the file, even move it between directories!  The only restriction is that you cannot move it across volumes.  You select the file and can then edit its full pathname.  The option is abortable.

"Format" lets you format a disk.  NuPak will display a list of devices from which you select the device to format.  You also enter the volume name to use in formatting the disk.  NuPak then tells GS/OS to format the disk.

"Erase" is just like Format, except it simply writes a new volume directory to the disk without reformatting it.

"Page Setup" and "Print" do nothing.

"Quit" will quit back to the program selector.

**** The Edit menu has only one option used by NuPak.

"Select All" will automatically highlight all files in the currently open archive with.  If there is no archive open, or if the currently highlighted window is not an archive (ie, an NDA is in use), nothing will happen.

**** The Archive Options menu contains four options:

"Extract Records" will extract whatever records you have hilighted in the archive window.  You are prompted first for a disk or directory to extract to.

"Add Records" allows you to add files to *NuFX* archives.  You select the file or files to add, and then select message information.  The files are then added to the current open archive, using the compression method selected under User Preferences.

"Delete Records" is not functional as of yet and therefore dimmed.  In the future it may be possible to delete records within a NuFX archive.

"Rename Records" is not functional as of yet and therefore dimmed.  In the future it may be possible to rename records within a NuFX archive.

**** The Special Menu contains four options:

"Set Preferences" will allow you to configure NuPak for your own personal tastes.  You can select compression method (for use when adding to archives) and the default pathname for use in extracting.  These options are saved and will be set each time you run NuPak IIgs.  Note that the only compression method currently available is "uncompressed", and all other compression options are dimmed and cannot be selected.

"Make Binary II file" will allow you to make a Binary II file from a specified file.  You specify the source file and a destination filename, and a Binary II archive is created using the specified destination filename and containing the selected source file.

"Make AppleSingle File" will allow you to take a selected file (of any type) and make it into an AppleSingle format file [ N/A ].

"Make AppleDouble File" is the same as above, but produces its output in AppleDouble format [ N/A ].

        Now that you have a brief knowledge of the menu options, let's talk about some other basic operations.


Working with Archives
_____________________

        After you select an archive with "Open" (or make a new one with "New"), a window will appear on the screen.  The title is the filename and is followed by the type of archive, such as "MyArchive (NuFX)".  You can have more than one archive open at once also.  If you have multiple archives opened, simply click in the window of an archive to select it as the current archive.  The current archive always has its window hilighted.  Note that there doesn't have to be a current archive; an NDA can be the currently active window instead of an archive window.

       Inside the window is a general information line right below the title. It shows the creation and modification dates of the archive, and the number of files in the archive.  If the archive doesn't supply one of the dates, that field is dashed out.  The other is a list control showing all the files in the archive and some information on each one.  Generally it will show filename, filetype, auxtype, date when it was archived, size of the file, compression method, and how much it is compressed in percent.  A scrollbar in the window allows you to scroll if there are more than 12 files.

        The listing operates like this: if you click on a name, you select it and deselect all others.  Dragging the mouse drags the selection bar.  If you reach the top or bottom, the listing scrolls automatically. There are, however, two keys that modify the way you select items.  Holding SHIFT down will select a "range" of records.  For instance, if you clicked the first file, then held down shift and clicked a file 7 lines down, all files in between those, including the ends, are selected.  So you would select seven records with only two clicks.  And if you hold down OPEN-APPLE, clicking on a record will select that record but other records will NOT be deselected.  The best way to learn this is to try it first hand by opening a big archive if you have one.

        Once you select your files, you then select what to do with them.  Currently the only thing you can do is "Extract" files from the archive (Open-Apple-E on the keyboard), although in the future you may be able to rename or delete files within the archive.  After selecting extract, if any of the records to extract are files, you are asked to select a destination pathname (If you have a default pathname set up in the Preferences [see "Misc Options" section], this will be the initial location pointed to in the window).  Choose the volume using the Disk button.  This can be any writeable device, be it a floppy, hard disk, or file server volume.  Next, use the Open and Close buttons to move into the desired subdirectory on the volume.  Note that double-clicking a directory also opens a it.  After selecting the destination pathame, you can either click the "Cancel" button to abort extraction, or click the "Extract" button to continue.

        When extracting disk records from an archive, NuPak displays a window from which you select the destination device for the disk record.  The window contains three controls.  The first two are buttons, the default button (selected by clicking it or hitting RETURN) is "Continue".  The second is "Cancel", which must be clicked to be selected.  The third control is a list of devices from which you select a destination device.  Up to five names are displayed at once; if there are more than five, you can scroll the listing to display the extra devices  NuPak automatically makes sure you extract onto a device of the proper type to hold the disk record.  If the device cannot accept the record, you are given another chance to select a device.

        The program begins the extraction process and a status dialog is placed on the screen which will show the filename being extracted and the status using three "thermometers".  The top thermometer is labeled "Data Fork", and fills up red as the data fork of a file (or a disk) is written out.  The middle thermometer is labeled "Resource Fork" and fills up with the color blue as the resource fork of a file is extracted.  Many files do not have resource forks, and disks never do, so you probably will not see it fill very often. The final thermometer is labeled "Message" and it will fill up with the color yellow as each message is loaded into memory for you to look at.  Finally, there is a "Cancel" button you can click which will abort extraction, but only between records (you cannot currently abort in the middle of extracting a single file or disk).

        Several things can interrupt extraction.  Errors that abort extraction include GS/OS errors (such as volume full or I/O error), unknown thread types in NuFX archives, and Out of Memory errors. If a compression method is encountered that NuPak can't handle, it will ask you what to do.  You can either continue and extract the file to disk (so that you may use another program to decompress it), or skip that file.  If a file being extracted already exists, you are given the option to skip that file, extract to a different filename (N/A), or delete the old file.  And if messages are encountered in a NuFX archive, you are asked at each message if you want to view it, save it to disk, or both.  Note that any records that NuPak never attempted to extract (if you abort or if an error aborts the extraction) are not deselected when the extraction process ends.

        There are two messages that can be displayed during or after extraction of a record.  The first message can appear anytime during uncompression, it is a "Data Damaged" message.  This means that the data is seriously damaged and Nupak cannot continue uncompressing reliably.  This error will abort the extraction process.  The second error occurs at the end of extracting a record.  It tells you that the "CRC of the data does not match".  NuFX archives have several checks for damages, called CRCs.  NuPak always calculates CRCs on its own and makes sure they match those stored in the archive.  If they don't match, then the data is damaged.  This error is not serious enough to abort extraction, and NuPak will continue to the next record.  Text files or pictures may be intact enough to warrant keeping, but a program file will very likely not run correctly.

        When all records have been extracted, you will see an "Operation Completed" message.  You can click the Continue button or just press Return, and you will be returned to the "normal mode" of the program, ready to open new archives, add, or whatever you wish.


Adding to an Archive
____________________

        NuPak IIGS also offers the ability to add files to NuFX archives.  In the future it will also be possible to compress files as they are added, as well as add whole disk to an archive.

        Adding is functionally similar to extracting.  After opening the NuFX archive to add to, select "Add" (or OA-A from the keyboard).  You will be presented with a dialog where you can select files to add.  The Disk, Open, and Close buttons function normally.  To select files to add, use the mouse button and the SHIFT and OPEN-APPLE keys as outlined in the previous sections.  When finished selecting, click Accept to continue or Cancel to abort.

        After selecting your files to add, you are next asked to select any message types to add.  Since this is not yet completed, just click "Do It" to continue.

        From here on the adding process is just like extracting.  The status window has three thermometers that fill up as the files are added, and errors behave the same way as in extraction.


StuffIT Support
_______________

        Version 2.0 of this program offers support for StuffIT archives, which is pretty much the standard for the Macintosh, on BBSs and on America Online.

        NuPak IIgs can handle StuffIT archives in two formats.  The first is the archive with a 32-byte header.  This format is used when downloading the archives from America Online using the Apple II (or IIGS) version of the program.  The other is the archive with a 128-byte Macbinary header.  You will find archives this way on local BBSs and on other information services.  Please note, however, that the format of the archive is transparent to you; the program senses automatically and adjusts itself.

        Extracting from StuffIT files is very much like normal extraction procedures with a few minor changes:

        o Filenames are converted to ProDOS format IF NEEDED.  Which means
          if an HFS FST becomes available, you can unpack right to an HFS
          disk with no filename translation.
        o Directories in an archive don't list the contents of the folder,
          only the folder itself.  The folder's size will be the size of
          all its contents.  Extracting the directory extracts everthing
          inside as well.
        o Filetypes are translated if necessary into ProDOS filetypes.  As
          of this writing, the following HFS filetypes are converted:

                        "TEXT" becomes "TXT"
                        "APPL" becomes "S16"
                        "CDEV" becomes "CDV"
                        "SIT!" becomes "LBR", subtype $0000
                        "PIT!" becomes "LBR", subtype $0000

          All other filetypes are extracted as "BIN" files.

        o At this time the date IS NOT PRESERVED during extraction.  When
          I get info on the date format on the Mac I'll fix this.

        If you experience any problems with unStuffing, PLEASE TELL ME!  This has never been done on an Apple IIgs (or any other Apple II) before, and I'm not an expert on Stuffit archives.

Miscellanous Options
____________________

Format/Erase:

        These two options allow you to format or erase a disk.  Formatting physically reformats a device, while erasing simply erases the main directory and makes the disk look fresh, but doesn't physically reformat (meaning the data is actually still on the disk).  Both options work the same way.  NuPak will display a window (almost exactly like the window when extracting a disk from an archive) with four controls in it.  The first two are "Continue" and "Cancel" buttons.  They are pretty self explanatory, but you should know that hitting RETURN selects "Continue" by default.  You still have a second chance to cancel after that though, so don't get excited if you mess up.

        The third control is a list of all available devices on your system, from which you select the device to format/erase.  Only five names are displayed at once; additional names can be reached by scrolling the listing with the scrollbar.  If there are five or less names, the scrollbar is inactive and doesn't function.

        The fourth and final control is an editing line directly below the device name listing.  Here, you enter the name to use when formatting or erasing the selected disk.  Click in this box brings up the cursor, as will hitting any key except RETURN (which of course selects "Continue").  The default name here is ":Untitled", just like in the GS Finder.

        Once you have selected a device and entered a volume name, hit RETURN or click "Continue" to go to the GS/OS format menu.  I won't explain the GS/OS menu, as it's the same thing as what comes up in the Finder when you select Format or Erase.  You can also Cancel from here if you change your mind.

Delete/Rename:

        Theses two options allow you to delete or rename any file.  For delete, you are prompted to select the file to delete from a list of files.  Clicking "Open" or hitting RETURN will continue.  You are then asked to confirm the deletion.  Here, hitting RETURN will select "Cancel".  If you wish to continue, click the "Delete" button.  The file will be deleted if possible.

        The rename option works similarly.  After selecting the file to rename, you are prompted to enter the new name for the file.  The default pathname is the current pathname.  Note that you can actually rename a file to a different directory ON THE SAME DISK ONLY, as well as just rename the file itself.  To rename a file to a different directory, leave the filename itself alone, and just edit the appropriate directory name(s)s in the displayed pathname.  After you enter the new name, click "Rename" to continue, or press RETURN or click "Cancel" to cancel the option and leave the file alone.

Preferences:

        This option (under the Special menu) allows you to set certain defaults which are set every time you run NuPak IIGS.  This option displays a dialog, from which you can select compression mode and a default pathname.

        To select the compression mode, click on the appropriate "radio button" to select that option.  Only one option can be selected at once...selecting a mode deselects all other automatically.

        The default pathname is simple to edit.  Just type in the full GS/OS pathname of where you will most often put extracted files.  Leaving this name blank tells NuPak to not bother with a default pathname.  What NuPak does with the default is set the path to your default pathname right before putting up the "Select Pathname" extraction dialog, so that you can just hit "Extract" right away and get going, or select another path.  NuPak does not skip the selection so that you can still select a path other than the default pathname.

        For saving your preferences, you have three options.  Hitting RETURN or clicking "Cancel" aborts the changes you have made and leaves the preferences alone.  Clicking "Make Changes Temporary" will change the preferences, but the changes will not be saved back to disk.  Use this, for instance, to temporarily use a new default path or a different compression mode.  And finally, if you select "Make Changes Permanent", NuPak will not only change the preferences, but will save them back to disk WHEN YOU QUIT THE PROGRAM.  If you Ctrl-Reset and reboot out of NuPak without quitting, your preferences are not saved, so be careful!

Make Binary II File:

        The final option is Make a Binary II file.  Many information services require uploaded files to be in Binary II format.

        First, you are prompted for a source file to make the Binary II file with.  Select the file from the list and click "Open" to continue or "Cancel" to abort.  Second, you are prompted for the filename to use in creating the Binary II file.  Select an appropriate directory, type in a filename, and click "Save" to continue or "Cancel" to abort.

        NuPak will now make your Binary II file.  What happens is the output file is created and a Binary II header written to it.  Then the source file is copied byte-for-byte into the output file, creating your Binary II file.  As this process continues, you can watch the progress in a window like that used during extraction.  A thermometer will fill red as the process continues.

        NOTE: You may have heard of "BXY" files.  Some services prefer this format of file.  A BXY file is simply a Binary II file containing a NuFX archive.  To make a BXY file, simply create a Binary II file using a NuFX archive.  You can either do this to an existing archive, or create a new one within NuPak, add files to it, save it, and then convert it to BXY.


Conclusion
__________

        Now you have mastered NuPak IIgs and you should be ready to use the program the next time you wish to pack or unpack an archive.  Keep an eye out for future revisions as they are just around the corner. You may have also noticed new options, yet to be integrated into the program, in the menus. We are adding in these options continuously, with more important options being written first.

        It is hoped that NuPak IIgs will bring you hours of packing or unpacking enjoyment.  Archive away!!


Where to get ahold of us
________________________

You can reach Frontier Technologies in two ways:

America Online: Frontier T

US Mail       : Frontier Technologies
                P.O. Box 165
                Grosse Ile, MI  48138-2009

The author of NuPak IIGS can be reached in either the above ways or at the following additional electronic mail addresses:

America Online: Joshua T6

Internet      : joshuat2@nucleus.mi.org
_____________________________________________________________________________

NuPak IIgs is a trademark of Frontier Technologies, ShrinkIT and NuFX are a trademark of Paper Bag Productions, GS/OS, AppleShare, and Macintosh are trademarks of Apple Computer Incorporated, America Online, ACU and AppleLink are a trademark of Quantum Computer Services, Stuffit was developed by Raymond Lau.


