Help file for PackDisc 0.11
===========================

Overview
--------

This program will increase the free space on any FileCore based filing
system. This free space which is created comes from the wasted space in
shared fragments. !PackDisc rearranges which files share fragments with each
other in such a way as to minimise the remaining wasted space.

PackDisc is ideal on directories which have constant contents and several
small files, for example application directories, as the small files can be
rearranged more effectively and the space saved should remain saved.
It may also be useful for PD libraries or magazine discs or anyone else who
wants to use every last sector on a floppy - it can usually save at least a
couple of KB from a typical floppy. I saved 11K on a copy of the RISC OS 3
App1 disc. On my whole hard drive I saved about 10MB.

The whole of the re-arrangement is done using high-level filing system calls
to minimise the risk of corrupting discs. However, the FileCore bug which
can corrupt nearly-full discs *could* rear its ugly head. I have not had any
problems with the current version. An early development version *did* cause
a corruption of a couple of very large files but these are handled
differently now so the corruption should not occur.


Usage
-----

Before running this program on a disc you should make sure it has enough
free space on it for PackDisc to operate. If necessary move a large file off
the disc and replace it afterwards. I would recommend having at least 1MB
of free space on a hard drive and about 30K on a floppy. It is probably
possible to do it with less but very risky...

If you use FSLock, you will either need to edit the !RunImage and change the
names of the temporary directories Scratch and STORE to a writable
location on the disc or disable it while PackDisc is running.

Either double click on the icon to run it single tasking, or shift-drag it
to a TaskWindow.

Enter the filename of the directory you want to optimise. This is put
through CanonicalisePath, so will be relative to the CSD. If you do not
enter a full path including the FS and disc name/drive number, the
canonicalised path will be displayed. In any case the path must be on a
filecore based filing system. You should not attempt to optimise any of the
parent directories of the temp directories, or directories in image files.

You may either optimise just the directory stated, or recurse into all its
subdirectories as well.

The Verbosity level is set near the start of the program. This will determine
how much output is given.

Level 0  Gives only the space saved statistics for the whole run of the program
         when it finishes.
Level 1  Also gives you the space saved statistics for each directory.
Level 2  Tells you what overall operation it is trying to acheive at each step.
Level 3  Tells you as it moves each file and gives a breakdown of the groups.
Level 4  Gives some information on how the grouping is being derived.

After a while the program should terminate, telling you how much space the
files take (rounded to sectors), how much wasted space was recovered as free
space, and how much wasted space remains. This often shows that about a third
of the original wasted space was recovered, but depends very much on how many
relatively small files there are in the directories optimised.

There is no point running it more than once on the same directory as no further
space can be saved (at least not with this program)

IMPORTANT: do not run *ANY* other program which could possibly write to the
disc and alter the amount of free space at the same time as PackDisc. At best
it will cause PackDisc to report the space saved incorrectly, but it will
probably make it bomb out with an error.

Utilities such as LongFiles or SymLinks will cause problems, so should be
disabled before running - I would recommend running on a cleanly restarted
machine without running the boot sequence (hold down <shift> while
restarting).  PackDisc will complain if it comes across a filename of more
than 10 characters to try to prevent some of these problems.

If an error does occur, don't worry, none of your files will be lost. Any
files or directories which appear to be missing are in PackDisc's store
directory. This is $.STORE on the disc you are optimising unless you have
amended the program to get round FSLock. PackDisc will tell you which
directory the contents of the store should be moved to when it exits. It
will also open directory viewers on the store directory and the directory
where the contents should be put if you ran it from the desktop.

During the course of its normal operation, PackDisc will create several
directories which fsck describes as "Directories bigger than the minimum
size". This is nothing to worry about - it is allowing more files to share
the same fragment with the directory.

Another way that you can create more space on a hard disc is to reduce its
size. If you have a disc formatted to a value between about 500MB and 512MB
or so, and the LFAU is 2K, reducing it to just less than 500MB so that the
LFAU is only 1K and putting all the files back on will probably halve the
wasted space. I had over 40MB of wasted space on my disc at 511.8M,
reformatting it to about 499.5M reduced this to about 20M representing an
overall saving of nearly 10M. There is another boundary size for the .5K to
1K LFAU transition but I don't know what this is. Equally for 2K to 4K etc.


