Annotation of pta/pta.1, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 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: .\"
! 17: .Dd $Mdocdate$
! 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.
! 35: Lines starting with hash characters
! 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
! 155: The profit table ends with line summing up
! 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