summaryrefslogtreecommitdiff
path: root/doc/ledger3.texi
diff options
context:
space:
mode:
authorCraig Earls <enderw88@gmail.com>2015-01-21 22:03:11 -0700
committerCraig Earls <enderw88@gmail.com>2015-01-21 22:03:11 -0700
commit28b0d6756785b5d36ae73c4614a9295d9697041a (patch)
tree20257fd9d99acc7a9d55a655e078a95a12f6e577 /doc/ledger3.texi
parenta65033b66cc084ca0c40538a9aa0e243cc32ab8c (diff)
parentbec52e3221d74ce3bf1383b245beae5a6214e387 (diff)
downloadfork-ledger-28b0d6756785b5d36ae73c4614a9295d9697041a.tar.gz
fork-ledger-28b0d6756785b5d36ae73c4614a9295d9697041a.tar.bz2
fork-ledger-28b0d6756785b5d36ae73c4614a9295d9697041a.zip
Merge commit 'bec52e3221d74ce3bf1383b245beae5a6214e387' into next
Conflicts: lisp/ledger-reconcile.el
Diffstat (limited to 'doc/ledger3.texi')
-rw-r--r--doc/ledger3.texi761
1 files changed, 376 insertions, 385 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index 81d1849f..9597083c 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -1,6 +1,7 @@
\input texinfo @c -*-texinfo-*-
@setfilename ledger3.info
+@include version.texi
@settitle Ledger: Command-Line Accounting
@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with
@@ -146,7 +147,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@titlepage
@title Ledger: Command-Line Accounting
-@subtitle For Version 3.1 of Ledger
+@subtitle For Version @value{VERSION} of Ledger
@author John Wiegley
@page
@vskip 0pt plus 1filll
@@ -160,7 +161,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@node Top, Introduction to Ledger, (dir), (dir)
@top Overview
-Ledger is a command line accounting tool that provides double-entry
+Ledger is a command-line accounting tool that provides double-entry
accounting based on a text journal. It provides no bells or whistles,
and returns the user to the days before user interfaces were even a
twinkling in their father's CRT.
@@ -175,7 +176,7 @@ twinkling in their father's CRT.
* Transactions::
* Building Reports::
* Reporting Commands::
-* Command-line Syntax::
+* Command-Line Syntax::
* Budgeting and Forecasting::
* Time Keeping::
* Value Expressions::
@@ -366,24 +367,30 @@ data, not for altering it.
@node Building the program, Getting help, Fat-free Accounting, Introduction to Ledger
@section Building the program
-Ledger is written in ANSI C++, and should compile on any platform. It
-depends on the GNU multiple precision arithmetic library (libgmp), and
-the Perl regular expression library (libpcre). It was developed using
-GNU make and gcc 3.3, on a PowerBook running OS/X.
-
-To build and install once you have these libraries on your system,
-enter these commands:
+Ledger is written in ANSI C++, and should compile on any unix platform.
+The easiest way to build and install ledger is to use the prepared
+acprep script, that does a lot of the footwork:
@smallexample
-$ ./configure && make install
+ # to install missing dependencies
+ ./acprep dependencies
+ # building ledger
+ ./acprep update
+ # to run the actual installation
+ make install
@end smallexample
+See the `help` subcommand to `acprep`, which explains some of its many
+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.md` in the source directory for more up do date build instructions.
+
@node Getting help, , Building the program, Introduction to Ledger
@section Getting help
@findex help
Ledger has a complete online help system based on GNU Info. This
-manual can be searched directly from the command line using the
+manual can be searched directly from the command-line using the
following options: @code{ledger --help} brings up this entire manual in
your TTY.
@@ -423,17 +430,17 @@ If you would rather start with your own journal right away please
* Balance Report::
* Register Report::
* Cleared Report::
-* Using the Windows Command Line::
+* Using the Windows Command-Line::
@end menu
-Please note that as a command line program, Ledger is controlled from
+Please note that as a command-line program, Ledger is controlled from
your shell. There are several different command shells that all
behave slightly differently with respect to some special characters.
In particular, the ``bash'' shell will interpret @samp{$} signs
differently than ledger and they must be escaped to reach the actual
program. Another example is ``zsh'', which will interpret @samp{^}
differently than ledger expects. In all cases that follow you should
-take that into account when entering the command line arguments as given.
+take that into account when entering the command-line arguments as given.
There are too many variations between shells to give concrete examples
for each.
@@ -595,7 +602,7 @@ $ ledger -f drewr3.dat register payee "Organic"
Assets:Checking $ -225.00 0
@end smallexample
-@node Cleared Report, Using the Windows Command Line, Register Report, Run a Few Reports
+@node Cleared Report, Using the Windows Command-Line, Register Report, Run a Few Reports
@subsection Cleared Report
@cindex cleared report
@findex cleared
@@ -638,8 +645,8 @@ $ ledger -f drewr3.dat cleared
The first column shows the outstanding balance, the second column
shows the ``cleared'' balance.
-@node Using the Windows Command Line, , Cleared Report, Run a Few Reports
-@subsection Using the Windows Command Line
+@node Using the Windows Command-Line, , Cleared Report, Run a Few Reports
+@subsection Using the Windows Command-Line
@cindex windows cmd.exe
@cindex currency symbol display on windows
@@ -1075,10 +1082,10 @@ the left value's commodity. The result of this command might be:
@menu
* Commodity price histories::
-* Commodity equivalencies::
+* Commodity equivalences::
@end menu
-@node Commodity price histories, Commodity equivalencies, Commodities and Currencies, Commodities and Currencies
+@node Commodity price histories, Commodity equivalences, Commodities and Currencies, Commodities and Currencies
@subsection Commodity price histories
Whenever a commodity is purchased using a different commodity (such as
@@ -1100,13 +1107,13 @@ its various reports. It will always report balances in terms of the
commodity total, rather than the current value of those commodities.
To enable pricing reports, use one of the commodity reporting options.
-@node Commodity equivalencies, , Commodity price histories, Commodities and Currencies
-@subsection Commodity equivalencies
+@node Commodity equivalences, , Commodity price histories, Commodities and Currencies
+@subsection Commodity equivalences
Sometimes a commodity has several forms which are all equivalent. An
example of this is time. Whether tracked in terms of minutes, hours
or days, it should be possible to convert between the various forms.
-Doing this requires the use of commodity equivalencies.
+Doing this requires the use of commodity equivalences.
For example, you might have the following two postings, one which
transfers an hour of time into a @samp{Billable} account, and another
@@ -1136,8 +1143,8 @@ $ ledger --no-total balance Billable Project
This example works because ledger already knows how to handle seconds,
minutes and hours, as part of its time tracking support. Defining
-other equivalencies is simple. The following is an example that
-creates data equivalencies, helpful for tracking bytes, kilobytes,
+other equivalences is simple. The following is an example that
+creates data equivalences, helpful for tracking bytes, kilobytes,
megabytes, and more:
@smallexample @c input:validate
@@ -1152,7 +1159,7 @@ and a default precision, with a certain quantity of another commodity.
In the above example, kilobytes are reported with two decimal places
of precision and each kilobyte is equal to 1024 bytes.
-Equivalency chains can be as long as desired. Whenever a commodity
+Equivalence chains can be as long as desired. Whenever a commodity
would report as a decimal amount (less than @samp{1.00}), the next
smallest commodity is used. If a commodity could be reported in terms
of a higher commodity without resulting to a partial fraction, then
@@ -2081,6 +2088,7 @@ the syntax @code{[ACTUAL_DATE]} or @code{[=EFFECTIVE_DATE]} or
@item P
@findex --download
+@findex P
Specifies a historical price for a commodity. These are usually found
in a pricing history file (see the @option{--download (-Q)} option).
The syntax is:
@@ -2205,7 +2213,7 @@ until an @samp{end apply account} directive was found.
Define an alias for an account name. If you have a deeply nested tree
of accounts, it may be convenient to define an alias, for example:
-@smallexample @c input:validate
+@smallexample @c input:94A99E8
alias Dining=Expenses:Entertainment:Dining
alias Checking=Assets:Credit Union:Joint Checking Account
@@ -2218,11 +2226,11 @@ The aliases are only in effect for transactions read in after the alias
is defined and are affected by @code{account} directives that precede
them.
-@smallexample @c command:validate
+@smallexample @c command:94A99E8
$ ledger bal --no-total ^Exp
@end smallexample
-@smallexample
+@smallexample @c output:94A99E8
$10.00 Expenses:Entertainment:Dining
@end smallexample
@@ -2230,7 +2238,7 @@ With the option @option{--recursive-aliases}, aliases can refer to other
aliases, the following example produces exactly the same transactions
and account names as the preceding one:
-@smallexample @c input:validate
+@smallexample @c input:83E1FB3
alias Entertainment=Expenses:Entertainment
alias Dining=Entertainment:Dining
alias Checking=Assets:Credit Union:Joint Checking Account
@@ -2240,11 +2248,11 @@ alias Checking=Assets:Credit Union:Joint Checking Account
Checking
@end smallexample
-@smallexample @c command:validate
+@smallexample @c command:83E1FB3
$ ledger balance --no-total --recursive-aliases ^Exp
@end smallexample
-@smallexample
+@smallexample @c output:83E1FB3
$10.00 Expenses:Entertainment:Dining
@end smallexample
@@ -2261,6 +2269,7 @@ assert <VALUE EXPRESSION BOOLEAN RESULT>
@end smallexample
@item bucket
+@anchor{bucket}
@c instance_t::default_account_directive
Defines the default account to use for balancing transactions.
Normally, each transaction has at least two postings, which must
@@ -2539,6 +2548,7 @@ This is a synonym for @code{comment} and must be closed by an
@code{end} tag.
@item year
+@anchor{year}
@c instance_t::year_directive in textual.cc
Denotes the year used for all subsequent transactions that give a date
without a year. The year should appear immediately after the
@@ -2554,12 +2564,15 @@ alone, for backwards compatibility with older Ledger versions.
@table @code
@item A
-See @code{bucket}.
+@findex A
+@xref{bucket}.
@item Y
-See @code{year}.
+@findex Y
+@xref{year}.
@item N SYMBOL
+@findex N
Indicates that pricing information is to be ignored for a given
symbol, nor will quotes ever be downloaded for that symbol. Useful
with a home currency, such as the dollar @samp{$}. It is recommended
@@ -2572,6 +2585,7 @@ N SYMBOL
@item D AMOUNT
@findex xact
+@findex D
Specifies the default commodity to use, by specifying an amount in the
expected format. The @command{xact} command will use this commodity as
@@ -2586,6 +2600,7 @@ D $1,000.00
@end smallexample
@item C AMOUNT1 = AMOUNT2
+@findex C
Specifies a commodity conversion, where the first amount is given to
be equivalent to the second amount. The first amount should use the
decimal precision desired during reporting:
@@ -2595,6 +2610,12 @@ C 1.00 Kb = 1024 bytes
@end smallexample
@item I, i, O, o, b, h
+@findex I
+@findex i
+@findex O
+@findex o
+@findex b
+@findex h
These four relate to timeclock support, which permits Ledger to read
timelog files. See timeclock's documentation for more info on the
syntax of its timelog files.
@@ -3397,10 +3418,10 @@ double braces price form is a shorthand only.
Plus, it comes with dangers. This works fine:
-@smallexample
+@smallexample @c input:validate
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash $750.00
+ Assets:Brokerage:Cash $-500.00
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
@@ -3606,7 +3627,7 @@ after modifying them to suit your needs.
An automated transaction is a special kind of transaction which adds
its postings to other transactions any time one of that other
transactions' postings matches its predicate. The predicate uses the
-same query syntax as the Ledger command line.
+same query syntax as the Ledger command-line.
Consider this posting:
@@ -4409,7 +4430,7 @@ transactions @emph{displayed} to just those since last February, even
though those transactions from before will be computed as part of the
balance.
-@node Reporting Commands, Command-line Syntax, Building Reports, Top
+@node Reporting Commands, Command-Line Syntax, Building Reports, Top
@chapter Reporting Commands
@menu
@@ -4664,7 +4685,7 @@ a very naive but still useful application of the Babel system:
The following are some entries and I have requested that ledger be run
to generate a balance on the accounts. I could have asked for
a register or, in fact, anything at all the ledger can do through
-command line options.
+command-line options.
#+begin_src ledger :cmdline bal :results value
2010/01/01 * Starting balance
@@ -4808,7 +4829,7 @@ evaluating this code block (@kbd{C-c C-c}) would be:
If, instead, you wished to generate a register of all the transactions,
you would change the @code{#+begin_src} line for the code block to
-include the required command line option:
+include the required command-line option:
@smallexample
#+begin_src ledger :cmdline reg
@@ -5310,17 +5331,17 @@ FIX THIS ENTRY @c FIXME thdox
FIX THIS ENTRY @c FIXME thdox
-@node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top
-@chapter Command-line Syntax
+@node Command-Line Syntax, Budgeting and Forecasting, Reporting Commands, Top
+@chapter Command-Line Syntax
@menu
* Basic Usage::
-* Command Line Quick Reference::
+* Command-Line Quick Reference::
* Detailed Option Description::
* Period Expressions::
@end menu
-@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
This chapter describes Ledger's features and options. You may wish to
@@ -5364,8 +5385,8 @@ There are many, many command options available with the @file{ledger}
program, and it takes a while to master them. However, none of them are
required to use the basic reporting commands.
-@node Command Line Quick Reference, Detailed Option Description, Basic Usage, Command-line Syntax
-@section Command Line Quick Reference
+@node Command-Line Quick Reference, Detailed Option Description, Basic Usage, Command-Line Syntax
+@section Command-Line Quick Reference
@menu
* Basic Reporting Commands::
@@ -5377,10 +5398,10 @@ required to use the basic reporting commands.
* Commodity Reporting::
@end menu
-@node Basic Reporting Commands, Basic Options, Command Line Quick Reference, Command Line Quick Reference
+@node Basic Reporting Commands, Basic Options, Command-Line Quick Reference, Command-Line Quick Reference
@subsection Basic Reporting Commands
-@ftable @code
+@ftable @command
@item balance
@itemx bal
@@ -5419,222 +5440,222 @@ Generate transactions based on previous postings.
@end ftable
-@node Basic Options, Report Filtering, Basic Reporting Commands, Command Line Quick Reference
+@node Basic Options, Report Filtering, Basic Reporting Commands, Command-Line Quick Reference
@subsection Basic Options
-@ftable @code
+@ftable @option
-@item --help @c option
+@item --help
@itemx -h
Print summary of all options.
-@item --version @c option
+@item --version
@itemx -v
Print version information and exit.
-@item --file @var{FILE} @c option
+@item --file @var{FILE}
@itemx -f @var{FILE}
Read @file{FILE} as a ledger file.
-@item --output @var{FILE} @c option
+@item --output @var{FILE}
@itemx -o @var{FILE}
Redirect output to @file{FILE}.
-@item --init-file @var{FILE} @c option
+@item --init-file @var{FILE}
@itemx -i @var{FILE}
Specify an options file.
-@item --account @var{STR} @c option
+@item --account @var{STR}
@itemx -a @var{STR}
Specify default account @var{STR} for QIF file postings.
@end ftable
-@node Report Filtering, Error Checking and Calculation Options, Basic Options, Command Line Quick Reference
+@node Report Filtering, Error Checking and Calculation Options, Basic Options, Command-Line Quick Reference
@subsection Report Filtering
-@ftable @code
+@ftable @option
-@item --current @c option
+@item --current
@itemx -c
Display only transactions on or before the current date.
-@item --begin @var{DATE} @c option
+@item --begin @var{DATE}
@itemx -b @var{DATE}
Limit the processing to transactions on or after @var{DATE}.
-@item --end @var{DATE} @c option
+@item --end @var{DATE}
@itemx -e @var{DATE}
Limit the processing to transactions before @var{DATE}.
-@item --period @var{PERIOD_EXPRESSION} @c option
+@item --period @var{PERIOD_EXPRESSION}
@itemx -p @var{PERIOD_EXPRESSION}
Limit the processing to transactions in @var{PERIOD_EXPRESSION}.
-@item --period-sort @var{VEXPR} @c option
+@item --period-sort @var{VEXPR}
Sort postings within each period according to @var{VEXPR}.
-@item --cleared @c option
+@item --cleared
@itemx -C
Display only cleared postings.
-@item --dc @c option
+@item --dc
Display register or balance in debit/credit format.
-@item --uncleared @c option
+@item --uncleared
@itemx -U
Display only uncleared postings.
-@item --real @c option
+@item --real
@itemx -R
Display only real postings.
-@item --actual @c option
+@item --actual
@itemx -L
Display only actual postings, not automated ones.
-@item --related @c option
+@item --related
@itemx -r
Display related postings.
-@item --budget @c option
+@item --budget
Display how close your postings meet your budget.
-@item --add-budget @c option
+@item --add-budget
Show unbudgeted postings.
-@item --unbudgeted @c option
+@item --unbudgeted
Show only unbudgeted postings.
-@item --forecast-while @var{VEXPR} @c option
+@item --forecast-while @var{VEXPR}
@itemx --forecast @var{VEXPR}
Project balances into the future.
-@item --limit @var{EXPR} @c option
+@item --limit @var{EXPR}
@itemx -l @var{EXPR}
Limit which postings are used in calculations by @var{EXPR}.
-@item --amount @var{EXPR} @c option
+@item --amount @var{EXPR}
@itemx -t @var{EXPR}
Change value expression reported in @command{register} report.
-@item --total @var{VEXPR} @c option
+@item --total @var{VEXPR}
@itemx -T @var{VEXPR}
Change the value expression used for ``totals'' column in
@command{register} and @command{balance} reports.
@end ftable
-@node Error Checking and Calculation Options, Output Customization, Report Filtering, Command Line Quick Reference
+@node Error Checking and Calculation Options, Output Customization, Report Filtering, Command-Line Quick Reference
@subsection Error Checking and Calculation Options
-@ftable @code
+@ftable @option
-@item --strict @c option
+@item --strict
Accounts, tags or commodities not previously declared will cause
warnings.
-@item --pedantic @c option
+@item --pedantic
Accounts, tags or commodities not previously declared will cause errors.
-@item --check-payees @c option
+@item --check-payees
Enable strict and pedantic checking for payees as well as accounts,
commodities and tags. This only works in conjunction with
@option{--strict} or @option{--pedantic}.
-@item --immediate @c option
+@item --immediate
Instruct ledger to evaluate calculations immediately rather than lazily.
@end ftable
-@node Output Customization, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference
+@node Output Customization, Grouping Options, Error Checking and Calculation Options, Command-Line Quick Reference
@subsection Output Customization
-@ftable @code
+@ftable @option
-@item --collapse @c option
+@item --collapse
@itemx -n
Collapse transactions with multiple postings.
-@item --subtotal @c option
+@item --subtotal
@itemx -s
Report register as a single subtotal.
-@item --by-payee @c option
+@item --by-payee
@itemx -P
Report subtotals by payee.
-@item --empty @c option
+@item --empty
@itemx -E
Include empty accounts in the report.
-@item --weekly @c option
+@item --weekly
@itemx -W
Report posting totals by week.
-@item --quarterly @c option
+@item --quarterly
Report posting totals by quarter.
-@item --yearly @c option
+@item --yearly
@itemx -Y
Report posting totals by year.
-@item --dow @c option
+@item --dow
Report posting totals by day of week.
-@item --sort @var{VEXPR} @c option
+@item --sort @var{VEXPR}
@itemx -S @var{VEXPR}
Sort a report using @var{VEXPR}.
-@item --wide @c option
+@item --wide
@itemx -w
Assume 132 columns instead of 80.
-@item --head @var{INT} @c option
+@item --head @var{INT}
Report the first @var{INT} postings.
-@item --tail @var{INT} @c option
+@item --tail @var{INT}
Report the last @var{INT} postings.
-@item --pager @var{FILE} @c option
+@item --pager @var{FILE}
Direct output to @var{FILE} pager program.
-@item --average @c option
+@item --average
@itemx -A
Report the average posting value.
-@item --deviation @c option
+@item --deviation
@itemx -D
Report each posting's deviation from the average.
-@item --percent @c option
+@item --percent
@itemx -%
Show subtotals in the balance report as percentages.
@c @item --totals
@c Include running total in the @command{xml} report
-@item --pivot @var{TAG} @c option
+@item --pivot @var{TAG}
Produce a pivot table of the @var{TAG} type specified.
-@item --amount-data @c option
+@item --amount-data
@itemx -j
Show only the date and value columns to format the output for plots.
-@item --plot-amount-format @var{FORMAT_STRING} @c option
+@item --plot-amount-format @var{FORMAT_STRING}
Specify the format for the plot output.
-@item --total-data @c option
+@item --total-data
@itemx -J
Show only the date and total columns to format the output for plots.
-@item --plot-total-format @var{FORMAT_STRING} @c option
+@item --plot-total-format @var{FORMAT_STRING}
Specify the format for the plot output.
-@item --display @var{EXPR} @c option
+@item --display @var{EXPR}
@itemx -d @var{EXPR}
Display only postings that meet the criteria in the @var{EXPR}.
-@item --date-format @var{DATE_FORMAT} @c option
+@item --date-format @var{DATE_FORMAT}
@itemx -y @var{DATE_FORMAT}
Change the basic date format used in reports.
@@ -5645,87 +5666,87 @@ Change the basic date format used in reports.
@itemx -F @var{FORMAT_STRING}
Set the reporting format for various reports.
-@item --anon @c option
+@item --anon
Print the ledger register with anonymized accounts and payees, useful
for filing bug reports.
@end ftable
-@node Grouping Options, Commodity Reporting, Output Customization, Command Line Quick Reference
+@node Grouping Options, Commodity Reporting, Output Customization, Command-Line Quick Reference
@subsection Grouping Options
-@ftable @code
+@ftable @option
-@item --by-payee @c option
+@item --by-payee
@itemx -P
Group postings by common payee names.
-@item --daily @c option
+@item --daily
@itemx -D
Group postings by day.
-@item --weekly @c option
+@item --weekly
@itemx -W
Group postings by week.
-@item --monthly @c option
+@item --monthly
@itemx -M
Group postings by month.
-@item --quarterly @c option
+@item --quarterly
Group postings by quarter.
-@item --yearly @c option
+@item --yearly
@itemx -Y
Group postings by year.
-@item --dow @c option
+@item --dow
Group by day of weeks.
-@item --subtotal @c option
+@item --subtotal
@itemx -s
Group postings together, similar to the balance report.
@end ftable
-@node Commodity Reporting, , Grouping Options, Command Line Quick Reference
+@node Commodity Reporting, , Grouping Options, Command-Line Quick Reference
@subsection Commodity Reporting
-@ftable @code
+@ftable @option
-@item --price-db @var{FILE} @c option
+@item --price-db @var{FILE}
Use @file{FILE} for retrieving stored commodity prices.
-@item --price-exp @var{INT} @c option
+@item --price-exp @var{INT}
@itemx -Z @var{INT}
Set expected freshness of prices in @var{INT} minutes.
-@item --download @c option
+@item --download
@itemx -Q
Download quotes using the script named @file{getquote}.
-@item --getquote @var{FILE} @c option
+@item --getquote @var{FILE}
Sets the path to a user-defined script to download commodity prices.
-@item --quantity @c option
+@item --quantity
@itemx -O
Report commodity totals without conversion.
-@item --basis @c option
+@item --basis
@itemx -B
Report cost basis.
-@item --market @c option
+@item --market
@itemx -V
Report last known market value.
-@item --gain @c option
+@item --gain
@itemx -G
Report net gain or loss for commodities that have a price history.
@end ftable
-@node Detailed Option Description, Period Expressions, Command Line Quick Reference, Command-line Syntax
+@node Detailed Option Description, Period Expressions, Command-Line Quick Reference, Command-Line Syntax
@section Detailed Option Description
@menu
@@ -5749,25 +5770,25 @@ GUIs, which would make use of the different scopes by keeping an
instance of Ledger running in the background and running multiple
sessions with multiple reports per session.
-@ftable @code
+@ftable @option
-@item --args-only @c option
+@item --args-only
Ignore all environment and init-file settings and
use only command-line arguments to control Ledger. Useful for debugging
or testing small journal files not associated with your main financial
database.
-@item --debug @var{CODE} @c option
+@item --debug @var{CODE}
FIX THIS ENTRY @c FIXME thdox
-@item --help @c option
+@item --help
@itemx -h
Display the man page for ledger.
-@item --init-file @var{FILE} @c option
+@item --init-file @var{FILE}
Specify the location of the init file. The default is @file{~/.ledgerrc}.
-@item --options @c option
+@item --options
Display the options in effect for this Ledger invocation, along with
their values and the source of those values, for example:
@@ -5798,22 +5819,22 @@ $ ledger --options bal --cleared
@noindent
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
is @code{?normalize} the value was set internally by ledger, in
a function called @code{normalize_options}.
-@item --script @var{FILE} @c option
+@item --script @var{FILE}
Execute a ledger script.
-@item --trace @var{INT} @c option
+@item --trace @var{INT}
Enable tracing. The @var{INT} specifies the level of trace desired.
-@item --verbose @c option
+@item --verbose
@itemx -v
Print detailed information on the execution of Ledger.
-@item --verify @c option
+@item --verify
Enable additional assertions during run-time. This causes a significant
slowdown. When combined with @option{--debug @var{CODE}} ledger will
produce memory trace information.
@@ -5836,7 +5857,7 @@ GUIs, which would make use of the different scopes by keeping an
instance of Ledger running in the background and running multiple
sessions with multiple reports per session.
-@ftable @code
+@ftable @option
@item --cache @var{FIXME}
FIX THIS ENTRY @c FIXME thdox
@@ -5847,29 +5868,29 @@ FIX THIS ENTRY @c FIXME thdox
@item --day-break
FIX THIS ENTRY @c FIXME thdox
-@item --decimal-comma @c option
+@item --decimal-comma
Direct Ledger to parse journals using the European standard comma as
a decimal separator, not the usual period.
-@item --download @c option
+@item --download
@itemx -Q
Direct Ledger to download prices using the script defined via the option
@option{--getquote @var{FILE}}.
-@item --explicit @c option
+@item --explicit
FIX THIS ENTRY @c FIXME thdox
-@item --file @var{FILE} @c option
+@item --file @var{FILE}
@itemx -f @var{FILE}
Specify the input @file{FILE} for this invocation.
-@item --getquote @var{FILE} @c option
+@item --getquote @var{FILE}
@cindex getquote
@cindex download prices
Tell ledger where to find the user defined script to download prices
information.
-@item --input-date-format @var{DATE_FORMAT} @c option
+@item --input-date-format @var{DATE_FORMAT}
Specify the input date format for journal entries. For example,
@smallexample
@@ -5880,7 +5901,7 @@ Would convert the @file{Export.csv} file to ledger format, assuming
the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time
Format Codes}).
-@item --master-account @var{STR} @c option
+@item --master-account @var{STR}
Prepend all account names with the argument.
@smallexample @c command:A76BB56
@@ -5908,19 +5929,19 @@ $ ledger -f drewr3.dat bal --no-total --master-account HUMBUG
$ 200.00 Mortgage:Principal
@end smallexample
-@item --no-aliases @c option
+@item --no-aliases
Ledger does not expand any aliases if this option is specified.
-@item --pedantic @c option
+@item --pedantic
Accounts, tags or commodities not previously declared will cause errors.
@item --permissive
FIX THIS ENTRY @c FIXME thdox
-@item --price-db @var{FILE} @c option
+@item --price-db @var{FILE}
Specify the location of the price entry data file.
-@item --price-exp @var{INT} @c option
+@item --price-exp @var{INT}
@itemx -Z @var{INT}
@itemx --leeway @var{INT}
Set the expected freshness of price quotes, in @var{INT} minutes. That
@@ -5929,7 +5950,7 @@ and if @option{--download} is being used, then the Internet will be
consulted again for a newer price. Otherwise, the old price is still
considered to be fresh enough.
-@item --strict @c option
+@item --strict
Ledger normally silently accepts any account or commodity in a posting,
even if you have misspelled a commonly used one. The option
@option{--strict} changes that behavior. While running with
@@ -5938,12 +5959,12 @@ correct, and if it encounters a new account or commodity (same as
a misspelled commodity or account) it will issue a warning giving you
the file and line number of the problem.
-@item --recursive-aliases @c option
+@item --recursive-aliases
Normally, ledger only expands aliases once. With this option, ledger
tries to expand the result of alias expansion recursively, until no more
expansions apply.
-@item --time-colon @c option
+@item --time-colon
The @option{--time-colon} option will display the value for a seconds
based commodity as real hours and minutes.
@@ -5965,9 +5986,9 @@ GUIs, which would make use of the different scopes by keeping an
instance of Ledger running in the background and running multiple
sessions with multiple reports per session.
-@ftable @code
+@ftable @option
-@item --abbrev-len @var{INT} @c option
+@item --abbrev-len @var{INT}
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
account name will be truncated on the right. If @var{INT} is greater
@@ -5975,54 +5996,54 @@ 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
desired width.
-@item --account @var{STR} @c option
+@item --account @var{STR}
Prepend @var{STR} to all accounts reported. That is, the option
@samp{--account Personal} would tack @samp{Personal:} to the beginning
of every account reported in a balance report or register report.
-@item --account-width @var{INT} @c option
+@item --account-width @var{INT}
Set the width of the account column in the @command{register} report
to @var{INT} characters.
-@item --actual @c option
+@item --actual
@itemx -L
Report only real transactions, ignoring all automated or virtual
transactions.
-@item --add-budget @c option
+@item --add-budget
Show only unbudgeted postings.
-@item --amount @var{EXPR} @c option
+@item --amount @var{EXPR}
@itemx -t @var{EXPR}
Apply the given value expression to the posting amount (@pxref{Value
Expressions}). Using @option{--amount @var{EXPR}} you can apply an
arbitrary transformation to the postings.
-@item --amount-data @c option
+@item --amount-data
@itemx -j
On a register report print only the date and amount of postings.
Useful for graphing and spreadsheet applications.
-@item --amount-width @var{INT} @c option
+@item --amount-width @var{INT}
Set the width in characters of the amount column in the
@command{register} report.
-@item --anon @c option
+@item --anon
Anonymize registry output, mostly for sending in bug reports.
@item --auto-match
FIX THIS ENTRY @c FIXME thdox
-@item --aux-date @c option
+@item --aux-date
@itemx --effective
Show auxiliary dates for all calculations (@pxref{Effective Dates}).
-@item --average @c option
+@item --average
@itemx -A
Print average values over the number of transactions instead of
running totals.
-@item --balance-format @var{FORMAT_STRING} @c option
+@item --balance-format @var{FORMAT_STRING}
Specify the format to use for the @command{balance} report (@pxref{Format
Strings}). The default is:
@@ -6037,16 +6058,16 @@ Strings}). The default is:
@item --base
FIX THIS ENTRY @c ASK JOHN
-@item --basis @c option
+@item --basis
@itemx -B
@itemx --cost
Report the cost basis on all posting.
-@item --begin @var{DATE} @c option
+@item --begin @var{DATE}
Specify the start @var{DATE} of all calculations. Transactions before
that date will be ignored.
-@item --bold-if @var{VEXPR} @c option
+@item --bold-if @var{VEXPR}
Print the entire line in bold if the given value expression is true
(@pxref{Value Expressions}).
@@ -6063,7 +6084,7 @@ Only display budgeted items. In a register report this
displays transactions in the budget, in a balance report this displays
accounts in the budget (@pxref{Budgeting and Forecasting}).
-@item --budget-format @var{FORMAT_STRING} @c option
+@item --budget-format @var{FORMAT_STRING}
Specify the format to use for the @command{budget} report (@pxref{Format
Strings}). The default is:
@@ -6075,16 +6096,16 @@ Strings}). The default is:
"--------------------\n"
@end smallexample
-@item --by-payee @c option
+@item --by-payee
@itemx -P
Group the register report by payee.
-@item --cleared @c option
+@item --cleared
@itemx -C
Consider only transactions that have been cleared for display and
calculation.
-@item --cleared-format @var{FORMAT_STRING} @c option
+@item --cleared-format @var{FORMAT_STRING}
FIX THIS ENTRY @c FIXME thdox: to keep?
Specify the format to use for the @command{cleared} report (@pxref{Format
Strings}). The default is:
@@ -6101,26 +6122,26 @@ Strings}). The default is:
"---------------- ---------------- ---------\n"
@end smallexample
-@item --collapse @c option
+@item --collapse
@itemx -n
By default ledger prints all accounts in an account tree. With
@option{--collapse} it prints only the top level account specified.
-@item --collapse-if-zero @c option
+@item --collapse-if-zero
Collapse the account display only if it has a zero balance.
-@item --color @c option
+@item --color
@itemx --ansi
Use color if the terminal supports it.
-@item --columns @var{INT} @c option
+@item --columns @var{INT}
Specify the width of the @command{register} report in characters.
-@item --count @c option
+@item --count
Direct ledger to report the number of items when appended to the
@command{commodities}, @command{accounts} or @command{payees} command.
-@item --csv-format @var{FORMAT_STRING} @c option
+@item --csv-format @var{FORMAT_STRING}
Specify the format to use for the @command{csv} report (@pxref{Format
Strings}). The default is:
@@ -6135,29 +6156,29 @@ Strings}). The default is:
"%(quoted(join(note | xact.note)))\n"
@end smallexample
-@item --current @c option
+@item --current
Shorthand for @samp{--limit "date <= today"}.
-@item --daily @c option
+@item --daily
@itemx -D
Shorthand for @samp{--period "daily"}.
-@item --date @var{EXPR} @c option
+@item --date @var{EXPR}
Transform the date of the transaction using @var{EXPR}.
-@item --date-format @var{DATE_FORMAT} @c option
+@item --date-format @var{DATE_FORMAT}
@itemx -y @var{DATE_FORMAT}
Specify the format ledger should use to read and print dates
(@pxref{Date and Time Format Codes}).
-@item --date-width @var{INT} @c option
+@item --date-width @var{INT}
Specify the width, in characters, of the date column in the
@command{register} report.
@item --datetime-format @var{FIXME}
FIX THIS ENTRY @c ASK JOHN
-@item --dc @c option
+@item --dc
Display register or balance in debit/credit format If you use
@option{--dc} with either the @command{register} (reg) or
@command{balance} (bal) commands, you will now get extra columns.
@@ -6216,29 +6237,29 @@ And with @option{--dc} it becomes this:
$145 $145 0
@end smallexample
-@item --depth @var{INT} @c option
+@item --depth @var{INT}
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
two levels, i.e. @samp{Expenses:Entertainment} but not
@samp{Expenses:Entertainment:Dining}. This is a display predicate, which
means it only affects display, not the total calculations.
-@item --deviation @c option
+@item --deviation
Report each posting’s deviation from the average. It is only meaningful
in the register and prices reports.
-@item --display @var{EXPR} @c option
+@item --display @var{EXPR}
Display only lines that satisfy the expression @var{EXPR}.
-@item --display-amount @var{EXPR} @c option
+@item --display-amount @var{EXPR}
Apply a transformation to the @emph{displayed} amount. This happens
after calculations occur.
-@item --display-total @var{EXPR} @c option
+@item --display-total @var{EXPR}
Apply a transformation to the @emph{displayed} total. This happens after
calculations occur.
-@item --dow @c option
+@item --dow
@itemx --days-of-week
Group transactions by the day of the week.
@@ -6249,15 +6270,15 @@ $ ledger reg Expenses --dow --collapse
@noindent
Will print all Expenses totaled for each day of the week.
-@item --empty @c option
+@item --empty
@itemx -E
Include empty accounts in the report and in average calculations.
-@item --end @var{DATE} @c option
+@item --end @var{DATE}
Specify the end @var{DATE} for a transaction to be considered in the
report. All transactions on or after this date are ignored.
-@item --equity @c option
+@item --equity
Related to the @command{equity} command (@pxref{The @command{equity}
command}). Gives current account balances in the form of a register
report.
@@ -6265,7 +6286,7 @@ report.
@item --exact
FIX THIS ENTRY @c ASK JOHN
-@item --exchange @var{COMMODITY} @c option
+@item --exchange @var{COMMODITY}
@itemx -X @var{COMMODITY}
Display values in terms of the given @var{COMMODITY}. The latest
available price is used. The syntax
@@ -6273,50 +6294,50 @@ available price is used. The syntax
in terms of @var{COMMODITY2} using the latest available price, but
will not automatically covert any other commodities to
@var{COMMODITY2}. Multiple @option{-X} arguments may be used on a
-single command line (as in
+single command-line (as in
@option{-X COMMODITY1:COMMODITY2 -X COMMODITY3:COMMODITY2}),
which is particularly useful for situations where many prices are
available for reporting in terms of @var{COMMODITY2}, but only a few
should be displayed that way.
-@item --flat @c option
+@item --flat
Force the full names of accounts to be used in the balance report. The
balance report will not use an indented tree.
-@item --force-color @c option
+@item --force-color
Output TTY color codes even if the TTY doesn't support them. Useful
for TTYs that don't advertise their capabilities correctly.
-@item --force-pager @c option
+@item --force-pager
Force Ledger to paginate its output.
-@item --forecast-while @var{VEXPR} @c option
+@item --forecast-while @var{VEXPR}
@itemx --forecast @var{VEXPR}
Continue forecasting while @var{VEXPR} is true.
-@item --forecast-years @var{INT} @c option
+@item --forecast-years @var{INT}
Forecast at most @var{INT} years into the future.
-@item --format @var{FORMAT_STRING} @c option
+@item --format @var{FORMAT_STRING}
@itemx -F @var{FORMAT_STRING}
Use the given format string to print output.
-@item --gain @c option
+@item --gain
@itemx -G
@itemx --change
Report on gains using the latest available prices.
-@item --generated @c option
+@item --generated
Include auto-generated postings (such as those from automated
transactions) in the report, in cases where you normally wouldn't want
them.
-@item --group-by @var{EXPR} @c option
+@item --group-by @var{EXPR}
Group transactions together in the @command{register} report.
@var{EXPR} can be anything, although most common would be @code{payee}
or @code{commodity}. The @code{tags()} function is also useful here.
-@item --group-title-format @var{FORMAT_STRING} @c option
+@item --group-title-format @var{FORMAT_STRING}
Set the format for the headers that separates the report sections of
a grouped report. Only has an effect with a @option{--group-by
@var{EXPR}} register report.
@@ -6334,19 +6355,19 @@ $ ledger reg Expenses --group-by "payee" --group-title-format "-----------------
...
@end smallexample
-@item --head @var{INT} @c option
+@item --head @var{INT}
@itemx --first @var{INT}
Print the first @var{INT} entries. Opposite of @option{--tail
@var{INT}}.
-@item --historical @c option
+@item --historical
@itemx -H
FIX THIS ENTRY @c FIXME thdox
-@item --immediate @c option
+@item --immediate
FIX THIS ENTRY @c FIXME thdox
-@item --inject @c option
+@item --inject
Use @code{Expected} amounts in calculations. In case you know
what amount a transaction should be, but the actual transaction has the
wrong value you can use metadata to specify the expected amount:
@@ -6360,105 +6381,105 @@ wrong value you can use metadata to specify the expected amount:
Then using the command @code{ledger reg --inject=Expected Income} would
treat the transaction as if the ``Expected Value'' was actual.
-@item --invert @c option
+@item --invert
Change the sign of all reported values.
-@item --limit @var{EXPR} @c option
+@item --limit @var{EXPR}
@itemx -l @var{EXPR}
Only transactions that satisfy @var{EXPR} are considered in
calculations and for display.
-@item --lot-dates @c option
+@item --lot-dates
Report the date on which each commodity in a balance report was
purchased.
-@item --lot-notes @c option
+@item --lot-notes
@itemx --lot-tags
Report the tag attached to each commodity in a balance report.
-@item --lot-prices @c option
+@item --lot-prices
Report the price at which each commodity in a balance report was
purchased.
-@item --lots @c option
+@item --lots
Report the date and price at which each commodity was purchased in
a balance report.
@item --lots-actual
FIX THIS ENTRY
-@item --market @c option
+@item --market
@itemx -V
Use the latest market value for all commodities.
-@item --meta @var{TAG} @c option
+@item --meta @var{TAG}
In the register report, prepend the transaction with the value of the
given @var{TAG}.
-@item --meta-width @var{INT} @c option
+@item --meta-width @var{INT}
Specify the width of the Meta column used for the @option{--meta
@var{TAG}} options.
-@item --monthly @c option
+@item --monthly
@itemx -M
Synonym for @samp{--period "monthly"}.
-@item --no-aliases @c option
+@item --no-aliases
Aliases are completely ignored.
-@item --no-color @c option
+@item --no-color
Suppress any color TTY output.
-@item --no-rounding @c option
+@item --no-rounding
Don't output @samp{<Rounding>} postings. Note that this will cause the
running total to often not add up! Its main use is for
@option{--amount-data (-j)} and @option{--total-data (-J)} reports.
-@item --no-titles @c option
+@item --no-titles
Suppress the output of group titles.
-@item --no-total @c option
+@item --no-total
Suppress printing the final total line in a balance report.
-@item --now @var{DATE} @c option
+@item --now @var{DATE}
Define the current date in case you want to calculate in the past or
future using @option{--current}.
-@item --only @var{FIXME} @c option
+@item --only @var{FIXME}
This is a postings predicate that applies after certain transforms have
been executed, such as periodic gathering.
-@item --output @var{FILE} @c option
+@item --output @var{FILE}
Redirect the output of ledger to the file defined in @file{FILE}.
-@item --pager @var{FILE} @c option
+@item --pager @var{FILE}
Specify the pager program to use.
-@item --payee @var{VEXPR} @c option
+@item --payee @var{VEXPR}
Sets a value expression for formatting the payee. In the
@command{register} report this prevents the second entry from having
a date and payee for each transaction.
-@item --payee-width @var{INT} @c option
+@item --payee-width @var{INT}
Set the number of columns dedicated to the payee in the register
report to @var{INT}.
-@item --pending @c option
+@item --pending
Use only postings that are marked pending.
-@item --percent @c option
+@item --percent
@itemx -%
Calculate the percentage value of each account in balance reports.
Only works for accounts that have a single commodity.
-@item --period @var{PERIOD_EXPRESSION} @c option
+@item --period @var{PERIOD_EXPRESSION}
Define a period expression that sets the time period during which
transactions are to be accounted. For a @command{register} report only
the transactions that satisfy the period expression with be displayed.
For a @command{balance} report only those transactions will be accounted
in the final balances.
-@item --pivot @var{TAG} @c option
+@item --pivot @var{TAG}
Produce a balance pivot report @emph{around} the given @var{TAG}. For
example, if you have multiple cars and track each fuel purchase in
@samp{Expenses:Auto:Fuel} and tag each fuel purchase with a tag
@@ -6479,60 +6500,60 @@ $ ledger bal Fuel --pivot "Car" --period "this year"
@xref{Metadata values}.
-@item --plot-amount-format @var{FORMAT_STRING} @c option
+@item --plot-amount-format @var{FORMAT_STRING}
Define the output format for an amount data plot. @xref{Visualizing
with Gnuplot}.
-@item --plot-total-format @var{FORMAT_STRING} @c option
+@item --plot-total-format @var{FORMAT_STRING}
Define the output format for a total data plot. @xref{Visualizing with
Gnuplot}.
-@item --prepend-format @var{FORMAT_STRING} @c option
+@item --prepend-format @var{FORMAT_STRING}
Prepend @var{STR} to every line of the output.
-@item --prepend-width @var{INT} @c option
+@item --prepend-width @var{INT}
Reserve @var{INT} spaces at the beginning of each line of the output.
-@item --price @c option
+@item --price
@itemx -I
Use the price of the commodity purchase for performing calculations.
-@item --pricedb-format @var{FORMAT_STRING} @c option
+@item --pricedb-format @var{FORMAT_STRING}
Set the format expected for the historical price file.
@item --prices-format @var{FORMAT_STRING}
Set the format for the @command{prices} report.
-@item --primary-date @c option
+@item --primary-date
@itemx --actual-dates
Show primary dates for all calculations (@pxref{Effective Dates}).
-@item --quantity @c option
+@item --quantity
@itemx -O
Report commodity totals (this is the default).
-@item --quarterly @c option
+@item --quarterly
Synonym for @samp{--period "quarterly"}.
-@item --raw @c option
+@item --raw
In the @command{print} report, show transactions using the exact same
syntax as specified by the user in their data file. Don't do any
massaging or interpreting. This can be useful for minor cleanups, like
just aligning amounts.
-@item --real @c option
+@item --real
@itemx -R
Account using only real transactions ignoring virtual and automatic
transactions.
-@item --register-format @var{FORMAT_STRING} @c option
+@item --register-format @var{FORMAT_STRING}
Define the output format for the @command{register} report.
-@item --related @c option
+@item --related
In a @command{register} report show the related account. This is the
other @emph{side} of the transaction.
-@item --related-all @c option
+@item --related-all
Show all postings in a transaction, similar to @option{--related} but
show both @emph{sides} of each transaction.
@@ -6549,11 +6570,11 @@ FIX THIS ENTRY
@itemx --detail
FIX THIS ENTRY @c FIXME thdox
-@item --seed @var{FIXME} @c option
-Set the random seed to @var{FIXME} for the @code{generate} command.
+@item --seed @var{INT}
+Set the random seed to @var{INT} for the @code{generate} command.
Used as part of development testing.
-@item --sort @var{VEXPR} @c option
+@item --sort @var{VEXPR}
@itemx -S @var{VEXPR}
Sort the @command{register} report based on the value expression given
to sort.
@@ -6561,11 +6582,11 @@ to sort.
@c @item --sort-all @var{FIXME}
@c FIX THIS ENTRY
-@item --sort-xacts @var{VEXPR} @c option
+@item --sort-xacts @var{VEXPR}
@itemx --period-sort @var{VEXPR}
Sort the postings within transactions using the given value expression.
-@item --start-of-week @var{INT} @c option
+@item --start-of-week @var{INT}
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
week.
@@ -6574,7 +6595,7 @@ week.
@itemx -s
FIX THIS ENTRY
-@item --tail @var{INT} @c option
+@item --tail @var{INT}
@itemx --last @var{INT}
Report only the last @var{INT} entries. Only useful in
a @command{register} report.
@@ -6582,62 +6603,62 @@ a @command{register} report.
@item --time-report
FIX THIS ENTRY @c FIXME thdox
-@item --total @var{VEXPR} @c option
+@item --total @var{VEXPR}
@itemx -T @var{VEXPR}
Define a value expression used to calculate the total in reports.
-@item --total-data @c option
+@item --total-data
@itemx -J
Show only dates and totals to format the output for plots.
-@item --total-width @var{INT} @c option
+@item --total-width @var{INT}
Set the width of the total field in the register report.
-@item --truncate @var{CODE} @c option
+@item --truncate @var{CODE}
Indicates how truncation should happen when the contents of columns
exceed their width. Valid arguments are @samp{leading}, @samp{middle},
and @samp{trailing}. The default is smarter than any of these three,
as it considers sub-names within the account name (that style is
called ``abbreviate'').
-@item --unbudgeted @c option
+@item --unbudgeted
Show only unbudgeted postings.
-@item --uncleared @c option
+@item --uncleared
@itemx -U
Use only uncleared transactions in calculations and reports.
-@item --unrealized @c option
+@item --unrealized
Show generated unrealized gain and loss accounts in the balance
report.
-@item --unrealized-gains @var{STR} @c option
+@item --unrealized-gains @var{STR}
Allow the user to specify what account name should be used for
unrealized gains. Defaults to @samp{"Equity:Unrealized Gains"}.
Often set in one's @file{~/.ledgerrc} file to change the default.
-@item --unrealized-losses @var{STR} @c option
+@item --unrealized-losses @var{STR}
Allow the user to specify what account name should be used for
unrealized gains. Defaults to @samp{"Equity:Unrealized Losses"}.
Often set in one's @file{~/.ledgerrc} file to change the default.
-@item --unround @c option
+@item --unround
Perform all calculations without rounding and display results to full
precision.
-@item --values @c option
+@item --values
Shows the values used by each tag when used in combination with the
@command{tags} command.
-@item --weekly @c option
+@item --weekly
@itemx -W
Synonym for @samp{--period "weekly"}.
-@item --wide @c option
+@item --wide
Let the register report use 132 columns instead of 80 (the default).
Identical to @samp{--columns "132"}.
-@item --yearly @c option
+@item --yearly
@itemx -Y
Synonym for @samp{--period "yearly"}.
@@ -6650,31 +6671,31 @@ These are the most basic command options. Most likely, the user will
want to set them using environment variables (see @ref{Environment
variables}), instead of using actual command-line options:
-@ftable @code
+@ftable @option
-@item --help @c option
+@item --help
@itemx -h
Print a summary of all the options, and what they are used for. This
can be a handy way to remember which options do what.
-@item --version @c option
+@item --version
Print the current version of ledger and exits. This is useful for
sending bug reports, to let the author know which version of ledger you
are using.
-@item --file @var{FILE} @c option
+@item --file @var{FILE}
@itemx -f @var{FILE}
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
times. Typically, the environment variable @env{LEDGER_FILE} is set,
rather than using this command-line option.
-@item --output @var{FILE} @c option
+@item --output @var{FILE}
@itemx -o @var{FILE}
Redirect output from any command to @file{FILE}. By default, all output
goes to standard output.
-@item --init-file @var{FILE} @c option
+@item --init-file @var{FILE}
@itemx -i @var{FILE}
Causes @file{FILE} to be read by ledger before any other ledger file.
This file may not contain any postings, but it may contain option
@@ -6691,7 +6712,7 @@ example init file:
Option settings on the command-line or in the environment always take
precedence over settings in the init file.
-@item --account @var{STR} @c option
+@item --account @var{STR}
@itemx -a @var{STR}
Specify the default account which QIF file postings are assumed to
relate to.
@@ -6704,13 +6725,13 @@ relate to.
These options change which postings affect the outcome of a
report, in ways other than just using regular expressions:
-@ftable @code
+@ftable @option
-@item --current @c option
+@item --current
@itemx -c
Display only transactions occurring on or before the current date.
-@item --begin @var{DATE} @c option
+@item --begin @var{DATE}
@itemx -b @var{DATE}
Constrain the report to transactions on or after @var{DATE}. Only
transactions after that date will be calculated, which means that the
@@ -6718,12 +6739,12 @@ running total in the balance report will always start at zero with the
first matching transaction. (Note: This is different from using
@option{--display @var{EXPR}} to constrain what is displayed).
-@item --end @var{DATE} @c option
+@item --end @var{DATE}
@itemx -e @var{DATE}
Constrain the report so that transactions on or after @var{DATE} are
not considered.
-@item --period @var{PERIOD_EXPRESSION} @c option
+@item --period @var{PERIOD_EXPRESSION}
@itemx -p @var{PERIOD_EXPRESSION}
Set the reporting period to @var{STR}. This will subtotal all matching
transactions within each period separately, making it easy to see
@@ -6732,7 +6753,7 @@ even specify the beginning and end of the report range, using simple
terms like @samp{last June} or @samp{next month}. For more details on
period expressions, see @ref{Period Expressions}.
-@item --period-sort @var{VEXPR} @c option
+@item --period-sort @var{VEXPR}
Sort the postings within each reporting period using the value
expression @var{EXPR}. This is most often useful when reporting
monthly expenses, in order to view the highest expense categories at
@@ -6743,28 +6764,28 @@ the top of each month:
$ ledger -M --period-sort total reg ^Expenses
@end smallexample
-@item --cleared @c option
+@item --cleared
@itemx -C
Display only postings whose transaction has been marked ``cleared''
(by placing an asterisk to the right of the date).
-@item --uncleared @c option
+@item --uncleared
@itemx -U
Display only postings whose transaction has not been marked ``cleared''
(i.e., if there is no asterisk to the right of the date).
-@item --real @c option
+@item --real
@itemx -R
Display only real postings, not virtual. (A virtual posting is
indicated by surrounding the account name with parentheses or brackets;
see @ref{Virtual postings} for more information).
-@item --actual @c option
+@item --actual
@itemx -L
Display only actual postings, and not those created by automated
transactions.
-@item --related @c option
+@item --related
@itemx -r
Display postings that are related to whichever postings would
otherwise have matched the filtering criteria. In the register
@@ -6794,25 +6815,25 @@ posting that matched:
Assets:Checking $-85.00 $-65.00
@end smallexample
-@item --budget @c option
+@item --budget
Useful for displaying how close your postings meet your budget.
@option{--add-budget} also shows unbudgeted postings, while
@option{--unbudgeted} shows only those. @option{--forecast @var{VEXPR}}
is a related option that projects your budget into the future, showing
how it will affect future balances. @xref{Budgeting and Forecasting}.
-@item --limit @var{EXPR} @c option
+@item --limit @var{EXPR}
@itemx -l @var{EXPR}
Limit which postings take part in the calculations of a report.
-@item --amount @var{EXPR} @c option
+@item --amount @var{EXPR}
@itemx -t @var{EXPR}
Change the value expression used to calculate the ``value'' column in
the @command{register} report, the amount used to calculate account
totals in the @command{balance} report, and the values printed in the
@command{equity} report. @xref{Value Expressions}.
-@item --total @var{VEXPR} @c option
+@item --total @var{VEXPR}
@itemx -T @var{VEXPR}
Set the value expression used for the ``totals'' column in the
@command{register} and @command{balance} reports.
@@ -6869,50 +6890,50 @@ Set the value expression used for the ``totals'' column in the
These options affect only the output, but not which postings are
used to create it:
-@ftable @code
+@ftable @option
-@item --collapse @c option
+@item --collapse
@itemx -n
Cause transactions in a @command{register} report with multiple
postings to be collapsed into a single, subtotaled transaction.
-@item --subtotal @c option
+@item --subtotal
@itemx -s
Cause all transactions in a @command{register} report to be collapsed
into a single, subtotaled transaction.
-@item --by-payee @c option
+@item --by-payee
@itemx -P
Report subtotals by payee.
-@item --empty @c option
+@item --empty
@itemx -E
Include even empty accounts in the @command{balance} report.
-@item --weekly @c option
+@item --weekly
@itemx -W
Report posting totals by the week. The week begins on whichever day of
the week begins the month containing that posting. To set a specific
begin date, use a period string, such as @samp{weekly from DATE}.
-@item --monthly @c option
+@item --monthly
@itemx -M
Report posting totals by month.
-@item --yearly @c option
+@item --yearly
@itemx -Y
Report posting totals by year. For more complex periods, use
@option{--period}.
@c TODO end this sentence
-@item --period @var{PERIOD_EXPRESSION} @c option
+@item --period @var{PERIOD_EXPRESSION}
Option described above.
-@item --dow @c option
+@item --dow
Report posting totals for each day of the week. This is an easy way
to see if weekend spending is more than on weekdays.
-@item --sort @var{VEXPR} @c option
+@item --sort @var{VEXPR}
@itemx -S @var{VEXPR}
Sort a report by comparing the values determined using the value
expression @var{VEXPR}. For example, using @samp{-S "-abs(total)"} in
@@ -6920,16 +6941,16 @@ the @command{balance} report will sort account balances from greatest to
least, using the absolute value of the total. For more on how to use
value expressions, see @ref{Value Expressions}.
-@item --pivot @var{TAG} @c option
+@item --pivot @var{TAG}
Produce a pivot table around the @var{TAG} provided. This requires
meta data using valued tags.
-@item --wide @c option
+@item --wide
@itemx -w
Cause the default @command{register} report to assume 132 columns
instead of 80.
-@item --head @var{INT} @c option
+@item --head @var{INT}
Cause only the first @var{INT} transactions to be printed. This is
different from using the command-line utility @file{head}, which would
limit to the first @var{INT} postings. @option{--tail @var{INT}} outputs
@@ -6938,21 +6959,21 @@ simultaneously. If a negative amount is given, it will invert the
meaning of the flag (instead of the first five transactions being
printed, for example, it would print all but the first five).
-@item --pager @var{FILE} @c option
+@item --pager @var{FILE}
Tell Ledger to pass its output to the given pager program; very useful
when the output is especially long. This behavior can be made the
default by setting the @env{LEDGER_PAGER} environment variable.
-@item --average @c option
+@item --average
@itemx -A
Report the average posting value.
-@item --deviation @c option
+@item --deviation
@itemx -D
Report each posting's deviation from the average. It is only meaningful
in the @command{register} and @command{prices} reports.
-@item --percent @c option
+@item --percent
@itemx -%
Show account subtotals in the @command{balance} report as percentages of
the parent account.
@@ -6961,19 +6982,19 @@ the parent account.
@c @command{xml} report.
@item --amount-data
-@itemx -j @c option
+@itemx -j
Change the @command{register} report so that it prints nothing but the
date and the value column, and the latter without commodities. This is
only meaningful if the report uses a single commodity. This data can
then be fed to other programs, which could plot the date, analyze it,
etc.
-@item --total-data @c option
+@item --total-data
@itemx -J
Change the @command{register} report so that it prints nothing but the
date and total columns, without commodities.
-@item --display @var{EXPR} @c option
+@item --display @var{EXPR}
@itemx -d @var{EXPR}
Limit which postings or accounts are actually displayed in a report.
They might still be calculated, and be part of the running total of a
@@ -7000,7 +7021,7 @@ amount for the reporting range (using @option{--period
@var{PERIOD_EXPRESSION} (-p)}), or simply a display restricted to the
reporting range (using @option{--display @var{EXPR} (-d)}).
-@item --date-format @var{DATE_FORMAT} @c option
+@item --date-format @var{DATE_FORMAT}
@itemx -y @var{DATE_FORMAT}
Change the basic date format used by reports. The default uses a date
like @samp{2004/08/01}, which represents the default date format of
@@ -7009,13 +7030,13 @@ easiest way is to put @option{--date-format @var{DATE_FORMAT}} in the
Ledger initialization file @file{~/.ledgerrc} (or the file referred to
by @env{LEDGER_INIT}).
-@item --format @var{FORMAT_STRING} @c option
+@item --format @var{FORMAT_STRING}
@itemx -F @var{FORMAT_STRING}
Set the reporting format for whatever report ledger is about to make.
@xref{Format Strings}. There are also specific format commands for
each report type:
-@item --balance-format @var{FORMAT_STRING} @c option
+@item --balance-format @var{FORMAT_STRING}
Define the output format for the @command{balance} report. The default
(defined in @file{report.h} is:
@@ -7033,7 +7054,7 @@ Define the output format for the @command{balance} report. The default
--------------------\n"
@end smallexample
-@item --cleared-format @var{FORMAT_STRING} @c option
+@item --cleared-format @var{FORMAT_STRING}
Define the format for the cleared report. The default is:
@smallexample
@@ -7048,7 +7069,7 @@ Define the format for the cleared report. The default is:
---------------- ---------------- ---------\n"
@end smallexample
-@item --register-format @var{FORMAT_STRING} @c option
+@item --register-format @var{FORMAT_STRING}
Define the output format for the @command{register} report. The default
(defined in @file{report.h} is:
@@ -7100,7 +7121,7 @@ Set the format for @command{csv} reports. The default is:
%(quoted(join(note | xact.note)))\n"
@end smallexample
-@item --plot-amount-format @var{FORMAT_STRING} @c option
+@item --plot-amount-format @var{FORMAT_STRING}
Set the format for amount plots, using the @option{--amount-data (-j)}
option. The default is:
@@ -7108,7 +7129,7 @@ option. The default is:
"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n"
@end smallexample
-@item --plot-total-format @var{FORMAT_STRING} @c option
+@item --plot-total-format @var{FORMAT_STRING}
Set the format for total plots, using the @option{--total-data (-J)}
option. The default is:
@@ -7116,14 +7137,14 @@ option. The default is:
"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n"
@end smallexample
-@item --pricedb-format @var{FORMAT_STRING} @c option
+@item --pricedb-format @var{FORMAT_STRING}
Set the format expected for the historical price file. The default is:
@smallexample
"P %(datetime) %(display_account) %(scrub(display_amount))\n"
@end smallexample
-@item --prices-format @var{FORMAT_STRING} @c option
+@item --prices-format @var{FORMAT_STRING}
Set the format for the @command{prices} report. The default is:
@smallexample
@@ -7138,9 +7159,9 @@ Set the format for the @command{prices} report. The default is:
These options affect how commodity values are displayed:
-@ftable @code
+@ftable @option
-@item --price-db @var{FILE} @c option
+@item --price-db @var{FILE}
Set the file that is used for recording downloaded commodity prices.
It is always read on startup, to determine historical prices. Other
settings can be placed in this file manually, to prevent downloading
@@ -7161,7 +7182,7 @@ download script maintain this file.
The format of the file can be changed by telling ledger to use the
@option{--pricedb-format @var{FORMAT_STRING}} you define.
-@item --price-exp @var{INT} @c option
+@item --price-exp @var{INT}
@itemx -Z @var{INT}
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,
@@ -7169,7 +7190,7 @@ and if @option{--download} is being used, then the Internet will be
consulted again for a newer price. Otherwise, the old price is still
considered to be fresh enough.
-@item --download @c option
+@item --download
@itemx -Q
Cause quotes to be automagically downloaded, as needed, by running
a script named @file{getquote} and expecting that script to return
@@ -7188,21 +7209,21 @@ expressions, and the @option{--amount @var{EXPR} (-t)} and
several ``default'' reports, which will satisfy most users' basic
reporting needs:
-@ftable @code
+@ftable @option
-@item --quantity @c option
+@item --quantity
@itemx -O
Report commodity totals (this is the default).
-@item --basis @c option
+@item --basis
@itemx -B
Report the cost basis for all postings.
-@item --market @c option
+@item --market
@itemx -V
Use the last known value for commodities to calculate final values.
-@item --gain @c option
+@item --gain
@itemx -G
Report the net gain/loss for all commodities in the report that have
a price history.
@@ -7390,7 +7411,7 @@ option settings in the file @file{~/.ledgerrc}, for example:
--pager /bin/cat
@end smallexample
-@node Period Expressions, , Detailed Option Description, Command-line Syntax
+@node Period Expressions, , Detailed Option Description, Command-Line Syntax
@section Period Expressions
@c TODO use @var below
@@ -7478,7 +7499,7 @@ last oct
weekly last august
@end smallexample
-@node Budgeting and Forecasting, Time Keeping, Command-line Syntax, Top
+@node Budgeting and Forecasting, Time Keeping, Command-Line Syntax, Top
@chapter Budgeting and Forecasting
@menu
@@ -7565,7 +7586,7 @@ makes this easy to do, using the same periodic transactions as are used
for budgeting. An example forecast report can be generated with:
@smallexample @c command:validate
-$ ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
+$ ledger --file drewr3.dat --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
@end smallexample
This report continues outputting postings until the running total
@@ -7732,13 +7753,6 @@ considering children.
The cost of a posting; the cost of an account, without its
children.
-@item v
-The market value of a posting or an account, without its children.
-
-@item g
-The net gain (market value minus cost basis), for a posting or an
-account, without its children. It is the same as @samp{v-b}.
-
@item l
The depth (``level'') of an account. If an account has one parent,
its depth is one.
@@ -7771,19 +7785,6 @@ and all its children.
The total count of postings affecting an account and all its
children.
-@item B
-The total cost of all postings seen so far; the total cost of an
-account and all its children.
-
-@item V
-The market value of all postings seen so far, or of an account and
-all its children.
-
-@item G
-The total net gain (market value minus cost basis), for a series of
-postings, or an account and its children. It is the same as
-@samp{V-B}.
-
@end table
@node Functions, Operators, Variables, Value Expressions
@@ -7802,10 +7803,6 @@ The absolute (unsigned) value of the argument.
@item S
Strips the commodity from the argument.
-@item A
-The arithmetic mean of the argument; @samp{Ax} is the same as
-@samp{x/n}.
-
@item P
The present market value of the argument. The syntax @samp{P(x,d)} is
supported, which yields the market value at time @samp{d}. If no date
@@ -8055,7 +8052,7 @@ account or posting in custom ways.
There are several additional flags that allow you to define formats
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.
@itemize
@@ -8243,7 +8240,7 @@ functions are described later):
@subsection Field Widths
The following codes return the width allocated for the specific fields.
-The defaults can be changed using the corresponding command line
+The defaults can be changed using the corresponding command-line
options:
@itemize
@@ -8491,7 +8488,7 @@ Surrounds the string representing value with ANSI codes to give it
@item justify(value, first_width, latter_width, right_justify, colorize)
Right or left justify the string representing @code{value}. The width
of the field in the first line is given by @code{first_width}. For
-subsequent lines the width is given by @code{latterwidth}. 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.
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
@@ -8520,7 +8517,7 @@ generated the posting.
@table @code
@item filename
-the name of ledger the data file from whence the posting came,
+the name of the ledger data file from whence the posting came,
abbreviated @samp{S}.
@item beg_pos
@@ -8536,7 +8533,7 @@ line number in @code{filename} where entry for posting begins,
abbreviated @samp{b}.
@item end_line
-line number in @code{filename} where posting's entry for posting ends,
+line number in @code{filename} where entry for posting ends,
abbreviated @samp{e}.
@end table
@@ -9232,7 +9229,7 @@ This command simply echoes its argument back to the output.
Forces ledger to reload any journal files. This function exists to
support external programs controlling a running ledger process and does
-nothing for a command line user.
+nothing for a command-line user.
@node @command{source}, Debug Options, @command{reload}, Developer Commands
@subsection @command{source}
@@ -9249,7 +9246,7 @@ are found.
These options are primarily for Ledger developers, but may be of some
use to a user trying something new.
-@ftable @code
+@ftable @option
@item --args-only
Ignore init files and environment variables for the ledger run.
@@ -9481,20 +9478,29 @@ In case several test files belong to the same bug number the files by appending
@code{_X} where @samp{X} is the number of the test, e.g. @samp{1234_1.test},
@samp{1234_2.test}.
+@anchor{Baseline Test Types}
+@multitable @columnfractions .3 .7
+@headitem Type @tab Use
+@item @code{cmd} @tab Ledger commands like @code{register} or @code{balance}
+@item @code{dir} @tab ?
+@item @code{feat} @tab ?
+@item @code{opt} @tab Ledger options such as @option{--period} or @option{--format}
+@end multitable
+
A ledger test file contains three sections:
@enumerate
@item the journal data used for the test, this can be empty in certain
scenarios
-@item the ledger commandline options used for the test
+@item the ledger command-line options used for the test
@item the expected output
@end enumerate
-Ledger has a special command directive for tests, everythin between
+Ledger has a special command directive for tests, everything between
@code{test} and @code{end test} is treated like a comment, so every
Ledger test is automatically a valid Ledger file.
The test scripts take the remainder of the @code{test} line and use
-it as commandline arguments for ledger, the text enclosed in @code{test}
+it as command-line arguments for ledger, the text enclosed in @code{test}
and @code{end test} is expected output, for example:
@smallexample
@@ -9504,7 +9510,7 @@ year 2014
Assets:Bank ¤ -150,00
Expenses:Presents
-; The following line specifies the ledger commandline options for this test and
+; The following line specifies the ledger command-line options for this test and
; everything between the next line and `end test` specifies the expected output
test reg --payee=code
14-Dec-24 C0d3 Assets:Bank ¤ -150,00 ¤ -150,00
@@ -9712,21 +9718,6 @@ $ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25
(Liabilities:Tithe Owed) -1.0
@end smallexample
-@menu
-* Baseline Test Types::
-@end menu
-
-@node Baseline Test Types, , Cookbook, Miscellaneous Notes
-@section Baseline Test Types
-
-@multitable @columnfractions .3 .7
-@headitem Type @tab Use
-@item @code{cmd} @tab Ledger commands like @code{register} or @code{balance}
-@item @code{dir} @tab ?
-@item @code{feat} @tab ?
-@item @code{opt} @tab Ledger options such as @option{--period} or @option{--format}
-@end multitable
-
@node Concepts Index, Commands & Options Index, Miscellaneous Notes, Top
@unnumbered Concepts Index