ReadMe for 

METOO and MOIAUSSI! (C) Copyright Bill Buckels 1990 - 2008.
All rights reserved.
Apple //e ProDOS 8 Version 2.0

Introduction

This ReadMe is not the user documentation. Please see the pdf's for
that.

This is the technical ReadMe for building the MeToo project.

When reviewing the seemingly confusing large number of files in this
project you should keep in mind that this project is organized into two
parts which are eventually used to build the program disks for both the
English and French versions:

1. Program Files

- ProDOS 8 - the Apple II operating system
- ME2.SYSTEM and MOI2.SYSTEM - the main programs
- *.OVR - the overlays (program modules)


2. Data Files

- LANG.TXT - determines English or French
- OLDIES.BIN - The Splash Screen
- PLOGO.RAG - the English or French Title Screen
- FATFONT.FNT - the Multi-lingual Font
- *.RIB the English or French Text and Graphics Data Libraries

At first-blush this all seems straight forward and it really is when it
comes to building the disk images. However, 2 general factors dictate
how both the program and its data files have been organized.

1. Space on Disk and in Memory
2. French and English Versions

The reasons behind all the fiddling that is necessary to make sure this
all works pretty-much dictates how the program amd its data files needed
to be designed, and how the disks needed to be laid-out.

Appendix A - METOO Program Architecture in the MeToo.pdf provides the
memory layout that I used for MeToo and several other of earlier
projects like TIME.SYSTEM. You will need to review this to properly
understand everything.

And finally the reason that I split this into pieces instead of jsut
making it work on a larger disk image is because I want METOO to 
work on a real Apple //e with only a floppy disk. That's all I have
and there are probably other folks who don't have fancy Apple //e's
either so I consider this the lowest common denominator.

Topic 1 - The Root Program and Overlays (program modules)

The overlays and their organization are based on earlier projects that
I have done like TIME.SYSTEM. However disk space requirements due to
the many graphics used in METOO required that the main program
(ME2.SYSTEM or MOI2.SYSTEM) be capable of running from the startup
disk, with the overlays and libraries (graphics etc.) being put
together on the data disk.In my earlier projects like TIME.SYSTEM this
was not necessary, and only one of my earlier projects (LOGIC.SYSTEM)
needed to be split into 2 disks since ProDOS would not fit on the
program disk.

Anyway, the second factor to consider when designing the overlays was
the relative size of the root module plus the size of the largest
overlay. This always needs to be taken into consideration because if
the root is too large and contains code other than commonly used code,
there will be no room for the overlay, and when the program loads, it
will clobber the system, because the program allocates the overlay
reuirements and memeory holes when it loads.

Techniques involved to balance all this require several test compiles
and moving things around. Sometimes code that is common will need to be
duplicated in several overlays if the root doesn't have room, but it is
always best to try to add common code to the root until it blows-out
then to remove the common code from the root and put it into each
ovrelay that uses it. However, more disk space is required if this
appraoch is use so it is a balancing act for sure.

METOO has been balanced extremely well in this respect. Only the text
plotting functions needed to be duplicated throughout the overalys that
use them. However doing this precluded creating a dynamic English -
French Toggle, since not enough room was available for a composite
grammar.

I should note at this point that I ruled-out compressing graphics early
in this project after doing comprative tests on file size savings.
Native mode uncompressed graphics load more quickly, and the small
amount of disk space savings that were achieved did not warrant the
extra work and the adding the decompression code, and in fact the extra
indexes that METOO would need. Some graphics were larger when run
length encoded. I would have needed to use a combined library of raw
and decompressed graphics to gain the optimal advantages which would
have made file seeking more complicated. The English-French toggle just
wasn't worth the extra fussing, all things considered.

The mouse routines that I added have increased the program size almost
to the breaking point as well and made programming all this fairly
complicated.

A balancing act for sure. So to recap:

1. Root and Overlays have been balanced to generally keep common code
in root, and module specific code in overlays with exceptions to avoid
memory blow-outs while at the same time to keep overlays as small as
possible on disk.

