Contents
~~~~~~~~
Invoking BFG:
 - Options
 - Examples

The Language:
 - Declarations
 - Events


Invoking BFG
~~~~~~~~~~~~
  bfg [options] [file]

Options:

  -o, --output=<file>
      Name of output file (default: stdout)

  -s, --summary
      Don't output the calculations; just show the results.

  -c, --current
      Suppress output of calculations with the same comment that
      sum up to zero.

  -x, --tex
      Format the output as (La)TeX source.

  -t, --time-period=<specification>
      Take only events into account which fall into the specified
      period. In <specification>, a four-digit number specifies a
      year, a smaller number a month, a roman number a quarter of a
      year. (Examples: -t 2004, -t 2004-3, -t i/2004)

  -d, --data=<list>
      <List> is a comma-separated list of account names.
      Produce a file that contains the daily values of the given
      accounts as functions of the time (days from the Epoch) in
      a format suitable as input for Gnuplot.

  -g, --gnuplot[=<file>]
      Together with `--data': Call Gnuplot to display the data.
      If <file> is given, it is used to store the commands given
      to Gnuplot.

  -f, --force
      Do not suppress output in case of an error.

  -h, --help
      Output help and exit.

  -V, --version
      Output version information and exit.

If the input file is not specified, BFG takes stdin.

Examples:

  bfg joe-2004.bfg -o joe-2004.txt

      Take the input file joe-2004.bfg and dump all accounts to the
      output file joe-2004.txt (which can then be emailed to the tax
      attourney).

  bfg joe-2004.bfg --summary -o joe-2004.txt

      Same as above, but output only one line for each account
      containing the sum.

  bfg joe-2004.bfg --summary | less

      Same as above, but pipe the output to `less' instead of
      storing it in a file.

  bfg joe-2004.bfg --data=Income,Expenses -o joe-2004.data

      Create a file `joe-2004.data' containing three columns of
      numbers:
       - date (days from the Epoch)
       - current balance of the account "Income"
       - current balance of the account "Expenses"
      The output will look similar to this:

        #    Day      Income    Expenses
           12424        0.00       12.50
           12425        0.00      111.49
           12426     1000.00      111.49
           12427     1000.00      111.49
           12428     1000.00      111.49
           12429     1200.00      911.49

      Programs like Gnuplot can produce nice curves from this and
      export them to LaTeX, PostScript, or whatever you like.

  bfg joe-2004.bfg --data=Income,Expenses -o joe-2004.data --gnuplot

      Create the file sketched above and invoke Gnuplot to display it.
      (BFG creates a temporary file containing the necessary Gnuplot
      commands.)

  bfg joe-2004.bfg --data=Income,Expenses -o joe-2004.data \
      --gnuplot=joe-2004.gnuplot

      Same as above, but keep the file with the Gnuplot commands as
      `joe-2004.gnuplot'.

  bfg joe-2004.bfg --data=Income,Expenses --gnuplot

      Create the data file as a temporary file, let Gnuplot display
      it, and remove it afterwards.


The Language
~~~~~~~~~~~~
Every line can be
 - a comment,
 - a date specification,
 - a declaration, or
 - an event.

Long lines can be broken using `\' as the very last character of a
line:

  account Foo = Bar + Baz \
                - Fred + Barney

Comments start with `#' and extend to the end of the line:

  # I hate bookkeeping

