Annotation of pta/pta-journal.5, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 2: .\"
! 3: .\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\"
! 17: .Dd $Mdocdate$
! 18: .Dt PTA-JOURNAL 5
! 19: .Os
! 20: .Sh NAME
! 21: .Nm pta-journal
! 22: .Nd main input file format for the plain text accounting program
! 23: .Sh DESCRIPTION
! 24: The file
! 25: .Pa journal.txt
! 26: in the current directory is the main input file for
! 27: .Xr pta 1 .
! 28: Like all
! 29: .Xr pta 1
! 30: input files, it is an
! 31: .Xr ascii 7
! 32: text file using strings of one or more space characters
! 33: as the field delimiter and using the hash character
! 34: .Pq Sq #
! 35: in the first column to mark lines as ignored.
! 36: .Pp
! 37: In this manual page, terms defined in
! 38: .Xr pta-glossary 7
! 39: are
! 40: .Em emphasized
! 41: when first used.
! 42: .Pp
! 43: With a few exceptions discussed below, each line in the file represents one
! 44: .Em journal entry .
! 45: Fields are given in the following order:
! 46: .Bl -enum
! 47: .It
! 48: The date in the eight-digit form YYYYMMDD;
! 49: entries have to appear in chronological order.
! 50: .It
! 51: A booking identifier, consisting of one or more capital latin letters
! 52: in the range
! 53: .Bq A\(enZ ,
! 54: optionally followed by a pair of numbers separated by a slash.
! 55: Typically, the letters are used to identify a bank account, a credit card,
! 56: or a cash office, the digits before the slash represent the number of a
! 57: bank statement or cashbook sheet, and the digits after the slash a sheet
! 58: or entry number within the bank statement or cashbook sheet.
! 59: Booking identifiers need not be unique.
! 60: .It
! 61: A debit
! 62: .Em account
! 63: number.
! 64: It has to be defined in the
! 65: .Xr pta-accounts 5
! 66: file.
! 67: .It
! 68: A credit account number, also defined in the
! 69: .Xr pta-accounts 5
! 70: file.
! 71: .It
! 72: The amount in decimal notation, consisting of one or more digits,
! 73: a decimal point, and again one or more digits.
! 74: .It
! 75: A text string that can include space characters.
! 76: .El
! 77: .Pp
! 78: If the text starts with as string enclosed in
! 79: .Bq square brackets ,
! 80: the enclosed string is used as the name of a
! 81: .Em cost center .
! 82: .Pp
! 83: If the text starts with as string enclosed in
! 84: .Pq parentheses ,
! 85: the enclosed string is used as the name of a
! 86: .Em subaccount ,
! 87: applying only to revenue and expense accounts on this line,
! 88: but not to asset, liability, and equity accounts.
! 89: In the unusual case that both the debit and the credit account is a
! 90: revenue or expense account, using the split notation described below
! 91: is recommended to disambiguate which account the subaccount name
! 92: applies to.
! 93: .Pp
! 94: If both a cost center and a subaccount are given on the same line,
! 95: the cost center is expected to precede the subaccount.
! 96: .Ss Split journal entries
! 97: All transactions can be represented by using only elementary
! 98: .Em journal entries
! 99: as described above.
! 100: However, in some situations, it can be convenient to consider more
! 101: than two
! 102: .Em account entries
! 103: as forming a single journal entry.
! 104: For example, when buying several different items in a single
! 105: transaction, the receipt typically lists a total price to be booked
! 106: as a whole as a credit amount to a cash or credit card account and
! 107: multiple prices of individual items to be booked as debit amounts
! 108: to various different expense accounts.
! 109: Another example of a transaction naturally involving more than
! 110: two accounts is a sale including tax, touching a bank or cash account,
! 111: a revenue account, and a tax account.
! 112: Many more examples of various kinds exist.
! 113: .Pp
! 114: In the
! 115: .Xr pta 1
! 116: journal, split journal entries are represented in a special
! 117: multi-line format, using one line for each account involved.
! 118: The first line lists the total amount in question and contains the
! 119: number 0 instead of either the debit or the credit account number,
! 120: whichever side of the entry needs to be split.
! 121: Each of the following lines contains only three fields:
! 122: the contra account number to be used instead of the 0 in the initial line,
! 123: the partial amount going to that contra account, and a text string.
! 124: The sum of the partial amounts is expected to exactly match the
! 125: total amount in the initial line, or parsing will fail.
! 126: By inserting a sufficient number of space characters,
! 127: it is recommended to align the contra account numbers with the 0
! 128: above and the amounts with the other amounts in the file.
! 129: This is not required and does not influence parsing of the journal,
! 130: but it keeps the file more readable.
! 131: .Pp
! 132: Each line of a split journal entry creates one account entry
! 133: for the account mentioned in the line.
! 134: In the account entry generated from the initial line, the contra
! 135: account is set to 0 and the list of contra accounts is instead
! 136: appended to the text string, avoiding duplicates.
! 137: This account entry does not contain information about the partial
! 138: amounts nor about the text strings given on the subsequent lines.
! 139: .Pp
! 140: In the account entries generated from the subsequent lines, the
! 141: date, booking identifier, and contra account are set as specified
! 142: on the initial line.
! 143: The text string is the concatenation of the text string on the
! 144: initial line and the text string on the line in question.
! 145: This account entry does not contain information about the total
! 146: amount nor about the partial amounts and text strings on the
! 147: other subsequent lines.
! 148: .Pp
! 149: When booking a purchase or sale of multiple items, the text string
! 150: in the initial line typically contains the name of the business partner,
! 151: whereas the subsequent lines contain descriptions of the items traded.
! 152: When deciding what to put into the text strings of split journal
! 153: entries for other purposes, keep in mind that the text string given
! 154: on the first line is copied to all generated account entries, while
! 155: each of text strings given on subsequent lines only appears in one
! 156: account entry.
! 157: .Pp
! 158: Currently, splitting both sides of a journal entry is not supported,
! 159: but a similar effect can be achieved by including one or more lines
! 160: with negative amounts between the initial line and the subsequent
! 161: lines.
! 162: .Ss Current prices
! 163: In bookkeeping, the book value of an asset usually is the cost price,
! 164: i.e. the price that was paid when the asset was acquired, even if that
! 165: happened many years ago.
! 166: If the market price of the asset rises, even if the profit is not yet
! 167: realized by selling the asset, one might feel tempted to book the
! 168: unrealized profit, increasing the book value of the asset to match
! 169: the current market price.
! 170: However, in many countries, this is not even permitted, and even where
! 171: it is permitted, it may not be desirable because booked profits are
! 172: usually subject to tax, whereas unrealized profits are often fully
! 173: or partially exempt from tax until they are finally realized.
! 174: .Pp
! 175: Consequently, in order to track the performance of financial
! 176: investments, a method is required that does not change the content
! 177: of the balance sheet.
! 178: In
! 179: .Xr pta 1 ,
! 180: the required supplementary information can be provided using
! 181: .Em price lines
! 182: in the journal file, even though the craft of bookkeeping in general
! 183: does not expect such lines in a journal.
! 184: Right before each opening
! 185: .Em journal entry ,
! 186: each purchase, each selling, and before the end of the journal file,
! 187: provide a price line for the respective asset.
! 188: To track the performance up to arbitrary additional points in time,
! 189: additional price lines can optionally be added anywhere in the file.
! 190: .Pp
! 191: The format of price lines is similar to the format of entry lines,
! 192: with two exceptions:
! 193: .Bl -enum
! 194: .It
! 195: Instead of the credit
! 196: .Em account
! 197: number, provide the number of units
! 198: owned before and after that point in time, joined together with
! 199: a hash character
! 200: .Pq Sq # .
! 201: .It
! 202: Instead of the amount, provide the current market price for one unit.
! 203: .El
! 204: .Pp
! 205: The only purpose price lines are used for is calculating
! 206: unrealized profits by
! 207: .Xr pta 1
! 208: .Fl p .
! 209: .Sh SEE ALSO
! 210: .Xr pta 1 ,
! 211: .Xr pta-accounts 5 ,
! 212: .Xr pta-glossary 7
! 213: .Sh AUTHORS
! 214: .An Ingo Schwarze Aq Mt schwarze@openbsd.org
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pta-journal.5 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / pta