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 just 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