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