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