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. 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.
You should create a "scratch folder" to put tutorial files in. Open your "My Documents" folder, and create a new folder called "cpt" (CiderPress Tutorial). To keep things simple, put the two sample files (cp.sample1.bxy and cp.sample2.sdk) in this folder. If you are using Windows' default "hide extensions of known types" feature, these files will show up as "cp.sample1" and "cp.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 a comment.
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 specifies the format converter that was used. In this case, "[Converted Text]" means that the carriage returns found at the end of each line of the text file were converted to Windows "CRLF" format, and any "high ASCII" characters were stripped out.
You can click on the "Comment" button on the left to view the comment instead of the file contents. Clicking on the "Raw" button changes to an un-converted view (no change will be visible under Win2K/XP), and clicking on the "Hex" button changes to a hex dump. The "Best" button switches back to Converted Text. You can also select modes from the pop-up menu.
Click "Done" to close the file viewer. Let's try this a different way. 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...". 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. Now switch to the hi-res image. Using the pop-up menu, change the format conversion from "Hi-Res / Color" to "Hi-Res / B&W". Notice how the color fringes disappear, leaving a sharper image. Some graphics look better in black & white than in color.
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 in Windows Explorer (open My Documents from the desktop or Windows Start menu, 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 in Windows Explorer 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" and move over to "ShrinkIt 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 "cp.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 we have file converters turned on, and those change it to Windows format. Once the file is converted to a BMP, it's no longer an Apple II file, and trying to preserve the "BIN" file type 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 select all files ("Edit" then "Select all", or hit Ctrl-A), click on "Actions", then "Delete...", and hit "OK" when asked to confirm the deletion. 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, 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 quick way 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 35 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. Use the conversion selector to turn color highlights on and off.
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 default hi-res and double-hi-res graphics to black and white. 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 with Windows Explorer, you will find a new file called "CP.TEST.2mg" (or just "CP.TEST" if extensions aren't being shown). 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 -> ShrinkIt 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".
Working with disk images is a little different than working with ShrinkIt archives. Filenames have limited lengths and may only contain certain characters, file lengths are limited, and on non-ProDOS volumes the selection of file types will be limited. On the plus side, disk images can be used directly by Apple II emulators.
Let's start by creating a disk image. Click on the "File" menu, then "New -> Disk image...". This opens the Create Disk Image dialog.
Leave the values set to the defaults and click "OK" to create a 140K ProDOS image. When the "save" dialog comes up, type "testdisk" into the "file name" field. Leave the file type set to "DOS-ordered image (*.do)". Click "Save".
Your brand-new ProDOS disk will open automatically. The disk has one entry for the volume directory, called ":NEW.DISK". Let's add some files.
Click "Actions" then "Add files...". Select the three files with "#123456" stuff in the filenames (DBL.BESSEL.PIC#062000, SAMPLE.AWP#1ac0fd, and sample.text#040000.txt) by clicking on the first one and control-clicking on the other two. Make sure "use file attribute preservation tags" is set.
You will notice that the "Text conversion" options are now available. The files we're adding are from an Apple II, so we don't want to mess with them. Click on "Don't convert text files". Now click "Accept" to add the files. You should be back in the CiderPress file listing, with four files on the screen (the volume directory and the three files you just added). Double-click on them to verify that they're all okay.
You may notice that only "sample.awp" is in lower case. That's because, by default, CiderPress adds files to ProDOS disks in upper-case only. If you use a version of ProDOS 8 older than v1.8, you will get errors on disks with lower-case names. (You can change this behavior from the disk images preferences screen.) So why is "sample.awp" in lower case? Because AppleWorks files have lower-case flags in their "aux type" field. If CiderPress sees a file with type AWP, ADB, or ASP, the flags in the aux type are used.
One nifty thing about ProDOS disks is that you can tuck files into subdirectories (usually called "folders" in Apple-speak). Let's create one now. You have to tell CiderPress which directory the new subdirectory will appear in, so start by clicking on the volume directory (":NEW.DISK"). Click on "Actions" then "Create subdirectory...". Type "My Stuff" as the name. Click "OK". A new subdirectory, called "MY.STUFF", appears. (If lower case were enabled, it would have been added as "My Stuff" instead.)
Suppose we want to add more files. Where do they go? In the volume directory, or in MY.STUFF? Let's find out. Click on a blank area of the window so that nothing is highlighted. (You may still see a thin dashed line around one entry; that's okay.) Click on "Actions" then "Add files...". You will see a dialog that asks you to pick the location.
As you can see, you are able to add files to the volume directory or the folder you created. As noted in the "tip" at the bottom, you can avoid seeing this dialog by clicking on the target subdirectory before you select "Add files...".
We don't really want to add anything here, so click "Cancel". Close the disk image by selecting "Close" from the "File" menu. Let's create another image, this time a DOS 3.3 disk. From "File", select "New -> Disk image...".
Click on the "DOS 3.3" button in the upper left. The ProDOS volume name entry field is greyed out, the DOS 3.3 options in the upper right corner become active, and our choice of sizes is now limited to just 140K disks. Leave the defaults alone and click "OK". Click on "testdisk.do" (the disk we recently created) and click "Save". When asked if you want to replace the existing file, click "Yes".
Now we have open an empty DOS 3.3 disk image. Let's add a file. Click "Actions" then "Add files...". Open up the "win" folder inside "cpt", and select "sample.text" (or "sample.text.TXT"). Click "Accept".
The file has been added, but something is strange. Our text file has type $F2. The reason this happened is because CiderPress didn't see it as an Apple II file, and gave it a file type of NON. However, there is no direct equivalent to NON for DOS 3.3. Instead, CiderPress used the DOS file type 'S'. There's no ProDOS equivalent to 'S', so CiderPress displays it as $F2. Because DOS 3.3 'S' files don't have an explicit file length, the length is rounded off to 512 (two DOS sectors).
Yuck. Fortunately there's a simple way around this. Click "Actions" and "Add files..." again. This time, click the "Use tags and guess type from extension" button. This tells CiderPress that we want it to guess the type of the file from the filename extension. Since we're adding a text file to a DOS disk, we also want it to convert from Windows format (low ASCII, CRLF) to DOS 3.3 format (high ASCII, CR), so click on the "Convert text files by file type" button.
Click on "sample.text" again, and click "Accept". When it asks you if you want to replace the previous file, say "Yes". You should now have a text file with a reasonable length. If you double-click on it and view it in hex dump mode, you'll see that it's in "high ASCII" with carriage returns, as all good DOS 3.3 text files should be.
Select "Close" from the "File" menu to close the disk image.
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.