sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc updated

Browse source
This commit is contained in:
John Wiegley 2004-09-25 07:21:07 -04:00
parent 0af7e5f44d
commit d74e926b43
1 changed files with 132 additions and 121 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

253
ledger.texi
View file

@ -59,10 +59,10 @@ accounting tools.
The next step up from a checkbook ledger, is a ledger that keeps track The next step up from a checkbook ledger, is a ledger that keeps track
of all your accounts, not just checking. In such a ledger, you record of all your accounts, not just checking. In such a ledger, you record
not only who gets paid---in the case of a debit---but where the not only who gets paid---in the case of a debit---but where the money
money came from. In a checkbook ledger, its assumed that all the came from. In a checkbook ledger, its assumed that all the money
money comes from your checking account. But in a general ledger, you comes from your checking account. But in a general ledger, you write
write transaction two-lines: the source account and target account. transaction two-lines: the source account and target account.
@emph{There must always be a debit from at least one account for every @emph{There must always be a debit from at least one account for every
credit made to another account}. This is what is meant by credit made to another account}. This is what is meant by
``double-entry'' accounting: the ledger must always balance to zero, ``double-entry'' accounting: the ledger must always balance to zero,
@ -225,28 +225,34 @@ separately.
@subsection register @subsection register
The @command{register} command displays all the transactions occurring in The @command{register} command displays all the transactions occurring
a single account, line by line. The account regexp must be specified in a single account, line by line. The account regexp must be
as the only argument to this command. If any regexps occur after the specified as the only argument to this command. If any regexps occur
required account name, the register will contain only those after the required account name, the register will contain only those
transactions that match. Very useful for hunting down a particular transactions that match. Very useful for hunting down a particular
transaction. transaction.
The output from ``register'' is very close to what a typical checkbook, The output from @command{register} is very close to what a typical
or single account ledger, would look like. It also shows a running checkbook, or single-account ledger, would look like. It also shows a
balance. The final running balance of any register should always be running balance. The final running balance of any register should
the same as the current balance of that account. always be the same as the current balance of that account.
If you have gnuplot installed, you may plot the amount or running
total of any register by using the script @file{report}, which is
included in the Ledger distribution. The only requirement is that you
add either @option{-j} or @option{-J} to your register command, in
order to plot either the amount or total column, respectively.
@subsection print @subsection print
The @command{print} command prints out ledger entries just as they appear in The @command{print} command prints out ledger entries just as they
the original ledger. They will be properly formatted, and output in appear in the original ledger. They will be properly formatted, and
the most economic form possible. The ``print'' command also takes a output in the most economic form possible. The ``print'' command also
list of optional regexps, which will cause only those transactions takes a list of optional regexps, which will cause only those
which match in some way to be printed. transactions which match in some way to be printed.
The @command{print} command can be a handy way to clean up a ledger file The @command{print} command can be a handy way to clean up a ledger
whose formatting has gotten out of hand. file whose formatting has gotten out of hand.
@subsection equity @subsection equity
@ -263,8 +269,8 @@ trend.
@subsection entry @subsection entry
The @command{entry} commands simplifies the creation of new entries. It The @command{entry} commands simplifies the creation of new entries.
works on the principle that 80% of all transactions are variants of It works on the principle that 80% of all transactions are variants of
earlier transactions. Here's how it works: earlier transactions. Here's how it works:
Let's say you have an old transaction of the following form: Let's say you have an old transaction of the following form:
@ -368,14 +374,15 @@ what they are used for. This can be a handy way to remember which
options do what. This help screen is also printed if ledger is run options do what. This help screen is also printed if ledger is run
without a command. without a command.
@option{--version} (@option{-v}) prints the current version of ledger and @option{--version} (@option{-v}) prints the current version of ledger
exits. This is useful for sending bug reports, to let the author know and exits. This is useful for sending bug reports, to let the author
which version of ledger you are using. know which version of ledger you are using.
@option{--init FILE} (@option{-i FILE}) causes FILE to be read by ledger before any @option{--init FILE} (@option{-i FILE}) causes FILE to be read by
other ledger file. This file may not contain any transactions, but it ledger before any other ledger file. This file may not contain any
may contain option settings. To specify options in the init file, use transactions, but it may contain option settings. To specify options
the same syntax as the command-line. Here's an example init file: in the init file, use the same syntax as the command-line. Here's an
example init file:
@example @example
--price-db ~/finance/.pricedb --price-db ~/finance/.pricedb
@ -384,21 +391,22 @@ the same syntax as the command-line. Here's an example init file:
Option settings on the command-line or in the environment always take Option settings on the command-line or in the environment always take
precedence over settings in the init file. precedence over settings in the init file.
@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. This command @option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.
may be used multiple times. FILE may also be a list of file names This command may be used multiple times. FILE may also be a list of
separated by colons. Typically, the environment variable file names separated by colons. Typically, the environment variable
@var{LEDGER_FILE} is set, rather than using this command-line option. @var{LEDGER_FILE} is set, rather than using this command-line option.
@option{--cache FILE} identifies FILE as the default binary cache file. That @option{--cache FILE} identifies FILE as the default binary cache
is, if the ledger files to be read are specified using the environment file. That is, if the ledger files to be read are specified using the
variable @var{LEDGER_FILE}, then whenever a command is finished a binary environment variable @var{LEDGER_FILE}, then whenever a command is
copy will be written to the specified cache, to speed up the loading finished a binary copy will be written to the specified cache, to
time of subsequent queries. This filename can also be given using the speed up the loading time of subsequent queries. This filename can
environment variable @var{LEDGER_CACHE}, or by putting the option into also be given using the environment variable @var{LEDGER_CACHE}, or by
your init file. putting the option into your init file.
@option{--output FILE} (@option{-o FILE}) redirects output from any command to @option{--output FILE} (@option{-o FILE}) redirects output from any
@var{FILE}. By default, all output goes to standard output. command to @var{FILE}. By default, all output goes to standard
output.
@option{--set-price CONV} (@option{-z CONV}) specifies a forced @option{--set-price CONV} (@option{-z CONV}) specifies a forced
commodity conversion. If a setting like @samp{COMM=$1.20} is used, commodity conversion. If a setting like @samp{COMM=$1.20} is used,
@ -424,10 +432,10 @@ will always start at zero with the first matching entry. (Note: This
is different from using @option{--display} to constrain what is is different from using @option{--display} to constrain what is
displayed). displayed).
@option{--end-date DATE} (@option{-e DATE}) contrains the report so that @option{--end-date DATE} (@option{-e DATE}) contrains the report so
entries on or after @var{DATE} are not considered. This ending date that entries on or after @var{DATE} are not considered. This ending
is not inclusive, therefore always use a date that is later than the date is not inclusive, therefore always use a date that is later than
last entry you want to see. the last entry you want to see.
@option{--current}(@option{-c}) displays only entries occurring on or @option{--current}(@option{-c}) displays only entries occurring on or
before the current date. before the current date.
@ -436,21 +444,21 @@ before the current date.
has been marked ``cleared'' (by placing an asterix to the right of the has been marked ``cleared'' (by placing an asterix to the right of the
date). date).
@option{--uncleared} (@option{-U}) displays only transactions whose entry @option{--uncleared} (@option{-U}) displays only transactions whose
has not been marked ``cleared'' (i.e., if there is no asterix to the entry has not been marked ``cleared'' (i.e., if there is no asterix to
right of the date). the right of the date).
@option{--real} (@option{-R}) displays only real transactions, not @option{--real} (@option{-R}) displays only real transactions, not
virtual. (A virtual transaction is indicated by surrounding the virtual. (A virtual transaction is indicated by surrounding the
account name with parentheses or brackets; see the section on using account name with parentheses or brackets; see the section on using
virtual transactions for more information). virtual transactions for more information).
@option{--related} (@option{-r}) displays transactions that are related to @option{--related} (@option{-r}) displays transactions that are
whichever transactions would otherwise have matched the filtering related to whichever transactions would otherwise have matched the
criteria. In the register report, this shows where money went to, or filtering criteria. In the register report, this shows where money
the account it came from. In the balance report, it shows all the went to, or the account it came from. In the balance report, it shows
accounts affected by entries having a related transaction. For all the accounts affected by entries having a related transaction.
example, if a file had this entry: For example, if a file had this entry:
@example @example
2004/03/20 Safeway 2004/03/20 Safeway
@ -479,10 +487,10 @@ transaction that matched.
These options affect only the output, but not which transactions are These options affect only the output, but not which transactions are
used to create it: used to create it:
@option{--date-format STR} (@option{-y STR}) changes the basic date format @option{--date-format STR} (@option{-y STR}) changes the basic date
used by reports. The default uses a date like 2004/08/01, which format used by reports. The default uses a date like 2004/08/01,
represents the default date format of @samp{%Y/%m/%d}. To change the which represents the default date format of @samp{%Y/%m/%d}. To
way dates are printed in general, the easiest way is to change the way dates are printed in general, the easiest way is to
@option{--date-format FORMAT} to the initialize file @file{~/.ledgerc} @option{--date-format FORMAT} to the initialize file @file{~/.ledgerc}
(or the file referred to by @var{LEDGER_INIT}). (or the file referred to by @var{LEDGER_INIT}).
@ -510,33 +518,34 @@ Sets the default format for the @command{print} report.
Sets the default format for the @command{prices} report. Sets the default format for the @command{prices} report.
@item --plot-value-format STR @item --plot-value-format STR
Sets the default format for the @command{register} report, when @option{-j} Sets the default format for the @command{register} report, when
is being used. @option{-j} is being used.
@item --plot-total-format STR @item --plot-total-format STR
Sets the default format for the @command{register} report, when @option{-J} Sets the default format for the @command{register} report, when
is being used. @option{-J} is being used.
@end table @end table
@option{--empty} (@option{-E}) includes even empty accounts in the @option{--empty} (@option{-E}) includes even empty accounts in the
@command{balance} report. @command{balance} report.
@option{--collapse} (@option{-n}) causes entries in a @command{register} @option{--collapse} (@option{-n}) causes entries in a
report with multiple transactions to be collapsed into a single, @command{register} report with multiple transactions to be collapsed
subtotaled entry. into a single, subtotaled entry.
@option{--subtotal} (@option{-s}) causes all entries in a @option{--subtotal} (@option{-s}) causes all entries in a
@command{register} report to be collapsed into a single, subtotaled @command{register} report to be collapsed into a single, subtotaled
entry. entry.
@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing the @option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
values determined using the value expression @var{EXPR}. For example, the values determined using the value expression @var{EXPR}. For
using @option{-S -AT} in the balance report will sort account balances example, using @option{-S -AT} in the balance report will sort account
from greatest to least, using the absolute value of the total. For balances from greatest to least, using the absolute value of the
more on how to use value expressions, see @ref{Value expressions}. total. For more on how to use value expressions, see @ref{Value
expressions}.
@option{--interval STR} (@option{-p STR}) sets the reporting interval to @option{--interval STR} (@option{-p STR}) sets the reporting interval
@var{STR}. This will subtotal all matching entries within each to @var{STR}. This will subtotal all matching entries within each
interval separately, making it easy to see weekly, monthly, quarterly, interval separately, making it easy to see weekly, monthly, quarterly,
etc., transaction totals. An interval string can even specify the etc., transaction totals. An interval string can even specify the
beginning and end of the report range, using simple terms like ``last beginning and end of the report range, using simple terms like ``last
@ -547,19 +556,19 @@ june'' or ``next month''. For more using interval expressions, see
This is an easy way to see if weekend spending is more than on This is an easy way to see if weekend spending is more than on
weekdays. weekdays.
@option{--weekly} (@option{-W}) reports transaction totals by the week. @option{--weekly} (@option{-W}) reports transaction totals by the
The week begins on whichever day a transaction is first found, so to week. The week begins on whichever day a transaction is first found,
start each week on a Sunday, specifying a beginning date for the so to start each week on a Sunday, specifying a beginning date for the
report that falls on a Sunday. @option{--monthly} (@option{-M}) reports report that falls on a Sunday. @option{--monthly} (@option{-M})
transaction totals by month; @option{--yearly} (@option{-Y}) reports reports transaction totals by month; @option{--yearly} (@option{-Y})
transaction totals by year. For more complex interval, using the reports transaction totals by year. For more complex interval, using
@option{--interval} option described above. the @option{--interval} option described above.
@option{--limit EXPR} (@option{-l EXPR}) limits which transactions take @option{--limit EXPR} (@option{-l EXPR}) limits which transactions
part in the calculations of a report. take part in the calculations of a report.
@option{--display EXPR} (@option{-d EXPR}) limits which transactions or @option{--display EXPR} (@option{-d EXPR}) limits which transactions
accounts or actually displayed in a report. They might still be or accounts or actually displayed in a report. They might still be
calculated, and be part of the running total of a register report, for calculated, and be part of the running total of a register report, for
example, but they will not be displayed. This is useful for seeing example, but they will not be displayed. This is useful for seeing
last month's checking transactions, against a running balance which last month's checking transactions, against a running balance which
@ -581,35 +590,35 @@ Which is more useful depends on what you're looking to know: the total
amount for the reporting range (@option{-p}), or simply a display amount for the reporting range (@option{-p}), or simply a display
restricted to the reporting range (using @option{-d}). restricted to the reporting range (using @option{-d}).
@option{--value EXPR} (@option{-t EXPR}) changes the value expression used @option{--value EXPR} (@option{-t EXPR}) changes the value expression
to calculate the ``value'' column in the @command{register} report, used to calculate the ``value'' column in the @command{register}
and the totals in the @command{equity} report. @xref{Value report, and the totals in the @command{equity} report. @xref{Value
expressions}. expressions}.
@option{--total EXPR} (@option{-T EXPR}) sets the value expression used by @option{--total EXPR} (@option{-T EXPR}) sets the value expression
the ``total'' column in the @command{register} report, and also the used by the ``total'' column in the @command{register} report, and
@command{balance} report. also the @command{balance} report.
@option{--value-data} (@option{-j}) changes the @command{register} report @option{--value-data} (@option{-j}) changes the @command{register}
so that it output nothing but the date and the value column, and the report so that it output nothing but the date and the value column,
latter without commodities. This is only meaningful if the report and the latter without commodities. This is only meaningful if the
uses a single commodity. This data can then be fed to other programs, report uses a single commodity. This data can then be fed to other
which could plot the date, analyze it, etc. programs, which could plot the date, analyze it, etc.
@option{--total-data} (@option{-J}) changes the @command{register} report @option{--total-data} (@option{-J}) changes the @command{register}
so that it output nothing but the date and totals column, without report so that it output nothing but the date and totals column,
commodities. without commodities.
@node Commodity reporting, Environment variables, Output customization, Options @node Commodity reporting, Environment variables, Output customization, Options
@subsection Commodity reporting @subsection Commodity reporting
These options affect how commodity values are displayed: These options affect how commodity values are displayed:
@option{--price-db FILE} (@option{-P FILE}) sets the file that is used for @option{--price-db FILE} (@option{-P FILE}) sets the file that is used
recording downloaded commodity prices. It is always read on startup, for recording downloaded commodity prices. It is always read on
to determine historical prices. Other settings can be placed in this startup, to determine historical prices. Other settings can be placed
file manually, to prevent downloading quotes for a specific, for in this file manually, to prevent downloading quotes for a specific,
example. This is done by adding a line like the following: for example. This is done by adding a line like the following:
@example @example
; Don't download quotes for the dollar, or timelog values ; Don't download quotes for the dollar, or timelog values
@ -625,11 +634,12 @@ Perl, is provided in the distribution. Downloaded quote price are
then appended to the price database, usually specified using the then appended to the price database, usually specified using the
environment variable @var{LEDGER_PRICE_DB}. environment variable @var{LEDGER_PRICE_DB}.
@option{--price-exp MINS} (@option{-L MINS}) sets the expected freshness @option{--price-exp MINS} (@option{-L MINS}) sets the expected
of price quotes, in minutes. That is, if the last known quote for any freshness of price quotes, in minutes. That is, if the last known
commodity is older than this value---and if @option{--download} is being quote for any commodity is older than this value---and if
used---then the Internet will be consulted again for a newer price. @option{--download} is being used---then the Internet will be
Otherwise, the old price is still considered to be fresh enough. consulted again for a newer price. Otherwise, the old price is still
considered to be fresh enough.
There are several different ways that ledger can report the totals it There are several different ways that ledger can report the totals it
displays. The most flexible way to adjust them is by using value displays. The most flexible way to adjust them is by using value
@ -665,10 +675,11 @@ on the way the trend values change in the totals column of the
@command{register} report. @command{register} report.
@item --weighted-trend @item --weighted-trend
(@option{-Z}) reports the trend, like @option{--trend}, but factors in the (@option{-Z}) reports the trend, like @option{--trend}, but factors in
passage of time. Older transactions do not swing the trend numbers as the passage of time. Older transactions do not swing the trend
much as recent and future transactions. Thus, recent heavy spending numbers as much as recent and future transactions. Thus, recent heavy
will indicate a higher trend, than if time were not considered. spending will indicate a higher trend, than if time were not
considered.
@end table @end table
@node Environment variables, , Commodity reporting, Options @node Environment variables, , Commodity reporting, Options
@ -693,9 +704,9 @@ option settings in the file @file{~/.ledgerrc}, for example:
Format strings can be used to change the output format of reports. Format strings can be used to change the output format of reports.
They are specified by passing a formatting string to the They are specified by passing a formatting string to the
@option{--format} (@option{-F}) option. Within that string, constructs @option{--format} (@option{-F}) option. Within that string,
are allowed which make it possible to display the various parts of an constructs are allowed which make it possible to display the various
account or transaction in custom ways. parts of an account or transaction in custom ways.
Within a format strings, a subtitution is specified using a percent Within a format strings, a subtitution is specified using a percent
character (@samp{%}). The basic format of all substitutions is: character (@samp{%}). The basic format of all substitutions is:
@ -864,8 +875,8 @@ each variable for both is specified.
@item t @item t
This maps to whatever the user specified with @option{-t}. In a This maps to whatever the user specified with @option{-t}. In a
register report, @option{-t} changes the value column; in a balance register report, @option{-t} changes the value column; in a balance
report, it has no meaning by default. If @option{-t} was not specified, report, it has no meaning by default. If @option{-t} was not
the current report style's value expression is used. specified, the current report style's value expression is used.
@item T @item T
This maps to whatever the user specified with @option{-T}. In a This maps to whatever the user specified with @option{-T}. In a
@ -1375,7 +1386,7 @@ making it easier to run the balance command:
$ bal $ bal
@end example @end example
To use this script, it must be copied from the @strong{scripts} To use this script, it must be copied from the @file{scripts}
directory in the ledger distribution, to a directory along your directory in the ledger distribution, to a directory along your
@var{PATH}. Also, you must set the environment variable @var{LEDGER} @var{PATH}. Also, you must set the environment variable @var{LEDGER}
to point to your main ledger file. to point to your main ledger file.
@ -1475,11 +1486,11 @@ Note that all amounts must be specified now:
Company XYZ:Accounts Payable:Your Name $-100.00 Company XYZ:Accounts Payable:Your Name $-100.00
@end example @end example
To ``pay back'' the reimbursement, just reverse the order of everything, To ``pay back'' the reimbursement, just reverse the order of
except this time drawing the money from a company asset, paying it to everything, except this time drawing the money from a company asset,
accounts payable, and then drawing it again from the reimbursement paying it to accounts payable, and then drawing it again from the
account, and paying it to your personal asset account. It's easier reimbursement account, and paying it to your personal asset account.
shown than said: It's easier shown than said:
@example @example
2004/10/15 Company XYZ 2004/10/15 Company XYZ