$Id: 0-StartHere.txt,v 1.2 2001/07/14 06:28:38 tundra Exp $

                          INTRODUCTION TO HB
                          ==================

(BIG HINT: You do not care about HB as a useful program (probably),
but if you're trying to learn Python, it may help.)


What Is HB?
===========

HB is a fairly simple, but not trivial, Home Budget management program
written in the Python programming language. (You'll need a version of
Python for your operating system to run hb.py, the actual HB program.
You can get this at www.python.org.)  HB is not going to replace
Quicken or MS-Money any time soon, but as the next section explains, I
had a good reason or two for writing it.


Why Did I Write It?
===================

Two Reasons:

Years ago - decades, actually - one of the very first programs I wrote
in BASIC was the inevitable Home Budget program.  In those days it was
written in MBASIC on a TRS-80 Model 1 talking to cassette tape for
storage.  Over the years the program evolved first to floppy disk,
then to MS-DOS, then to compiled QuickBASIC.  It was never a very well
written program in the first place and all that evolving didn't make
it any prettier.  It was a pain to maintain, but I actually *liked*
using it.  You see, I hate all the complexity that GUIs brought to
personal computing.  My finances are not like John D. Rockerfeller's
and I don't need a whiz-bang GUI, scratches-your-back-while-it-does-
your-taxes program just to figure out how much money I'm going to owe
at the end of the month, fer cryin' out loud.  So, one reason I did HB
was to replace my old piece-of-crap BASIC program.

The (much more important) other reason I wrote HB was because I wanted
to learn the Python programming language.  This is the reason you care
about HB at all, if you do (because only 1 out of 280 million
Americans (me) is actually going to use it for its intended purpose).

I'm a Computer Scientist by training and a lot of graduate school 
(1 - M.S. and 1/2 Ph.D. ;) stuff I did involved languages and compiler
design and I just *love* fiddling around with new computer languages.
Over the years I've programmed some or a lot in: BASIC, Assembly
Languages, C, C++, LISP, FORTRAN, PL/M, PL/1, AWK, Perl, Visual BASIC,
Java, and Forth. When I first started playing with Python, I realized
that this was one of the very coolest languages I'd ever seen.  It is
good for just about everything (except, probably, writing operating
systems), promotes good programming style, causes you to write lots of
good code *fast*, and, well, it's just plain FUN.

The problem is that, while you can learn the basic syntactic elements
and get a sense of semantics of a language from a tutorial, you really
don't "get it" until you write a non-trivial program.  In my
experience, this is the only way to being learning the "idioms" of a
language.  OTOH, if the program you start with is trying to solve too
complex a problem, you'll end up spending all your time on the problem
not the language.  For instance, you probably do not want to make your
first Python program do non-linear differential equations (unless you
happen to be a whiz at them, in which case, you have my condolences ;).

So, I decided to reimplement my old home budget program in Python.
The program is solving an intellectually simple problem, but it is
non-trivial in the sense that it requires I/O (disk, printer,
keyboard), needs to manage a display space, needs to parse user input,
and so on.  Along the way, I added some "nifty" features like unlimited
Undo capability and a table-driven command interpreter that's kinda cool,
if I do say so myself.


Why Am I Distributing It?
=========================

As I was writing (and rewriting, and rewriting, and ...) HB, it
occured to me that other people might be able to learn Python a little
faster if they had a complete application to look at.  So, I went back
and heavily commented the code (about 50% of hb.py is *comments*),
wrote these docs and decided to make it available to anyone who wanted
to paw through it.

It also occurs to me that, having misspent my youth in academics,
people teaching Python programming might want to use HB for class
work.  This would make me very happy.  Too much of what is taught in
school involves "toy problems" that never get much beyond the trivial
example stage.

IMPORTANT NOTE: This is not intended to "teach" you Python or
programming or anything else.  The idea is that you already know how
to program and have a basic understanding of how Python does things.
The point here is to "Put It All Together" and show an application of
all the pieces as an integrated whole.


Program Features
================

This is a pretty straighforward Budget Management system.  Nothing too
esoteric here, really:

Unlimited Different Budgets
    Up to the limit of your disk space.

Unlimited Accounts 
    Well, the limit is what you can squeeze on a single screen.

Unlimited UnDo
    Limited by memory - if you run out of UnDo stack,
    you're using HB for WAY too complicated budgets ;)

Prints Reports To Printer (Win32 Only) Or Disk File (All OS)

Handles Monthly "Burn Rate" For Each Account

Pay, Debit, Credit, And Transfer Funds

Balance The Budget

Read And Write Budget Files


Code Features
=============

This is probably what you really care about:

Uses Every Major Python Data Structure
    Tuples, Tuples Of Tuples, Tuples Of Tuples Of Tuples, Lists,
    Dictionaries, and Objects

Has Mixture Of OO And Procedural Code
    Python is *really* good at this.

Uses A Regular Expression For Input Validation

Uses 'eval' To Demonstrate Runtime String Execution

(Some) Exception Handling

Disk, Keyboard, And Device I/O

Code Is Completely "UnStrung"
    There are no literals (other than newlines) embedded in the code
    which makes maintenance and internationalization very simple.

Completely Table-Driven Command Interpreter
    Kinda cool, actually.  A little complicated at first, but it makes
    adding new features a snap AND prepares the way for mating the program
    to a GUI if you must have one in your life.

Stack-Based Context Management And UnDo Facilities

LOADED With Explanatory Comments So You Understand What's Going On


Caveats And Acknowledgements
============================

I am an experienced programmer, but not an experienced *Python*
programmer.  This means that not everything in HB is necessarily good
Python - I hope it is, it probably mostly is, but it probably also has
some warts.  If you *are* an experienced "Pythonista" and you see
something in HB that makes you just wince, send me an email and let me
know what needs fixin'.

I also want to take a moment and thank the many friendly people of
comp.lang.python who answer my many stupid questions promptly and
correctly both on the newsgroup and privately.

Also, a big "Thank You" to www.diveintopython.org for one of the best
language tutorials I've ever seen.  It is a work-in-progress, but a
"must" if you are learning Python.

Finally, a huge thanks to GVR and the many people who designed,
implemented, and refine one of the slickest programming languages
around...


How To Proceed
==============

All the files in HB documentation directory begin with a number.  All
you have to do is read them in order.  This document begins with '0-',
so the next thing you need to read is the one starting with '1-' (the
HB Licensing document - you MUST read and agree to those terms to make
use of HB in any way)... and so on.


Political Statement
===================

Some people view Open Source and Freeware as Marxists:

    "Code should be made available because it belongs to everyone
     and there is a moral imperative to make it freely available."

In other words, "From each according to their ability, to each according
to their need."  (This really worked well in the 20th Century, don't you 
think?)

This is drivel of the worst kind. If you don't understand why, read
"Economics In One Lesson" by Hazlitt, "The Road To Serfdom" by Hayek, and
"Capitalism, The Unknown Ideal" by Rand.  I view HB as a Libertarian:

     "HB is my property (well, the property of my corporation).  I
     created it on my own, so it belongs to me.  I make it freely
     available because *I can* and *I want to*.  The *only* way I
     make it available is if you agree to my licensing terms.  If
     you do not, don't use HB.  I have no moral obligation to 
     make it available at all, I do it because it suits me."


Questions Or Comments?
=====================

Send 'em to: tundra@tundraware.com