PTA-JOURNAL(5) File Formats Manual PTA-JOURNAL(5)

pta-journalmain input file format for plain text accounting

The file journal.txt in the current directory is the main input file for pta(1). Like all pta(1) input files, it is an ascii(7) text file using strings of one or more space characters as the field delimiter and using the hash character (‘#’) in the first column to mark lines as ignored.

In this manual page, terms defined in pta-glossary(7) are when first used.

With a few exceptions discussed below, each line in the file represents one journal entry. Fields are given in the following order:

  1. The date in the eight-digit form YYYYMMDD; entries have to appear in chronological order.
  2. A booking identifier, consisting of one or more capital latin letters in the range [A–Z], optionally followed by a pair of numbers separated by a slash. Typically, the letters are used to identify a bank account, a credit card, or a cash office, the digits before the slash represent the number of a bank statement or cashbook sheet, and the digits after the slash a sheet or entry number within the bank statement or cashbook sheet. Booking identifiers need not be unique.
  3. A debit account number. It has to be defined in the pta-accounts(5) file.
  4. A credit account number, also defined in the pta-accounts(5) file.
  5. The amount in decimal notation, consisting of one or more digits, a decimal point, and again one or more digits.
  6. A text string that can include space characters.

If the text contains a string enclosed in [square brackets], the enclosed string is used as the name of a .

If the text contains a string enclosed in (parentheses), the enclosed string is used as the name of a , 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.

All transactions can be represented by using only elementary journal entries as described above. However, in some situations, it can be convenient to consider more than two 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.

In the 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.

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.

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.

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.

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.

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.

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 pta(1), the required supplementary information can be provided using in the journal file, even though the craft of bookkeeping in general does not expect such lines in a journal. Right before each opening 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.

The format of price lines is similar to the format of entry lines, with two exceptions:

  1. Instead of the credit account number, provide the number of units owned before and after that point in time, joined together with a hash character (‘#’).
  2. Instead of the amount, provide the current market price for one unit.

The only purpose price lines are used for is calculating unrealized profits by pta(1) -p.

pta(1), pta-accounts(5), pta-glossary(7)

Ingo Schwarze <schwarze@openbsd.org>

September 27, 2020 OpenBSD 6.7