+---------------------------+
| Apple II  Expense tracker |
| By Craig Bower 25/02/2007 |
|  www.turbo-2.com/apple    |
+---------------------------+

------------------
First things first
------------------

** First things first, whats in the ZIPFILE? **

If you received the proper distribution package (http://www.turbo-2.com/apple/a2x.zip) you'll have the following:

>> a2x.dsk (Dos 3.3 Version)
>> a2x-readme.txt (this File!)

-----------------------
Whats on the DSK image?
-----------------------

** a2x.dsk (Dos 3.3) contains the following **
+------------------------------------------------------------------+
|								   |
| ]CATALOG	  						   |
|								   |
| DISK VOLUME 254						   |
|								   |
| *A 063 a2x	     <<   a2x eXecutable (Applesoft - //e version) |
| *T 005 a2x.data    <<   a2x saved data file.			   |
|								   |								   |
+------------------------------------------------------------------+

---------------
Getting started
---------------

Load the disk image into your favorite emulator and boot it up.

After the initial title screen, you'll be presented with a 'quasi-familiar' operating system
screen.  To open any menu, press the key corresponding to the first letter of that menu item.

For example - press the "F" key to open the file menu, "E" key for the edit menu, and the "V"
key for the view menu.  At the desktop with no file menus open, the "ESC" will prompt for an
exit back into the default OS you are running under.  Since it is written to perform under
DOS 3.3, I'd recommend leaving it on a DOS 3.3 formatted OS.  Those of you brave enough to 
"port" it to ProDOS 8 or ProDOS 16, I wish you luck! :)

Once a menu is open, you'll see the options under that menu and the arrow keys can then be used
to navigate.  Use the up and down arrows to highlight an option, and return to select it.  Also
when any menu is open, you can press the right or left arrow to scroll over to the next menu.

For example, you've pressed "E" and opened the edit menu.  At that point, when you press the
right arrow key, it will close the edit menu and open up the view menu, etc.  Pressing the "ESC"
key when a menu is open will close that menu and default to the desktop.

--------------------------
Starting up a new database 
--------------------------

You can select EDIT > LOAD to load in the default example database, or you can flat out start
a complete new database and write over the default one with your own data.

To start a new database, select edit>payees, and then using the arrow keys and return, you can
enter up to 12 payees particular to your monthly expenses.

At this point, press "ESC" until you are at the desktop proper and then select "F"ile and highlight
save.  This will save your newly entered payee list to the disk under the file name "A2X.DATA"

If you wish to choose a different filename, you can do so under "F"ile > Disk.  I recommend you
use that option only to save archived or backup versions of your database, as A2X is coded to 
load and save the default database "A2X.DATA"

--------------------
Entering information
--------------------

Once you have a payee list entered into the database, you can input payment data to those payees
under the "E"dit > Payments selection.  Highlight the payee and then press return to be able to
select the month you wish to input data for.  Once you have the month highlighted, press return
and you'll be able to enter the payment amount for that month.

Once you have your payments entered for each payee, I'd recommend pressing "ESC" again, until you
are at the desktop, then selecting "F"ile > Save.  Nothing is more frustrating than getting the
database all 'setup' in RAM only to have a hiccup lose it all on you.

*************************************************************************************************
**  NOTE:  **  Since I didn't technically build this program for distribution, I have foregone
a LOT and I mean a LOT of error trapping.  There is no ONERR GOTO statement, and if you crash
the software with some unreasonable input or a CTRL-C, you run the risk of losing the current
database in RAM.

The INPUTs themselves are standard Applesoft "INPUT" statements, with rudimentary string checking
to ensure something that resembles what the software is looking for.  Use caution when offered a
cursor for data input, as A2X doesn't really "watchdog" what you are putting in.
Remember: Garbage in equals garbage out.
*************************************************************************************************

---------------
Viewing reports
---------------

From the desktop, press "V" for View and then select payments.  Once here, you'll be able to select
the type of information you'd like to see.  Year to date totals, Monthly payments, etc.  You can
do no harm to any of the database from the view menu, so fool around at will.

---------------
Technical stuff
---------------

While A2X is written in applesoft, I have appended a ML routine and title page to the applesoft
component.  The locations are as follows:

$40C9 - $40FD >> subroutine to display title graphics.
$4100 - $4500 >> title page storage.

And as lame as it sounds, if you try to edit A2X (the applesoft program) your efforts will result
in non-functioning software.  With that in mind, I'm providing a quick run down of how you would
go about modifying the software without resulting in a crash next time you run it.

What you need to do is remove the ML component and restore it after editing the applesoft component.
To accomplish this, you would do the following.

]LOAD A2X

]BSAVE ML.COMPONENT,A$40C9,L$438

Then you can edit the applesoft component, such as changing the default database filename in line 100.

]SAVE A2X.MODIFIED

]BLOAD ML.COMPONENT,A$40C9

]CALL -151

*AF:00 45

*3D0G

]SAVE A2X.MODIFIED

Next you would want to perform a cold start or CTRL-OA-RESET restart of your machine and test your
newly created "A2X.MODIFIED" file.  Keep in mind, there is precious few bytes after the applesoft
component prior to the ML component, so large scale changes require you to eliminate the titlepage
routine altogether, or at the very least relocate it in RAM.  If you wish to remove the ML sub-
component completely, simply change line 225 (in the applesoft component) to a REM statement instead
of the current CALL 16585.

Now supposing you want to relocate the ML component after a large change to the applesoft component,
you must ensure that whatever page offset you place the title page at is reflected in the "ADC"
located at $40D9.  Currently it does an ADC $3D ... what this means is once GBASCALC is JSR'd to
and the zero page locations $26 and $27 are set, we load the data from ZP location $27 and ADD
$3D to it to arrive at the proper location to grab data from.  Zero page location $27 (after
GBASCALC with $00 in the Accumulator will equate to $04)  So a $3D and a $04 added = $41 or, you
guessed it, the start of our title page data in RAM.

--------------------
Author's perspective
--------------------

A2X was written to allow for tracking of my expenses.  Not everyone has 12 or less bills in any
given month.  This makes A2X quite limited in what it can do.  Enjoy it for what it is, and if you
find it useful to you in some manner, then thats an added bonus!

On the topic of writing software:  I write bloated, twisted code.  Especially in Applesoft.
GOTO's and GOSUBS are my favorite statements to use.  When doing a list of A2X, you'll see how
convoluted it can get.  If you are really set on adding something to, or changing something in
A2X, let me save you the trouble and recommend you use a different software package for
tracking expenses. :)

------------------
Want to know more?
------------------

]If you'd like to know more, by all means contact me at the following e-mail address:

omni@turbo-2.com

Later,
Craig