Use the `@' sign to speficy the current date:

  @ 2004-05-18

This affects events that come below this line.

Declarations:

  include "my-declarations.bfg"

      Read input from that include file. Can be nested.

  alias Foo = Bar

      Accept "Foo" as an alias for "Bar". This works in almost every
      context.
    
  format date = "%d.%m.%Y"

      How do you want to input your dates? Specify it here.
      As in date(1), %d means the day, %m the month, %Y the year.
      Years have four digits. BFG might barf if you use dates before
      1970 or after 2038.

  format TeXdecpoint = ","
  format TeXthsep = "\,"

      In (La)TeX output, use the specified strings as the decimal
      point / thousand separator.

  default VAT = 0.20

      Set the default VAT to 20%. (Default is 16%.)

  section "Balance"

      For output formatting. When accounts are output, you can group
      them to named sections.

  account Income
    
      Declare an account (i.e. a container for money - a variable)
      with the name "Income". About everything except the space
      character is okay in account names. An underscore ("_") will
      be translated to a space in (La)TeX output.

  account 8400 Income
    
      Declare an account with the short name "8400" and the long
      name "Income". In principle, there is no difference between
      both names; you can use either of both in events (see below).

      Professional bookkeepers love account numbers. This is what
      this is for.

  account for VAT 0.16 Spent_VAT_16%
    
      Declare an account named "Spent_VAT_16%" and tell BFG to use
      this one for collecting the 16% VAT you paid to others.

      Sometimes you pay other percentages of VAT to others. In that
      case you need more than one "for VAT" account.

      If you do not need to care about VAT, just forget it and be
      happy.

  account from VAT 0.16 Collected_VAT_16%
    
      Declare an account named "Collected_VAT_16%" and tell BFG to
      use this one for the 16% VAT you got from others.

      If the percentage of VAT you take from others varies, you need
      more than one account of this sort.

  account for opening Previous_Year

      Money that is on an account at the beginning of the year must
      be recorded to come from an account. With this declaration you
      tell bfg that the account "Previous_Year" is used for that
      purpose. When calculating the sum of all money that was
      transferred from/to an account, bfg excludes money transfer
      with the "for opening" account.

  account Profit = Income + Expenses \
                   + Spent_VAT_16% + Collected_VAT_16% \
                   - SomeOtherAccount

      Declare a function "Profit" returning the expression on the
      right hand side of the `=' sign. Valid expressions are sums
      and differences of other accounts.

      (You would have intuitively recognised the meaning of the `\'
      sign even if I would not have it explained above. Keep this in
      mind for your next discussion about intuitive user interfaces.;-)

      Due to the nature of double-entry bookkeeping you will need
      the `-' sign only in a few exceptional cases. Almost
      everything is covered by the `+' sign.

      In case you miss a `*' sign for calculating VAT on the fly or
      whatever: Just forget it. The tax office will not accept it.

      The whole magic of double-entry bookkeeping can be written
      down as a set of function declarations of this type. By
      defining the "correct" functions, you can use BFG to create a
      balance that will answer all those nasty questions of your tax
      office.

  account for stoneage Silly_Sum \
    = Collected_VAT_16% + Expenses + Previous_Year

      Economists do not like negative numbers. With this declaration
      you tell bfg to sum up the other accounts not the natural way,
      but to sum up all positive values, display that, sum up all
      negative values, display that, and finally calculate the
      difference. I see no use of this, but this is how it must be
      displayed on some forms.

Events:

  <mode> <value> from <account> for <account> [VAT <number>]

Modes:

  gross

      Subtract the given amount from the "from" account.
      Add the VAT to the "for VAT" account.
      Add the remaining money to the "for" account.

  net

      Subtract the given amount from the "from" account.
      Take additional money - the VAT - from the "from VAT" account.
      Add the sum to the "for" account.

  antigross

      Add the given amount to the "for" account.
      Subtract the VAT from the "from VAT" account.
      Subtract the remaining money from the "from" account.

  antinet

      Add the given amount to the "for" account.
      Add additional money - the VAT - to the "to VAT" account.
      Subtract the sum from the "from" account.

  noVAT

      Subtract the given amount from the "from" account
      and add it to the "for" account.

There are cases where the VAT factor varies. For instance when you
buy books in Germany, VAT is only 7% instead of 16%. For such cases,
the syntax for the event is

  <mode> <value> from <account> for <account> VAT <factor>

and you need an "account for VAT" for that factor if you want to
record the VAT.
