penny-bin-0.6.0.0: man/penny-selloff.1

.TH penny-selloff 1

.SH NAME
penny-selloff - calculate capital gains and losses from commodity sales

.SH SYNOPSIS
.B penny-selloff
.I PROCEEDS-ACCOUNT FILE...

.SH DESCRIPTION

This is a description of how
.B penny-selloff
works. You will be lost if you have not read
.BR penny-commodities (7)
and looked at the
.I stocks.pny
file in the
.I examples
directory of the
.I penny-bin
tarball.

.B penny-selloff
examines the names of the sub-accounts of the
.IR PROCEEDS-ACCOUNT .
The first sub-account name is ignored (typically it will be
.IR Proceeds .)
The second sub-accont is the
.I group
(typically it will be the name of the commodity you are selling,
though it does not have to be.) The third sub-account is the date
(and, optionally, the time) when you sold the commodity.

.B penny-selloff
then parses all the ledger files given on the command line. (If no
files are given, or if a file is
.IR - ,
it reads standard input.)
Then
.B penny-selloff
examines the balance of the proceeds account. It must have exactly one
debit amount and one credit amount in the balance. The debit balance
is the commodity you are selling. The credit balance is the commodity
you received in return for the sale (typically your home currency.)

Next,
.B penny-selloff
examines the balances of all accounts in the parsed ledger files. It
finds accounts that have
.I Basis
as the first sub-account and whose second sub-account matches the
.I group
found in the proceeds account (again, typically this will be the name
of the commodity you are selling, though it does not have to be.) The
third sub-account must be a date and optional time, which was when the
commodity was purchased. Each of these accounts must have one debit
amount, which is the cost of the purchase, and a credit balance, which
is the amount of the commodity that was purchased.

Finally,
.B penny-selloff
computes postings that will eliminate the balances of the
.I Basis
accounts. It also computes the capital gain or loss from each
sale. The oldest commodities are sold first.

.B penny-selloff
creates a single transaction with postings that eliminate the balances
.I Basis
accounts corresponding to the commodities that were sold. The
transaction also contains postings with the capital gain or loss from
each sale. This transaction is printed to standard output.

.SH EXIT STATUS
0 if everything went fine; non-zero if there was a problem.

.SH BUGS
Please report bugs in the program or documentation to
.MT omari@smileystation.com
Omari Norman.
.ME

.SH SEE ALSO
.BR penny-suite "(7), " penny-commodities (7)