Table of Contents
-----------------
1. Introduction
2. Changes in this release (0.9.1)
3. License and source code
4. unace binary
5. Limitations of AceExpander
6. Limitations of unace
7. Personal note


Introduction
------------
AceExpander is a Mac OS X graphical user interface to the unace command line
utility. With AceExpander installed, you can simply double-click on any
ACE archive(s) in the Finder and the contents of the archive will be
extracted to a sub-folder of the same folder where the original archive
is located. To configure AceExpander, or to use additional program features,
you have to directly launch the application.

For a detailed description of AceExpander's features, see the MANUAL
document (available from AceExpander's Help menu).

ACE archives can be created with WinAce. For more information about this
application, see http://www.winace.com.

You can check for the most recent version of AceExpander on its homepage
http://aceexpander.herzbube.ch/


Changes in this release
-----------------------
- released version 0.9.1
- added central handling for severe error conditions via the notification
  sub-system of Cocoa
- archive content listing is not lost anymore after the archive is expanded
- the content list drawer now opens automatically if it is closed and
  the list command is selected
- added items "MANUAL", "ReleasePlan" and "TODO" to the Help menu

For more details see the ChangeLog document.



License and source code
-----------------------
AceExpander is licensed under the GNU General Public License (GPL). See
the file COPYING inside the application bundle, or start the application
and choose the appropriate item in the Help menu to view the detailed
license.

The source code for AceExpander can be downloaded from its homepage
http://www.herzbube.ch/Software/AceExpander/AceExpanderIndex.shtml
You will get the source files ready for building with ProjectBuilder.


unace binary
------------
AceExpander packages its own version of the unace binary so that it can
be distributed and run as a stand-alone application. If you wish you
may set your own version of unace in the Preferences dialog, however you
should be aware that AceExpander may stop working properly after you make
this change, because AceExpander makes a number of assumptions about how
unace is working, which command line switches and options it uses, and
how its output on stdout is formatted.

Of course you can always change your preferences back to use the unace
that was packaged with this application.


Limitations of AceExpander
--------------------------
- I developed and tested AceExpander on Mac OS X 10.2.8, so I can only
  hope that it also works on later OS versions. It definitely does
  not run on pre-10.2 systems, because the .nib file format is >= 10.2
  and because a number of classes and methods are used that are not
  available on pre-10.2 systems.

- If you turn on the "Use password" option, the password you enter will
  be passed to unace in clear text. If someone watches your system's
  process list that person might be able to catch the password as it is part
  of the unace command line. It is also possible (notably if you also turn
  on the option "Debug mode") that the password might appear in clear text
  in one of the text boxes in the result window.

- AceExpander has too many features. I tried to keep them down to a
  reasonable number, but as this is a learning project for me, I often
  couldn't resist...


Limitations of unace
--------------------
- If you try to extract a password-protected file but specify an incorrect
  password, unace first extracts the encrypted file from the archive, but
  is then unable to decrypt the file, and dies. Unfortunately, the
  encrypted file is left lying around for you to clean up :-(

- If you try to extract a file without the overwrite option turned on, and
  a file with the same name already exists, unace dies with a segmentation
  fault. In combination with the above problem with password-protected
  files, this may prove to be quite nasty. Imagine this situation:
  1) In your first try to extract a password-protected file, you mistype
     the password and get an error message.
  2) In your second try, you type the correct password, but you still get
     an error message. Reason: you didn't turn on the overwrite option,
     but there is still the encrypted file from 1) lying around. After
     a couple of tries you might start to think that you have the wrong
     password, but in effect you just have to delete a file, or turn on
     overwrite.

- If you try to extract a file without the overwrite option turned on, and
  a file with the same name already exists, you must also have the
  "assume yes" option turned on in AceExpander, otherwise unace dies with a
  segmentation fault. AceExpander takes care of this problem for you by
  always turning on the "assume yes" option when the overwrite option is
  turned on.

  Technical note: the problem actually exists because of how AceExpander
  interacts with unace: when invoking unace, AceExpander explicitly sets all
  possible switches on the unace command line, even if the specified setting
  is the default for unace and therefore could be omitted (the reason why
  I coded it like this is that I did not want AceExpander to have specific
  knowledge about unace defaults; the less AceExpander knows about unace,
  the better).
  Now for the "assume yes" option: as explained, even though the option is
  turned off in the GUI, and "off" is unace's default for the switch,
  AceExpander still explicitly sets the switch on the command line to "-y-".
  Now the bug in unace is that the overwrite switch stops working as soon as
  "-y-" is set explicitly; if "-y-" is not set explicitly, the overwrite
  switch works fine.

- Most of the time when unace encounters an error, it dies with a
  segmentation fault. This is not a big problem, the error handling just
  becomes somewhat un-differentiated. If you're only using the GUI and are
  not interested in what happens under the hood of AceExpander, you can
  forget about this issue.


Personal note
-------------
I would like to thank Marcel Lemke for providing us with unace, and Kolja
Koischwitz for porting unace to the Mac. I would also like to mention
another GUI frontend to unace, MacUnace by Gabriel Gritsch, which has
influenced some of AceExpander's features (http://www.gritsch-soft.com/).

And, of course, a big Thanks to you for trying out this little program. It
is my first Cocoa application, and in fact, it is also the first Open
Source software that I release. As such it is probably full of shortcomings,
if not bugs. If you see something that needs improvement, please don't
hesitate to let me know.

Patrick Näf <aceexpander@herzbube.ch>
