.\" $Id: pta.1,v 1.5 2020/11/01 20:08:43 schwarze Exp $
.\"
.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: November 1 2020 $
.Dt PTA 1
.Os
.Sh NAME
.Nm pta
.Nd plain text accounting
.Sh SYNOPSIS
.Nm pta
.Op Fl abcnps
.Op Fl L Cm de
.Sh DESCRIPTION
The Plain Text Accounting program reads bookkeeping journals that
users are expected to create and maintain with arbitrary text editors
and writes account lists, balances, and cost center assessments
to standard output.
All input files are
.Xr ascii 7
text files, using strings of one or more space characters
as field separators.
Blank lines and lines starting with hash characters
.Pq Sq #
are ignored and can be used for comments.
.Pp
To familiarize themselves with the terminology used by
.Nm ,
new users are invited to read
.Xr pta-glossary 7
first.
In the following, terms defined in the glossary are
.Em emphasized
when first used.
.Pp
If none of the options
.Fl abcnps
is specified to
.Nm ,
.Fl abcps
is assumed.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a
Print
.Em account
lists.
For each account, the account number, the account title, and the
account type are printed, followed by a table of account entries
in chronological order, one per line.
From left to right, the table columns contain the date, the booking
identifier, the contra account, the debit amount, the credit amount,
the running total, and the text string.
The account balance can be found in the running total column
of the last line of the table.
.Pp
If an account contains at least one
.Em subaccount ,
all entries associated with any subaccount are omitted
from the table.
Instead, the list of all entries that are not associated with any
subaccount is followed by one line for each subaccount, containing
only the balance of the subaccount, the running total of the
account, and the title of the subaccount, but omitting dates, booking
ids, contra accounts, and amounts of individual entries in the
subaccount.
This is intended to make the account list more readable
and more informative.
.It Fl b
Print the
.Em balance
sheet.
Each line in the table represents one
.Em account .
From left to right, the columns are account number, account balance
(debit), account balance (credit), and account title.
The balance sheet is followed by a listing of statistical accounts
as defined in
.Xr pta-accounts 5 .
.It Fl c
Print the accounts and balances for each
.Em cost center .
For each cost center, all related account entries are printed,
grouped by accounts, followed by a balance sheet for the cost center.
.It Fl L Cm de
In standard output, use German instead of English terms.
There are no plans to fully internationalize
.Nm .
This options is only intended to make the output look more consistent with
.Xr pta-accounts 5
and
.Xr pta-journal 5
files using the German language for text strings.
.It Fl n
Does not produce any output.
This option can be used to only check for parsing errors.
.It Fl p
Print
.Em profits
and losses generated by financial investments.
This includes both realized and unrealized profits
without distinguishing the two kinds; to see realized
profits and losses only, look at
.Em account
lists instead.
From left to right, the columns of the tables are the date, the
booking identifier, the individual amount of a profit or revenue
(without a sign) or of a loss or expense (with a minus sign), the
relative size of the amount in percent of the current value of the
asset, the current value of the asset before the respective event,
the relative profit or loss from the event per year, the name of the
.Em cost center ,
and a text string.
.Pp
If some units of the investment were already owned at the beginning
of the accounting period, the first line of the table contains the
book value of the asset at the beginning of the accounting period
instead of the current value before the event, such that the first
line of the table informs about the unrealized profit accumulated
during earlier accounting periods.
.Pp
Whenever the journal contains lines quoting the current price of
the asset, a line appears in the profit table giving the unrealized
profit or loss resulting from the price change since the previous
change in the number of units owned, or since the beginning of the
accounting period, whichever is later.
Such unrealized profits or losses do not change
the book value of the asset.
.Pp
The profit table does not contain lines for purchases and sells
because these are considered to be executed at the current price;
by definition, they do not generate profits or losses
but only realize them.
There are often lines listing surcharges and fees related to purchases
and sells, though.
.Pp
In lines listing revenues like interest or dividends and costs like
surcharges and fees, the text string is the original text string
from the respective
.Em journal entry .
.Pp
The profit table ends with a line summing up
the total profit or loss during the current accounting period.
Lines that do not contribute to this sum because they are related
to previous accounting period rather than to the current one
or because they are included in later lines
are marked with double trailing dashes
.Pq Sq \-\- .
On this final line, the column for the current value of the asset
contains the average market value of the investment held
during the accounting period, and the two columns for the relative
profit or loss are calculated in relation to this average.
.It Fl s
Print
.Em subaccount
lists.
For each subaccount, the account naumber, account name, account
type, and subaccount name are printed, followed by a table table
of account entries as documented for the
.Fl a
option.
.El
.Sh FILES
.Bl -tag -width accounts.example.en
.It Pa ./accounts.txt
account definition list, see
.Xr pta-accounts 5
.It Pa accounts.example.en
example account list with English account titles
.It Pa accounts.example.de
example account list with German account titles
.It Pa ./journal.txt
main input file, see
.Xr pta-journal 5
.It Pa journal.example.en
example input file
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr pta-accounts 5 ,
.Xr pta-journal 5 ,
.Xr pta-glossary 7
.Pp
The
.Nm
homepage:
.Lk https://mandoc.bsd.lv/pta/
.Sh AUTHORS
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
.Sh BUGS
Currently,
.Nm
has the following limitations:
.Bl -dash
.It
All amounts are expected to be expressed in the same currency.
Currency conversion is not yet supported.
Any one currency can be used, but it cannot be specified which
currency that is.
.It
In the balance sheet, all accounts are listed individually.
Grouping of accounts is not yet supported.
.It
Currently, the annual financial statement can only be generated
in the form of a balance sheet.
Generating an annual financial statement in the form of a statement
on the excess of receipts over expenses is not yet supported.
.It
Custom business assessments are not yet supported.
.It
Cost centers can only be regarded individually.
Grouping of cost centers is not yet supported.
.It
Only a single level of subaccounts is supported.
Subaccounts can not yet be nested.
.It
Automatically splitting journal entries that include tax into three
account entries (gross amount, net amount, and tax) is not yet
supported.
.It
Bookkeeping can only be done for one single accounting period at a time,
typically for one year.
Comparing and aggregating data of multiple accounting periods
is not yet supported.
.El