Annotation of pta/pta.1, Revision 1.2
1.2 ! schwarze 1: .\" $Id: pta.1,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 1
19: .Os
20: .Sh NAME
21: .Nm pta
22: .Nd plain text accounting
23: .Sh SYNOPSIS
24: .Nm pta
25: .Op Fl abcnps
26: .Op Fl L Cm de
27: .Sh DESCRIPTION
28: The Plain Text Accounting program reads bookkeeping journals
29: and writes account lists, balances, and cost center assessments
30: to standard output.
31: All input files are
32: .Xr ascii 7
33: text files, using strings of one or more space characters
34: as field separators.
1.2 ! schwarze 35: Blank lines and lines starting with hash characters
1.1 schwarze 36: .Pq Sq #
37: are ignored and can be used for comments.
38: .Pp
39: To familiarize themselves with the terminology used by
40: .Nm ,
41: new users are invited to read
42: .Xr pta-glossary 7
43: first.
44: In the following, terms defined in the glossary are
45: .Em emphasized
46: when first used.
47: .Pp
48: If none of the options
49: .Fl abcnps
50: is specified to
51: .Nm ,
52: .Fl abcps
53: is assumed.
54: .Pp
55: The options are as follows:
56: .Bl -tag -width Ds
57: .It Fl a
58: Print
59: .Em account
60: lists.
61: For each account, the account number, the account title, and the
62: account type are printed, followed by a table of account entries
63: in chronological order, one per line.
64: From left to right, the table columns contain the date, the booking
65: identifier, the contra account, the debit amount, the credit amount,
66: the running total, and the text string.
67: The account balance can be found in the running total column
68: of the last line of the table.
69: .Pp
70: If an account contains at least one
71: .Em subaccount ,
72: all entries associated with any subaccount are omitted
73: from the table.
74: Instead, the list of all entries that are not associated with any
75: subaccount is followed by one line for each subaccount, containing
76: only the balance of the subaccount, the running total of the
77: account, and the title of the subaccount, but omitting dates, booking
78: ids, contra accounts, and amounts of individual entries in the
79: subaccount.
80: This is intended to make the account list more readable
81: and more informative.
82: .It Fl b
83: Print the
84: .Em balance
85: sheet.
86: Each line in the table represents one
87: .Em account .
88: From left to right, the columns are account number, account balance
89: (debit), account balance (credit), and account title.
90: The balance sheet is followed by a listing of statistical accounts
91: as defined in
92: .Xr pta-accounts 5 .
93: .It Fl c
94: Print the accounts and balances for each
95: .Em cost center .
96: For each cost center, all related account entries are printed,
97: grouped by accounts, followed by a balance sheet for the cost center.
98: .It Fl L Cm de
99: In standard output, use German instead of English terms.
100: There are no plans to fully internationalize
101: .Nm .
102: This options is only intended to make the output look more consistent with
103: .Xr pta-accounts 5
104: and
105: .Xr pta-journal 5
106: files using the German language for text strings.
107: .It Fl n
108: Does not produce any output.
109: This option can be used to only check for parsing errors.
110: .It Fl p
111: Print
112: .Em profits
113: and losses generated by financial investments.
114: This includes both realized and unrealized profits
115: without distinguishing the two kinds; to see realized
116: profits and losses only, look at
117: .Em account
118: lists instead.
119: From left to right, the columns of the tables are the date, the
120: booking identifier, the individual amount of a profit or revenue
121: (without a sign) or of a loss or expense (with a minus sign), the
122: relative size of the amount in percent of the current value of the
123: asset, the current value of the asset before the respective event,
124: the relative profit or loss from the event per year, the name of the
125: .Em cost center ,
126: and a text string.
127: .Pp
128: If some units of the investment were already owned at the beginning
129: of the accounting period, the first line of the table contains the
130: book value of the asset at the beginning of the accounting period
131: instead of the current value before the event, such that the first
132: line of the table informs about the unrealized profit accumulated
133: during earlier accounting periods.
134: .Pp
135: Whenever the journal contains lines quoting the current price of
136: the asset, a line appears in the profit table giving the unrealized
137: profit or loss resulting from the price change since the previous
138: change in the number of units owned, or since the beginning of the
139: accounting period, whichever is later.
140: Such unrealized profits or losses do not change
141: the book value of the asset.
142: .Pp
143: The profit table does not contain lines for purchases and sells
144: because these are considered to be executed at the current price;
145: by definition, they do not generate profits or losses
146: but only realize them.
147: There are often lines listing surcharges and fees related to purchases
148: and sells, though.
149: .Pp
150: In lines listing revenues like interest or dividends and costs like
151: surchanges and fees, the text string is the original text string
152: from the respective
153: .Em journal entry .
154: .Pp
1.2 ! schwarze 155: The profit table ends with a line summing up
1.1 schwarze 156: the total profit or loss during the current accounting period.
157: Lines that do not contribute to this sum because they are related
158: to previous accounting period rather than to the current one
159: or because they are included in later lines
160: are marked with double trailing dashes
161: .Pq Sq \-\- .
162: On this final line, the column for the current value of the asset
163: contains the average market value of the investment held
164: during the accounting period, and the two columns for the relative
165: profit or loss are calculated in relation to this average.
166: .It Fl s
167: Print
168: .Em subaccount
169: lists.
170: For each subaccount, the account naumber, account name, account
171: type, and subaccount name are printed, followed by a table table
172: of account entries as documented for the
173: .Fl a
174: option.
175: .El
176: .Sh FILES
177: .Bl -tag -width accounts.example.en
178: .It Pa ./accounts.txt
179: account definition list, see
180: .Xr pta-accounts 5
181: .It Pa accounts.example.en
182: example account list with English account titles
183: .It Pa accounts.example.de
184: example account list with German account titles
185: .It Pa ./journal.txt
186: main input file, see
187: .Xr pta-journal 5
188: .It Pa journal.example.en
189: example input file
190: .El
191: .Sh EXIT STATUS
192: .Ex -std
193: .Sh SEE ALSO
194: .Xr pta-accounts 5 ,
195: .Xr pta-journal 5 ,
196: .Xr pta-glossary 7
197: .Sh AUTHORS
198: .An Ingo Schwarze Aq Mt schwarze@openbsd.org
199: .Sh BUGS
200: Currently,
201: .Nm
202: has the following limitations:
203: .Bl -dash
204: .It
205: All amounts are expected to be expressed in the same currency.
206: Currency conversion is not yet supported.
207: Any one currency can be used, but it cannot be specified which
208: currency that is.
209: .It
210: In the balance sheet, all accounts are listed individually.
211: Grouping of accounts is not yet supported.
212: .It
213: Currently, the annual financial statement can only be generated
214: in the form of a balance sheet.
215: Generating an annual financial statement in the form of a statement
216: on the excess of receipts over expenses is not yet supported.
217: .It
218: Custom business assessments are not yet supported.
219: .It
220: Cost centers can only be regarded individually.
221: Grouping of cost centers is not yet supported.
222: .It
223: Only a single level of subaccounts is supported.
224: Subaccounts can not yet be nested.
225: .It
226: Automatically splitting journal entries that include tax into three
227: account entries (gross amount, net amount, and tax) is not yet
228: supported.
229: .It
230: Bookkeeping can only be done for one single accounting period at a time,
231: typically for one year.
232: Comparing and aggregating data of multiple accounting periods
233: is not yet supported.
234: .El
CVSweb