Under construction ...

8< -----------------------------------------------------------------

A simple example for a valid BFG source follows.

  account Purse
  account Bank-Account
  account Computer-Hardware
  account Private-Life
  account Hacking-Jobs
  account for VAT 0.16 Spent-VAT-16%
  account from VAT 0.16 Collected-VAT-16%

  @ 2004-01-10
  noVAT 100.00 from Bank-Account for Purse

  @ 2004-01-11
  gross 1160.00 from Bank-Account for Computer-Hardware

  @ 2004-01-13
  net 2000.00 from Hacking-Jobs for Bank-Account

  @ 2004-01-14
  noVAT 500.00 from Bank-Account for Private-Life

It is best for your health to think of business expenses in "gross"
mode, of private expenses in "noVAT" mode, and to think of income
always in "net" mode. (Yes, you got 2320.00 EUR for that hacking
job, but only 2000.00 EUR really belong to you; the rest belongs to
your tax office.)

If your business is as simple as this, you can already use the
scheme above to calculate your VAT declaration. :-)

If you want to know how much VAT you have to pay to the tax
office, you have to add the values of Spent-VAT-16% and of
Collected-VAT-16%. Both have opposite signs, so this is in fact
a difference.

Instead of doing this manually, we introduce an additional account -
a function declaration:

  account VAT-Difference = Spent-VAT-16% + Collected-VAT-16%

8< -----------------------------------------------------------------

The most typical cases are:
 - You buy something: gross
 - You gain something: net
 - Internal money transfer (e.g. bank --> purse): noVAT

What do they mean?

In the most simple case, you just transfer money from A to B, for
instance from your bank account to your purse:

  # Account declarations are typically in an include file, e.g.
  # "accounts.bfg". They usually do not change for many years;
  # events change each day.
  account Purse
  account Bank-Account

  @ 2004-01-10
  noVAT 100.00 from Bank-Account for Purse

This means that you have taken 100.00 currency units (for sake of
simplicity, I say "EUR" from now on) from your bank account to your
purse. From the program's point of view, you transferred 100.00 EUR
from the account named "Bank-Account" to another account named
"Purse".

Things get more complicated when value-added tax (VAT) is involved.
Consider you bought new computer hardware for 1160.00 EUR, including
16% VAT, on 11 Jan 2004. Then your input reads:

  # Remember to put all account declarations into an include file ...
  account Purse
  account Bank-Account
  account Computer-Hardware
  account for VAT 0.16 Spent-VAT-16%

  @ 2004-01-10
  noVAT 100.00 from Bank-Account for Purse

  @ 2004-01-11
  gross 1160.00 from Bank-Account for Computer-Hardware

If you run BFG on this input (see "Invoking BFG" above), you get the
following output:

  Purse
  ~~~~~
  2004-01-10                                             100.00
                                                   ------------
                            +100.00       -0.00         +100.00

  Bank-Account
  ~~~~~~~~~~~~
  2004-01-10                                            -100.00
  2004-01-11                                           -1160.00
                                                   ------------
                              +0.00    -1260.00        -1260.00

  Computer-Hardware
  ~~~~~~~~~~~~~~~~~
  2004-01-11                                            1000.00
                                                   ------------
                           +1000.00       -0.00        +1000.00

  Spent-VAT-16%
  ~~~~~~~~~~~~~
  2004-01-11                                             160.00
                                                   ------------
                            +160.00       -0.00         +160.00

The "gross" mode tells BFG that only part of the money is
transferred from the "from" account to the "for" account. Some
fraction - the VAT; default: 0.16 - is transferred to the "for VAT"
account instead.
Double-Entry Bookkeeping
~~~~~~~~~~~~~~~~~~~~~~~~
If you have not yet fed BFG with the example above, do it now.
You will notice that the account Hacking-Jobs has a negative value.
This looks counter-intuitive since you _got_ that money for your
hacking job.

If you look further you will notice that Spent-VAT-16% and
Collected-VAT-16% have the same problem, but VAT-Difference is
intuitive again: Negative values indicate that you have to pay
something.

Fortunately, the origin of those negative signs is easy to
understand: Double-entry bookkeeping shares some concepts such as
matter and anti-matter with physics of elementary particles. We just
need two axioms:

 A1: The sum of all money in the universe is zero.

 A2: The sum of all money generated in each event is zero.

In order not to get confused from an unintuitive sign, one can think
of some accounts consisting of "matter" and some consisting of
"anti-matter". In the example above, "Purse" and "Bank-Account" are
matter, "Computer-Hardware", "Hacking-Jobs", "Spent-VAT-16%", and
"Collected-VAT-16%" are anti-matter.

