This file describes version 1.0 of afid.
The latest version should be available for anonymous FTP from
cs.ubc.ca in /ftp/local/src/afid.

afid is a utility which allows you to manipulate an Apple ][ DOS 3.3
disk image.  It currently doesn't handle Prodos disk images and only
reads and writes 35 track, 16 sector diskette images.

afid provides a simple command line interface.  You start it up
by giving it the name of a disk image:

	afid file.dsk

It then reads the disk image into memory, does a few sanity checks and
gives you the "] " prompt.  You can use the following commands:

catalog - show a list of the files on the disk image
free - display a map of free sectors and the number of free sectors
quit, exit - leave afid
binary - no translation of file data is done during copies (this is the default)
text - CR <-> LF and Apple <-> ASCII translations are done to file data
reorder - switch disk sector order between DOS 3.3 (default) and Prodos
read file - copy the given file from the disk image to a UNIX file
write file - copy the given UNIX file onto the disk image
save file-image - save the in-memory disk image to the given UNIX file

Notes:

"save" is important, and changes made with "write" will not be permanent
until you save the disk image.  File names are translated to all uppercase
on the Apple disk and to all lowercase on the UNIX end.  This is convenient,
but could be annoying.  I'm not sure that the text translation is done
correctly.  I just empirically judged that twiddling the top bit was
the right thing to do.  Binary file copy is a little hokey; pay no mind
to the extra stuff it spits out at you.  Disk block ordering can be a
little tricky.  Basically, if you make the disk image on a machine running
Prodos, you'll have to re-order the sectors.  This means that probably
anything extracted from a Shrinkit archive will need to be reordered.
It can be hard to tell since the most obvious symptom is a shortened
catalog which is not a lot different from a normally short catalog.

The free command spits out some crap about the sector mask.  You can
ignore it, but knowledgable folks could help me out.  I gather that
the mask allows you to specify sectors which cannot be used, but
I've never seen a mask that was usable.  What's wrong?

I've compiled afid on a Sun sparcstation with gcc and on a PC with
Turbo-C 2.0.  It should be fairly portable if your machine has enough
memory.  I hope this inspires someone to create a Prodos version.

Things to do:

The most obvious extension is file operations such as type changing
and deletion.  If the disk fills up, you're left with a partial file
on the disk.  The file system is still stable at that point, but
not deleting the failed file is pretty messy.  File reads should
do something smart like paying attention to the file type.
A warning that the disk blocks are out of order could be put in.
Options to switch the file-name mapping on and off would be nice.
A file-duplicating mechanism could be useful if you ever should run
into files with holes.  Sector allocation is not done in the same
way as DOS 3.3 (not so bad) and may not be very efficient at times
(not so good).

The code could use some cleaning up, for sure.  I'd try and completely
localize things like the VTOC accesses and come up with a few
master directory scanning and file scanning loops instead of duplicating
the code here and there.

I'm looking towards getting a Deluxe Option Board for my PC.  I know
it can read apple ][ disks into bit images.  Should I get the board
and can figure out the format of those bit images, you can bet afid
will be enhanced.  This should provide a very nice file transfer path:
diskette -> bit file image -> afid -> bit file image -> diskette.
This is pretty plausible, but real pie in the sky would be a program
that could work directly with the apple ][ disk on your PC with the
option board.  Probably won't happen as I doubt programming information
on the option board will be easy to find.