Thank you for giving CiderPress a try! We hope you find it useful and easy to use. This page uses minimal formatting to be printer-friendly.
This tutorial will get you started working with CiderPress. You will need to download the sample files if you want to follow along. These are stored in a ZIP archive because historically some browsers have enjoyed corrupting SHK archives. Also, because of patent restrictions in some countries, the sample files are stored without compression. ZIP archives can be unpacked with WinZip, or under WinXP just open the "Zip folder" and copy the data out.
This tutorial assumes that you are already familiar with using a computer and with Microsoft Windows.
Start by installing CiderPress if you haven't yet. There aren't really any options to set, so just let it do its thing.
Create a "scratch folder" to put files in. Open your "My Documents" folder, and create a new folder called "cpt" (CiderPress Tutor). To keep things simple, put the two sample files (sample1.bxy and sample2.sdk) in this folder. If you are using Windows default "hide extensions of known types" feature, these files will show up as "sample1" and "sample2" after CiderPress is installed.
Launch CiderPress. The easiest way to do this is to click on Start, then Programs, then the CiderPress group, and finally on the CiderPress entry.
Glance through the menus and toolbar buttons. As you select items from the menu or move the mouse over a toolbar button, a description will appear on the "status bar" at the bottom of the screen. Most of the items are grayed out, because you don't have a file open.
Let's fix that. Click on the "File" menu and select "Open...". A standard Windows dialog appears. Change to the folder where the sample files are, click on "cp.sample1", and then click on the "Open" button. Your display will look something like this:
If you've used ShrinkIt on the Apple II, this display should look familiar. If you haven't, you're looking at ProDOS files stored in a ShrinkIt archive. The columns show the filename, some file type information, and other useful stuff. The little yellow rectangle next to "sample.text" means it has space for a comment allocated.
You can change the sort order of the files by clicking on the column headers (e.g. click on "Size" to sort by size). Click a second time on the same header to reverse the sort order. You can restore the original archive sort order by clicking on the "Edit" menu, then "Sort", and "By original order".
Let's take a look at what we have in the archive. Double-click on "sample.text", a simple text file. This opens the File Viewer window:
The title bar tells you the name of the file you're looking at, and lists any format converters that were used. In this case, "[CRLF]" means that the carriage returns found at the end of each line of the text file were converted to Windows "CRLF" format.
That wasn't very exciting, so close the window by clicking the "Done" button, and select all files in the archive by clicking on "Edit" and then "Select all". Right click on one of the highlighted file names to bring up a short menu of commands. Click on "View...". Because you went through a menu instead of double-clicking, you're given an opportunity to make some choices. The defaults are okay, so just click "OK".
The File Viewer is back, but this time the "Next" button is enabled. Click on it to advance to the next file, and again to see the third file. Move back and forth. One of the files is the text file we looked at earlier, another is a hi-res graphic image of a "double Bessel function", and the third is an AppleWorks word processing document.
Use the "Next" and "Prev" buttons to find the AppleWorks document ("SAMPLE.AWP"). Try resizing the window, and watch how the margins, centering, and right justification work. When you're done, press the "Done" button to close the window. (NOTE for Windows 98 users: right-justified text may not display correctly when the window is resized. This appears to be a bug in Win98. You can cut & paste from the file viewer window into Word or WordPad and see the correct text.)
Adding files to and extracting files from Apple II archives is a little more complicated than just moving files around. When adding files, it may be useful to restore the ProDOS file type information. When extracting, it may be necessary to convert the data into a different format for it to be useful under Windows.
We're going to extract and add the files twice. The first time we will preserve the original files exactly, the second time we will convert them to a format useful in Windows.
Let's begin by extracting the files. Click on "Actions" and then "Extract...". This brings up a dialog with lots of options:
The first thing we need to do is choose where the files will go. The folder listed at the top of the screen is probably not the one we want, so lets change it. Click on the folder icon in the upper-right corner, next to the filename entry field. This brings up the "Choose folder" dialog. Navigate through the folders until the "cpt" folder you created earlier is highlighted, and click "Select". (If you created "cpt" under "My Documents", don't be surprised if the name shown starts something like "C:\Documents and Settings\UserName\". This is normal for Win2K and WinXP.)
In the "Files to extract" box, select "Extract all files". Make sure both checkboxes in the "miscellaneous" section are unchecked. Finally, click on the large button near the bottom that says "Configure to preserve Apple II formats". This will configure the remaining options so that files extracted can be added to a new archive that is as close as possible to the original.
Once everything is set up as described (it should match the options shown in the picture above), click the "Extract" button. On a fast machine, you'll see little more than a flash as the files are extracted.
If you open the "cpt" folder (open My Documents, then open "cpt"), you will see three new files:
The junk starting with "#" that was added to the filename is a file attribute preservation sequence. The first two digits are the ProDOS file type, the next four are the ProDOS aux type. For DBL.BESSEL.PIC, it's $06 ("BIN") and $2000 (the typical load location of a hi-res image). None of the files has a filetype that Windows recognizes, which makes sense: none of the files is in a format Windows likes.
You might think that "sample.text" is a text file, and Windows likes text files, but it's not that simple. Rename "sample.text#04000" to "sample.text#04000.txt". Now Windows recognizes it as a text file. Double-click on it. If you have Windows "Notepad" as your default text viewer, you will probably notice that the file doesn't look right. Instead of line breaks there are funny little rectangles. Because we told CiderPress to preserve the original file formats, the carriage returns in the original file were left unmodified. Double-clicking on the other files will most likely not yield anything useful, because they're in formats that only an Apple II can readily handle.
We don't have to stand for that, however. Go back to CiderPress, and click on "Actions" and "Extract..." again. This time, click on the filename in the edit box, and hit the right arrow key until you're all the way at the right of the filename. We're going to extract into a sub-folder called "win", so type "win" at the end of the name. (It should now look something like "C:\Documents and Settings\Administrator\My Documents\cpt\win".) There's no need to create the folder ahead of time, CiderPress will create it for us.
Click on the large button labeled "Configure for easy access in Windows". Make sure "Extract all files" is selected, and leave the rest untouched.
Click the "Extract" button. Stuff happens, probably faster than you can see it. Open the "cpt" folder again, and then open the new "win" folder. Inside, you will find:
(Again, if you have "known extensions" hidden, you won't see any of the ".xxx" shown above.)
Double-clicking on the first launches the default Windows bitmap editor, where you can view the double-Bessel function in all its glory. Double-clicking the second launches the default Windows Rich Text Format editor, usually Windows WordPad or Microsoft Word. Double-clicking on the third opens the text file, nicely formatted for easy viewing.
Now that we've extracted some files, let's try adding them back into an archive.
Click on "File" and then "New .shk archive". Create a new archive called "test.shk" in the "cpt" folder. Creating or opening an archive causes the currently open one to be closed, so "sample1.bxy" disappears and "test.shk" takes its place.
Click on "Actions" and then "Add files...". This brings up the Add Files dialog.
Leave the "File attribute preservation" setting on "Use file attribute preservation tags". This tells CiderPress to look for the "#062000" stuff, but not to get excited if it's not there. The remaining fields aren't important for what we're doing now, so leave them alone.
Select the three files with the funny "#062000" stuff in the names. You can either click on the first and then shift-click on the last, or click on the first and then control-click on the other two. When all three have been selected, click "Accept". (You may notice a file with a name like "CPtmp_12345" in the folder. This is a temporary file used when ShrinkIt archives are opened, and can be ignored.)
The files are added in a flash. Double-click on them to verify that they are all intact. Note that the file types and modification dates match the originals.
Now lets add the second, converted set. Click "Actions" then "Add files...". Make sure "Include subfolders" is checked and "Strip folder names" is not checked. Click on "win" once (don't double-click it, or the folder will open) and then click "Accept". This adds everything in the "win" folder to the archive.
You will end up with three new files, each prefixed with "win:". Your archive should look something like this:
The file types of the three you just added are all "NON", and double-clicking on them in the CiderPress file list is disappointing. This is because these files have crossed over to the Dark Side (i.e. they're in Windows formats now), and the File Viewer is only able to display Apple II formats. Once you have converted files into Windows BMP or RTF files, it's more appropriate to store them in a ZIP archive than a ShrinkIt archive.
Generally speaking, when extracting files you can either choose to preserve the original format or choose to put them in a format easily accessible in Windows. CiderPress does not know how to un-convert BMP or RTF documents back to hi-res or AppleWorks format, so you should use one approach if you're planning to add the files back into an archive for use on an Apple II, and the other approach if you want to include them in Windows documents.
Let's try an experiment. In the CiderPress file listing for the "test.shk" we created above, click on "DBL.BESSEL.PIC". Click "Actions" then "Extract...", and make sure the extraction path is still set to the "win" sub-folder of our "cpt" folder. Hit "Configure for easy access in Windows" and then check the box labeled "Add file attribute preservation". Make sure the button in "Files to extract" is set to "Extract 1 selected file".
Click "Extract". You might expect to end up with "DBL.BESSEL.PIC#062000.bmp", but instead you get a warning about overwriting "DBL.BESSEL.PIC.bmp". Hit "Cancel" to cancel the extraction.
Why didn't a file attribute preservation sequence get added to the filename? Because once the file is converted to a BMP, it's no longer an Apple II file. The file type identifies the contents of a file, and "BIN" is no longer appropriate. The situation is similar for BASIC programs converted to text listings and AppleWorks word processor documents converted to RTF. If we added SAMPLE.AWP.rtf with an "AWP" file type, and then tried to load the file in AppleWorks, we'd be greatly disappointed.
We're done with this set of files, so click on "Actions", then "Delete...", select "Delete all files", and click the "Delete" button. Go to "File" and select "Close". The empty archive is automatically removed.
It's worth mentioning at this point that archives are not handled the same way word processing documents are. You can't make a set of changes, undo them, do some other things, and then save the results. (Technically speaking, it's possible, but CiderPress doesn't work that way.) Any change you make immediately modifies the archive file, and there is no "undo".
The ".BXY" extension is used for a ShrinkIt archive with a Binary II header. CiderPress is capable of opening both ShrinkIt and Binary II archives, so how does it decide which to open?
CiderPress tries to guess what you want, but it's easy to make your choice explicit. Click "File", then "Open...", and look at the "Files of type" selector. Click on it and change the setting to "Binary II". Double-click on "cp.sample1", which is a .BXY file.
This time, when the file opens, you see only one entry. "SAMPLE.SHK" is the ShrinkIt archive embedded inside the Binary II file. If you want to convert a .BXY to a .SHK, all you have to do is open the archive as Binary II and then extract the ShrinkIt archive. CiderPress does not have the ability to write to Binary II archives, which is why the title bar now also says "(read only)".
ShrinkIt archives are often found on disk images or inside other ShrinkIt archives, so CiderPress provides a faster means of opening them. Double-click on SAMPLE.SHK and watch as a new copy of CiderPress is launched. A copy of SAMPLE.SHK was written into the system temp folder, and the new CiderPress window opened it automatically. The file will be deleted when the second window is closed, which is why the new window is also marked "(read only)". Go ahead and close the second window before continuing.
Disk images are very different from ShrinkIt archives. They come in many different file formats, can be written with sectors scrambled in different orders, and can be in different filesystem formats (DOS, ProDOS, etc.). With most programs you have to know a fair bit about a disk image before you can access it, possibly having to convert it from one format to another, but with CiderPress that's not necessary.
Click "File" then "Open...", select "Disk Images" in the "Files of type" selector, and double-click cp.sample2. The disk image opens, and about 30 files are displayed. Notice that in the "Format" column, some files are listed as "ProDOS" and some as "DOS". This is because the disk image is of an 800K ProDOS volume with a 200K DOS 3.3 volume embedded in it. The title bar of the window now shows that this is a disk image of a ProDOS volume called "/CP.TEST".
(For those interested in technical details: CiderPress passed "cp.sample2.sdk" to the "DiskImg" library and asked it to open the file. DiskImg opened the file, figured out that it was a compressed ShrinkIt disk archive, and unpacked it to a buffer in memory. The disk structure was scanned, and DiskImg determined that it was a ProDOS volume in ProDOS sector order. It then examined the structure of every file on the disk, and determined that there was an embedded volume. This second volume was then opened, scanned, and found to be a DOS 3.3 disk in ProDOS sector order. The contents of the DOS volume were scanned. Control then returned to the CiderPress application, which took the list of files and displayed them in the window. Don't try that on an empty stomach!)
The files are shown in a "flat" list, though the real disk has most of the files in folders. For example, "Graphics:WORLD.MAP.PIC" is actually a file called "WORLD.MAP.PIC" in a folder called "Graphics". The files in the DOS 3.3 sub-volume aren't actually visible from ProDOS, so CiderPress prepends "_DOS001:" to make the separation clear.
Try double-clicking on some files to view them. You should probably start by double-clicking on "ReadMe",. a file in TeachText format that describes the contents of the disk. Try some BASIC programs like "STARTUP" in the ProDOS area or "ANIMALS" in the DOS area.
You may notice that some of the files appear to be compressed -- the "Ratio" column isn't 100%. This is because the files are "sparse". ProDOS and DOS 3.3 have the ability to store empty disk blocks without using lots of disk space. The difference between "Size" and "Packed" represents the space saved by using sparse blocks.
If you double-click on "TestFiles:SPARSE", you will get an error message from the File Viewer indicating that the file is too large. The file is actually 16MB, but because it's almost entirely sparse blocks it only occupies about 1.5KB. If you want, you can view this file by increasing the file viewer limit. Click on "Edit", then "Preferences...", then on the "File Viewer" tab. The "Viewer file size limit" can be set in 1K increments. There are a number of other configurable items in here, including settings that let you convert hi-res and double-hi-res graphics to black and white instead of color. Click on the "Help" button or use the question mark icon in the window title bar to get more information about specific things. Click on "Cancel" to close the dialog.
Click on the "File" menu, then "Open...", change "Files of type" to "ShrinkIt Archives", and open "cp.sample2". You should see a single entry, for an 800K disk image. (If you want, double-click on the entry to pop open a second instance of CiderPress with the disk image contents in it. Close it when you're done.)
Click on "Actions" and "Extract...". Set the extract folder to "cpt", and click "Configure for easy access in Windows". Note that "Extract disks as .2MG" is checked. Click "Extract".
If you open the "cpt" folder, you will find a new file called "CP.TEST.2mg" (or just "CP.TEST"). Depending on how your file associations are configured, you should be able to double-click this file and launch the default 2MG application (which is probably an Apple II emulator or CiderPress; file associations can be set from within CiderPress by clicking "Edit", "Preferences", and then the "Associations..." button).
That was easy enough. Now let's try adding the disk image to an archive. Click on the "File" menu then "New .shk archive", and create a new archive called "mydisk.shk" in the "cpt" folder. Click on the "Actions" menu then "Add disk image...". Navigate to the "cpt" folder if you're not there already, click on "CP.TEST", and click "Open". The disk image is added.
Let's try a different way. Extract the disk image you just added (still working in "mydisk.shk), but this time click on "Configure to preserve Apple II formats.". Click "Extract" to create "CP.TEST#000640i". (The "640" is the number of blocks in hexadecimal, and the "i" indicates that it's a disk image.) This file is a ProDOS-ordered sector image; if you check the "Add type extension" box before extraction, it will be given a ".PO" extension and can be opened with the default ".PO" viewer (usually CiderPress or an Apple II emulator).
Let's add it back to the archive. We could use the "Add disks" menu item, but we have another option. Click on "Actions" and then "Add files...". Make sure the "File attribute preservation" setting is on "Use file attribute preservation tags", click on "CP.TEST#000640i", and click "Accept". When asked if you want to overwrite the file, click "Yes".
Nothing appears to happen, but you've actually just replaced the disk image that was in the archive with the new one. You were able to add the disk image with the "Add files" dialog because of the file attribute preservation strings (the "#000640i" part). If you had set "File attribute preservation" to "Ignore file attribute preservation flags", you would have added a file called "CP.TEST#000640i" instead of a disk image called "CP.TEST".
CiderPress is a powerful tool with lots of features. Start with the default settings and quick configuration buttons. The additional flexibility is there if you need it. Click the "Help" button on a screen for detailed help on that screen, or select "Help" then "Contents..." to start from the beginning. In many screens you can click on a question mark button in the title bar and then click on a button to get more information on that button.