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