But when A1 holds, how can we take into account that we had some
money on our bank account at the beginning of the recorded data?
We need an additional account and an additional event. Let's say, on
2004-01-01 we had 78.90 EUR in our purse and 1234.56 EUR on our bank
account. Then the input file reads:

  account Purse
  account Bank-Account
  account Computer-Hardware
  account Private-Life
  account Hacking-Jobs
  account for VAT 0.16 Spent-VAT-16%
  account from VAT 0.16 Collected-VAT-16%
  account Previous-Year
  
  account VAT-Difference = Spent-VAT-16% + Collected-VAT-16%

  @ 2004-01-01
  noVAT 1234.56 from Previous-Year for Bank-Account
  noVAT 78.90 from Previous-Year for Purse

  @ 2004-01-10
  noVAT 100.00 from Bank-Account for Purse

  @ 2004-01-11
  gross 1160.00 from Bank-Account for Computer-Hardware

  @ 2004-01-13
  net 2000.00 from Hacking-Jobs for Bank-Account

  @ 2004-01-14
  noVAT 500.00 from Bank-Account for Private-Life

Calculating the Profit
~~~~~~~~~~~~~~~~~~~~~~
Add your sources of income, your business-related expenses and all
VAT accounts to calculate your profit:

  account Anti-Profit = Hacking-Jobs + Computer-Hardware \
                        + Spent-VAT-16% + Collected-VAT-16%

The signs of income and expenses are opposite, thus this
declaration can be read as: "How much of our income was neither
re-invested nor given to the tax office?"

Since we have added anti-matter accounts, the sign of the result is
negative. Thus I name it "Anti-Profit".

According to A1 above, the sum of all remaining accounts must give
the same number with the opposite sign - the intuitive one. This is
our "Profit".

  account Profit = Purse + Bank-Account \
                   + Previous-Year \
                   + Private-Life

Since "Previous-Year" is anti-matter, the plus sign in front of it
has the effect of a minus sign, so we can read the declaration above
as: "How much money do we have in our purse and on our bank account,
compared with the previous year, and how much did we spend on
private stuff? The sum of this is our profit."

Important note: Before you present such a calculation of profit to
the tax office, consult a tax attourney! There might be laws we are
not aware of containing detailed requirements what has to be added
up in which order. BFG can do it all, but we must feed it with the
"correct" account declarations.

Balance
~~~~~~~
This is another method to calculate the profit - and many other
things we do not really want to know. In our small example with no
in-advance payment of VAT etc. the profit calculation breaks down
to:

  account Balance-Profit = Purse + Bank-Account \
                   + Private-Life + Previous-Year \
                   + Spent-VAT-16% + Collected-VAT-16%
  account Balance-Anti-Profit = Hacking-Jobs + Computer-Hardware

If you ever need to produce balances, let a tax attourney do it for
you one time. Then, write the appropriate BFG declarations to
reproduce it _exactly_ for every account. After that, you will be
able to produce balances from the new events you entered.

Finally, here comes the complete example. To make it realistic, let
us split it into two files.

accounts.bfg:
  
  # Account declarations for Joe R. Hacker

  section "Accounts"
  account Purse
  account Bank-Account
  account Computer-Hardware
  account Private-Life
  account Hacking-Jobs
  account for VAT 0.16 Spent-VAT-16%
  account from VAT 0.16 Collected-VAT-16%
  account Previous-Year
  
  section "Calculating the VAT"
  account VAT-Difference = Spent-VAT-16% + Collected-VAT-16%

  section "Calculating the Profit"
  account Profit = Purse + Bank-Account \
                   + Private-Life + Previous-Year
  account Anti-Profit = Hacking-Jobs + Computer-Hardware \
                        + Spent-VAT-16% + Collected-VAT-16%

  section "Balance (just the profit)"
  account Balance-Profit = Purse + Bank-Account \
                   + Private-Life + Previous-Year \
                   + Spent-VAT-16% + Collected-VAT-16%
  account Balance-Anti-Profit = Hacking-Jobs + Computer-Hardware

joe-2004.bfg:

  # Business Data of Joe R. Hacker, 2004

  include "accounts.bfg"

  @ 2004-01-01
  noVAT 1234.56 from Previous-Year for Bank-Account
  noVAT 78.90 from Previous-Year for Purse

  @ 2004-01-10
  noVAT 100.00 from Bank-Account for Purse

  @ 2004-01-11
  gross 1160.00 from Bank-Account for Computer-Hardware

  @ 2004-01-13
  net 2000.00 from Hacking-Jobs for Bank-Account

  @ 2004-01-14
  noVAT 500.00 from Bank-Account for Private-Life

Debugging
~~~~~~~~~
Once you have _many_ accounts and written _many_ functions to sum
them up, the added-up profits and anti-profits might fail to match.
If that happens to you, remember A1: Since the sum of all accounts
must be zero, you must have overseen an account in the big sum.
Every account must either be contained in the profit sum or in the
anti-profit sum.

Have fun!
