Annotation of pta/pta-journal.5, Revision 1.3
1.3 ! schwarze 1: .\" $Id: pta-journal.5,v 1.2 2020/09/27 15:36:43 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
1.3 ! schwarze 51: A booking identifier, consisting of one or more non-blank characters.
! 52: For example, it might begin with a few letters to identify a bank
! 53: account, a credit card, or a cash office, the ordinal number of a
! 54: bank statement or a cashbook sheet might follow, and it might end
! 55: with an entry number within the bank statement or cashbook sheet.
! 56: Following a consistent format within each journal file is recommended
! 57: but not required.
1.1 schwarze 58: Booking identifiers need not be unique.
59: .It
60: A debit
61: .Em account
62: number.
63: It has to be defined in the
64: .Xr pta-accounts 5
65: file.
66: .It
67: A credit account number, also defined in the
68: .Xr pta-accounts 5
69: file.
70: .It
71: The amount in decimal notation, consisting of one or more digits,
72: a decimal point, and again one or more digits.
73: .It
74: A text string that can include space characters.
75: .El
76: .Pp
1.2 schwarze 77: If the text contains a string enclosed in
1.1 schwarze 78: .Bq square brackets ,
79: the enclosed string is used as the name of a
80: .Em cost center .
81: .Pp
1.2 schwarze 82: If the text contains a string enclosed in
1.1 schwarze 83: .Pq parentheses ,
84: the enclosed string is used as the name of a
85: .Em subaccount ,
86: applying only to revenue and expense accounts on this line,
87: but not to asset, liability, and equity accounts.
88: In the unusual case that both the debit and the credit account is a
89: revenue or expense account, using the split notation described below
90: is recommended to disambiguate which account the subaccount name
91: applies to.
92: .Ss Split journal entries
93: All transactions can be represented by using only elementary
94: .Em journal entries
95: as described above.
96: However, in some situations, it can be convenient to consider more
97: than two
98: .Em account entries
99: as forming a single journal entry.
100: For example, when buying several different items in a single
101: transaction, the receipt typically lists a total price to be booked
102: as a whole as a credit amount to a cash or credit card account and
103: multiple prices of individual items to be booked as debit amounts
104: to various different expense accounts.
105: Another example of a transaction naturally involving more than
106: two accounts is a sale including tax, touching a bank or cash account,
107: a revenue account, and a tax account.
108: Many more examples of various kinds exist.
109: .Pp
110: In the
111: .Xr pta 1
112: journal, split journal entries are represented in a special
113: multi-line format, using one line for each account involved.
114: The first line lists the total amount in question and contains the
115: number 0 instead of either the debit or the credit account number,
116: whichever side of the entry needs to be split.
117: Each of the following lines contains only three fields:
118: the contra account number to be used instead of the 0 in the initial line,
119: the partial amount going to that contra account, and a text string.
120: The sum of the partial amounts is expected to exactly match the
121: total amount in the initial line, or parsing will fail.
122: By inserting a sufficient number of space characters,
123: it is recommended to align the contra account numbers with the 0
124: above and the amounts with the other amounts in the file.
125: This is not required and does not influence parsing of the journal,
126: but it keeps the file more readable.
127: .Pp
128: Each line of a split journal entry creates one account entry
129: for the account mentioned in the line.
130: In the account entry generated from the initial line, the contra
131: account is set to 0 and the list of contra accounts is instead
132: appended to the text string, avoiding duplicates.
133: This account entry does not contain information about the partial
134: amounts nor about the text strings given on the subsequent lines.
135: .Pp
136: In the account entries generated from the subsequent lines, the
137: date, booking identifier, and contra account are set as specified
138: on the initial line.
139: The text string is the concatenation of the text string on the
140: initial line and the text string on the line in question.
141: This account entry does not contain information about the total
142: amount nor about the partial amounts and text strings on the
143: other subsequent lines.
144: .Pp
145: When booking a purchase or sale of multiple items, the text string
146: in the initial line typically contains the name of the business partner,
147: whereas the subsequent lines contain descriptions of the items traded.
148: When deciding what to put into the text strings of split journal
149: entries for other purposes, keep in mind that the text string given
150: on the first line is copied to all generated account entries, while
151: each of text strings given on subsequent lines only appears in one
152: account entry.
153: .Pp
154: Currently, splitting both sides of a journal entry is not supported,
155: but a similar effect can be achieved by including one or more lines
156: with negative amounts between the initial line and the subsequent
157: lines.
158: .Ss Current prices
159: In bookkeeping, the book value of an asset usually is the cost price,
160: i.e. the price that was paid when the asset was acquired, even if that
161: happened many years ago.
162: If the market price of the asset rises, even if the profit is not yet
163: realized by selling the asset, one might feel tempted to book the
164: unrealized profit, increasing the book value of the asset to match
165: the current market price.
166: However, in many countries, this is not even permitted, and even where
167: it is permitted, it may not be desirable because booked profits are
168: usually subject to tax, whereas unrealized profits are often fully
169: or partially exempt from tax until they are finally realized.
170: .Pp
171: Consequently, in order to track the performance of financial
172: investments, a method is required that does not change the content
173: of the balance sheet.
174: In
175: .Xr pta 1 ,
176: the required supplementary information can be provided using
177: .Em price lines
178: in the journal file, even though the craft of bookkeeping in general
179: does not expect such lines in a journal.
180: Right before each opening
181: .Em journal entry ,
182: each purchase, each selling, and before the end of the journal file,
183: provide a price line for the respective asset.
184: To track the performance up to arbitrary additional points in time,
185: additional price lines can optionally be added anywhere in the file.
186: .Pp
187: The format of price lines is similar to the format of entry lines,
188: with two exceptions:
189: .Bl -enum
190: .It
191: Instead of the credit
192: .Em account
193: number, provide the number of units
194: owned before and after that point in time, joined together with
195: a hash character
196: .Pq Sq # .
197: .It
198: Instead of the amount, provide the current market price for one unit.
199: .El
200: .Pp
201: The only purpose price lines are used for is calculating
202: unrealized profits by
203: .Xr pta 1
204: .Fl p .
205: .Sh SEE ALSO
206: .Xr pta 1 ,
207: .Xr pta-accounts 5 ,
208: .Xr pta-glossary 7
209: .Sh AUTHORS
210: .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