[BACK]Return to pta-journal.5 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / pta

Annotation of pta/pta-journal.5, Revision 1.2

1.2     ! schwarze    1: .\" $Id: pta-journal.5,v 1.1 2020/09/27 14:35:34 schwarze Exp $
1.1       schwarze    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: .\"
1.2     ! schwarze   17: .Dd $Mdocdate: September 27 2020 $
1.1       schwarze   18: .Dt PTA-JOURNAL 5
                     19: .Os
                     20: .Sh NAME
                     21: .Nm pta-journal
1.2     ! schwarze   22: .Nd main input file format for plain text accounting
1.1       schwarze   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
1.2     ! schwarze   78: If the text contains a string enclosed in
1.1       schwarze   79: .Bq square brackets ,
                     80: the enclosed string is used as the name of a
                     81: .Em cost center .
                     82: .Pp
1.2     ! schwarze   83: If the text contains a string enclosed in
1.1       schwarze   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: .Ss Split journal entries
                     94: All transactions can be represented by using only elementary
                     95: .Em journal entries
                     96: as described above.
                     97: However, in some situations, it can be convenient to consider more
                     98: than two
                     99: .Em account entries
                    100: as forming a single journal entry.
                    101: For example, when buying several different items in a single
                    102: transaction, the receipt typically lists a total price to be booked
                    103: as a whole as a credit amount to a cash or credit card account and
                    104: multiple prices of individual items to be booked as debit amounts
                    105: to various different expense accounts.
                    106: Another example of a transaction naturally involving more than
                    107: two accounts is a sale including tax, touching a bank or cash account,
                    108: a revenue account, and a tax account.
                    109: Many more examples of various kinds exist.
                    110: .Pp
                    111: In the
                    112: .Xr pta 1
                    113: journal, split journal entries are represented in a special
                    114: multi-line format, using one line for each account involved.
                    115: The first line lists the total amount in question and contains the
                    116: number 0 instead of either the debit or the credit account number,
                    117: whichever side of the entry needs to be split.
                    118: Each of the following lines contains only three fields:
                    119: the contra account number to be used instead of the 0 in the initial line,
                    120: the partial amount going to that contra account, and a text string.
                    121: The sum of the partial amounts is expected to exactly match the
                    122: total amount in the initial line, or parsing will fail.
                    123: By inserting a sufficient number of space characters,
                    124: it is recommended to align the contra account numbers with the 0
                    125: above and the amounts with the other amounts in the file.
                    126: This is not required and does not influence parsing of the journal,
                    127: but it keeps the file more readable.
                    128: .Pp
                    129: Each line of a split journal entry creates one account entry
                    130: for the account mentioned in the line.
                    131: In the account entry generated from the initial line, the contra
                    132: account is set to 0 and the list of contra accounts is instead
                    133: appended to the text string, avoiding duplicates.
                    134: This account entry does not contain information about the partial
                    135: amounts nor about the text strings given on the subsequent lines.
                    136: .Pp
                    137: In the account entries generated from the subsequent lines, the
                    138: date, booking identifier, and contra account are set as specified
                    139: on the initial line.
                    140: The text string is the concatenation of the text string on the
                    141: initial line and the text string on the line in question.
                    142: This account entry does not contain information about the total
                    143: amount nor about the partial amounts and text strings on the
                    144: other subsequent lines.
                    145: .Pp
                    146: When booking a purchase or sale of multiple items, the text string
                    147: in the initial line typically contains the name of the business partner,
                    148: whereas the subsequent lines contain descriptions of the items traded.
                    149: When deciding what to put into the text strings of split journal
                    150: entries for other purposes, keep in mind that the text string given
                    151: on the first line is copied to all generated account entries, while
                    152: each of text strings given on subsequent lines only appears in one
                    153: account entry.
                    154: .Pp
                    155: Currently, splitting both sides of a journal entry is not supported,
                    156: but a similar effect can be achieved by including one or more lines
                    157: with negative amounts between the initial line and the subsequent
                    158: lines.
                    159: .Ss Current prices
                    160: In bookkeeping, the book value of an asset usually is the cost price,
                    161: i.e. the price that was paid when the asset was acquired, even if that
                    162: happened many years ago.
                    163: If the market price of the asset rises, even if the profit is not yet
                    164: realized by selling the asset, one might feel tempted to book the
                    165: unrealized profit, increasing the book value of the asset to match
                    166: the current market price.
                    167: However, in many countries, this is not even permitted, and even where
                    168: it is permitted, it may not be desirable because booked profits are
                    169: usually subject to tax, whereas unrealized profits are often fully
                    170: or partially exempt from tax until they are finally realized.
                    171: .Pp
                    172: Consequently, in order to track the performance of financial
                    173: investments, a method is required that does not change the content
                    174: of the balance sheet.
                    175: In
                    176: .Xr pta 1 ,
                    177: the required supplementary information can be provided using
                    178: .Em price lines
                    179: in the journal file, even though the craft of bookkeeping in general
                    180: does not expect such lines in a journal.
                    181: Right before each opening
                    182: .Em journal entry ,
                    183: each purchase, each selling, and before the end of the journal file,
                    184: provide a price line for the respective asset.
                    185: To track the performance up to arbitrary additional points in time,
                    186: additional price lines can optionally be added anywhere in the file.
                    187: .Pp
                    188: The format of price lines is similar to the format of entry lines,
                    189: with two exceptions:
                    190: .Bl -enum
                    191: .It
                    192: Instead of the credit
                    193: .Em account
                    194: number, provide the number of units
                    195: owned before and after that point in time, joined together with
                    196: a hash character
                    197: .Pq Sq # .
                    198: .It
                    199: Instead of the amount, provide the current market price for one unit.
                    200: .El
                    201: .Pp
                    202: The only purpose price lines are used for is calculating
                    203: unrealized profits by
                    204: .Xr pta 1
                    205: .Fl p .
                    206: .Sh SEE ALSO
                    207: .Xr pta 1 ,
                    208: .Xr pta-accounts 5 ,
                    209: .Xr pta-glossary 7
                    210: .Sh AUTHORS
                    211: .An Ingo Schwarze Aq Mt schwarze@openbsd.org

CVSweb