Emma 0.2
Lukasz Anforowicz 1999
Thank you for your interest in Emma, a money management program for X
using the GTK+ and GNOME libraries.
This version isn't a finished program, but it already contains many
nice features:
* hierarchical accounts
* double-entry accounting
* scheduled transactions
* sorting of transactions
* the ability to calculate only wanted transactions -
possible through a python interface
* special dialog to edit python expressions
* can edit multiple transactions at once
* graphical charts
* can select multiple transactions by python expression
Although it is a stable release there are probably some bugs in it.
If you find one please mail me at <lanfor@atr.bydgoszcz.pl>
INSTALLATION
============
See INSTALL file.
USAGE
=====
Emma data files are flat, ASCII files. Your ledger accounts and
transactions can be converted to the emma format using the usual
Unix text processing tools.
LEDGER ACCOUNTS
===============
When you create a new data file you are asked whether or not to
automatically add a standard chart of ledger accounts to your
newly created file. These accounts classify your income,
expenses and assets. If you are not satisfied with the
standard 58 accounts, you can change them later or make your
own - read on for instructions.
Each data file contains its chart of ledger accounts in its header.
The first line of the file is an integer which is the number of
lines in the header and also the number of ledger accounts
currently defined. The remainder of the header consists of five
columns separated by blanks. The last column (ledger account names)
can contain blanks within the account names without the usual
quoting, parenthesizing or escaping.
Each ledger account entry has five columns:
acct_no parent_no reversed_flag unlimited_flag acct_name
Coincidentally the account number is also the line number in the
heading (if you count the first (integer-only) line as the 0th
line). The parent number is the account number of the parent
account or 0 in the case of the top level accounts, such as
Assets, Expenses, or Income.
The flags have values of 0 (for off) or 1 (for on). The
reversed flag is used to negate the result of calculations
in an account. You normally want this when dealing with
incomes and expenses - you transfer money _from_ incomes
and _into_ expenses, but you probably want income to be
positive and expenses to be negative - you do that with the
reversed flag. If it is not very clear, you don't have to
worry - accounts created automatically by a File/New command
are set up for you, so you probably won't need to change
anything. The unlimited flag usually deals with assets. When
you set this flag, all transactions influence the account.
An example will be better for this. Let's say you want to
check your income in July. You do this by typing
'month(emma.date()) == 7' (see section LIMITS). But you
probably don't want this to include your cash account -
that's where unlimited flag comes in. With the unlimited
flag set to off you would see the _change_ in the amount
of the cash account.
The account name must be unique - it is used whenever you
refer to the account.
When converting existing ledger account and transaction
data to emma0.7-3 format, there are two things to note.
If all five ledger account columns exceed 40 characters
in length, a segfault/core dump will result on loading.
If you attempt to load in a chart of ledger accounts
header with no transactions, a segfault/core dump will
result unless the last line of the data file contains
a single zero. An automatically created new data file
contains two lines with lone zeroes on them.
Most accounts have a parent - that's an easy way to split parent
accounts into smaller ones (i.e. you may want to keep track of
all your bills in one big account, but you would probably prefer
to create subaccounts named 'Telephone bills' 'Gas bills' and so on
to easily differntiate among them. If you want to split an account
into subaccounts there is a easy way to do it. Just create proper
subaccounts and then select the transactions you want to move into
one of the subaccounts. (You can select them using ``Select
Transactions..'' dialog.) Then change their from/to account to the
newly created subaccount. Do this for all the subaccounts you have
just created.
You can click your third (right) mouse button on an account. Doing that
in the amount column will pop-up a new transaction with a from_account
field set to the account you clicked on. Clicking in any other column
allows you to edit the account.
Also note that during account entries (for example while editing
the account field of a transaction) you can press PgDn to perform an
account completion. It will use an entry that matches prefix from the
new entry.
TRANSACTIONS
============
Basically every transaction records a money transfer between accounts.
So when you earn money you may want to put in a transaction like this
"amount=100.00 from=Salary to=Cash date=07/01/99 desc=Monthly pay".
(That's only a example - I don't really earn $100 a month ;-)
Every transaction has the following fields:
amount from_account to_account date description
I think the names are self-explanatory.
When working with transactions, you can select more than one of
them and then edit all the transactions you selected at once.
When you enter an 'Edit transaction...' dialog while you
have multiple transactions selected, you will notice that
some of the fields in the dialog contain ``<don't change>''
text. That happens when the transactions selected doesn't have
the same data in that field. You may want to set this data field
to something else to change it in all transactions selected
or leave as it is to leave this field unchanged. If ``<don't
change>'' didn't came up, that means that all transactions
selected have the same data in that field.
You can sort transactions by clicking on the appropriate column
header. When you click the column header for the second time
the sorting order changes from descending to ascending.
You can click the third (right) mouse button in a transactions
registry to pop-up a menu with edit/delete commands.
If you want to get some info about selected transactions, go to
the transactions menu and click ``Transactions info''. I find it
easier to select transactions I want to get info about than to
make a graphical chart for that purpose.
There is a Ctrl-N shortcut for a 'New transaction...' command.
You can setup the transactions view, so some of the transactions
will have different background. Just select appriopriate option
from menu transaction->highlightmode. The first two modes are
"none" and "striped", which I think needs no further explanation.
The third mode is "by sort order". An example will be suitable here.
If you sort by date and highlighting is by sort order, than
transactions happening on the same day will have the same color.
Try it and see if you like it.
LIMITS
======
Well, it's the main feature of the program. Using limits
you may limit transactions shown and influence accounts.
Thanks to limits you can easily analyse your income
in, let's say, last month or in every December or transactions
associated with a subaccount of another account (i.e. account
``Bills'').
Limits are implemented using a scripting language - python.
Emma defines six functions to use with limits. These are
emma.amount() - returns the amount of money transfered with
transaction being calculated
emma.acc_from() - returns the name of the account from which
you transfered the money
emma.acc_to() - returns the name of the account into which
you transfered the money
emma.date() - returns the date of the transaction in seconds
since epoch (typically Jan 1, 1970)
emma.day()
emma.month() - these return day/month/year of the date field
emma.year() in the transaction
emma.desc() - returns the description text
emma.parents(account) - returns a list of names of parent accounts
of the account specified by the name of this
account itself
Additionally there is emma.date_val(date_str) which
returns seconds since epoch for date specified by a date_str.
I added that one because of i18n support I compiled in it,
which is missing in the python module ``time''.
And there is another one - emma.register_func(name,desc) which
you would usually put in your python file after declaring some
new fancy emma functions. It makes sure your function appears
in the limit dialog. Its arguments are self-explanatory.
You can parse any python source file with -p command line argument.
This can be used to define frequently used expressions as functions.
You can import any of the python modules using -i command line argument
and then use them as usual. You can, for example, import string module.
You can edit limits by the limit dialog. You can enter expression directly
into entry field or you can use the notebook tabs and set up expression
by just clicking. Notebook deals at the moment with acc_from(),
acc_to() and date().
Ok. Now you know how to operate on limits, but what are they for? Well,
when you set global limit to non-empty expression, then only
transactions matching this expression will be shown and only those
transactions will affect accounts (with exception of unlimited
accounts). You can also use limits if you want to make your graphical
charts a little bit more complex - for example you can make two charts
- one with expenses in first half of a month and second with
expenses in the rest of a month. You can also select transactions
using a python expression.
Some examples:
emma.amount >= 100 - only transactions with amount field not less than 100
emma.month() == 1 - only transactions recorded in January (EVERY January
that is)
'Bills' in emma.parents(emma.acc_to()) - only transactions transfering
money to bills or any of its subaccounts
string.find(emma.desc(), 'book') <> (-1) - only transactions containing
``book'' in their description (this uses string module
which you have to import first using -i command line
argument)
SCHEDULE
========
Thanks to Sean there is a thing called scheduled transaction. for those
transactions that happen every month or week or so. Now, instead of
putting them in yourself every time, you can put in a scheduled
transaction once. Emma will insert them every month or week or whatever
frequency you choose.
Scheduled transactions look the same as normal transactions, but they
have a slightly modified meaning of the date field and have additional data -
frequency and prompt. The meaning of frequency is obvious - it tells how
often the transaction happens. The prompt tells emma whether to ask
(whenever the transaction is actually inserted) if you want to change
something or even cancel the transaction.
CHARTS
======
Graphical charts help you analyse your accounts. To use charts you have
to setup the chart data first. There are three tabs in the setup chart
dialog. First is ``Chart type'' which is there for future enhancement only -
you can only choose bar chart. The second tab is named ``Accounts''. Here
you enter which accounts to include in the chart - the purpose of buttons
in this tab is obvious. The last tab is ``Groups''. It let you make more
than one chart actually. You may view your expenses in first half of the
year and in the second one. All you have to do is to set up groups - only
transactions that match the python expression of the group are taken into
account when evaluating account's amounts.
How the program draws the charts is subject to change - there is a
project called ``Guppi'' which aims to develop an embedable charts viewer.
PREFERENCES
===========
You can setup your own preferences through a preferences dialog, available
in file menu. At the moment you can set a file to open at startup with a
default limit and depth to which accounts are expanded when a file is open.
Note that specifying a file to open on the command line will override
preference settings.
Additionaly emma now remembers the size of columns in the accounts tree,
transactions registry and schedule list as well as the sorting order.
TIPS & TRICKS
=============
- if you miss a reconcilation feature you can create a subaccount of your
checking account, name it ``reconciled'' and there it is - you can
reconcile your emma data with what the bank thinks it schould be
(just move reconciled transactions one level deeper - to the
subaccount you have created)
- I have included a sample emma.py in this distribution. It is in your
/usr/share (better place than before) directory. It should be parsed
automatically at startup. If it isn't (my fault :-( , than copy it
to ~/.emma.py, and it will be parsed at startup for sure.
It contains many functions I find useful. Take a look at that file -
I think everything is self-explanatory. And one more thing -
functions from this file will register themselves so they appear
in the limit dialog in the functions tab.
- Note that specyfing '-' (single dash) as a file to open results
in reading from standard input.
THE END
=======
Thank you for your interest in Emma, I hope you enjoy using it.
---
Lukasz Anforowicz
mailto:lanfor@atr.bydgoszcz.pl
