         ______      ____     ______
        /\  _  \    /  __ \  /\  ___\
        \ \ \L\ \  /\  \ \_\ \ \ \__/
         \ \  __ \ \ \  \/_L_ \ \  _\
          \ \ \/\ \ \ \  \_\ \ \ \ \/___
           \ \_\ \_\ \ \_____/  \ \_____\
            \/_/\/_/  \_____/    \/_____/   Version 0.1 beta

                 (Allegro Con Eiffel)

                       By Peter Monks, 1997


#include <std_disclaimer.h>

   "I do not accept responsibility for any effects, adverse or otherwise, 
    that this code may have on you, your computer, your sanity, your dog, 
    and anything else that you can think of. Use it at your own risk."


======================================
============ Introduction ============
======================================

This document does not need to be read if all you plan to do is use ACE in
your own projects.  It merely aims to spell out the requirements I set myself
in order to determine which of many possible designs was most appropriate.

If you find this document boring and irrelevant, my apologies, and I hope
you find ACE convenient to use as it stands.  If, however, you don't like
something about ACE, please read the following to try to understand what
drove me to design it the way I did, and then help me to make it better, by
suggesting changes to either the requirements, the design, or the
implementation.

I've also tried to evaluate whether I've been successful at meeting each of
these criteria, and identified areas where ACE still needs work.

ACE will probably be in beta until I'm convinced no one (including me) has
any more criticisms!


==========================================
============ A Bit of History ============
==========================================

When I started this project I was mainly concerned with producing something
that worked, regardless of the techniques used to develop it.  Needless to
say, I ended up with something that, although it worked, was awful to
maintain, and even worse to use.

Still, this initial prototype proved that what I wanted to do was possible,
and also made me focus on what I actually wanted the package to provide (ie.
come up with requirements for ACE).

There are still some hints of this initial prototype hanging around, despite
my best efforts to get rid of them.  If you spot one of these little nasties,
please get in touch, so I can get rid of it.


======================================
============ Requirements ============
======================================

1. I didn't want to change either Allegro, SmallEiffel or DJGPP.  I wanted
   ACE to work with the "off-the-shelf" versions of these packages so that
   future releases don't break the ACE package.

   Result:
   Through the use of the support routines (found in the SUPPORT directory),
   I feel I've been pretty successful at meeting this criteria.  I've been
   through two releases of Allegro and four releases of SmallEiffel, and very
   little has needed fixing because of these releases (although SmallEiffel
   v-0.86 broke a lot of things because it is a little buggy under DOS).


2. I wanted the ACE library to be as "clean" an OO design as the underlying
   procedural library allowed.  This meant adherance to the concept of
   "Design by Contract", and the liberal use of assertions, amonsgt other
   things.

   Result:
   I think I've made a decent first attempt at a "nice" OO design for the
   library.  There are many inter-dependencies between classes that aren't
   particularly nice, but that's the nature of Allegro.
   The biggest problem, however, is my very limited OO design experience, so
   I can't really identify where I've made an OO design blunder.
   Take, for example, the concept of "command-query separation".  I've heard
   a lot of people talking about how good it is, and I can guess what it is
   and what its advantages are from its name, but I really don't _know_
   anything about it!  Thus, I'm hoping for lots of (constructive!) criticism
   about ACE's design.


3. I wanted to encapsulate as much of the Allegro functionality as possible.

   Result:
   I've been able to package up most of the 2D, sound and input
   functionality, but none of Allegro's 3D capabilities.  I have a very
   limited understanding of 3D graphics, so I felt it was a bit beyond me
   to try to encapsulate it.  Your help could change this!
   GUI functions are not yet supported.  I think this functionality could
   be included in ACE, through the use of the CECIL library.  I've got CECIL
   working (check out FILE_ITERATOR.E to see a working C callback), but need
   to really sit down and nut out how the Allegro GUI system works before
   committing to a design approach.


4. I wanted to ensure that everyone, no matter how rich or poor could use
   the package.

   Result:
   Because of the generosity of such people as Shawn Hargreaves, DJ
   Delorie and Dominique Colnet, the Internet community has access to a
   wide variety of free products of *excellent* quality.  We should all be
   supremely grateful for the effort these (and others) put into their
   free products.  Certainly without their efforts, ACE wouldn't exist!


5. I'm sure there were others, but they escape me right now!  :-)


=======================================
============ Contacting Me ============
=======================================

If you've read this far, you probably already have a list of issues you
want to talk to me about, but I'll say it anyway!

If you have any problems, comments, grievances etc. about ACE I want to
hear about them!!  At least then I'll know that this little project was
worth the time I spent on it.

Since I move around a bit, e-mail is the only reliable way to get in
contact with me.  My address is pmonks@iname.com.

Happy Eiffeling!
