Misery HOWTO

Misery is accounting software for clubs, holidays, expeditions etc. 

It is used as a 'compiler' to process the transaction and config files
into a set of HTML accounts.

The data is stored in files in a set of directories.
The following directories must exist:
config - config for units (currencies, tallies)
initial - every account (people, expense types, bistromatics events) must be listed in here
splits - allocations of how one account is divided into others
vaccounts - virtual accounts (collecting accounts in 'initial' directory)
vaccounts_late - virtual accounts calculated from other virtual accounts
html - output directory for calculated accounts

An example is helpful here to explain.

lets say we have 4 people on a trip, for a few days, who need to
account for accommodation, food, transport, and meals out on 2 nights. 
You would need this set of accounts in 'initial':
andrew, brian, carol, dave, accommodation, shopping, transport,
meal-sat, meal-sun. The filenames can be anything but should not
contain spaces, and it's a good idea to keep them short but
descriptive. These names are called 'short-names'. 

Every payment or owing on the trip is recorded in one of these account
files, and allocated to another.

Files of the same short-names in the 'splits' directory describe how
things are divided between people (or other accounts if doing
something more complex).

The data is processed by running 'misery' in the top of the directory
tree. 

Fundamentally that's it, but this simple structure is powerful and
allows for complex accounting. More complex examples are given below. 

=================
Files and Formats
=================

'config' directory
==================

config/title  (required file)
This file contains a single line giving the overall title of the
accounts, (e.g. '2012 Skitrip', or 'Fencing club accounts - 2009/2010')
This name appears at the top of the accounts summary page in the output.

config/units  (required file)
This file defines currencies or other units of accounting. As well as
defining normal currencies you can define the price of 'a campsite
night' or 'a beer', and allocate the costs of 6 nights, or 8 beers, 
directly from counts.

For simple single-currency accounts this file may just contain one
line, naming the currency.

The format of each line is:

name (for default currency, 1st line only)
or:
unit-char,name,factor
or:
unit-char,name,factor,in-terms-of

where:
  unit-char is a single character identifying the unit being defined
  name is a textual name for the unit
  factor is a decimal number saying how many default
    units there are in the new unit being defined
  in-terms-of is a single unit character (say X) defined earlier
    in the file.  If this is specified, factor specifies
    how many X units there are in the new unit being defined.

Example:
Simple single currency accounts:
USD

Dual-currency accounts with campsite nights defined:
GBP
E,EUR,0.85
C,BaseCampNights,8.00,E

These define GBP as the default units if simply an amount is given, that
'E' in an amount indicates euros, and each is worth 0.85 GBP. And
finally that basecamp nights are indicated with the letter 'C' and are
are worth 8 Euros each.


'initial' directory 
===================

This is the main directory where each account is named, and described,
and all the transactions are recorded.

Each account is a person or pool, or bank account, or category
(transport, food), or meal-event, or bar-session. Anything you wish
to make payments from or allocate payments/costs to, in fact.

For each account credits on that account (e.g. payments by people) are
positive, debts on that account (e.g. owings by people) are negative.
This works for everything except bank-accounts and cash kitties which
have the opposite sense (see '=' below for how to deal with this).

The short-name for the account is given by the filename. The long name
for the account, it's characteristics and transactions are defined in
the file.

The file format is
Long Name
Option lines
Transaction lines

Files must not contain blank lines.

The Long Name must be the first line, and is shown in the HTML accounts output.

Options
-------

Option lines must come after the Long Name and before the transaction
lines.

There are two options:

1) group
The format is: 
group=Description

'group' must be lower case. Description can have spaces in it. 

An account will only appear on the summary sheet if it has a group set
here. It will appear under the 'Description' given. All accounts with
the same 'Description' are grouped together in the output.
These 'Description' groups are listed in alphabetical order.

2) must_be_zero
the format is:
must_be_zero=true

This specifies that this account should sum to zero overall. If it
does, then 'OK' is printed (in green) on the summary sheet; if it
doesn't, 'Not correct' is shown (in red).

Normally accounts which are people do not have this option set, whilst
accounts which are categories (accommodation, shopping, lift-passes,
gear-pool, kitty) do have it set.

'must_be_zero' must be all lower case. You cannot use 'yes' or '1'; it
must be 'true'.


Transactions
------------

Each line represents a payment or notional payment/debt.

The format is:
YYYY-MM-DD,short-name,amount,description