2. Data Library design and program features consider these constraints,
as well as program performance and code size to achieve a reeasonable
compromise.

Topic 2 - The Data and Libraries

Minipix (88 x 52 Graphics)

Earlier projects that I did loaded Data Libraries (.RIB files - .RAG
Libraries) into memory (both conventional and Auxilliary). Because of
the large number of Graphics these would neither fit into memory, nor
even on disk as conventional files since there were too many for ProDOS
to catalog. This left me with no choice but to load these particular
graphics as required from the .RIB file on disk rather than preload
these into memory as I do with all the other libraries.

Other Libraries and Memory Saving Techniques

I long ago developed a memory map (Appendix A - METOO Program
Architecture in the MeToo.pdf) for Aztec C ProDOS SYS programs. In
designing this map, I have taken advantage of unused memory on the
Apple //e to store the font (FATFONT.FNT) as well as to buffer my
cursor library (CURSSORS.RIB) used by the Main Menu. This reduces the
amount of memory needed by METOO and its modules. I also use the area
used by the cursor libary for a read buffer, including when reading
METOO.RIB (the main library) into Auxilliary Memory.

One of the things that is new for METOO is to reduce the size of the
libraries (.RIB files) so they take-up less disk space by not storing
empty buffers for screen back-ups and such. I still reserve these areas
of memory, but I don't initially fill them with blank data read from
disk as I did in my earlier projects thereby resulting in disk space-
saving. Effectively, I just tag the offsets for the screen-save buffers
that I want to the end of the disk data.

I don't want to confuse anyone with the above explanation and would
urge you to read the program in some detail to properly understand if
you wish to delve further.

My utility RIBCOOK.EXE is used to make library files. It started life
as a utility for graphics (.RAG, .TOP, and .BOT files) and then I
expanded it to include .BIN files (Binary Chunks). I could do more with
it and add indexes and chunk types. In the meantime for reasons
laziness I have not.

METOO's words and sentences are sequential binary chunks. The image
fragments for the menu bar and pieces of screens used throughout the
program are .RAGs. The METOO program uses the image fragments in
conjunction with a layout manager in the root module to build the
screens. This is a departure from previous projects of this type where
I just loaded the entire screen, and the layout manager technique saves
much disk space.

For further understanding, of how all this works in detail, please
review the METOO source code.

The BAGGAGE sub-drectory contains the graphics and binary chunks that I
have used to produce METOO's data and shows how I did so. If you are
interested in this level of detail then take a look at the respective
sub-directories beneath baggage. All of the image fragments were
created from IBM-PC 4 Color CGA BSaved Images and most of these were
created using Fraggle.EXE which is now part of the AppleX compiler
ditsribution. These are the files with the extension .PUT.

The FRAGRAG utility converts .PUT files to .RAG files which are then
put into the libraries (.RIB files) with RIBCOOK (previously noted). A
review of the tools directory in AppleX might also prove informative.

None of this is necessary to simply build METOO since all Data Files
are already done, but a good working knowledge of how I did what I did
requires that you review the tools and their source code in detail.

Topic 3 - The MAKEFILE and Building METOO

This all assumes that you are working in AppleX of course. To build
METOO type "MAKE" in the AppleX cmd window.

It's really as simple as that.

I haven't integrated METOO into any kind of disk image utility, but
have provided both the disk images and the required files for each in
the respective directories ENGLISH and FRENCH. These disk images can be
reviewed for template of what is expected for ProDOS to run METOO. The
MAKEFILE also should be reviewed for the details of the build process.

Topic 4 - Additional Notes

I want to mention that METOO is the most complicated project that I
have done for the Apple //e. None of the source code is an easy read.
Lots of sub-processes were required to put all this together. But METOO
is also the very best example Aztec C project that I have done. I can
pretty much guarantee that if you understand METOO's build process and
design in detail that you will have no problems creating similar
projects yourself.

And if you don't understand, you should really start-off with something
easier.

Have Fun!

Bill Buckels
July 2008









