$Id: 2-HowToUse.txt,v 1.4 2002/09/04 23:29:21 tundra Exp $

                            HOW TO USE HB
                            =============

Before you dive into the code, it's useful to get a basic understanding
of how HB works from a user's point-of-view.


Budget Files
============

Before starting HB, you have to create a budget file with any old
editor (one of the ways you might extend HB as a programming exercise
would be adding the ability to create new budgets).  This file
is organized like this:

Cash        3000        2343.44
Books       100         55.41       
Creditcards 0.0         562.8      
Dsl         39.0        0.0         
Rent        1000.0      0.0         
Savings     200.0       4320
Utilities   160.0       0.0         


The first column is the the account Name.

The second column is the amount you add to that account (the "Burn Rate")
every month.  For example, the Cash account has a burn rate of 3000 -
that is presumably how much money you bring in to that budget every
month.

The third column is the current account Balance.  You can either set
this to be 0 intitially, and enter the amounts through HB, or prime
the Budget with the amount you want.

The columns should be separated with spaces and terminate with a
single new line.  HB does very little checking on the sanity of the
budget file, so mis-formatting this file will blow up the program.
Waddya want fer free?

You then have to make one edit to the hb.py file and tell it where
it can find its budget files.  At the top of the program a very few
variables that users should change.  You'll see something like this:

BASEDIR  = getenv("HOME") + "/"
BUDFIL   = "hb.txt"  

This says that the directory which holds HB budget files is the
current directory, and the default budget files is called 'hb.txt'
which is what HB will load when it starts up.


Starting The Program
====================

The usual 'python hb.py' will work on all systems.

Under Unix, make sure the first line of the hb.py file correctly
describes where python can be found.  Then make sure hb.py file
permissions are set to mode 755.  Finally, make sure the hb.py
file is in a directory somewhere in $PATH.  You can then run
the program by just using 'hb.py'.

There are two optional command line arguments:

      -d Name of directory where budget files live
      -f Name of desired budget file


Running The Program
===================

Once it starts up, HB will show you a screen something like this:

------
              HomeBudget - Version 1.83 Fri Jul 13 23:10:33 2001             
           Copyright (c) 2001, TundraWare Inc.  All Rights Reserved.           
                                 Budget: hb.txt                                




Books       55.41       Creditcards 562.8       Dsl         0.0         
Rent        0.0         Savings     4320.0      Utilities   0.0         
-------------------------------------------------------------------------------
Total Cash: 2343.44    Total Debits: 4938.21     Available Cash: -2594.77



<!>abandon  <B>alance   <C>redit    <D>ebit     <L>oad      <M>onthly
<P>ay       save+<Q>uit p<R>int     <S>ave      <T>ransfer  <U>ndo

Command?
-----

The 'hotkey' to invoke a command is delimited by <>.

If you key in an EOF at any point, the program will exit w/o saving

If you key in a Ctrl-C, it does nothing under Unix, and aborts the
program under Win32.

If you hit Enter to any prompt (blank line) the program will abort
the transaction underway and take you back to this main screen prompt.

The columns above the separator line are your accounts.  The sum of
all these accounts is your Total Debits.  

Available Cash = Cash-Debits  In this case you're running a big deficit,
so you better either get more Cash, or quit reserving so much in Savings ;)


Here's roughly what the commands do:

<!>abandon   Exit w/o saving and recalculate budget.

<B>alance    If you have more Cash than Debits, put the excess in Savings.
             If you have more Debits than Cash, move money from Savings into
             Cash.  This feature requires there be a Savings account.  If
             there is not one, the feature will not appear on the toolbar.

<C>redit     Add funds to an account.

<D>ebit      Remove funds from an account.  If you just hit Enter, HB
             understands this to mean you want to debit the entire
             current balance - i.e. Set the account to 0.

<L>oad       Load a new budget.  If you just hit Enter at the prompt,
             it will reload the budget you are working on.

<M>onthly    Increase each account by its monthly Burn Rate amount.
             You typically do this at the beginning of a month in anticipation
             of getting paid and having your recurring bills show up.

<P>ay        Each account reflects an indebtedness or liability.
             When you pay from an account, the account balance is
             reduced by the amount you select and Cash is decremented
             accordingly (Unless your try to pay from the Cash account -
             then it only subtracts the amount once.)  When prompted
             for an amount to pay, if you just hit Enter, HB understands
             this to mean you want to pay the entire amount in that account
             and does so.

save+<Q>uit  Ummm, it saves the current budget and quits the program.

p<R>int      Print a report to the last used reporting file/device.
             Initially, by default, under Win32, this is LPT1: Under
             any other OS, it is a file called 'HB-Report.txt'.  But,
             when you select this option it will prompt you for the
             name of an output file or device.  If you just hit Enter,
             it takes the default, otherwise you can enter whatever
             you like.

<S>ave       Save the current budget, but don't exit.

<T>ransfer   Move funds from one account to another.

<U>ndo       UnDo the last thing you did.  You can keep UnDoing things
             until HB is back to the point at which it started.  UnDo
             has no effect for Saves or Prints, but it does return to
             the state prior to loading a budget.  Try it - it's fun.




