Readme for penny-0.32.0.10

Penny - double-entry accounting

Penny is a double-entry accounting system which is inspired by, but incompatible with, Ledger, which is available at

Features

Penny is:

double-entry accounting. It does not attempt to hide the machinery of double-entry accounting from you; for instance, it uses the terms "Debit" and "Credit". For a refresher on the basics of double-entry accounting, pick up a used accounting textbook from your favorite bookseller (they can be had cheaply, for less than ten U.S. dollars including shipping) or check out

http://www.principlesofaccounting.com/

which is a great free online text.
oriented around the command line and your text editor.
extensible in Haskell; I have built many ancillary tools that I use "in-house" to do things like check the consistency of my records. Included are tools to automatically process and reconcile bank statements.
but fully-featured even if you know no Haskell, and you need not learn any Haskell to use Penny.
logical. Or at least I hope so. The command-line syntax attempts to be as regular as possible.
good with Unicode text.
colorful and can use 256-color terminals. Reports make great effort to use all of your screen space automatically to present the most readable reports possible.
able to handle multiple commodities in a logical and consistent way--handy if you wish to track stock or real estate holdings or transactions in different currencies.
obsessive. If there was a choice between an easy way and a correct way, I picked the correct way. For instance, all arithmetic is done using decimal numbers rather than binary floating-point types.
freely licensed under the BSD license.
intended for use only on UNIX-like operating systems. In particular, the libraries it uses to print things to your terminal are available primarily on UNIX. Maybe it works on Cygwin too; I have no idea as I use Penny only on UNIX-like systems.
tested with QuickCheck.

Installation

Dependencies

cabal install will take care of all Haskell dependencies for you; however, there are also at least two C libraries you will need to install as Penny depends on other Haskell libraries that use these C libraries. You will need to make sure you have the "development" package installed if you use many Linux distributions; a few distributors, such as Arch, Slackware, and Gentoo, generally don't ship separate "development" packages so that won't apply to you. The C libraries are:

pcre - http://www.pcre.org/ - on Debian GNU/Linux systems this package is called libpcre3-dev
curses - on GNU systems this is known as ncurses, http://www.gnu.org/software/ncurses/ Perhaps other, non-GNU curses implementations will work as well; I do not know. On Debian GNU/Linux systems, install libncurses5-dev.

Haskell compiler

You will need to get the Glasgow Haskell Compiler. Most Linux distributors package it, or you might be able to get it from the GHC website. Penny has been tested with GHC versions 7.4.1 and 7.6.3; any version between those two versions should also work.

Cabal tool

The Cabal tool will help you get the Haskell dependencies you need.

An easy way to get both GHC and the Cabal tool is to get the Haskell Platform. Currently, versions 2013.2.0.0 or version 2012.4.0.0 should both work.

Penny itself

To install Penny, just do:

cabal update
cabal install --enable-tests penny

I encourage you to run the tests, so the above commands will do that, but if you want to skip them, instead just do

cabal install penny

Documentation

To install the manual pages and the documentation, you need to find the downloaded archive. Typically this is at $HOME/.cabal/packages/hackage.haskell.org/penny. Unpack this archive and look inside. Run

sh install-docs

It will install the manual pages to $PREFIX/share/man and the other documentation to $PREFIX/share/doc/penny. By default $PREFIX is /usr/local; you can change this by editing the install-docs file and changing the PREFIX variable.

To remove the manual pages and the documentation, run

sh install-docs remove

The first thing you will want to look at is the manual page penny-basics(7). Then you will want to examine the starter.pny file in the examples directory, which will show you how to write a ledger file. penny-suite(7) will then direct you to other documentation that may interest you.

Penny on the Web

Find Penny on Hackage at

http://hackage.haskell.org/package/penny

and on Github at

http://www.github.com/massysett/penny

and web pages are here:

http://massysett.github.io/penny

(I am going to phase out the separate web pages in favor of files in the main source code tree.)

Development and bugs

If you find any bugs or if you wish to contribute, please use Github (preferred) or send email to omari@smileystation.com (which works just as well as Github, but if everything else is equal for you and you would flip a coin to determine which contact method to use, then please use Github.)

Version numbers

Versions are numbered like this: A.B.C.D. All regular releases that are ready for use have only even numbers for each of A, B, C, and D. Development releases have an odd number in at least one of A, B, C, or D.

A is currently 0 and probably won't change soon.

I change B whenever I make a breaking change in the library, which is quite often; or

I change C when I add functions to the library; or

I change D when I fix bugs, add documentation, or make adjustments to the specification of which packages Penny depends on.

Dependency documentation and bugs

Since the Haskell libraries Penny depends upon can move along quickly, and because Haskell packages can weave complex dependency graphs, sometimes Penny might not build for you. There is no silver bullet solution to this; if you have build problems, please report them to me via email or Github. Also, note that there are two files in the Penny package that can help you diagnose issues:

The minimum-versions.txt file will show the oldest software dependencies that are known to work with Penny; and
The current-versions.txt file will show more recent dependencies that are also known to work with Penny.