[doc] Whitespace edit

to end each sentence with two spaces.
This commit is contained in:
Alexis Hildebrandt 2015-02-15 09:41:00 +01:00
parent bd427a9d32
commit 82cdeff471
2 changed files with 168 additions and 168 deletions

View file

@ -310,7 +310,7 @@ fit inside the
If If
.Ar INT .Ar INT
is zero, then the is zero, then the
account name will be truncated on the right. If account name will be truncated on the right. If
.Ar INT .Ar INT
is greater is greater
than than
@ -321,7 +321,7 @@ desired width.
.It Fl \-account Ar EXPR .It Fl \-account Ar EXPR
Prepend Prepend
.Ar EXPR .Ar EXPR
to all accounts reported. That is, the option to all accounts reported. That is, the option
.Fl \-account Ar \*q'Personal'\*q .Fl \-account Ar \*q'Personal'\*q
would tack would tack
.Ar Personal: .Ar Personal:
@ -346,7 +346,7 @@ transactions used.
.It Fl \-add-budget .It Fl \-add-budget
Show only un-budgeted postings. Show only un-budgeted postings.
.It Fl \-amount Ar EXPR Pq Fl t .It Fl \-amount Ar EXPR Pq Fl t
Apply the given value expression to the posting amount. Using Apply the given value expression to the posting amount. Using
.Fl \-amount Ar EXPR .Fl \-amount Ar EXPR
you can apply an you can apply an
arbitrary transformation to the postings. arbitrary transformation to the postings.
@ -391,12 +391,12 @@ Alias for
.It Fl \-begin Ar DATE Pq Fl b .It Fl \-begin Ar DATE Pq Fl b
Specify the start Specify the start
.Ar DATE .Ar DATE
of all calculations. Transactions before of all calculations. Transactions before
that date will be ignored. that date will be ignored.
.It Fl \-bold-if Ar EXPR .It Fl \-bold-if Ar EXPR
Print the entire line in bold if the given value expression is true. Print the entire line in bold if the given value expression is true.
.It Fl \-budget .It Fl \-budget
Only display budgeted items. In a Only display budgeted items. In a
.Ic register .Ic register
report this displays transaction in the budget, in a balance report this report this displays transaction in the budget, in a balance report this
displays accounts in the budget. displays accounts in the budget.
@ -428,7 +428,7 @@ Make the
.Ic register .Ic register
report report
.Ar INT .Ar INT
characters wide. By default characters wide. By default
.Nm .Nm
will use all available columns in your terminal. will use all available columns in your terminal.
.It Fl \-cost .It Fl \-cost
@ -511,7 +511,7 @@ but not
This is a display predicate, which means it only affects display, This is a display predicate, which means it only affects display,
not the total calculations. not the total calculations.
.It Fl \-deviation .It Fl \-deviation
Report each posting's deviation from the average. It is only meaningful Report each posting's deviation from the average. It is only meaningful
in the in the
.Ic register No and Ic prices .Ic register No and Ic prices
reports. reports.
@ -546,7 +546,7 @@ distribution. Downloaded quote price are then appended to the price
database, usually specified using the environment variable database, usually specified using the environment variable
.Ev LEDGER_PRICE_DB . .Ev LEDGER_PRICE_DB .
.It Fl \-effective .It Fl \-effective
Show auxiliary dates for all calculations. Alias for Show auxiliary dates for all calculations. Alias for
.Fl \-aux-date . .Fl \-aux-date .
.It Fl \-empty Pq Fl E .It Fl \-empty Pq Fl E
Include empty accounts in report. Include empty accounts in report.
@ -574,15 +574,15 @@ Read journal data from
.It Fl \-first Ar INT .It Fl \-first Ar INT
Print the first Print the first
.Ar INT .Ar INT
entries. Opposite of entries. Opposite of
.Fl \-last Ar INT . .Fl \-last Ar INT .
Alias for Alias for
.Fl \-head . .Fl \-head .
.It Fl \-flat .It Fl \-flat
Force the full names of accounts to be used in the balance report. The Force the full names of accounts to be used in the balance report. The
balance report will not use an indented tree. balance report will not use an indented tree.
.It Fl \-force-color .It Fl \-force-color
Output TTY color codes even if the TTY doesn't support them. Useful Output TTY color codes even if the TTY doesn't support them. Useful
for TTYs that don't advertise their capabilities correctly. for TTYs that don't advertise their capabilities correctly.
.It Fl \-force-pager .It Fl \-force-pager
Force Force
@ -628,7 +628,7 @@ register report.
.It Fl \-head Ar INT .It Fl \-head Ar INT
Print the first Print the first
.Ar INT .Ar INT
entries. Opposite of entries. Opposite of
.Fl \-tail Ar INT . .Fl \-tail Ar INT .
Alias for Alias for
.Fl \-first .Fl \-first
@ -668,9 +668,9 @@ Change the sign of all reported values.
.It Fl \-last Ar INT . .It Fl \-last Ar INT .
Report only the last Report only the last
.Ar INT .Ar INT
entries. Opposite of entries. Opposite of
.Fl \-first Ar INT . .Fl \-first Ar INT .
Only useful on a register report. Alias for Only useful on a register report. Alias for
.Fl \-tail . .Fl \-tail .
.It Fl \-leeway Ar INT Pq Fl Z .It Fl \-leeway Ar INT Pq Fl Z
Alias for Alias for
@ -729,7 +729,7 @@ Suppress printing the final total line in a balance report.
.It Fl \-now Ar DATE .It Fl \-now Ar DATE
Use Use
.Ar DATE .Ar DATE
as the current date. This affects the output when using as the current date. This affects the output when using
.Fl \-period , .Fl \-period ,
.Fl \-begin , .Fl \-begin ,
.Fl \-end , .Fl \-end ,
@ -754,7 +754,7 @@ Use
.Ar STR .Ar STR
as the pager program. as the pager program.
.It Fl \-payee .It Fl \-payee
Sets a value expression for formatting the payee. In the Sets a value expression for formatting the payee. In the
.Ic register .Ic register
report this prevents the second entry from having report this prevents the second entry from having
a date and payee for each transaction. a date and payee for each transaction.
@ -771,7 +771,7 @@ Calculate the percentage value of each account in a balance reports.
Only works for account that have a single commodity. Only works for account that have a single commodity.
.It Fl \-period Ar PERIOD Pq Fl p .It Fl \-period Ar PERIOD Pq Fl p
Define a period expression that sets the time period during which Define a period expression that sets the time period during which
transactions are to be accounted. For a transactions are to be accounted. For a
.Ic register .Ic register
report only report only
the transactions that satisfy the period expression with be displayed. the transactions that satisfy the period expression with be displayed.
@ -804,12 +804,12 @@ Use the price of the commodity purchase for performing calculations.
.It Fl \-price-exp Ar STR Pq Fl Z .It Fl \-price-exp Ar STR Pq Fl Z
Set the expected freshness of price quotes, in Set the expected freshness of price quotes, in
.Ar INT .Ar INT
minutes. That minutes. That
is, if the last known quote for any commodity is older than this value, is, if the last known quote for any commodity is older than this value,
and if and if
.Fl \-download .Fl \-download
is being used, then the Internet will be is being used, then the Internet will be
consulted again for a newer price. Otherwise, the old price is still consulted again for a newer price. Otherwise, the old price is still
considered to be fresh enough. considered to be fresh enough.
Alias for Alias for
.Fl \-leeway . .Fl \-leeway .
@ -820,7 +820,7 @@ report.
.It Fl \-pricedb-format Ar FMT .It Fl \-pricedb-format Ar FMT
Set the format expected for the historical price file. Set the format expected for the historical price file.
.It Fl \-primary-date .It Fl \-primary-date
Show primary dates for all calculations. Alias for Show primary dates for all calculations. Alias for
.Fl \-actual-dates .Fl \-actual-dates
.It Fl \-quantity Pq Fl O .It Fl \-quantity Pq Fl O
Report commodity totals (this is the default). Report commodity totals (this is the default).
@ -906,7 +906,7 @@ Report register as a single subtotal.
.It Fl \-tail Ar INT .It Fl \-tail Ar INT
Report only the last Report only the last
.Ar INT .Ar INT
entries. Only useful on a register report. Alias for entries. Only useful on a register report. Alias for
.Fl \-last Ar INT .Fl \-last Ar INT
.It Fl \-time-colon .It Fl \-time-colon
Display the value for commodities based on seconds as hours and minutes. Display the value for commodities based on seconds as hours and minutes.
@ -922,12 +922,12 @@ Show only dates and totals to format the output for plots.
.It Fl \-total-width Ar INT .It Fl \-total-width Ar INT
Set the width of the total field in the register report. Set the width of the total field in the register report.
.It Fl \-trace Ar INT .It Fl \-trace Ar INT
Enable tracing. The Enable tracing. The
.Ar INT .Ar INT
specifies the level of trace desired. specifies the level of trace desired.
.It Fl \-truncate Ar STR .It Fl \-truncate Ar STR
Indicates how truncation should happen when the contents of columns Indicates how truncation should happen when the contents of columns
exceed their width. Valid arguments for exceed their width. Valid arguments for
.Ar STR .Ar STR
are are
.Ar leading , .Ar leading ,
@ -947,14 +947,14 @@ Show generated unrealized gain and loss accounts in the balance
report. report.
.It Fl \-unrealized-gains .It Fl \-unrealized-gains
Allow the user to specify what account name should be used for Allow the user to specify what account name should be used for
unrealized gains. Defaults to unrealized gains. Defaults to
.Sy "Equity:Unrealized Gains" . .Sy "Equity:Unrealized Gains" .
Often set in one's Often set in one's
.Pa ~/.ledgerrc .Pa ~/.ledgerrc
file to change the default. file to change the default.
.It Fl \-unrealized-losses .It Fl \-unrealized-losses
Allow the user to specify what account name should be used for Allow the user to specify what account name should be used for
unrealized gains. Defaults to unrealized gains. Defaults to
.Sy "Equity:Unrealized Losses" . .Sy "Equity:Unrealized Losses" .
Often set in one's Often set in one's
.Pa ~/.ledgerrc .Pa ~/.ledgerrc
@ -972,13 +972,13 @@ Set a global value expression annotation.
Print detailed information on the execution of Print detailed information on the execution of
.Nm . .Nm .
.It Fl \-verify .It Fl \-verify
Enable additional assertions during run-time. This causes a significant Enable additional assertions during run-time. This causes a significant
slowdown. When combined with slowdown. When combined with
.Fl \-debug Ar CODE .Fl \-debug Ar CODE
.Nm .Nm
will produce memory trace information. will produce memory trace information.
.It Fl \-verify-memory .It Fl \-verify-memory
Verify that every constructed object is properly destructed. This is for Verify that every constructed object is properly destructed. This is for
debugging purposes only. debugging purposes only.
.It Fl \-version .It Fl \-version
Print version information and exit. Print version information and exit.
@ -993,7 +993,7 @@ Shorthand for
.El .El
.Sh PRE-COMMANDS .Sh PRE-COMMANDS
Pre-commands are useful when you aren't sure how a command or option Pre-commands are useful when you aren't sure how a command or option
will work. The difference between a pre-command and a regular command will work. The difference between a pre-command and a regular command
is that pre-commands ignore the journal data file completely, nor is is that pre-commands ignore the journal data file completely, nor is
the user's init file read. the user's init file read.
.Bl -tag -width -indent .Bl -tag -width -indent
@ -1225,7 +1225,7 @@ Return
.Ar value .Ar value
rounded to rounded to
.Ar n .Ar n
digits. Does not affect formatting. digits. Does not affect formatting.
.\".It Sy scrub .\".It Sy scrub
.\".It Sy status .\".It Sy status
.\".It Sy strip .\".It Sy strip