where:
  YYYY is the year
  MM is the month
  DD is the day
  short-name is the short name of the account (creditor or debtor)
  amount is the sum involved (e.g. 23.40, E3.40, -E7.60)
  description is a text string describing the transaction

Note that amount must be given to 2 decimal places (otherwise
you get a 'malformed line' error) i.e. 11.00 not 11

An account line may not contain a space after a comma, nor two
consecutive spaces. These will stop it being parsed properly. 

Dates are always given in ISO format to avoid confusion and allow
correct sorting.

Amount can be prefixed by a currency indicator, which is the 'unit
character' given in config/units. Positive values are payments made by
the person/from this account. Negative values are owings of this
person/debts on this account.

Every short-name referred-to in a transaction must appear as an
account file in 'initial' (except 'phantom').

The short-name can be prefixed by '=' or '!'. 

'=' means that rather than adding the transaction to one account and
subtracting it from another, it is added (or subtracted) from both.
This is used for accounts which have the opposite 'sense' from normal,
and the usual example is bank-accounts.

'!' means that the transaction is only added to the account of this
file, not to the account named in the transaction. This is normally
used in combination with the special account 'phantom' to import
owings/state from previous accounts. 

You can add 'FIXME' to the end of any transaction line to indicate
that it is not finalised. You can also add it to the account Long Name
on the first line. See 'Output' for details.  

Examples:
Most 'category' accounts are simple and just have a name, a group and
a must_be_zero option:

Shopping
group=Expenses
must_be_zero=true


'meal-events' accounts tend to have the amount owed by each
participant in. (The payment(s) go in the
individual's accounts). They usually have an associated 'splits' file
to ensure things add up/divvy up tips etc. If the meal is being split
evenly then the transactions are not needed - only the splits file. 

Food for lunch, Saturday
group=Meals and drinks
must_be_zero=true
2012-02-14,dave,9.95,Burger
2012-02-14,andrew,10.50,Pasta+beer
2012-02-14,carol,17.95,Burger+Beer

Personal accounts usually contain all the payments made by that person
Dave Scroggins
group=Cavers
2012-02-13,shopping,42.00,Shopping on the way there
2012-02-12,carol,139.49,Carol's new harness (bought by Dave)
2012-02-12,lunch-sat,45.12,Lunch at the Pub
2012-02-14,transport,67.65,Fuel
....

Example with '=' to reverse account sense
Dave Scroggins
group=Members
2012-02-12,=bank-account,30.00,Membership cheque

This means that 30 is added both to Dave's account (payments by dave
are positive on his account, as normal), and 30 is added to the bank account
(payments into the account are positive). So generally every occurrence
of payments to account 'bank-account' will be written '=bank-account'
to make everything make sense. 


Phantom example with '!'
Dave Scroggins
group=Members
2012-01-01,!phantom,-83.24,Owings brought forward from last year

This means that 83.24 appears on Dave's account as owed, and does not
appear anywhere else. 


'splits' directory
==================

Splits are used to allocate accounts across other accounts. It can be
done equally, or with factors (e.g. by number of days stayed, or
factors to do with shared transport).

There is normally a split for each 'category' account and one for each
'meal-event' account.

Meal-events usually have an associated split to ensure that costs are
shared entirely amongst those present e.g. when when simply splitting
the bill, or dealing with the common problem that things don't quite
add up, or allowing for taxes and tips.

The format is either:
short-name
or:
short-name,factor

where:
short-name identifies an account to be in the split;
factor is an integer or decimal number that specifies
  what proportion to assign to this account.
    If omitted, the factor is one.

short-name must appear in accounts

Examples:
simple 'accommodation' account split between all present:
The file splits/accommodation contains:
andrew
brian
carol
dave

indicating that this cost is split evenly between them

If they stayed different numbers of nights it might look like
andrew,6
brian,6
carol,6
dave,4

splits files can be links on Unix. This is useful if you have a
complex splits file used to allocate various accounts - duplicating it
could lead to errors. 


vaccounts directory
===================

This is for 'virtual accounts' which are accounts made by adding others
together, or for displaying them all on one page.

The format is
Long-Name
Options lines
short-name lines


Example:
A common use is listing all the club member's debts/credits.
Debtors and creditors
group=Totals
andrew
brian
carol
dave

This will generate an entry on the summary sheet called 'Debtors and
Creditors', and that page lists all the owings. 