DISCLAIMER
----------

While every effort has been taken to ensure that files do not get lost or
corrupted, I WILL NOT BE HELD RESPONSIBLE for any loss that occurs as a
direct or indirect result of using this program. It is up to you to make sure
any important data is adequately backed up, and irresponsible not to do so.
[I guess that makes *me* irresponsible... oh well 8-]

Having said that, I would like to know if there is a problem with the
program, especially if you can see where it needs fixing.


Shortcomings of this version
----------------------------

  - Single tasking (although it can be run in a taskwindow). Options
    (ie the display output level and names of temp directories) are changed
    by editing a line in the program code.
  - Uses far too many file operations. This makes it rather slow. A version
    using lower level operations would be able to go a lot faster.
  - Will not work if any other program is accessing the disc at the same time
    (or rather writing to it).
  - Does not cope gracefully with errors. The user must replace files which
    are stuck in its temp directory.
    Having said that, errors do not occur in my experience unless another
    program accesses the disc at the same time or there was too little free
    disc space.
  - Cannot check potential savings without first doing it. This makes for
    lots of tedious copying which may not free any space.
  - Can cause the free space map to become very fragmented during the course
    of normal operation. This can be partially alleviated by a *Compact.
  - Is slowed down considerably by a very fragmented free space map. This
    and the one above do not work together very well...
  - The optimisation algorithm is not perfect and sometimes gives
    sub-optimal arrangements. Indeed I have seen negative savings
    occasionally.
  - Not tested on RO2 - does ANYBODY still use it?  Should work though,
    although the call to CanonicalisePath will need removing.


History
-------

v0.11  Modified to cope with a problem that occurred on discs with LFAU
       at least 4KB, where a directory contains exactly 1 file whose
       size is between 30 and 31 times LFAU.

v0.10  Modified to handle 'big' discs correctly. Previous versions got the
       parameters wrong for >2GB discs. If someone who has such a disc
       could confirm that it now works on >2GB discs I would be grateful.

v0.09  Now opens filer windows on the STORE and current working directory
       in the event of a crash, to allow you to copy the files back more
       easily. Recreates working directory if it doesn't exist.
       Auto-compacts the disc if the free space map is getting very
       fragmented. To change the sensitivity of this change the value
       of MaxAttempts%. To disable this feature set to a value greater than 75.

v0.08  Added lo-res and hi-res mono versions of !Sprites.
       Desktop version still under development, but moving more slowly now
       I have a full-time job...

v0.07  Added call to OS_FSContol 37 (Canonicalise Path) to save typing in long
       pathnames (or rather allow me to shift-drag paths such as <Games$Dir> or
       Home:Steve to a taskwindow). Also corrected bug introduced in 0.06
       relating to completely empty directories.
       Desktop version well under development...

v0.06  Removed the remaining GOTO so that users of inferior editors don't have
       problems changing the options near the start of the program.

v0.05  First release version.  No longer corrupts large files, but does not
       remove wasted sectors from the end of them. This is the sort of
       situation that fsck will report as an overallocated file anyway (I
       think), and is considered abnormal so possibly not a problem. I think
       this was the only place corruptions occurred and have noticed no
       problems with this or more recent versions.

v0.04  Algorithmic improvements to earlier versions.  Negative "savings" very
       rare now. Noticed that large files are getting corrupted. (Bother! that
       was my favourite sound sample and I don't have a backup :-( ). This is
       probably due to the FileCore bug, and must be worked around before a
       release is made. Small files seem ok though.

v0.03  Added to grouping algorithm. Still several situations where savings are
       negative. Significant savings overall though.

v0.02  First automatic grouping version. Grouping of files is not always the
       best and often savings made are negative. Regrouping by hand necessary.

v0.01  Well, not really a version of the program, but a method from which it is
       derived.  Use RealCount to find where wasted space lies, and group files
       together by hand in a more optimal manner.


The Author
----------

PackDisc was written by Steve Lee <steve@banoffee.co.uk>. If you have any
technical queries about its operation, contact me.

Future development (converting to use GUI etc) has been taken over by
Patrick Mortara <mortara@fh-frankfurt.de>, so contact him with any
suggestions for future versions, or if you want to get the latest version.
