INTRODUCTION

Bo-Keep helps you keep your books so you don't get lost.

It provides to users simple custom entry interfaces for an accounting
system to speed up data entry and reduce errors.

Particular custom interfaces are provided by Bo-Keep plugins. Support
for working with different accounting programs is provided by backend
plugins. You can learn more about developing Bo-Keep plugins by
reading README_plugin_api.txt .

Bo-Keep is written in python and has been developed and tested on
GNU/Linux systems. Reasonable attempts have been made at portability,
so it will probably work in other places where the dependencies are
available with minimal effort.

Bo-Keep depends on and requires PyGTK (http://pygtk.org/) with Glade
support for its user-interface and ZODB (http://www.zodb.org/) for its
data storage.

Bo-Keep is most useful with a backend plugin to connect it to a real
accounting program, currently only a GnuCash (http://gnucash.org)
backend plugin exists, so installation of GnuCash is recommended as
well. (other paragraphs in this README will assume it is installed)
You'll need GnuCash 2.4.0 or later with python bindings enabled.

CHECKING INSTALLATION

Installation instructions for PyGTK, ZODB, Bo-Keep, and GnuCash under
GNU/Linux are provided in README_install_GNU_slash_Linux.txt. (an
installed python interpreter is assumed)

Here's a post-installation run-through for GNU/Linux:

After installation, it is assumed that pygtk, zodb, bokeep, and the
gnucash python bindings are either installed in locations where the
python interpreter will find them or specify via PYTHONPATH . To test
this is all right with the python interpreter
$ python
>>> import gtk
>>> import persistent
>>> import transaction
>>> import gnucash
>>> import bokeep

The main executable bo-keep should either be available via the PATH
environmental variable or the full path to it known.
(test availability via PATH by running
$ which bo-keep )

So, we run 

$ bo-keep
or
$ /the/path/to/bo-keep

You might also be able to run bo-keep via your desktop environment
application launching menu, as bo-keep installs a bo-keep.desktop in
/prefix/share/applications.

CREATING A CONFIGURATION FILE

If you haven't run it before, bo-keep will inform you that it would
like to create a .bo-keep.cfg file in your home directory. You can
also provide your own bo-keep configuration file by using the -c flag
or by having a .bo-keep.cfg file in your current working directory.

CONFIGURATION DIALOG

After you say yes, bo-keep will launch its configuration dialog. You
can return to this dialog at anytime via the BoKeep menu in the
application.

At the top you'll see the location where the bo-keep database will be kept. 
Note this for backup purposes.

ADDING AND CONFIGURING BOOKS

You can use BoKeep to manage multiple books at once.  Bo-keep plugins and 
backend plugins are installed on a per book basis, so you must first add a
book, and then set up its plugins.  

In the middle of the configuration dialog box is an area for viewing your 
existing (accounting) books.

Below that is an entry field for the name of a new book.  To create a 
new book, fill in this text field and click the New Book button.  Once you 
have added a book to the system, you can click on it in the list, and install 
its plugins as described below.

For adding a front-end plugin: 

You can have multiple front-end plugins (corresponding to transaction types)
in a book. To add a new front-end plugin to the selected book, use the pull-down
menu beside the Add button to select a plugin, or type in the name of the python 
package or module (with package.package notation) that corresponds to the plugin, 
then click Add.  Right now Bo-Keep ships with:

 bokeep.plugins.trust    - Track amounts held in trust for others
 bokeep.plugins.mileage  - Establish a $/km or $/mile rate and enter in
                           your distances traveled
 bokeep.plugins.payroll  - Support for running a Manitoba, Canada payroll
                           through a special configuration and data file format

You can learn more about these plugins in their respective READMEs:
 README_trust_plugin.txt
 README_mileage_plugin.txt
 README_payroll_plugin.txt

There is only one backend plugin per book. You can just edit the python
package name at the bottom of the configuration dialog or use the drop-down 
menu.  BoKeep ships with
 bokeep.backend_plugins.serialfile
    - Appends text descriptions of actions linearly to a text file
 bokeep.backend_plugins.null
    - Does nothing
 bokeep.backend_plugins.gnucash_backend
    - Works with GnuCash version 2.4.0 or later via with the
      python-bindings feature installed.

To finish adding or changing books, click OK.  This will take you back to the
main BoKeep data entry interface.

CONFIGURING PLUGINS

You can configure a plugin from within the BoKeep data entry interface, not 
the configuration dialog.

Choose which book you're editing with the Books pull-down menu.

If you chose a backend other than the default null, you can configure
it via Book->Configure Backend. In the case of gnucash_backend and
serialfile, the configuration consists of a file->open dialog. If you
already have Bo-Keep transactions in your book they will be copied
into the backend when you pick a file with this dialog.  Please note
that the GnuCash backend has only be tested with and works only with
XML GnuCash files.

Many front-end plugins will only be useful if themselves configured. 
Use Plugin->Configure to configure the plugin for the currently selected
transaction type in the currently selected book.

ENTERING TRANSACTIONS

You can create a new Bo-Keep transaction with the New button. A
transaction type can be selected from the type pull-down menu. These
come from the Bo-Keep plugins you have installed, so the more plugins
installed the more types you'll have to choose from. It may be
worthwhile to install all three plugins shipped with Bo-Keep to see
how the user-interface changes at the bottom of your bo-keep window
changes in place -- this might be the coolest thing about Bo-Keep's
design right now.  

You don't need to worry about saving, changes you make to Bo-Keep
transactions are saved nearly instantly.

The backend plugins used by Bo-Keep update their respective backends
when you close Bo-Keep or when you select the Book->Flush Backend menu
item. With some backends this can be a slow operation, be patient.

Between your transaction editor and the type pull-down menu you may
see a red alert light and status information regarding the current
transaction and the backend being out of sync (dirty). Except for new
transactions for which there hasn't been a flush attempt yet, this is
an indication of a problem. You probably need to configure either the
backend plugin and/or the plugin to address the problem. You can check
to see if this has worked by using the Book->Flush Backend menu item.

Check out the appearance of your Bo-Keep transactions in your
accounting backend. The trust and mileage plugins don't really provide
much of a wow factor for this, as they only result in single line
transactions. Even if you're not in Manitoba, Canada, the payroll
plugin is worth giving a try just for the wow factor, data entry can
be as simple as putting in worker's hours, and you instantly get a
full out payroll transaction with the three types of deductions (cpp,
ei, income tax), the two employer contributions (ei, cpp), and
vacation pay.

See README_payroll_plugin.txt for more.

BoKeep was developed by ParIT Worker Co-operative (http://parit.ca/)
with grant funding from Assiniboine Credit Union
(http://assiniboine.mb.ca) and Legal Aid Manitoba
(http://www.legalaid.mb.ca) .

It is used in-production by ParIT for its payroll and by a ParIT
customer, so you know we're eating our own dog food. Some of this code
(and our work on the GnuCash python bindings) goes all the way back to
late 2006.

It has been free software from the beginning, with the 1.0 release ParIT
is endeavoring to build a global development and user community around
it. Participation is welcome on the Bo-Keep development mailing list,
http://lists.nongnu.org/mailman/listinfo/bokeep-devel
and via support and patches features on the project's Savannah page:
http://savannah.nongnu.org/projects/bokeep/

Mercurial has been adopted for version control.
http://savannah.nongnu.org/hg/?group=bokeep

Professional support, plugin development, and customization services
are available from ParIT, direct from the experienced original
developers at competitive prices. All paid Bo-Keep work by ParIT will be
contributed back to the original codebase. ParIT will gladly list any
other providers of support services in this file that are in ethical
good standing with their community and workers.
Contract: [email protected] .

To learn more about copyright and contributions, please read
COPYRIGHT_AND_CONTRIBUTIONS.

Copyright (C) 2011  ParIT Worker Co-operative, Ltd <[email protected]>
This file is part of Bo-Keep.

Bo-Keep is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

 Author: Mark Jenkins <[email protected]>