putting a '-' in front of an account means that it is subtracted from
the total, not added. 


vaccounts_late directory
========================

This is exactly like vaccounts, but can also use the names of accounts
generated in vaccounts. This is often useful for calculating final
errors and checks.


Output
======

Output is generated in the 'html' directory. It is static HTML, in
table form, suitable for copying to a web-server for everyone to easily
check their accounts. It can also be browsed locally of course to
check the results.

There is a summary page 'index.html' listing all the accounts with a
'group' option. With links to the detailed breakdown for each account. 

Colouring is used to make the results clear:
 Green means 'positive' or 'OK'. red means 'negative' or 'Not correct'.
 Yellow means 'FIXME' has been put in the accounts somewhere. 'Needs
  attention' will be added for this entry on the summary page.

FIXME can be added to any transaction line or account Long Name first
line to indicate that it still needs checking/work.

output is controlled by adding 
group=Description
to each initial/<account> file

'group' must be lower case. Description can have spaces in it. 

An account will only appear on the summary sheet if it has a group set
here. It will appear under the 'Description' given. All accounts with
the same 'Description' are grouped together in the output on the
summary page.
These headings are listed in alphabetical order.

If the must_be_zero=true option is set for an account then 
it is listed as 'OK' (in green) (or 'Not correct', in red) on the summary page.

Icons are shown in the detailed breakdown pages. A smiley indicates
that a must_be_zero account did indeed sum to zero. A padlock
indicates a fixed, listed transaction, as opposed to one that was calculated. 
An exclamation mark appears on a phantom entry (brought in from
outside the accounts).

A transaction of '0' will not appear in the final output, but will be
tallied in the total transactions printed in 'Emitted nnn
transactions' when misery is run. 

4 standard files are needed in every html output directory for the icons and
CSS to work. These are:
exclamation.png
smiley.png
padlock.png
accounts.css

You need to copy these in to your html directory manually at the
moment.



meets directory
==============

'meets' is a special case account mostly useful to the authors of the
software - Cambridge University Caving Club. It understands special
rules about a trip (called a 'meet'), about how to allocate fees for
breakfast, dinner, meet fees, gear hire , different fees for drivers
etc.

It would be useful if this specialised logic could be made more general
for similar 'typical cases' for other groups. That would be a task for
future development. 

The values for the various fees are set in a files called 'meets' in
the 'config' directory.

driver_fee=17.00
non_driver_fee=21.50
light=0.50
gear=1.00
srt=4.50
breakfast=1.50
dinner=2.00


Each file in 'meets' has this format
Name line
Date line
Meet transaction lines
...

The name line is of the form 'name=long name'. The 'long name' is used in
html output and may contain spaces..

The Date line is of the form 'date=YYYY-MM-DD' (ISO date format). The
date is used for all transactions in this file.

Each meet transaction line summaries the transactions of a person on
the meet (who must exists as an account).

The format is 
name [driver] [keyword value] [keyword value] [keyword value]

i.e an account name followed by an optional 'driver' flag and optional pairs of
keywords and values. Each keyword matches an item listed in the config/meets
file, or is a normal account name. Values can either be amounts or
counts, depending on the keyword.

If just a name is given then a meet-fee is added, as are two
breakfasts and one dinner.

The 'breakfast' and 'dinner' items are added the number
of times specified unless explicitly set to 0.

If 'driver' is on a line then the 'driver-meet-fee' is added,
otherwise the 'meet-fee' is added. If 'special-meet-fee' is given then
that value is added instead of either 'driver-meet-fee' or 'meet-fee'.

If 'fuel' is entered on a line then 'driver' is assumed.

If an account name is used for the keyword then the transaction is
applied to that account as usual (using the date specified for the
meet).

Example:
name=Swales II
date=2010-01-29

dave driver fuel 43.12 special-meet-fee 8.00
alex driver
carol
ben food 43.00
david light 1 gear 1
andrew breakfast 1

This means that on this meet ('Swales II' on 2010-02-29):
dave is charged the special-meet-fee of 8.00, breakfast x2 and dinner
alex is charged the driver-meet-fee, breakfast x2 and dinner
carol is charged the meet-fee, breakfast x2 and dinner
dave's food and ben's fuel costs are added to the 'Swales II' account
david is charged the meet-fee, breakfast x2, dinner, one light rental
  fee and one gear rental fee
andrew is charged for only one breakfast, the meet-fee and dinner