View file

@ -58,7 +58,7 @@
@c the documentation itself, in that case the journal example data @c the documentation itself, in that case the journal example data
@c needs to be specially marked as well using @smallexample @c input:UUID, @c needs to be specially marked as well using @smallexample @c input:UUID,
@c again with the UUID being the UUID of the corresponding ledger example @c again with the UUID being the UUID of the corresponding ledger example
@c command. If multiple inputs with the same UUID are found they will be @c command. If multiple inputs with the same UUID are found they will be
@c concatenated together and given as one set of data to the example command. @c concatenated together and given as one set of data to the example command.
@c @c
@c @smallexample @c input:35CB2A3 @c @smallexample @c input:35CB2A3
@ -288,7 +288,7 @@ Here is a good place for an aside on the use of the word ``account''.
Most private people consider an account to be something that holds Most private people consider an account to be something that holds
money at an institution for them. Ledger uses a more general money at an institution for them. Ledger uses a more general
definition of the word. An account is anywhere money can go. Other definition of the word. An account is anywhere money can go. Other
finance programs use ``categories'', Ledger uses accounts. So, for finance programs use ``categories'', Ledger uses accounts. So, for
example, if you buy some groceries at Trader Joe's, then more groceries example, if you buy some groceries at Trader Joe's, then more groceries
at Whole Food Market, you might assign the transactions like this at Whole Food Market, you might assign the transactions like this
@ -382,8 +382,8 @@ acprep script, that does a lot of the footwork:
@end smallexample @end smallexample
See the `help` subcommand to `acprep`, which explains some of its many See the `help` subcommand to `acprep`, which explains some of its many
options. You can run `make check` to confirm the result, and `make options. You can run `make check` to confirm the result, and `make
install` to install. If these intructions do not work for you can check the install` to install. If these intructions do not work for you can check the
`INSTALL.md` in the source directory for more up do date build instructions. `INSTALL.md` in the source directory for more up do date build instructions.
@node Getting help, , Building the program, Introduction to Ledger @node Getting help, , Building the program, Introduction to Ledger
@ -1530,7 +1530,7 @@ Accounts}).
@cindex posting format details @cindex posting format details
@strong{The format is very flexible and it isn't necessary that you @strong{The format is very flexible and it isn't necessary that you
indent and space out things exactly as shown. The only requirements indent and space out things exactly as shown. The only requirements
are that the start of the transaction (the date typically) is at the are that the start of the transaction (the date typically) is at the
beginning of the first line of the transaction, and the accounts are beginning of the first line of the transaction, and the accounts are
indented by at least one space. If you omit the leading spaces in the indented by at least one space. If you omit the leading spaces in the
@ -1551,7 +1551,7 @@ Ledger has a starting point.
At some convenient point in time you knew the balances and outstanding At some convenient point in time you knew the balances and outstanding
obligation of every financial account you have. Those amounts form the obligation of every financial account you have. Those amounts form the
basis of the opening entry for ledger. For example if you chose the basis of the opening entry for ledger. For example if you chose the
beginning of 2011 as the date to start tracking finances with ledger, beginning of 2011 as the date to start tracking finances with ledger,
your opening balance entry could look like this: your opening balance entry could look like this:
@ -1660,7 +1660,7 @@ Dollars, Euros, Pounds, Francs, Shares etc. are all just ``commodities''.
Holdings in stocks, bonds, mutual funds and other financial Holdings in stocks, bonds, mutual funds and other financial
instruments can be labeled using whatever is convenient for you (stock instruments can be labeled using whatever is convenient for you (stock
ticker symbols are suggested for publicly traded assets).@footnote{You ticker symbols are suggested for publicly traded assets).@footnote{You
can track @emph{anything}, even time or distance traveled. As long as can track @emph{anything}, even time or distance traveled. As long as
it cannot be created or destroyed inside your accounting system.} it cannot be created or destroyed inside your accounting system.}
For the rest of this manual, we will only use the word ``commodities'' For the rest of this manual, we will only use the word ``commodities''
@ -1691,7 +1691,7 @@ business trip to Europe from the US:
@end smallexample @end smallexample
This says that $66.00 came out of checking and turned into 50 This says that $66.00 came out of checking and turned into 50
Euros. The implied exchange rate was $1.32. Then 35.00 Euros were Euros. The implied exchange rate was $1.32. Then 35.00 Euros were
spent on Dinner in Munich. spent on Dinner in Munich.
Running a ledger balance report shows: Running a ledger balance report shows:
@ -1748,7 +1748,7 @@ commodity name must be enclosed in double quotes @samp{"}:
Buying stock is a typical example that many will use that involves Buying stock is a typical example that many will use that involves
multiple commodities in the same transaction. The type of the share multiple commodities in the same transaction. The type of the share
(AAPL for Apple Inc.) and the share purchase price in the currency (AAPL for Apple Inc.) and the share purchase price in the currency
unit you made the purchase in ($ for AAPL). Yes, the typical unit you made the purchase in ($ for AAPL). Yes, the typical
convention is as follows: convention is as follows:
@smallexample @c input:validate @smallexample @c input:validate
@ -1842,8 +1842,8 @@ Assets:Checking because its amount is null.
@findex --exchange @var{COMMODITY} @findex --exchange @var{COMMODITY}
Ledger allows you to have very detailed control over how your Ledger allows you to have very detailed control over how your
commodities are valued. You can fine tune the results given using the commodities are valued. You can fine tune the results given using the
@option{--market} or @option{--exchange @var{COMMODITY}} options. There @option{--market} or @option{--exchange @var{COMMODITY}} options. There
are now several points of interception; you can specify the valuation are now several points of interception; you can specify the valuation
method: method:
@ -1874,7 +1874,7 @@ The reference date the price should be relative.
@item target @item target
A string identifying the ``target'' commodity, or the commodity the A string identifying the ``target'' commodity, or the commodity the
returned price should be in. This argument is null if @option{--market} returned price should be in. This argument is null if @option{--market}
was used instead of @option{--exchange @var{COMMODITY}}. was used instead of @option{--exchange @var{COMMODITY}}.
@end table @end table
@ -1883,7 +1883,7 @@ The valuation function should return an amount. If you've written
your function in Python, you can return something like your function in Python, you can return something like
@samp{Amount("$100")}. If the function returns an explicit value, @samp{Amount("$100")}. If the function returns an explicit value,
that value is always used, regardless of the commodity, the date, or that value is always used, regardless of the commodity, the date, or
the desired target commodity. For example, the desired target commodity. For example,
@smallexample @smallexample
define myfunc_seven(s, d, t) = 7 EUR define myfunc_seven(s, d, t) = 7 EUR
@ -2116,7 +2116,7 @@ postings, just as if it were a normal transaction.
@item ; # % | * @item ; # % | *
A line beginning with a semicolon, pound, percent, bar or asterisk A line beginning with a semicolon, pound, percent, bar or asterisk
indicates a comment, and is ignored. Comments will not be returned in indicates a comment, and is ignored. Comments will not be returned in
a ``print'' response. a ``print'' response.
@item indented ; @item indented ;
@ -2300,7 +2300,7 @@ bucket Assets:Checking
@findex register @findex register
Directs Ledger to replace any account matching a regex with the given Directs Ledger to replace any account matching a regex with the given
account. For example: account. For example:
@smallexample @c input:validate @smallexample @c input:validate
capture Expenses:Deductible:Medical Medical capture Expenses:Deductible:Medical Medical
@ -2361,7 +2361,7 @@ The @code{default} sub-directive marks this as the ``default'' commodity.
@item define @item define
@c instance_t::define_directive in textual.cc @c instance_t::define_directive in textual.cc
Allows you to define value expressions for future use. For example: Allows you to define value expressions for future use. For example:
@smallexample @c input:validate @smallexample @c input:validate
define var_name=$100 define var_name=$100
@ -2513,7 +2513,7 @@ is the equivalent of:
@c TODO: the following paragraph seems to be false, the automated tests @c TODO: the following paragraph seems to be false, the automated tests
@c fail, if anything appears after end apply tag. @c fail, if anything appears after end apply tag.
@c Note that anything following @code{end apply tag} is ignored. placing @c Note that anything following @code{end apply tag} is ignored. Placing
@c the name of the tag that is being closed is a simple way to keep @c the name of the tag that is being closed is a simple way to keep
@c track. @c track.
@ -2992,13 +2992,13 @@ You can gang up multiple tags by sharing colons:
@findex payees @findex payees
@findex --by-payee @findex --by-payee
``Payee'' is a special metadata field. If set on a posting, it will be ``Payee'' is a special metadata field. If set on a posting, it will be
used as the payee name for that posting. This affects the used as the payee name for that posting. This affects the
@command{register} report, the @command{payees} report, and the @command{register} report, the @command{payees} report, and the
@option{--by-payee} option. @option{--by-payee} option.
This is useful when for example you deposit 4 checks at a time to the This is useful when for example you deposit 4 checks at a time to the
bank. On the bank statement, there is just one amount @samp{$400}, but bank. On the bank statement, there is just one amount @samp{$400}, but
you can specify from whom each check came from, as shown by example you can specify from whom each check came from, as shown by example
below: below:
@ -3132,7 +3132,7 @@ the amount expression with parentheses:
If at the end of a posting's amount (and after the cost too, if there If at the end of a posting's amount (and after the cost too, if there
is one) there is an equals sign, then Ledger will verify that the is one) there is an equals sign, then Ledger will verify that the
total value for that account as of that posting matches the amount total value for that account as of that posting matches the amount
specified. See @option{--permissive} option to relax the balance assertions checks. specified. See @option{--permissive} option to relax the balance assertions checks.
There are two forms of this features: balance assertions, and balance There are two forms of this features: balance assertions, and balance
assignments. assignments.
@ -3834,7 +3834,7 @@ the generated posting.
@findex --effective @findex --effective
In the real world, transactions do not take place instantaneously. In the real world, transactions do not take place instantaneously.
Purchases can take several days to post to a bank account. And you may Purchases can take several days to post to a bank account. And you may
pay ahead for something for which you want to distribute costs. With pay ahead for something for which you want to distribute costs. With
Ledger you can control every aspect of the timing of a transaction. Ledger you can control every aspect of the timing of a transaction.
@ -3882,7 +3882,7 @@ $ ledger --effective --begin 2008/01/01 --end 2008/01/14 bal Income
@noindent @noindent
gives you your cash basis income in the same two weeks. gives you your cash basis income in the same two weeks.
Another use is distributing costs out in time. As an example, suppose Another use is distributing costs out in time. As an example, suppose
you just prepaid into a local vegetable co-op that sustains you you just prepaid into a local vegetable co-op that sustains you
through the winter. It costs $225 to join the program, so you write through the winter. It costs $225 to join the program, so you write
a check. You don't want your October grocery budget to be blown a check. You don't want your October grocery budget to be blown
@ -3929,7 +3929,7 @@ $ ledger --effective register Groceries
A periodic transaction starts with a @samp{~} followed by a period A periodic transaction starts with a @samp{~} followed by a period
expression. Periodic transactions are used for budgeting and expression. Periodic transactions are used for budgeting and
forecasting only, they have no effect without the @option{--budget} forecasting only, they have no effect without the @option{--budget}
option specified. For examples and details, @pxref{Budgeting and option specified. For examples and details, @pxref{Budgeting and
Forecasting}. Forecasting}.
@node Concrete Example of Automated Transactions, , Periodic Transactions, Automated Transactions @node Concrete Example of Automated Transactions, , Periodic Transactions, Automated Transactions
@ -4043,7 +4043,7 @@ may be excluded from reports by using @option{--real}.
The power of Ledger comes from the incredible flexibility in its The power of Ledger comes from the incredible flexibility in its
reporting commands, combined with formatting commands. Some options reporting commands, combined with formatting commands. Some options
control what is included in the calculations, and formatting controls control what is included in the calculations, and formatting controls
how it is displayed. The combinations are infinite. This chapter will how it is displayed. The combinations are infinite. This chapter will
show you the basics of combining various options and commands. In the show you the basics of combining various options and commands. In the
next chapters you will find details about the specific commands and next chapters you will find details about the specific commands and
options. options.
@ -4181,7 +4181,7 @@ $ ledger bal Expenses and not (Expenses:Drinks or Expenses:Candy or Expenses:Gif
@subsection Controlling Formatting @subsection Controlling Formatting
These examples all use the default formatting for the balance These examples all use the default formatting for the balance
report. Customizing the formatting can easily allowing to see only what report. Customizing the formatting can easily allowing to see only what
you want, or interface Ledger with other programs. you want, or interface Ledger with other programs.
@node Typical queries, Advanced Reports, Balance Reports, Building Reports @node Typical queries, Advanced Reports, Balance Reports, Building Reports
@ -4373,7 +4373,7 @@ third line is where we calculate and display the percentages. The
for the account in this line. The @code{parent.total} command gives for the account in this line. The @code{parent.total} command gives
the total for the next level up in the tree. @code{percent} formats the total for the next level up in the tree. @code{percent} formats
their ratio as a percentage. The fourth line tells ledger to display their ratio as a percentage. The fourth line tells ledger to display
the current market value of the line. The last two characters the current market value of the line. The last two characters
@samp{%/} tell Ledger what to do for the last line, in this case, @samp{%/} tell Ledger what to do for the last line, in this case,
nothing. nothing.
@ -4387,13 +4387,13 @@ nothing.
@findex --display @var{EXPR} @findex --display @var{EXPR}
If you have the ``Gnuplot'' program installed, you can graph any of the If you have the ``Gnuplot'' program installed, you can graph any of the
above register reports. The script to do this is included in the ledger above register reports. The script to do this is included in the ledger
distribution, and is named @file{contrib/report}. Install @file{report} distribution, and is named @file{contrib/report}. Install @file{report}
anywhere along your @env{PATH}, and then use @file{report} instead of anywhere along your @env{PATH}, and then use @file{report} instead of
@file{ledger} when doing a register report. The only thing to keep in @file{ledger} when doing a register report. The only thing to keep in
mind is that you must specify @option{--amount-data (-j)} or mind is that you must specify @option{--amount-data (-j)} or
@option{--total-data (-J)} to indicate whether ``Gnuplot'' should plot @option{--total-data (-J)} to indicate whether ``Gnuplot'' should plot
the amount, or the running total. For example, this command plots total the amount, or the running total. For example, this command plots total
monthly expenses made on your MasterCard. monthly expenses made on your MasterCard.
@smallexample @smallexample
@ -4416,7 +4416,7 @@ report -J reg ^income ^expenses # cash flow report
report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
# net worth report starting last February. the use of a display # net worth report starting last February. the use of a display
# predicate (-d) is needed, otherwise the balance will start at # predicate (-d) is needed, otherwise the balance will start at
# zero, and thus the y-axis will not reflect the true balance # zero, and thus the y-axis will not reflect the true balance
@ -4571,9 +4571,9 @@ Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Chec
1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,, 1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,,
@end smallexample @end smallexample
Unfortunately, as it stands Ledger cannot read it, but you can. Ledger Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
expects the first line to contain a description of the fields on each expects the first line to contain a description of the fields on each
line of the file. The fields ledger can recognize contain these line of the file. The fields ledger can recognize contain these
case-insensitive strings @code{date}, @code{posted}, @code{code}, case-insensitive strings @code{date}, @code{posted}, @code{code},
@code{payee} or @code{desc} or @code{description}, @code{amount}, @code{payee} or @code{desc} or @code{description}, @code{amount},
@code{cost}, @code{total}, and @code{note}. @code{cost}, @code{total}, and @code{note}.
@ -4600,7 +4600,7 @@ scripting.
If there are columns in the bank data you would like to keep in your If there are columns in the bank data you would like to keep in your
ledger data, besides the primary fields described above, you can name ledger data, besides the primary fields described above, you can name
them in the field descriptor list and Ledger will include them in the them in the field descriptor list and Ledger will include them in the
transaction as meta data if it doesn't recognize the field name. For transaction as meta data if it doesn't recognize the field name. For
example, if you want to capture the bank transaction number and it example, if you want to capture the bank transaction number and it
occurs in the first column of the data use: occurs in the first column of the data use:
@ -4615,21 +4615,21 @@ from the file above.
@findex --account @var{STR} @findex --account @var{STR}
@findex --rich-data @findex --rich-data
The @command{convert} command accepts three options. They are The @command{convert} command accepts three options. They are
@option{--invert} which inverts the amount field, @option{--invert} which inverts the amount field,
@option{--account @var{STR}} which you can use to specify the account to @option{--account @var{STR}} which you can use to specify the account to
balance against, and @option{--rich-data} which stores balance against, and @option{--rich-data} which stores
additional metadata as tags. There is, for example, additional metadata as tags. There is, for example,
a UUID field. If an entry with the same UUID tag is already included in a UUID field. If an entry with the same UUID tag is already included in
the normal ledger file (specified via @option{--file @var{FILE} (-f)} or the normal ledger file (specified via @option{--file @var{FILE} (-f)} or
via the environment variable @env{LEDGER_FILE}) this entry will not be via the environment variable @env{LEDGER_FILE}) this entry will not be
printed again. printed again.
You can also use @command{convert} with @code{payee} and @code{account} You can also use @command{convert} with @code{payee} and @code{account}
directives. First, you can use the @code{payee} and @code{alias} directives. First, you can use the @code{payee} and @code{alias}
directive to rewrite the @code{payee} field based on some rules. Then directive to rewrite the @code{payee} field based on some rules. Then
you can use the account and its @code{payee} directive to specify the you can use the account and its @code{payee} directive to specify the
account. I use it like this, for example: account. I use it like this, for example:
@smallexample @c input:validate @smallexample @c input:validate
payee Aldi payee Aldi
@ -4640,7 +4640,7 @@ account Aufwand:Einkauf:Lebensmittel
Note that it may be necessary for the output of @samp{ledger convert} Note that it may be necessary for the output of @samp{ledger convert}
to be passed through @code{ledger print} a second time if you want to to be passed through @code{ledger print} a second time if you want to
match on the new payee field. During the @code{ledger convert} run, match on the new payee field. During the @code{ledger convert} run,
only the original payee name as specified in the csv data seems to be only the original payee name as specified in the csv data seems to be
used. used.
@ -4726,7 +4726,7 @@ Using Babel, it is possible to record financial transactions
conveniently in an org file and subsequently generate the financial conveniently in an org file and subsequently generate the financial
reports required. reports required.
As of Org mode 7.01, Ledger support is provided. Check the Babel As of Org mode 7.01, Ledger support is provided. Check the Babel
documentation on Worg for instructions on how to achieve this but documentation on Worg for instructions on how to achieve this but
I currently do this directly as follows: I currently do this directly as follows:
@ -4738,7 +4738,7 @@ I currently do this directly as follows:
@end smallexample @end smallexample
Once Ledger support in Babel has been enabled, we can proceed to Once Ledger support in Babel has been enabled, we can proceed to
include Ledger entries within an org file. There are three ways (at include Ledger entries within an org file. There are three ways (at
least) in which these can be included: least) in which these can be included:
@enumerate @enumerate
@ -4777,7 +4777,7 @@ The first two are described in more detail in this short tutorial.
The easiest, albeit possibly least useful, way in which to use Ledger The easiest, albeit possibly least useful, way in which to use Ledger
within an org file is to use a single source block to record all Ledger within an org file is to use a single source block to record all Ledger
entries. The following is an example source block: entries. The following is an example source block:
@smallexample @smallexample
#+name: allinone #+name: allinone
@ -4807,11 +4807,11 @@ entries. The following is an example source block:
@end smallexample @end smallexample
In this example, we have combined both expenses and income into one set In this example, we have combined both expenses and income into one set
of Ledger entries. We can now generate register and balance reports (as of Ledger entries. We can now generate register and balance reports (as
well as many other types of reports) using Babel to invoke Ledger with well as many other types of reports) using Babel to invoke Ledger with
specific arguments. The arguments are passed to Ledger using the specific arguments. The arguments are passed to Ledger using the
@code{:cmdline} header argument. In the code block above, there is no @code{:cmdline} header argument. In the code block above, there is no
such argument so the system takes the default. For Ledger code blocks, such argument so the system takes the default. For Ledger code blocks,
the default @code{:cmdline} argument is @code{bal} and the result of the default @code{:cmdline} argument is @code{bal} and the result of
evaluating this code block (@kbd{C-c C-c}) would be: evaluating this code block (@kbd{C-c C-c}) would be:
@ -4841,16 +4841,16 @@ Evaluating the code block again would generate a different report.
Having to change the actual directive on the code block and re-evaluate Having to change the actual directive on the code block and re-evaluate
makes it difficult to have more than one view of your transactions and makes it difficult to have more than one view of your transactions and
financial state. Eventually, Babel will support passing arguments to financial state. Eventually, Babel will support passing arguments to
@code{#+call} evaluations of code blocks but this support is missing @code{#+call} evaluations of code blocks but this support is missing
currently. Instead, we can use the concepts of literary programming, as currently. Instead, we can use the concepts of literary programming, as
implemented by the @code{noweb} features of Babel, to help us. implemented by the @code{noweb} features of Babel, to help us.
@node Multiple Ledger source blocks with @code{noweb}, Income Entries, Embedded Ledger example with single source block, Org mode with Babel @node Multiple Ledger source blocks with @code{noweb}, Income Entries, Embedded Ledger example with single source block, Org mode with Babel
@subsubsection Multiple Ledger source blocks with @code{noweb} @subsubsection Multiple Ledger source blocks with @code{noweb}
The @code{noweb} feature of Babel allows us to expand references to The @code{noweb} feature of Babel allows us to expand references to
other code blocks within a code block. For Ledger, this can be used to other code blocks within a code block. For Ledger, this can be used to
group transactions according to type, say, and then bring various sets group transactions according to type, say, and then bring various sets
of transactions together to generate reports. of transactions together to generate reports.
@ -4861,9 +4861,9 @@ these into expenses and income, as follows:
@subsubsection Income Entries @subsubsection Income Entries
The first set of entries relates to income, either monthly pay or The first set of entries relates to income, either monthly pay or
interest, all typically going into one of my bank accounts. Here, I have interest, all typically going into one of my bank accounts. Here, I have
placed several entries, but we could have had each entry in a separate placed several entries, but we could have had each entry in a separate
@code{src} block. Note that all code blocks you wish to refer to later @code{src} block. Note that all code blocks you wish to refer to later
must have the @code{:noweb yes} header argument specified. must have the @code{:noweb yes} header argument specified.
@smallexample @smallexample
@ -4891,7 +4891,7 @@ must have the @code{:noweb yes} header argument specified.
@subsubsection Expenses @subsubsection Expenses
The following entries relate to personal expenses, such as rent and The following entries relate to personal expenses, such as rent and
food. Again, these have all been placed in a single @code{src} block but food. Again, these have all been placed in a single @code{src} block but
could have been done individually. could have been done individually.
@smallexample @smallexample
@ -4911,8 +4911,8 @@ could have been done individually.
Given the ledger entries defined above in the income and expenses code Given the ledger entries defined above in the income and expenses code
blocks, we can now refer to these using the noweb expansion directives, blocks, we can now refer to these using the noweb expansion directives,
@code{<<name>>}. We can now define different code blocks to generate @code{<<name>>}. We can now define different code blocks to generate
specific reports for those transactions. Below are two examples, one to specific reports for those transactions. Below are two examples, one to
generate a balance report and one to generate a register report of all generate a balance report and one to generate a register report of all
transactions. transactions.
@ -4922,7 +4922,7 @@ transactions.
The overall balance of your account and expenditure with a breakdown The overall balance of your account and expenditure with a breakdown
according to category is specified by passing the @code{:cmdline bal} according to category is specified by passing the @code{:cmdline bal}
argument to Ledger. This code block can now be evaluated (@kbd{C-c C-c}) argument to Ledger. This code block can now be evaluated (@kbd{C-c C-c})
and the results generated by incorporating the transactions referred to and the results generated by incorporating the transactions referred to
by the @code{<<income>>} and @code{<<expenses>>} lines. by the @code{<<income>>} and @code{<<expenses>>} lines.
@ -4968,7 +4968,7 @@ to tell Ledger to exclude sub-accounts in the report.
@findex --monthly @findex --monthly
You can also generate a monthly register (the @command{reg} command) by You can also generate a monthly register (the @command{reg} command) by
executing the following @code{src} block. This presents a summary of executing the following @code{src} block. This presents a summary of
transactions for each monthly period (the @option{--monthly (-M)} transactions for each monthly period (the @option{--monthly (-M)}
argument) with a running total in the final column (which should be 0 at argument) with a running total in the final column (which should be 0 at
the end if all the entries are correct). the end if all the entries are correct).
@ -4994,7 +4994,7 @@ the end if all the entries are correct).
@end smallexample @end smallexample
We could also generate a monthly report on our assets showing how these We could also generate a monthly report on our assets showing how these
are increasing (or decreasing!). In this case, the final column will be are increasing (or decreasing!). In this case, the final column will be
the running total of the assets in our ledger. the running total of the assets in our ledger.
@smallexample @smallexample
@ -5015,7 +5015,7 @@ the running total of the assets in our ledger.
@subsubsection Summary @subsubsection Summary
This short tutorial shows how Ledger entries can be embedded in an org This short tutorial shows how Ledger entries can be embedded in an org
file and manipulated using Babel. However, only simple Ledger features file and manipulated using Babel. However, only simple Ledger features
have been illustrated; please refer to the Ledger documentation for have been illustrated; please refer to the Ledger documentation for
examples of more complex operations on a ledger. examples of more complex operations on a ledger.
@ -5028,7 +5028,7 @@ ledger can generate a graph of the relationship between your various
commodities. The output file is in the ``dot'' format. commodities. The output file is in the ``dot'' format.
This is probably not very interesting, unless you have many different This is probably not very interesting, unless you have many different
commodities valued in terms of each other. For example, multiple commodities valued in terms of each other. For example, multiple
currencies and multiple investments valued in those currencies. currencies and multiple investments valued in those currencies.
@node The @command{xml} command, @command{prices} and @command{pricedb} commands, The @command{pricemap} command, Reports in other Formats @node The @command{xml} command, @command{prices} and @command{pricedb} commands, The @command{pricemap} command, Reports in other Formats
@ -5223,7 +5223,7 @@ pricedb database files.
The @command{accounts} command reports all of the accounts in the The @command{accounts} command reports all of the accounts in the
journal. Following the command with a regular expression will limit the journal. Following the command with a regular expression will limit the
output to accounts matching the regex. The output is sorted by name. output to accounts matching the regex. The output is sorted by name.
Using the @option{--count} option will tell you how many entries use Using the @option{--count} option will tell you how many entries use
each account. each account.
@ -5233,7 +5233,7 @@ each account.
The @command{payees} command reports all of the unique payees in the The @command{payees} command reports all of the unique payees in the
journal. Using the @option{--count} option will tell you how many journal. Using the @option{--count} option will tell you how many
entries use each payee. To filter the payees displayed you must use the entries use each payee. To filter the payees displayed you must use the
prefix @@: prefix @@:
@smallexample @smallexample
@ -5317,7 +5317,7 @@ $ ledger xact 4/9 viva dining "DM 11.50"
@end smallexample @end smallexample
@command{draft} and @command{entry} are both synonyms of @command{draft} and @command{entry} are both synonyms of
@command{xact}. @command{entry} is provided for backwards compatibility @command{xact}. @command{entry} is provided for backwards compatibility
with Ledger 2.X. with Ledger 2.X.
@node @command{stats}, @command{select}, @command{xact}, Reports about your Journals @node @command{stats}, @command{select}, @command{xact}, Reports about your Journals
@ -5346,7 +5346,7 @@ with Ledger 2.X.
@node Basic Usage, Command-Line Quick Reference, Command-Line Syntax, Command-Line Syntax @node Basic Usage, Command-Line Quick Reference, Command-Line Syntax, Command-Line Syntax
@section Basic Usage @section Basic Usage
This chapter describes Ledger's features and options. You may wish to This chapter describes Ledger's features and options. You may wish to
survey this to get an overview before diving into the @ref{Ledger survey this to get an overview before diving into the @ref{Ledger
Tutorial} and more detailed examples that follow. Tutorial} and more detailed examples that follow.
@ -5565,7 +5565,7 @@ Accounts, tags or commodities not previously declared will cause errors.
@item --check-payees @item --check-payees
Enable strict and pedantic checking for payees as well as accounts, Enable strict and pedantic checking for payees as well as accounts,
commodities and tags. This only works in conjunction with commodities and tags. This only works in conjunction with
@option{--strict} or @option{--pedantic}. @option{--strict} or @option{--pedantic}.
@item --immediate @item --immediate
@ -5795,7 +5795,7 @@ database.
Display the man page for ledger. Display the man page for ledger.
@item --init-file @var{FILE} @item --init-file @var{FILE}
Specify the location of the init file. The default is @file{~/.ledgerrc}. Specify the location of the init file. The default is @file{~/.ledgerrc}.
@item --options @item --options
Display the options in effect for this Ledger invocation, along with Display the options in effect for this Ledger invocation, along with
@ -5829,7 +5829,7 @@ $ ledger --options bal --cleared
@noindent @noindent
For the source column, a value starting with a @samp{-} or @samp{--} For the source column, a value starting with a @samp{-} or @samp{--}
indicated the source was a command-line argument. If the entry starts indicated the source was a command-line argument. If the entry starts
with a @samp{$}, the source was an environment variable. If the source with a @samp{$}, the source was an environment variable. If the source
is @code{?normalize} the value was set internally by ledger, in is @code{?normalize} the value was set internally by ledger, in
a function called @code{normalize_options}. a function called @code{normalize_options}.
@ -5837,14 +5837,14 @@ a function called @code{normalize_options}.
Execute a ledger script. Execute a ledger script.
@item --trace @var{INT} @item --trace @var{INT}
Enable tracing. The @var{INT} specifies the level of trace desired. Enable tracing. The @var{INT} specifies the level of trace desired.
@item --verbose @item --verbose
@itemx -v @itemx -v
Print detailed information on the execution of Ledger. Print detailed information on the execution of Ledger.
@item --verify @item --verify
Enable additional assertions during run-time. This causes a significant Enable additional assertions during run-time. This causes a significant
slowdown. When combined with @option{--debug @var{CODE}} ledger will slowdown. When combined with @option{--debug @var{CODE}} ledger will
produce memory trace information. produce memory trace information.
@ -5870,7 +5870,7 @@ sessions with multiple reports per session.
@item --check-payees @item --check-payees
Enable strict and pedantic checking for payees as well as accounts, Enable strict and pedantic checking for payees as well as accounts,
commodities and tags. This only works in conjunction with commodities and tags. This only works in conjunction with
@option{--strict} or @option{--pedantic}. @option{--strict} or @option{--pedantic}.
@item --day-break @item --day-break
@ -5912,7 +5912,7 @@ Specify the input @file{FILE} for this invocation.
@c information. @c information.
@item --input-date-format @var{DATE_FORMAT} @item --input-date-format @var{DATE_FORMAT}
Specify the input date format for journal entries. For example, Specify the input date format for journal entries. For example,
@smallexample @smallexample
$ ledger convert Export.csv --input-date-format "%m/%d/%Y" $ ledger convert Export.csv --input-date-format "%m/%d/%Y"
@ -5965,10 +5965,10 @@ Specify the location of the price entry data file.
@item --price-exp @var{INT} @item --price-exp @var{INT}
@itemx -Z @var{INT} @itemx -Z @var{INT}
@itemx --leeway @var{INT} @itemx --leeway @var{INT}
Set the expected freshness of price quotes, in @var{INT} minutes. That Set the expected freshness of price quotes, in @var{INT} minutes. That
is, if the last known quote for any commodity is older than this value, is, if the last known quote for any commodity is older than this value,
and if @option{--download} is being used, then the Internet will be and if @option{--download} is being used, then the Internet will be
consulted again for a newer price. Otherwise, the old price is still consulted again for a newer price. Otherwise, the old price is still
considered to be fresh enough. considered to be fresh enough.
@item --strict @item --strict
@ -5981,7 +5981,7 @@ a misspelled commodity or account) it will issue a warning giving you
the file and line number of the problem. the file and line number of the problem.
@item --recursive-aliases @item --recursive-aliases
Normally, ledger only expands aliases once. With this option, ledger Normally, ledger only expands aliases once. With this option, ledger
tries to expand the result of alias expansion recursively, until no more tries to expand the result of alias expansion recursively, until no more
expansions apply. expansions apply.
@ -6012,14 +6012,14 @@ sessions with multiple reports per session.
@item --abbrev-len @var{INT} @item --abbrev-len @var{INT}
Set the minimum length an account can be abbreviated to if it doesn't Set the minimum length an account can be abbreviated to if it doesn't
fit inside the @code{account-width}. If @var{INT} is zero, then the fit inside the @code{account-width}. If @var{INT} is zero, then the
account name will be truncated on the right. If @var{INT} is greater account name will be truncated on the right. If @var{INT} is greater
than @code{account-width} then the account will be truncated on the than @code{account-width} then the account will be truncated on the
left, with no shortening of the account names in order to fit into the left, with no shortening of the account names in order to fit into the
desired width. desired width.
@item --account @var{STR} @item --account @var{STR}
Prepend @var{STR} to all accounts reported. That is, the option Prepend @var{STR} to all accounts reported. That is, the option
@samp{--account Personal} would tack @samp{Personal:} to the beginning @samp{--account Personal} would tack @samp{Personal:} to the beginning
of every account reported in a balance report or register report. of every account reported in a balance report or register report.
@ -6038,7 +6038,7 @@ Show only unbudgeted postings.
@item --amount @var{EXPR} @item --amount @var{EXPR}
@itemx -t @var{EXPR} @itemx -t @var{EXPR}
Apply the given value expression to the posting amount (@pxref{Value Apply the given value expression to the posting amount (@pxref{Value
Expressions}). Using @option{--amount @var{EXPR}} you can apply an Expressions}). Using @option{--amount @var{EXPR}} you can apply an
arbitrary transformation to the postings. arbitrary transformation to the postings.
@item --amount-data @item --amount-data
@ -6068,7 +6068,7 @@ running totals.
@item --balance-format @var{FORMAT_STRING} @item --balance-format @var{FORMAT_STRING}
Specify the format to use for the @command{balance} report (@pxref{Format Specify the format to use for the @command{balance} report (@pxref{Format
Strings}). The default is: Strings}). The default is:
@smallexample @smallexample
"%(justify(scrub(display_total), 20, -1, true, color))" "%(justify(scrub(display_total), 20, -1, true, color))"
@ -6080,7 +6080,7 @@ Strings}). The default is:
@item --base @item --base
Reduce convertible commodities down the bottom of the conversion, e.g. Reduce convertible commodities down the bottom of the conversion, e.g.
display time in seconds. This also applies to custom commodity conversions. display time in seconds. This also applies to custom commodity conversions.
@item --basis @item --basis
@itemx -B @itemx -B
@ -6088,7 +6088,7 @@ display time in seconds. This also applies to custom commodity conversions.
Report the cost basis on all posting. Report the cost basis on all posting.
@item --begin @var{DATE} @item --begin @var{DATE}
Specify the start @var{DATE} of all calculations. Transactions before Specify the start @var{DATE} of all calculations. Transactions before
that date will be ignored. that date will be ignored.
@item --bold-if @var{VEXPR} @item --bold-if @var{VEXPR}
@ -6104,7 +6104,7 @@ list all transactions since the beginning of December and print in
bold any posting greater than $100. bold any posting greater than $100.
@item --budget @item --budget
Only display budgeted items. In a register report this Only display budgeted items. In a register report this
displays transactions in the budget, in a balance report this displays displays transactions in the budget, in a balance report this displays
accounts in the budget (@pxref{Budgeting and Forecasting}). accounts in the budget (@pxref{Budgeting and Forecasting}).
@ -6132,7 +6132,7 @@ calculation.
@item --cleared-format @var{FORMAT_STRING} @item --cleared-format @var{FORMAT_STRING}
@c FIXME thdox: to keep? @c FIXME thdox: to keep?
Specify the format to use for the @command{cleared} report (@pxref{Format Specify the format to use for the @command{cleared} report (@pxref{Format
Strings}). The default is: Strings}). The default is:
@smallexample @smallexample
"%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, " "%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, "
@ -6148,7 +6148,7 @@ Strings}). The default is:
@item --collapse @item --collapse
@itemx -n @itemx -n
By default ledger prints all accounts in an account tree. With By default ledger prints all accounts in an account tree. With
@option{--collapse} it prints only the top level account specified. @option{--collapse} it prints only the top level account specified.
@item --collapse-if-zero @item --collapse-if-zero
@ -6265,11 +6265,11 @@ And with @option{--dc} it becomes this:
Limit the depth of the account tree. In a balance report, for example, Limit the depth of the account tree. In a balance report, for example,
a @samp{--depth 2} statement will print balances only for accounts with a @samp{--depth 2} statement will print balances only for accounts with
two levels, i.e. @samp{Expenses:Entertainment} but not two levels, i.e. @samp{Expenses:Entertainment} but not
@samp{Expenses:Entertainment:Dining}. This is a display predicate, which @samp{Expenses:Entertainment:Dining}. This is a display predicate, which
means it only affects display, not the total calculations. means it only affects display, not the total calculations.
@item --deviation @item --deviation
Report each postings deviation from the average. It is only meaningful Report each postings deviation from the average. It is only meaningful
in the register and prices reports. in the register and prices reports.
@item --display @var{EXPR} @item --display @var{EXPR}
@ -6300,7 +6300,7 @@ Include empty accounts in the report and in average calculations.
@item --end @var{DATE} @item --end @var{DATE}
Specify the end @var{DATE} for a transaction to be considered in the Specify the end @var{DATE} for a transaction to be considered in the
report. All transactions on or after this date are ignored. report. All transactions on or after this date are ignored.
@item --equity @item --equity
Related to the @command{equity} command (@pxref{The @command{equity} Related to the @command{equity} command (@pxref{The @command{equity}
@ -6313,7 +6313,7 @@ posting occurring in that period.
@item --exchange @var{COMMODITY} @item --exchange @var{COMMODITY}
@itemx -X @var{COMMODITY} @itemx -X @var{COMMODITY}
Display values in terms of the given @var{COMMODITY}. The latest Display values in terms of the given @var{COMMODITY}. The latest
available price is used. The syntax available price is used. The syntax
@option{-X @var{COMMODITY1}:@var{COMMODITY2}} displays values in @var{COMMODITY1} @option{-X @var{COMMODITY1}:@var{COMMODITY2}} displays values in @var{COMMODITY1}
in terms of @var{COMMODITY2} using the latest available price, but in terms of @var{COMMODITY2} using the latest available price, but
@ -6326,11 +6326,11 @@ available for reporting in terms of @var{COMMODITY2}, but only a few
should be displayed that way. should be displayed that way.
@item --flat @item --flat
Force the full names of accounts to be used in the balance report. The Force the full names of accounts to be used in the balance report. The
balance report will not use an indented tree. balance report will not use an indented tree.
@item --force-color @item --force-color
Output TTY color codes even if the TTY doesn't support them. Useful Output TTY color codes even if the TTY doesn't support them. Useful
for TTYs that don't advertise their capabilities correctly. for TTYs that don't advertise their capabilities correctly.
@item --force-pager @item --force-pager
@ -6360,7 +6360,7 @@ them.
@item --group-by @var{EXPR} @item --group-by @var{EXPR}
Group transactions together in the @command{register} report. Group transactions together in the @command{register} report.
@var{EXPR} can be anything, although most common would be @code{payee} @var{EXPR} can be anything, although most common would be @code{payee}
or @code{commodity}. The @code{tags()} function is also useful here. or @code{commodity}. The @code{tags()} function is also useful here.
@item --group-title-format @var{FORMAT_STRING} @item --group-title-format @var{FORMAT_STRING}
Set the format for the headers that separates the report sections of Set the format for the headers that separates the report sections of
@ -6376,13 +6376,13 @@ $ ledger reg Expenses --group-by "payee" --group-title-format "-----------------
2011/06/02 AAA Dues Expenses:Auto:Misc $ 215.00 $ 215.00 2011/06/02 AAA Dues Expenses:Auto:Misc $ 215.00 $ 215.00
------------------------ ABC Towing and Wrecking --------------------- ------------------------ ABC Towing and Wrecking ---------------------
2011/03/17 ABC Towing and Wrec.. Expenses:Auto:Hobbies $ 48.20 $ 48.20 2011/03/17 ABC Towing and Wrec.. Expenses:Auto:Hobbies $ 48.20 $ 48.20
... ...
@end smallexample @end smallexample
@item --head @var{INT} @item --head @var{INT}
@itemx --first @var{INT} @itemx --first @var{INT}
Print the first @var{INT} entries. Opposite of @option{--tail Print the first @var{INT} entries. Opposite of @option{--tail
@var{INT}}. @var{INT}}.
@item --historical @item --historical
@ -6485,7 +6485,7 @@ Redirect the output of ledger to the file defined in @file{FILE}.
Direct output to @var{FILE} pager program. Direct output to @var{FILE} pager program.
@item --payee @var{VEXPR} @item --payee @var{VEXPR}
Sets a value expression for formatting the payee. In the Sets a value expression for formatting the payee. In the
@command{register} report this prevents the second entry from having @command{register} report this prevents the second entry from having
a date and payee for each transaction. a date and payee for each transaction.
@ -6503,13 +6503,13 @@ Only works for accounts that have a single commodity.
@item --period @var{PERIOD_EXPRESSION} @item --period @var{PERIOD_EXPRESSION}
Define a period expression that sets the time period during which Define a period expression that sets the time period during which
transactions are to be accounted. For a @command{register} report only transactions are to be accounted. For a @command{register} report only
the transactions that satisfy the period expression with be displayed. the transactions that satisfy the period expression with be displayed.
For a @command{balance} report only those transactions will be accounted For a @command{balance} report only those transactions will be accounted
in the final balances. in the final balances.
@item --pivot @var{TAG} @item --pivot @var{TAG}
Produce a balance pivot report @emph{around} the given @var{TAG}. For Produce a balance pivot report @emph{around} the given @var{TAG}. For
example, if you have multiple cars and track each fuel purchase in example, if you have multiple cars and track each fuel purchase in
@samp{Expenses:Auto:Fuel} and tag each fuel purchase with a tag @samp{Expenses:Auto:Fuel} and tag each fuel purchase with a tag
identifying which car the purchase was for @samp{; Car: Prius}, then the identifying which car the purchase was for @samp{; Car: Prius}, then the
@ -6530,11 +6530,11 @@ $ ledger bal Fuel --pivot "Car" --period "this year"
@xref{Metadata values}. @xref{Metadata values}.
@item --plot-amount-format @var{FORMAT_STRING} @item --plot-amount-format @var{FORMAT_STRING}
Define the output format for an amount data plot. @xref{Visualizing Define the output format for an amount data plot. @xref{Visualizing
with Gnuplot}. with Gnuplot}.
@item --plot-total-format @var{FORMAT_STRING} @item --plot-total-format @var{FORMAT_STRING}
Define the output format for a total data plot. @xref{Visualizing with Define the output format for a total data plot. @xref{Visualizing with
Gnuplot}. Gnuplot}.
@item --prepend-format @var{FORMAT_STRING} @item --prepend-format @var{FORMAT_STRING}
@ -6623,7 +6623,7 @@ Sort the postings within transactions using the given value expression.
@item --start-of-week @var{INT} @item --start-of-week @var{INT}
Tell ledger to use a particular day of the week to start its ``weekly'' Tell ledger to use a particular day of the week to start its ``weekly''
summary. @samp{--start-of-week=1} specifies Monday as the start of the summary. @samp{--start-of-week=1} specifies Monday as the start of the
week. week.
@item --subtotal @item --subtotal
@ -6632,7 +6632,7 @@ week.
@item --tail @var{INT} @item --tail @var{INT}
@itemx --last @var{INT} @itemx --last @var{INT}
Report only the last @var{INT} entries. Only useful in Report only the last @var{INT} entries. Only useful in
a @command{register} report. a @command{register} report.
@item --time-report @item --time-report
@ -6652,8 +6652,8 @@ Set the width of the total field in the register report.
@item --truncate @var{CODE} @item --truncate @var{CODE}
Indicates how truncation should happen when the contents of columns Indicates how truncation should happen when the contents of columns
exceed their width. Valid arguments are @samp{leading}, @samp{middle}, exceed their width. Valid arguments are @samp{leading}, @samp{middle},
and @samp{trailing}. The default is smarter than any of these three, and @samp{trailing}. The default is smarter than any of these three,
as it considers sub-names within the account name (that style is as it considers sub-names within the account name (that style is
called ``abbreviate''). called ``abbreviate'').
@ -6670,12 +6670,12 @@ report.
@item --unrealized-gains @var{STR} @item --unrealized-gains @var{STR}
Allow the user to specify what account name should be used for Allow the user to specify what account name should be used for
unrealized gains. Defaults to @samp{"Equity:Unrealized Gains"}. unrealized gains. Defaults to @samp{"Equity:Unrealized Gains"}.
Often set in one's @file{~/.ledgerrc} file to change the default. Often set in one's @file{~/.ledgerrc} file to change the default.
@item --unrealized-losses @var{STR} @item --unrealized-losses @var{STR}
Allow the user to specify what account name should be used for Allow the user to specify what account name should be used for
unrealized gains. Defaults to @samp{"Equity:Unrealized Losses"}. unrealized gains. Defaults to @samp{"Equity:Unrealized Losses"}.
Often set in one's @file{~/.ledgerrc} file to change the default. Often set in one's @file{~/.ledgerrc} file to change the default.
@item --unround @item --unround
@ -6721,9 +6721,9 @@ are using.
@item --file @var{FILE} @item --file @var{FILE}
@itemx -f @var{FILE} @itemx -f @var{FILE}
Read @file{FILE} as a ledger file. @var{FILE} can be @samp{-} which is Read @file{FILE} as a ledger file. @var{FILE} can be @samp{-} which is
a synonym for @samp{/dev/stdin}. This command may be used multiple a synonym for @samp{/dev/stdin}. This command may be used multiple
times. Typically, the environment variable @env{LEDGER_FILE} is set, times. Typically, the environment variable @env{LEDGER_FILE} is set,
rather than using this command-line option. rather than using this command-line option.
@item --output @var{FILE} @item --output @var{FILE}
@ -6978,7 +6978,7 @@ least, using the absolute value of the total. For more on how to use
value expressions, see @ref{Value Expressions}. value expressions, see @ref{Value Expressions}.
@item --pivot @var{TAG} @item --pivot @var{TAG}
Produce a pivot table around the @var{TAG} provided. This requires Produce a pivot table around the @var{TAG} provided. This requires
meta data using valued tags. meta data using valued tags.
@item --wide @item --wide
@ -6987,11 +6987,11 @@ Cause the default @command{register} report to assume 132 columns
instead of 80. instead of 80.
@item --head @var{INT} @item --head @var{INT}
Cause only the first @var{INT} transactions to be printed. This is Cause only the first @var{INT} transactions to be printed. This is
different from using the command-line utility @file{head}, which would different from using the command-line utility @file{head}, which would
limit to the first @var{INT} postings. @option{--tail @var{INT}} outputs limit to the first @var{INT} postings. @option{--tail @var{INT}} outputs
only the last @var{INT} transactions. Both options may be used only the last @var{INT} transactions. Both options may be used
simultaneously. If a negative amount is given, it will invert the simultaneously. If a negative amount is given, it will invert the
meaning of the flag (instead of the first five transactions being meaning of the flag (instead of the first five transactions being
printed, for example, it would print all but the first five). printed, for example, it would print all but the first five).
@ -7095,7 +7095,7 @@ Define the output format for the @command{balance} report. The default
@end smallexample @end smallexample
@item --cleared-format @var{FORMAT_STRING} @item --cleared-format @var{FORMAT_STRING}
Define the format for the cleared report. The default is: Define the format for the cleared report. The default is:
@smallexample @smallexample
"%(justify(scrub(get_at(display_total, 0)), 16, 16 + int(prepend_width), "%(justify(scrub(get_at(display_total, 0)), 16, 16 + int(prepend_width),
@ -7163,7 +7163,7 @@ Set the format for @command{csv} reports. The default is:
@item --plot-amount-format @var{FORMAT_STRING} @item --plot-amount-format @var{FORMAT_STRING}
Set the format for amount plots, using the @option{--amount-data (-j)} Set the format for amount plots, using the @option{--amount-data (-j)}
option. The default is: option. The default is:
@smallexample @smallexample
"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n" "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n"
@ -7178,14 +7178,14 @@ option. The default is:
@end smallexample @end smallexample
@item --pricedb-format @var{FORMAT_STRING} @item --pricedb-format @var{FORMAT_STRING}
Set the format expected for the historical price file. The default is: Set the format expected for the historical price file. The default is:
@smallexample @smallexample
"P %(datetime) %(display_account) %(scrub(display_amount))\n" "P %(datetime) %(display_account) %(scrub(display_amount))\n"
@end smallexample @end smallexample
@item --prices-format @var{FORMAT_STRING} @item --prices-format @var{FORMAT_STRING}
Set the format for the @command{prices} report. The default is: Set the format for the @command{prices} report. The default is:
@smallexample @smallexample
"%(date) %-8(display_account) %(justify(scrub(display_amount), 12, "%(date) %-8(display_account) %(justify(scrub(display_amount), 12,
@ -7224,10 +7224,10 @@ The format of the file can be changed by telling ledger to use the
@item --price-exp @var{INT} @item --price-exp @var{INT}
@itemx -Z @var{INT} @itemx -Z @var{INT}
Set the expected freshness of price quotes, in @var{INT} minutes. That Set the expected freshness of price quotes, in @var{INT} minutes. That
is, if the last known quote for any commodity is older than this value, is, if the last known quote for any commodity is older than this value,
and if @option{--download} is being used, then the Internet will be and if @option{--download} is being used, then the Internet will be
consulted again for a newer price. Otherwise, the old price is still consulted again for a newer price. Otherwise, the old price is still
considered to be fresh enough. considered to be fresh enough.
@item --download @item --download
@ -7285,7 +7285,7 @@ etc.
When you specify @option{--market (-V)}, or @option{--exchange When you specify @option{--market (-V)}, or @option{--exchange
@var{COMMODITY} (-X)}, you are requesting that some or all of the @var{COMMODITY} (-X)}, you are requesting that some or all of the
commodities be valuated as of today (or whatever @option{--now commodities be valuated as of today (or whatever @option{--now
@var{DATE}} is set to). But what does such a valuation mean? This @var{DATE}} is set to). But what does such a valuation mean? This
meaning is governed by the presence of a @var{VALUE} meta-data property, meaning is governed by the presence of a @var{VALUE} meta-data property,
whose content is an expression used to compute that value. whose content is an expression used to compute that value.
@ -7325,7 +7325,7 @@ they cannot have a different future value:
@end smallexample @end smallexample
This says the future valuation is the same as the valuation at the time This says the future valuation is the same as the valuation at the time
of posting. post.date equals the posting's date, while just 'date' is of posting. @code{post.date} equals the posting's date, while just 'date' is
the value of @option{--now @var{DATE}} (defaults to today). the value of @option{--now @var{DATE}} (defaults to today).
Or how about valuating miles based on a reimbursement rate during a Or how about valuating miles based on a reimbursement rate during a
@ -7928,7 +7928,7 @@ Useful for specifying a date in plain terms. For example, you could say
@item expr comment =~ /REGEX/ @item expr comment =~ /REGEX/
A regular expression that matches against a posting's comment A regular expression that matches against a posting's comment
field. This searches only a posting's field, not the transaction's note field. This searches only a posting's field, not the transaction's note
or comment field. For example, @code{ledger reg "expr" "comment =~ or comment field. For example, @code{ledger reg "expr" "comment =~
/landline/"} will match: /landline/"} will match:
@ -7953,7 +7953,7 @@ instead.
@item expr note =~ /REGEX/ @item expr note =~ /REGEX/
A regular expression that matches against a transaction's note field. A regular expression that matches against a transaction's note field.
This searches all comments in the transaction, including comments on This searches all comments in the transaction, including comments on
individual postings. Thus, @samp{ledger reg "expr" "note =~ /landline/"} individual postings. Thus, @samp{ledger reg "expr" "note =~ /landline/"}
will match both all the three examples below: will match both all the three examples below:
@smallexample @smallexample
@ -8030,7 +8030,7 @@ Assets:Cash ¤ 123,45
@defun ansify_if value color bool @defun ansify_if value color bool
Render the given @var{expression} as a string, applying the proper ANSI escape Render the given @var{expression} as a string, applying the proper ANSI escape
codes to display it in the given @var{color} if @var{bool} is true. It codes to display it in the given @var{color} if @var{bool} is true. It
typically checks the value of the option @option{--color}. Since ANSI escape typically checks the value of the option @option{--color}. Since ANSI escape
codes include non-printable character sequences, such as escape @kbd{^[} codes include non-printable character sequences, such as escape @kbd{^[}
the following example may not appear as the final result on the commandline. the following example may not appear as the final result on the commandline.
@smallexample @c command:4D836EE,with_input:3406FC1 @smallexample @c command:4D836EE,with_input:3406FC1
@ -8111,13 +8111,13 @@ Expenses:Office Supplies ¤ 123,00
@end defun @end defun
@defun format_date date format @defun format_date date format
Return the @var{date} as a string using @var{format}. See strftime (3) Return the @var{date} as a string using @var{format}. See strftime (3)
for format string details. for format string details.
@smallexample @c command:9605B13,with_input:3406FC1 @smallexample @c command:9605B13,with_input:3406FC1
$ ledger -f expr.dat --format "%(format_date(date, '%A, %B %d. %Y'))\n" reg assets $ ledger -f expr.dat --format "%(format_date(date, '%A, %B %d. %Y'))\n" reg assets
@end smallexample @end smallexample
@smallexample @c output:9605B13 @smallexample @c output:9605B13
Friday, January 16. 2015 Friday, January 16. 2015
@end smallexample @end smallexample
@end defun @end defun
@ -8143,7 +8143,7 @@ of the field in the first line is given by @var{first_width}. For
subsequent lines the width is given by @var{latter_width}. If subsequent lines the width is given by @var{latter_width}. If
@var{latter_width=-1}, then @var{first_width} is use for all lines. @var{latter_width=-1}, then @var{first_width} is use for all lines.
If @var{right_justify=true} then the field is right justify within If @var{right_justify=true} then the field is right justify within
the width of the field. If it is @var{false}, then the field is left the width of the field. If it is @var{false}, then the field is left
justified and padded to the full width of the field. If justified and padded to the full width of the field. If
@var{colorize} is true, then ledger will honor color settings. @var{colorize} is true, then ledger will honor color settings.
@smallexample @c command:082FB27,with_input:3406FC1 @smallexample @c command:082FB27,with_input:3406FC1
@ -8360,12 +8360,12 @@ $ ledger -f expr.dat --format "»%(trim(' Trimmed '))«\n" reg assets
Format strings may be used to change the output format of reports. They Format strings may be used to change the output format of reports. They
are specified by passing a formatting string to the @option{--format are specified by passing a formatting string to the @option{--format
@var{FORMAT_STRING} (-F)} option. Within that string, constructs are @var{FORMAT_STRING} (-F)} option. Within that string, constructs are
allowed which make it possible to display the various parts of an allowed which make it possible to display the various parts of an
account or posting in custom ways. account or posting in custom ways.
There are several additional flags that allow you to define formats There are several additional flags that allow you to define formats
for specific reports. These are useful to define in your configuration for specific reports. These are useful to define in your configuration
file and will allow you to run ledger reports from the command-line file and will allow you to run ledger reports from the command-line
without having to enter a new format for each command. without having to enter a new format for each command.
@ -8703,7 +8703,7 @@ Return the current date and time. If the @option{--now @var{DATE}}
option is defined it will return that value. option is defined it will return that value.
@item today @item today
Return the current date. If the @option{--now @var{DATE}} option is Return the current date. If the @option{--now @var{DATE}} option is
defined it will return that value. defined it will return that value.
@item to_datetime @item to_datetime
@ -8884,7 +8884,7 @@ of the field in the first line is given by @code{first_width}. For
subsequent lines the width is given by @code{latter_width}. If subsequent lines the width is given by @code{latter_width}. If
@code{latter_width=-1}, then @code{first_width} is use for all lines. @code{latter_width=-1}, then @code{first_width} is use for all lines.
If @code{right_justify=true} then the field is right justify within If @code{right_justify=true} then the field is right justify within
the width of the field. If it is @code{false}, then the field is left the width of the field. If it is @code{false}, then the field is left
justified and padded to the full width of the field. If justified and padded to the full width of the field. If
@code{colorize} is true, then ledger will honor color settings. @code{colorize} is true, then ledger will honor color settings.
@ -9646,7 +9646,7 @@ Ignore init files and environment variables for the ledger run.
@item --debug @var{CODE} @item --debug @var{CODE}
If Ledger has been built with debug options this will provide extra If Ledger has been built with debug options this will provide extra
data during the run. The following are the available @var{CODES} to data during the run. The following are the available @var{CODES} to
debug: debug:
@multitable @columnfractions .32 .43 .27 @multitable @columnfractions .32 .43 .27
@ -9679,7 +9679,7 @@ debug:
@ @
@item --trace @var{INT} @item --trace @var{INT}
Enable tracing. The @var{INT} specifies the level of trace desired: Enable tracing. The @var{INT} specifies the level of trace desired:
@multitable @columnfractions .3 .7 @multitable @columnfractions .3 .7
@item @code{LOG_OFF} @tab 0 @item @code{LOG_OFF} @tab 0
@ -9701,7 +9701,7 @@ Enable tracing. The @var{INT} specifies the level of trace desired:
Print detailed information on the execution of Ledger. Print detailed information on the execution of Ledger.
@item --verify @item --verify
Enable additional assertions during run-time. This causes a significant Enable additional assertions during run-time. This causes a significant
slowdown. When combined with @option{--debug @var{CODE}} ledger will slowdown. When combined with @option{--debug @var{CODE}} ledger will
produce memory trace information. produce memory trace information.
@ -9719,7 +9719,7 @@ Print version information and exit.
@cindex pre-commands @cindex pre-commands
Pre-commands are useful when you aren't sure how a command or option Pre-commands are useful when you aren't sure how a command or option
will work. The difference between a pre-command and a regular command will work. The difference between a pre-command and a regular command
is that pre-commands ignore the journal data file completely, nor is is that pre-commands ignore the journal data file completely, nor is
the user's init file read. the user's init file read.
@ -9964,10 +9964,10 @@ GnuCash file import.
The option @option{--performance (-g)}. The option @option{--performance (-g)}.
@item @item
The balance report now defaults to showing all relevant accounts. This The balance report now defaults to showing all relevant accounts. This
is the opposite of 2.x. That is, @command{bal} in 3.0 does what @samp{-s is the opposite of 2.x. That is, @command{bal} in 3.0 does what @samp{-s
bal} did in 2.x. To see 2.6 behavior, use @option{--collapse (-n)} bal} did in 2.x. To see 2.6 behavior, use @option{--collapse (-n)}
option in 3.0, like @samp{bal -n}. The @option{--subtotal (-s)} option option in 3.0, like @samp{bal -n}. The @option{--subtotal (-s)} option
no longer has any effect on balance reports. no longer has any effect on balance reports.
@end itemize @end itemize