 -=[ DirMap v1.0     Copyright 1989 Jason Harper     CompuServe 76703,4222 ]=-

STATUS:
Freeware: distribute but do not sell.

PURPOSE:
To show the directory structure of any GS/OS-readable disk in a graphical
format in which the displayed width of each directory is proportional to the
amount of disk space taken by files in that directory, including all files
in subdirectories.  This makes it easy to locate any directories that are
taking up more disk space than expected, perhaps due to some large files that
were placed there and forgotten.

REQUIREMENTS:
Apple IIgs.
512K memory should be sufficient for handling any reasonable disk structure.
GS/OS (System Disk 4.0 or higher).

Optional (needed only for alternate methods of use):
APW or Orca/GS command shell (text based, not Orca/Desktop).

LIMITATIONS:
The amount of disk space taken by the directories themselves isn't included in
the displayed directory sizes, since GS/OS doesn't support any file system
independant way of determining it (some file systems don't store directories
as separate entities, therefore the size of a directory on such a file system
isn't a meaningful concept).  The effects of this should be negligible.

Any directories that contain less than 1/320th of the total disk space used on
the volume probably will not appear in the display at all.

Disks or directories with a name longer than 32 characters will cause DirMap
to abort.  This can't happen with any current or expected GS/OS File System
Translators, but may be a problem in the future.

DirMap probably won't work on a network file server volume unless you have at
least read access to every directory on the volume.  It would be possible for
the program to skip over directories it can't access, but I don't think that
the display resulting from such an incomplete mapping would be useful.

When used normally, you can only select from the first 21 GS/OS disk volumes.
If this becomes a problem for you, let me know and I can produce a version of
DirMap that has a higher limit for no more than a few thousand dollars (which
should be pocket change to anybody who can afford to put more than 21 devices
on one IIgs).

You can easily capture the generated directory map screen with any of the
various screen grabber desk accessories available, but it is unlikely to do
you any good since the program uses 640 multi-palette mode graphics.  Not all
screen grabbers can properly capture such an image, no currently available
programs can edit them, few programs can even view them, and nothing that I'm
aware of (other than perhaps the Fingerprint card) can print them.

USAGE FROM A PROGRAM SELECTOR:
Just run DIRMAP like you would any other program.  You'll get a screen with
a button for each GS/OS-readable disk you have online: click on the one for
the disk you want to map.  After the mapping is complete, you'll be returned
to this screen.  There will also be buttons to reread all disk volumes (in
case you forgot to put the desired disk in a drive, or have to remove the disk
containing DirMap to do so), and to quit the program.  You can also perform
these functions from the keyboard by pressing 'R' or 'Q', respectively.

After you've selected a disk to be mapped, there will be a short delay while
the disk's directory structure is being read into memory.  When the map is
displayed, there will be a box across the top which represents the disk's
volume directory and all the files on the disk.  Underneath it will be a row
of boxes representing the directories contained in the disk's volume
directory: underneath each of them will be the directories they contain, and
so on.  The width of each directory's box is proportional to its size: a box
that is 1/4th of the width of the screen represents a directory that contains
files that total to 1/4th of the total space used on the disk (NOT 1/4th of
the total space available for use on the disk).  Any white space under a
directory box, not filled by boxes representing subdirectories, represents the
space taken by individual, non-directory files in that directory.  If you map
a disk containing no subdirectories at all, the entire screen will be filled
with a single box representing its volume directory.

Each directory box contains the name of the directory it represents, if it
will fit.  If not, just point the mouse cursor at the box and its full name
and exact size in disk blocks will appear at the bottom of the screen.
Clicking the mouse or pressing any key will return you to the list of online
disks, from which you can choose another disk to map or quit back to your
program selector.  If you click in a directory box and then immediately quit,
the prefix will be set to the directory you clicked in: this has no effect
with most program selectors, but with those that do make use of the prefix
(such as the APW or Orca/GS command shell) this feature can be used to quickly
examine directories that seem to be taking up more disk space than they
should.  If you're using such a program selector, and don't want to change the
prefix from what it was on entry to DirMap, make sure you always exit the map
view mode by pressing a key or clicking the mouse outside of any directory.

USAGE FROM THE APW OR ORCA/GS COMMAND SHELL:
If you use APW or Orca, you can still use DirMap as described above, but it
will be more convenient to use if you install it as a shell command.  Just
follow these steps:

1. Copy DIRMAP into your Utilities (prefix 6) directory:
    PREFIX (wherever dirmap currently is)
    COPY DIRMAP 6/
2. Change its filetype to EXE so the shell doesn't have to reload after use:
    FILETYPE 6/DIRMAP EXE
3. Add an entry for it in your commands table:
    EDIT 4/SYSCMND
insert the line (in alphabetical order):
    DIRMAP      U               ;disk directory mapper
Save the file back to disk, then exit and reenter the shell.

You can now call up DirMap by typing DIRMAP, no matter what the current prefix
is.  You can also tell DirMap to immediately map one or more disks by typing
their names (or the name of the device containing the disk, or the name of a
file or directory on the disk) after the DIRMAP command.  Each requested disk
will be mapped in turn: press the mouse button or any key to go on to the
next.  When all have been mapped, you'll be at DirMap's disk listing screen
and can click on Quit to return to the shell.  An example:
    DIRMAP /HARD1 .APPLEDISK3.5A */ 6
will map the following four disks:
1. the one named /HARD1,
2. whatever disk is in the device named .APPLEDISK3.5A,
3. the boot disk, and
4. whatever disk contains prefix 6 (the APW/Orca utilities directory).
