.\" $Id: pta-journal.5,v 1.3 2020/11/10 19:08:06 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 10 2020 $
.Dt PTA-JOURNAL 5
.Os
.Sh NAME
.Nm pta-journal
.Nd main input file format for plain text accounting
.Sh DESCRIPTION
The file
.Pa journal.txt
in the current directory is the main input file for
.Xr pta 1 .
Like all
.Xr pta 1
input files, it is an
.Xr ascii 7
text file using strings of one or more space characters
as the field delimiter and using the hash character
.Pq Sq #
in the first column to mark lines as ignored.
.Pp
In this manual page, terms defined in
.Xr pta-glossary 7
are
.Em emphasized
when first used.
.Pp
With a few exceptions discussed below, each line in the file represents one
.Em journal entry .
Fields are given in the following order:
.Bl -enum
.It
The date in the eight-digit form YYYYMMDD;
entries have to appear in chronological order.
.It
A booking identifier, consisting of one or more non-blank characters.
For example, it might begin with a few letters to identify a bank
account, a credit card, or a cash office, the ordinal number of a
bank statement or a cashbook sheet might follow, and it might end
with an entry number within the bank statement or cashbook sheet.
Following a consistent format within each journal file is recommended
but not required.
Booking identifiers need not be unique.
.It
A debit
.Em account
number.
It has to be defined in the
.Xr pta-accounts 5
file.
.It
A credit account number, also defined in the
.Xr pta-accounts 5
file.
.It
The amount in decimal notation, consisting of one or more digits,
a decimal point, and again one or more digits.
.It
A text string that can include space characters.
.El
.Pp
If the text contains a string enclosed in
.Bq square brackets ,
the enclosed string is used as the name of a
.Em cost center .
.Pp
If the text contains a string enclosed in
.Pq parentheses ,
the enclosed string is used as the name of a
.Em subaccount ,
applying only to revenue and expense accounts on this line,
but not to asset, liability, and equity accounts.
In the unusual case that both the debit and the credit account is a
revenue or expense account, using the split notation described below
is recommended to disambiguate which account the subaccount name
applies to.
.Ss Split journal entries
All transactions can be represented by using only elementary
.Em journal entries
as described above.
However, in some situations, it can be convenient to consider more
than two
.Em account entries
as forming a single journal entry.
For example, when buying several different items in a single
transaction, the receipt typically lists a total price to be booked
as a whole as a credit amount to a cash or credit card account and
multiple prices of individual items to be booked as debit amounts
to various different expense accounts.
Another example of a transaction naturally involving more than
two accounts is a sale including tax, touching a bank or cash account,
a revenue account, and a tax account.
Many more examples of various kinds exist.
.Pp
In the
.Xr pta 1
journal, split journal entries are represented in a special
multi-line format, using one line for each account involved.
The first line lists the total amount in question and contains the
number 0 instead of either the debit or the credit account number,
whichever side of the entry needs to be split.
Each of the following lines contains only three fields:
the contra account number to be used instead of the 0 in the initial line,
the partial amount going to that contra account, and a text string.
The sum of the partial amounts is expected to exactly match the
total amount in the initial line, or parsing will fail.
By inserting a sufficient number of space characters,
it is recommended to align the contra account numbers with the 0
above and the amounts with the other amounts in the file.
This is not required and does not influence parsing of the journal,
but it keeps the file more readable.
.Pp
Each line of a split journal entry creates one account entry
for the account mentioned in the line.
In the account entry generated from the initial line, the contra
account is set to 0 and the list of contra accounts is instead
appended to the text string, avoiding duplicates.
This account entry does not contain information about the partial
amounts nor about the text strings given on the subsequent lines.
.Pp
In the account entries generated from the subsequent lines, the
date, booking identifier, and contra account are set as specified
on the initial line.
The text string is the concatenation of the text string on the
initial line and the text string on the line in question.
This account entry does not contain information about the total
amount nor about the partial amounts and text strings on the
other subsequent lines.
.Pp
When booking a purchase or sale of multiple items, the text string
in the initial line typically contains the name of the business partner,
whereas the subsequent lines contain descriptions of the items traded.
When deciding what to put into the text strings of split journal
entries for other purposes, keep in mind that the text string given
on the first line is copied to all generated account entries, while
each of text strings given on subsequent lines only appears in one
account entry.
.Pp
Currently, splitting both sides of a journal entry is not supported,
but a similar effect can be achieved by including one or more lines
with negative amounts between the initial line and the subsequent
lines.
.Ss Current prices
In bookkeeping, the book value of an asset usually is the cost price,
i.e. the price that was paid when the asset was acquired, even if that
happened many years ago.
If the market price of the asset rises, even if the profit is not yet
realized by selling the asset, one might feel tempted to book the
unrealized profit, increasing the book value of the asset to match
the current market price.
However, in many countries, this is not even permitted, and even where
it is permitted, it may not be desirable because booked profits are
usually subject to tax, whereas unrealized profits are often fully
or partially exempt from tax until they are finally realized.
.Pp
Consequently, in order to track the performance of financial
investments, a method is required that does not change the content
of the balance sheet.
In
.Xr pta 1 ,
the required supplementary information can be provided using
.Em price lines
in the journal file, even though the craft of bookkeeping in general
does not expect such lines in a journal.
Right before each opening
.Em journal entry ,
each purchase, each selling, and before the end of the journal file,
provide a price line for the respective asset.
To track the performance up to arbitrary additional points in time,
additional price lines can optionally be added anywhere in the file.
.Pp
The format of price lines is similar to the format of entry lines,
with two exceptions:
.Bl -enum
.It
Instead of the credit
.Em account
number, provide the number of units
owned before and after that point in time, joined together with
a hash character
.Pq Sq # .
.It
Instead of the amount, provide the current market price for one unit.
.El
.Pp
The only purpose price lines are used for is calculating
unrealized profits by
.Xr pta 1
.Fl p .
.Sh SEE ALSO
.Xr pta 1 ,
.Xr pta-accounts 5 ,
.Xr pta-glossary 7
.Sh AUTHORS
.An Ingo Schwarze Aq Mt schwarze@openbsd.org