delete obsolete ledger.texi. Down with cruft!

2 files changed, 1 insertions, 4109 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 12f96444..275678a8 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -32,7 +32,7 @@ if(NOT BUILD_DOCS)
   return()
 endif()
 
-set(info_files ledger.texi ledger3.texi ledger-mode.texi)
+set(info_files ledger3.texi ledger-mode.texi)
 
 find_program(MAKEINFO makeinfo)
 find_program(TEXI2PDF texi2pdf)
diff --git a/doc/ledger.texi b/doc/ledger.texi
deleted file mode 100644
index 8389c383..00000000
--- a/doc/ledger.texi
+++ /dev/null
@@ -1,4108 +0,0 @@
-\input texinfo  @c -*-texinfo-*-
-
-@setfilename ledger.info
-@settitle Ledger: Command-Line Accounting
-
-@dircategory User Applications
-@copying
-Copyright (c) 2003-2010, John Wiegley.  All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-- Redistributions of source code must retain the above copyright
-  notice, this list of conditions and the following disclaimer.
-
-- Redistributions in binary form must reproduce the above copyright
-  notice, this list of conditions and the following disclaimer in the
-  documentation and/or other materials provided with the distribution.
-
-- Neither the name of New Artisans LLC nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-@end copying
-
-@documentencoding UTF-8
-
-@iftex
-@finalout
-@end iftex
-
-@titlepage
-@title Ledger: Command-Line Accounting
-@author John Wiegley
-@end titlepage
-
-@direntry
-* Ledger: (ledger).           Command Line Accounting
-@end direntry
-
-@contents
-
-@ifnottex
-@node Top, Introduction, (dir), (dir)
-@top Overview
-
-@insertcopying
-@end ifnottex
-
-@menu
-* Introduction::                
-* Quick Reference::             
-* Ledger Tutorial::             
-* Ledger in Practice::          
-@end menu
-
-@ifnottex
-@section Copyright
-@insertcopying
-@end ifnottex
-
-@node Introduction, Quick Reference, Top, Top
-@chapter Introduction
-
-Ledger is an accounting tool with the moxie to exist.  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.
-
-What it does offer is a double-entry accounting ledger with all the
-flexibility and muscle of its modern day cousins, without any of the
-fat.  Think of it as the Bran Muffin of accounting tools.
-
-To use it, you need to start keeping a ledger.  This is the basis of
-all accounting, and if you haven't started yet, now is the time to
-learn.  The little booklet that comes with your checkbook is a ledger,
-so we'll describe double-entry accounting in terms of that.
-
-A checkbook ledger records debits (subtractions, or withdrawals) and
-credits (additions, or deposits) with reference to a single account:
-the checking account.  Where the money comes from, and where it goes
-to, are described in the payee field, where you write the person or
-company's name.  The ultimate aim of keeping a checkbook ledger is to
-know how much money is available to spend.  That's really the aim of
-all ledgers.
-
-What computers add is the ability to walk through these postings,
-and tell you things about your spending habits; to let you devise
-budgets and get control over your spending; to squirrel away money
-into virtual savings account without having to physically move money
-around; etc.  As you keep your ledger, you are recording information
-about your life and habits, and sometimes that information can start
-telling you things you aren't aware of.  Such is the aim of all good
-accounting tools.
-
-The next step up from a checkbook ledger, is a ledger that keeps track
-of all your accounts, not just checking.  In such a ledger, you record
-not only who gets paid---in the case of a debit---but where the money
-came from.  In a checkbook ledger, its assumed that all the money
-comes from your checking account.  But in a general ledger, you write
-posting two-lines: the source account and target account.
-@emph{There must always be a debit from at least one account for every
-credit made to another account}.  This is what is meant by
-``double-entry'' accounting: the ledger must always balance to zero,
-with an equal number of debits and credits.
-
-For example, let's say you have a checking account and a brokerage
-account, and you can write checks from both of them.  Rather than keep
-two checkbooks, you decide to use one ledger for both.  In this
-general ledger you need to record a payment to Pacific Bell for your
-monthly phone bill.  The cost is $23.00, let's say, and you want to
-pay it from your checking account.  In the general ledger you need to
-say where the money came from, in addition to where it's going to.
-Such a transaction might look like this:
-
-@smallexample
-9/29       Pacific Bell                $23.00     $23.00
-           Checking                   $-23.00          0
-@end smallexample
-
-The posting must balance to $0: $23 went to Pacific Bell, $23 came
-from Checking.  There is nothing left over to be accounted for, since
-the money has simply moved from one account to another.  This is the
-basis of double-entry accounting: that money never pops in or out of
-existence; it is always a posting from one account to another.
-
-Keeping a general ledger is the same as keeping two separate ledgers:
-One for Pacific Bell and one for Checking.  In that case, each time a
-payment is written into one, you write a corresponding withdrawal into
-the other.  This makes it easier to write in a ``running balance'',
-since you don't have to look back at the last time the account was
-referenced---but it also means having a lot of ledger books, if you
-deal with multiple accounts.
-
-Enter the beauty of computerized accounting.  The purpose of the
-Ledger program is to make general ledger accounting simple, by keeping
-track of the balances for you.  Your only job is to enter the
-postings.  If a posting does not balance, Ledger displays an
-error and indicates the incorrect posting.@footnote{In some
-special cases, it automatically balances this transaction for you.}
-
-In summary, there are two aspects of Ledger use: updating the ledger
-data file, and using the Ledger tool to view the summarized result of
-your transactions.
-
-And just for the sake of example---as a starting point for those who
-want to dive in head-first---here are the ledger transactions from above,
-formatting as the ledger program wishes to see them:
-
-@smallexample
-2004/09/29 Pacific Bell
-     Expenses:Pacific Bell              $23.00
-     Assets:Checking
-@end smallexample
-
-The account balances and registers in this file, if saved as
-@file{ledger.dat}, could be reported using:
-
-@example
-$ ledger -f ledger.dat balance
-$ ledger -f ledger.dat register checking
-$ ledger -f ledger.dat register bell
-@end example
-
-@section More introduction
-
-The most important part of accounting is keeping a good ledger.  If
-you have a good ledger, tools can be written to work whatever
-mathematically tricks you need to better understand your spending
-patterns.  Without a good ledger, no tool, however smart, can help
-you.
-
-The Ledger program aims at making ledger transaction as simple as possible.
-Since it is a command-line tool, it does not provide a user interface
-for keeping a ledger.  If you like, you may use GnuCash to maintain
-your ledger, in which case the Ledger program will read GnuCash's data
-files directly.  In that case, read the GnuCash manual now, and skip
-to the next chapter.
-
-If you are not using GnuCash, but a text editor to maintain your
-ledger, read on.  Ledger has been designed to make data transaction as
-simple as possible, by keeping the ledger format easy, and also by
-automagically determining as much information as possible based on the
-nature of your transactions.
-
-For example, you do not need to tell Ledger about the accounts you
-use.  Any time Ledger sees a posting involving an account it knows
-nothing about, it will create it.  If you use a commodity that is new
-to Ledger, it will create that commodity, and determine its display
-characteristics (placement of the symbol before or after the amount,
-display precision, etc) based on how you used the commodity in the
-posting.
-
-Here is the Pacific Bell example from above, given as a Ledger
-posting:
-
-@smallexample
-9/29 Pacific Bell
-    Expenses:Utilities:Phone                   $23.00
-    Assets:Checking                           $-23.00
-@end smallexample
-
-As you can see, it is very similar to what would be written on paper,
-minus the computed balance totals, and adding in account names that
-work better with Ledger's scheme of things.  In fact, since Ledger is
-smart about many things, you don't need to specify the balanced
-amount, if it is the same as the first line:
-
-@smallexample
-9/29 Pacific Bell
-    Expenses:Utilities:Phone                   $23.00
-    Assets:Checking
-@end smallexample
-
-For this transaction, Ledger will figure out that $-23.00 must come from
-@samp{Assets:Checking} in order to balance the transaction.
-
-@section Building the program
-
-Ledger is written in ANSI C++, and should compile on any platform.  It
-depends on the GNU multiprecision integer 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:
-
-@example
-./configure && make install
-@end example
-
-@section Getting help
-
-If you need help on how to use Ledger, or run into problems, you can
-just the Ledger mailing list at the following Web address:
-
-@example
-https://lists.sourceforge.net/lists/listinfo/ledger-discuss
-@end example
-
-You can also find help at the @samp{#ledger} channel on the IRC server
-@samp{irc.freenode.net}.
-
-@node Quick Reference, Ledger Tutorial, Introduction, Top
-@chapter Quick Reference
-
-This chapter describes ledger's features and serves as a quick
-reference. You may wish to survey this to get an overview before diving
-in to the @ref{Ledger Tutorial} and more detailed examples that follow.
-
-Ledger has a very simple command-line interface, named---enticing
-enough---@command{ledger}.  It supports a few reporting commands, and
-a large number of options for refining the output from those commands.
-The basic syntax of any ledger command is:
-
-@example
-ledger [OPTIONS...] COMMAND [ARGS...]
-@end example
-
-Command options must always precede the command word.  After the
-command word there may appear any number of arguments.  For most
-commands, these arguments are regular expressions that cause the
-output to relate only to postings matching those regular
-expressions.  For the @command{transaction} command, the arguments have a
-special meaning, described below.
-
-The regular expressions arguments always match the account name that a
-posting refers to.  To match on the payee of the transaction instead,
-precede the regular expression with @samp{--}.  For example, the
-following balance command reports account totals for rent, food and
-movies, but only those whose payee matches Freddie:
-
-@example
-ledger bal rent food movies -- freddie
-@end example
-
-There are many, many command options available with the
-@command{ledger} command, and it takes a while to master them.
-However, none of them are required to use the basic reporting
-commands.
-
-@menu
-* Commands::                    
-* Options::                     
-* Period expressions::          
-* Format strings::              
-* Value expressions::           
-* File format::                 
-@end menu
-
-@node Commands, Options, Quick Reference, Quick Reference
-@section Commands
-
-@subsection balance
-
-The @command{balance} command reports the current balance of all
-accounts.  It accepts a list of optional regexps, which confine the
-balance report to the matching accounts.  If an account contains
-multiple types of commodities, each commodity's total is reported
-separately.
-
-@subsection register
-
-The @command{register} command displays all the postings occurring
-in a single account, line by line.  The account regexp must be
-specified as the only argument to this command.  If any regexps occur
-after the required account name, the register will contain only those
-postings that match.  Very useful for hunting down a particular
-posting.
-
-The output from @command{register} is very close to what a typical
-checkbook, or single-account ledger, would look like.  It also shows a
-running balance.  The final running balance of any register should
-always be the same as the current balance of that account.
-
-If you have Gnuplot installed, you may plot the amount or running
-total of any register by using the script @file{report}, which is
-included in the Ledger distribution.  The only requirement is that you
-add either @option{-j} or @option{-J} to your register command, in
-order to plot either the amount or total column, respectively.
-
-@subsection print
-
-The @command{print} command prints out ledger transactions in a textual
-format that can be parsed by Ledger.  They will be properly formatted,
-and output in the most economic form possible.  The ``print'' command
-also takes a list of optional regexps, which will cause only those
-postings which match in some way to be printed.
-
-The @command{print} command can be a handy way to clean up a ledger
-file whose formatting has gotten out of hand.
-
-@subsection output
-
-The @command{output} command is very similar to the @command{print}
-command, except that it attempts to replicate the specified ledger
-file exactly.  The format of the command is:
-
-@example
-ledger -f FILENAME output FILENAME
-@end example
-
-Where @file{FILENAME} is the name of the ledger file to output.  The
-reason for specifying this command is that only transactions contained
-within that file will be output, and not an included transactions (as can
-happen with the @command{print} command).
-
-@subsection xml
-
-The @command{xml} command outputs results similar to what
-@command{print} and @command{register} display, but as an XML form.
-This data can then be read in and processed.  Use the
-@option{--totals} option to include the running total with each
-posting.
-
-@subsection emacs
-
-The @command{emacs} command outputs results in a form that can be read
-directly by Emacs Lisp.  The format of the sexp is:
-
-@example
-((BEG-POS CLEARED DATE CODE PAYEE
-  (ACCOUNT AMOUNT)...)  ; list of postings
- ...)                   ; list of transactions
-@end example
-
-@subsection equity
-
-The @command{equity} command prints out accounts balances as if they
-were transactions.  This makes it easy to establish the starting balances
-for an account, such as when @ref{Archiving previous years}.
-
-@subsection prices
-
-The @command{prices} command displays the price history for matching
-commodities.  The @option{-A} flag is useful with this report, to
-display the running average price, or @option{-D} to show each price's
-deviation from that average.
-
-There is also a @command{pricesdb} command which outputs the same
-information as @command{prices}, but does in a format that can be
-parsed by Ledger.
-
-@subsection xact
-
-The @command{xact} commands simplifies the creation of new transactions.
-It works on the principle that 80% of all postings are variants of
-earlier postings.  Here's how it works:
-
-Say you currently have this posting in your ledger file:
-
-@smallexample
-2004/03/15 * Viva Italiano
-    Expenses:Food                       $12.45
-    Expenses:Tips                        $2.55
-    Liabilities:MasterCard             $-15.00
-@end smallexample
-
-Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva
-Italiano} again.  The exact amounts are different, but the overall
-form is the same.  With the @command{xact} command you can type:
-
-@example
-ledger xact 2004/4/9 viva food 11 tips 2.50
-@end example
-
-This produces the following output:
-
-@smallexample
-2004/04/09 Viva Italiano
-    Expenses:Food                       $11.00
-    Expenses:Tips                        $2.50
-    Liabilities:MasterCard             $-13.50
-@end smallexample
-
-It works by finding a past posting matching the regular expression
-@samp{viva}, and assuming that any accounts or amounts specified will
-be similar to that earlier posting.  If Ledger does not succeed in
-generating a new transaction, an error is printed and the exit code is set
-to @samp{1}.
-
-There is a shell script in the distribution's @file{scripts} directory
-called @file{xact}, which simplifies the task of adding a new transaction
-to your ledger.  It launches @command{vi} to confirm that the transaction
-looks appropriate.
-
-Here are a few more examples of the @command{xact} command, assuming
-the above journal transaction:
-
-@example
-ledger xact 4/9 viva 11.50
-ledger xact 4/9 viva 11.50 checking # (from `checking')
-ledger xact 4/9 viva food 11.50 tips 8
-ledger xact 4/9 viva food 11.50 tips 8 cash
-ledger xact 4/9 viva food $11.50 tips $8 cash
-ledger xact 4/9 viva dining "DM 11.50"
-@end example
-
-@node Options, Period expressions, Commands, Quick Reference
-@section Options
-
-With all of the reports, command-line options are useful to modify the
-output generated.  These command-line options always occur before the
-command word.  This is done to distinguish options from exclusive
-regular expressions, which also begin with a dash.  The basic form for
-most commands is:
-
-@example
-ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
-@end example
-
-The @var{OPTIONS} and @var{REGEXPS} expressions are both optional.
-You could just use @samp{ledger balance}, without any options---which
-prints a summary of all accounts.  But for more specific reporting, or
-to change the appearance of the output, options are needed.
-
-@subsection Basic options
-
-These are the most basic command options.  Most likely, the user will
-want to set them using environment variables (see @ref{Options}),
-instead of using actual command-line options:
-
-@option{--help} (@option{-h}) prints a summary of all the options, and
-what they are used for.  This can be a handy way to remember which
-options do what.  This help screen is also printed if ledger is run
-without a command.
-
-@option{--version} (@option{-v}) prints 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.
-
-@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.
-This command may be used multiple times.
-Typically, the environment variable
-@env{LEDGER_FILE} is set, rather than using this command-line option.
-
-@option{--output FILE} (@option{-o FILE}) redirects output from any
-command to @var{FILE}.  By default, all output goes to standard
-output.
-
-@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by
-ledger before any other ledger file.  This file may not contain any
-postings, but it may contain option settings.  To specify options
-in the init file, use the same syntax as the command-line, but put each
-option on it's own line.  Here's an example init file:
-
-@smallexample
---price-db ~/finance/.pricedb
---cache /tmp/ledger-cache
-
-; ~/.ledgerrc ends here
-@end smallexample
-
-Option settings on the command-line or in the environment always take
-precedence over settings in the init file.
-
-@option{--cache FILE} identifies FILE as the default binary cache
-file.  That is, if the ledger files to be read are specified using the
-environment variable @env{LEDGER_FILE}, then whenever a command is
-finished a binary copy will be written to the specified cache, to
-speed up the loading time of subsequent queries.  This filename can
-also be given using the environment variable @env{LEDGER_CACHE}, or by
-putting the option into your init file.  The @option{--no-cache}
-option causes Ledger to always ignore the binary cache.
-
-@option{--account NAME} (@option{-a NAME}) specifies the default
-account which QIF file postings are assumed to relate to.
-
-@subsection Report filtering
-
-These options change which postings affect the outcome of a
-report, in ways other than just using regular expressions:
-
-@option{--current}(@option{-c}) displays only transactions occurring on or
-before the current date.
-
-@option{--begin DATE} (@option{-b DATE}) constrains the report to
-transactions on or after @var{DATE}.  Only transactions after that date will be
-calculated, which means that the running total in the balance report
-will always start at zero with the first matching transaction.  (Note: This
-is different from using @option{--display} to constrain what is
-displayed).
-
-@option{--end DATE} (@option{-e DATE}) constrains the report so that
-transactions on or after @var{DATE} are not considered.  The ending date
-is inclusive.
-
-@option{--period STR} (@option{-p STR}) sets the reporting period
-to @var{STR}.  This will subtotal all matching transactions within each
-period separately, making it easy to see weekly, monthly, quarterly,
-etc., posting totals.  A period string can even specify the
-beginning and end of the report range, using simple terms like ``last
-june'' or ``next month''.  For more using period expressions, see
-@ref{Period expressions}.
-
-@option{--period-sort EXPR} sorts 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 the top of each month:
-
-@example
-ledger -M --period-sort -At reg ^Expenses
-@end example
-
-@option{--cleared} (@option{-C}) displays only postings whose transaction
-has been marked ``cleared'' (by placing an asterix to the right of the
-date).
-
-@option{--uncleared} (@option{-U}) displays only postings whose
-transaction has not been marked ``cleared'' (i.e., if there is no asterix to
-the right of the date).
-
-@option{--real} (@option{-R}) displays only real postings, not
-virtual.  (A virtual posting is indicated by surrounding the
-account name with parentheses or brackets; see the section on using
-virtual postings for more information).
-
-@option{--actual} (@option{-L}) displays only actual postings, and
-not those created due to automated postings.
-
-@option{--related} (@option{-r}) displays postings that are
-related to whichever postings would otherwise have matched the
-filtering criteria.  In the register report, this shows where money
-went to, or the account it came from.  In the balance report, it shows
-all the accounts affected by transactions having a related posting.
-For example, if a file had this transaction:
-
-@smallexample
-2004/03/20 Safeway
-    Expenses:Food                       $65.00
-    Expenses:Cash                       $20.00
-    Assets:Checking                    $-85.00
-@end smallexample
-
-And the register command was:
-
-@example
-ledger -r register food
-@end example
-
-The following would be output, showing the postings related to the
-posting that matched:
-
-@smallexample
-2004/03/20 Safeway              Expenses:Cash               $-20.00      $-20.00
-                                Assets:Checking              $85.00       $65.00
-@end smallexample
-
-@option{--budget} is 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} is a related option that projects your budget into
-the future, showing how it will affect future balances.
-@xref{Budgeting and forecasting}.
-
-@option{--limit EXPR} (@option{-l EXPR}) limits which postings
-take part in the calculations of a report.
-
-@option{--amount EXPR} (@option{-t EXPR}) changes 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}.
-
-@option{--total EXPR} (@option{-T EXPR}) sets the value expression
-used for the ``totals'' column in the @command{register} and
-@command{balance} reports.
-
-@subsection Output customization
-
-These options affect only the output, but not which postings are
-used to create it:
-
-@option{--collapse} (@option{-n}) causes transactions in a
-@command{register} report with multiple postings to be collapsed
-into a single, subtotaled transaction.
-
-@option{--subtotal} (@option{-s}) causes all transactions in a
-@command{register} report to be collapsed into a single, subtotaled
-transaction.
-
-@option{--by-payee} (@option{-P}) reports subtotals by payee.
-
-@option{--comm-as-payee} (@option{-x}) changes the payee of every
-posting to be the commodity used in that posting.  This can be
-useful when combined with other options, such as @option{-s}.
-
-@option{--empty} (@option{-E}) includes even empty accounts in the
-@command{balance} report.
-
-@option{--weekly} (@option{-W}) reports 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}.  @option{--monthly}
-(@option{-M}) reports posting totals by month; @option{--yearly}
-(@option{-Y}) reports posting totals by year.  For more complex
-period, using the @option{--period} option described above.
-
-@option{--dow} reports postings totals for each day of the week.
-This is an easy way to see if weekend spending is more than on
-weekdays.
-
-@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
-the values determined using the value expression @var{EXPR}.  For
-example, using @option{-S -UT} in the 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}.
-
-@option{--wide} (@option{-w}) causes the default @command{register}
-report to assume 132 columns instead of 80.
-
-@option{--head} causes only the first N transactions to be printed.  This
-is different from using the command-line utility @command{head}, which
-would limit to the first N postings.  @option{--tail} outputs only
-the last N transactions.  Both options may be used 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).
-
-@option{--pager} tells 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.
-
-@option{--average} (@option{-A}) reports the average posting
-value.
-
-@option{--deviation} (@option{-D}) reports each posting's
-deviation from the average.  It is only meaningful in the
-@command{register} and @command{prices} reports.
-
-@option{--percentage} (@option{-%}) shows account subtotals in the
-@command{balance} report as percentages of the parent account.
-
-@option{--totals} include running total information in the
-@command{xml} report.
-
-@option{--amount-data} (@option{-j}) changes the @command{register}
-report so that it outputs 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.
-
-@option{--total-data} (@option{-J}) changes the @command{register}
-report so that it outputs nothing but the date and totals column,
-without commodities.
-
-@option{--display EXPR} (@option{-d EXPR}) limits which postings
-or accounts or actually displayed in a report.  They might still be
-calculated, and be part of the running total of a register report, for
-example, but they will not be displayed.  This is useful for seeing
-last month's checking postings, against a running balance which
-includes all posting values:
-
-@example
-ledger -d "d>=[last month]" reg checking
-@end example
-
-The output from this command is very different from the following,
-whose running total includes only postings from the last month
-onward:
-
-@example
-ledger -p "last month" reg checking
-@end example
-
-Which is more useful depends on what you're looking to know: the total
-amount for the reporting range (@option{-p}), or simply a display
-restricted to the reporting range (using @option{-d}).
-
-@option{--date-format STR} (@option{-y STR}) changes the basic date
-format used by reports.  The default uses a date like 2004/08/01,
-which represents the default date format of @samp{%Y/%m/%d}.  To
-change the way dates are printed in general, the easiest way is to put
-@option{--date-format FORMAT} in the Ledger initialization file
-@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).
-
-@option{--format STR} (@option{-F STR}) sets the reporting format for
-whatever report ledger is about to make.  @xref{Format strings}.
-There are also specific format commands for each report type:
-
-@itemize
-@item @option{--balance-format STR}
-@item @option{--register-format STR}
-@item @option{--print-format STR}
-@item @option{--plot-amount-format STR} (-j @command{register})
-@item @option{--plot-total-format STR} (-J @command{register})
-@item @option{--equity-format STR}
-@item @option{--prices-format STR}
-@item @option{--wide-register-format STR} (-w @command{register})
-@end itemize
-
-@subsection Commodity reporting
-
-These options affect how commodity values are displayed:
-
-@option{--price-db FILE} sets 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 quotes for a specific, for
-example.  This is done by adding a line like the following:
-
-@example
-; Don't download quotes for the dollar, or timelog values
-N $
-N h
-@end example
-
-@option{--price-exp MINS} (@option{-L MINS}) sets the expected
-freshness of price quotes, in minutes.  That 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
-consulted again for a newer price.  Otherwise, the old price is still
-considered to be fresh enough.
-
-@option{--download} (@option{-Q}) causes quotes to be automagically
-downloaded, as needed, by running a script named @command{getquote}
-and expecting that script to return a value understood by ledger.  A
-sample implementation of a @command{getquote} script, implemented in
-Perl, is provided in the distribution.  Downloaded quote price are
-then appended to the price database, usually specified using the
-environment variable @env{LEDGER_PRICE_DB}.
-
-There are several different ways that ledger can report the totals it
-displays.  The most flexible way to adjust them is by using value
-expressions, and the @option{-t} and @option{-T} options.  However,
-there are also several ``default'' reports, which will satisfy most
-users basic reporting needs:
-
-@table @code
-@item -O, --quantity
-Reports commodity totals (this is the default)
-
-@item -B, --basis
-Reports the cost basis for all postings.
-
-@item -V, --market
-Reports the last known market value for all commodities.
-
-@item -G --gain
-Reports the net gain/loss for all commodities in the report that have
-a price history.
-@end table
-
-@subsection Environment variables
-
-Every option to ledger may be set using an environment variable.  If
-an option has a long name such @option{--this-option}, setting the
-environment variable @env{LEDGER_THIS_OPTION} will have the same
-affect as specifying that option on the command-line.  Options on the
-command-line always take precedence over environment variable
-settings, however.
-
-Note that you may also permanently specify option values by placing
-option settings in the file @file{~/.ledgerrc}, for example:
-
-@example
---cache /tmp/.mycache
---pager /bin/cat
-
-@end example
-
-@node Period expressions, Format strings, Options, Quick Reference
-@section Period expressions
-
-A period expression indicates a span of time, or a reporting interval,
-or both.  The full syntax is:
-
-@example
-[INTERVAL] [BEGIN] [END]
-@end example
-
-The optional @var{INTERVAL} part may be any one of:
-
-@example
-every day
-every week
-every monthly
-every quarter
-every year
-every N days     # N is any integer
-every N weeks
-every N months
-every N quarters
-every N years
-daily
-weekly
-biweekly
-monthly
-bimonthly
-quarterly
-yearly
-@end example
-
-After the interval, a begin time, end time, both or neither may be
-specified.  As for the begin time, it can be either of:
-
-@example
-from <SPEC>
-since <SPEC>
-@end example
-
-The end time can be either of:
-
-@example
-to <SPEC>
-until <SPEC>
-@end example
-
-Where @var{SPEC} can be any of:
-
-@example
-2004
-2004/10
-2004/10/1
-10/1
-october
-oct
-this week  # or day, month, quarter, year
-next week
-last week
-@end example
-
-The beginning and ending can be given at the same time, if it spans a
-single period.  In that case, just use @var{SPEC} by itself.  In that
-case, the period @samp{oct}, for example, will cover all the days in
-october.  The possible forms are:
-
-@example
-<SPEC>
-in <SPEC>
-@end example
-
-Here are a few examples of period expressions:
-
-@example
-monthly
-monthly in 2004
-weekly from oct
-weekly from last month
-from sep to oct
-from 10/1 to 10/5
-monthly until 2005
-from apr
-until nov
-last oct
-weekly last august
-@end example
-
-@node Format strings, Value expressions, Period expressions, Quick Reference
-@section Format strings
-
-Format strings may be used to change the output format of reports.
-They are specified by passing a formatting string to the
-@option{--format} (@option{-F}) option.  Within that string,
-constructs are allowed which make it possible to display the various
-parts of an account or posting in custom ways.
-
-Within a format strings, a substitution is specified using a percent
-character (@samp{%}).  The basic format of all substitutions is:
-
-@example
-%[-][MIN WIDTH][.MAX WIDTH]EXPR
-@end example
-
-If the optional minus sign (@samp{-}) follows the percent character,
-whatever is substituted will be left justified.  The default is right
-justified.  If a minimum width is given next, the substituted text
-will be at least that wide, perhaps wider.  If a period and a maximum
-width is given, the substituted text will never be wider than this,
-and will be truncated to fit.  Here are some examples:
-
-@example
-%-P     a transaction's payee, left justified
-%20P    The same, right justified, at least 20 chars wide
-%.20P   The same, no more than 20 chars wide
-%-.20P  Left justified, maximum twenty chars wide
-@end example
-
-The expression following the format constraints can be a single
-letter, or an expression enclosed in parentheses or brackets.  The
-allowable expressions are:
-
-@table @code
-@item %
-Inserts a percent sign.
-
-@item t
-Inserts the results of the value expression specified by @option{-t}.
-If @option{-t} was not specified, the current report style's value
-expression is used.
-
-@item T
-Inserts the results of the value expression specified by @option{-T}.
-If @option{-T} was not specified, the current report style's value
-expression is used.
-
-@item |
-Inserts a single space.  This is useful if a width is specified, for
-inserting a certain number of spaces.
-
-@item _
-Inserts a space for each level of an account's depth.  That is, if an
-account has two parents, this construct will insert two spaces.  If a
-minimum width is specified, that much space is inserted for each level
-of depth.  Thus @samp{%5_}, for an account with four parents, will
-insert twenty spaces.
-
-@item (EXPR)
-Inserts the amount resulting from the value expression given in
-parentheses.  To insert five times the total value of an account, for
-example, one could say @samp{%12(5*O)}.  Note: It's important to put
-the five first in that expression, so that the commodity doesn't get
-stripped from the total.
-
-@item [DATEFMT]
-Inserts the result of formatting a posting's date with a date
-format string, exactly like those supported by @code{strftime}.  For
-example: @samp{%[%Y/%m/%d %H:%M:%S]}.
-
-@item S
-Insert the pathname of the file from which the transaction's data was read.
-
-@item B
-Inserts the beginning character position of that transaction within the file.
-
-@item b
-Inserts the beginning line of that transaction within the file.
-
-@item E
-Inserts the ending character position of that transaction within the file.
-
-@item e
-Inserts the ending line of that transaction within the file.
-
-@item D
-By default, this is the same as @samp{%[%Y/%m%/d]}.  The date format
-used can be changed at any time with the @option{-y} flag, however.
-Using @samp{%D} gives the user more control over the way dates are
-output.
-
-@item d
-This is the same as the @samp{%D} option, unless the transaction has an
-effective date, in which case it prints
-@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.
-
-@item X
-If a posting has been cleared, this inserts @samp{*} followed by a
-space; otherwise nothing is inserted.
-
-@item Y
-This is the same as @samp{%X}, except that it only displays a state
-character if all of the member postings have the same state.
-
-@item C
-Inserts the checking number for a transaction, in parentheses, followed by
-a space; if none was specified, nothing is inserted.
-
-@item P
-Inserts the payee related to a posting.
-
-@item a
-Inserts the optimal short name for an account.  This is normally used
-in balance reports.  It prints a parent account's name if that name
-has not been printed yet, otherwise it just prints the account's name.
-
-@item A
-Inserts the full name of an account.
-
-@item W
-This is the same as @samp{%A}, except that it first displays the
-posting's state @emph{if the transaction's posting states are not
-all the same}, followed by the full account name.  This is offered as
-a printing optimization, so that combined with @samp{%Y}, only the
-minimum amount of state detail is printed.
-
-@item o
-Inserts the ``optimized'' form of a posting's amount.  This is
-used by the print report.  In some cases, this inserts nothing; in
-others, it inserts the posting amount and its cost.  It's use is
-not recommend unless you are modifying the print report.
-
-@item n
-Inserts the note associated with a posting, preceded by two spaces
-and a semi-colon, if it exists.  Thus, no none becomes an empty
-string, while the note @samp{foo} is substituted as @samp{ ; foo}.
-
-@item N
-Inserts the note associated with a posting, if one exists.
-
-@item /
-The @samp{%/} construct is special.  It separates a format string
-between what is printed for the first posting of a transaction, and
-what is printed for all subsequent postings.  If not used, the
-same format string is used for all postings.
-@end table
-
-@node Value expressions, File format, Format strings, Quick Reference
-@section Value expressions
-
-Value expressions are an expression language used by Ledger to
-calculate values used by the program for many different purposes:
-
-@enumerate
-@item
-The values displayed in reports
-@item
-For predicates (where truth is anything non-zero), to determine which
-postings are calculated (@option{-l}) or displayed (@option{-d}).
-@item
-For sorting criteria, to yield the sort key.
-@item
-In the matching criteria used by automated postings.
-@end enumerate
-
-Value expressions support most simple math and logic operators, in
-addition to a set of one letter functions and variables.  A function's
-argument is whatever follows it.  The following is a display predicate
-that I use with the @command{balance} command:
-
-@example
-ledger -d /^Liabilities/?T<0:UT>100 balance
-@end example
-
-The effect is that account totals are displayed only if: 1) A
-Liabilities account has a total less than zero; or 2) the absolute
-value of the account's total exceeds 100 units of whatever commodity
-contains.  If it contains multiple commodities, only one of them must
-exceed 100 units.
-
-Display predicates are also very handy with register reports, to
-constrain which transactions are printed.  For example, the following
-command shows only transactions from the beginning of the current month,
-while still calculating the running balance based on all transactions:
-
-@example
-ledger -d "d>[this month]" register checking
-@end example
-
-This advantage to this command's complexity is that it prints the
-running total in terms of all transactions in the register.  The following,
-simpler command is similar, but totals only the displayed
-postings:
-
-@example
-ledger -b "this month" register checking
-@end example
-
-@subsection Variables
-
-Below are the one letter variables available in any value expression.
-For the register and print commands, these variables relate to
-individual postings, and sometimes the account affected by a
-posting.  For the balance command, these variables relate to
-accounts---often with a subtle difference in meaning.  The use of each
-variable for both is specified.
-
-@table @code
-@item t
-This maps to whatever the user specified with @option{-t}.  In a
-register report, @option{-t} changes the value column; in a balance
-report, it has no meaning by default.  If @option{-t} was not
-specified, the current report style's value expression is used.
-
-@item T
-This maps to whatever the user specified with @option{-T}.  In a
-register report, @option{-T} changes the totals column; in a balance
-report, this is the value given for each account.  If @option{-T} was
-not specified, the current report style's value expression is used.
-
-@item m
-This is always the present moment/date.
-@end table
-
-@subsubsection Posting/account details
-
-@table @code
-@item d
-A posting's date, as the number of seconds past the epoch.  This
-is always ``today'' for an account.
-
-@item a
-The posting's amount; the balance of an account, without
-considering children.
-
-@item b
-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,
-it's depth is one.
-
-@item n
-The index of a posting, or the count of postings affecting an
-account.
-
-@item X
-1 if a posting's transaction has been cleared, 0 otherwise.
-
-@item R
-1 if a posting is not virtual, 0 otherwise.
-
-@item Z
-1 if a posting is not automated, 0 otherwise.
-@end table
-
-@subsubsection Calculated totals
-
-@table @code
-@item O
-The total of all postings seen so far, or the total of an account
-and all its children.
-
-@item N
-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
-
-@subsection Functions
-
-The available one letter functions are:
-
-@table @code
-@item -
-Negates the argument.
-
-@item U
-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
-is given, then the current moment is used.
-@end table
-
-@subsection Operators
-
-The binary and ternary operators, in order of precedence, are:
-
-@enumerate
-@item @samp{* /}
-@item @samp{+ -}
-@item @samp{! < > =}
-@item @samp{& | ?:}
-@end enumerate
-
-@subsection Complex expressions
-
-More complicated expressions are possible using:
-
-@table @code
-@item NUM
-A plain integer represents a commodity-less amount.
-
-@item @{AMOUNT@}
-An amount in braces can be any kind of amount supported by ledger,
-with or without a commodity.  Use this for decimal values.
-
-@item /REGEXP/
-@item W/REGEXP/
-A regular expression that matches against an account's full name.  If
-a posting, this will match against the account affected by the
-posting.
-
-@item //REGEXP/
-@item p/REGEXP/
-A regular expression that matches against a transaction's payee name.
-
-@item ///REGEXP/
-@item w/REGEXP/
-A regular expression that matches against an account's base name.  If
-a posting, this will match against the account affected by the
-posting.
-
-@item c/REGEXP/
-A regular expression that matches against the transaction code (the text
-that occurs between parentheses before the payee name).
-
-@item e/REGEXP/
-A regular expression that matches against a posting's note, or
-comment field.
-
-@item (EXPR)
-A sub-expression is nested in parenthesis.  This can be useful passing
-more complicated arguments to functions, or for overriding the natural
-precedence order of operators.
-
-@item [DATE]
-Useful specifying a date in plain terms.  For example, you could say
-@samp{[2004/06/01]}.
-@end table
-
-@node File format,  , Value expressions, Quick Reference
-@section File format
-
-The ledger file format is quite simple, but also very flexible.  It
-supports many options, though typically the user can ignore most of
-them.  They are summarized below.
-
-The initial character of each line determines what the line means, and
-how it should be interpreted.  Allowable initial characters are:
-
-@table @code
-@item NUMBER
-A line beginning with a number denotes a transaction.  It may be followed
-by any number of lines, each beginning with whitespace, to denote the
-transaction's account postings.  The format of the first line is:
-
-@example
-DATE[=EDATE] [*|!] [(CODE)] DESC
-@end example
-
-If @samp{*} appears after the date (with optional effective date), it
-indicates the transaction is ``cleared'', which can mean whatever the user
-wants it to mean.  If @samp{!} appears after the date, it indicates d
-the transaction is ``pending''; i.e., tentatively cleared from the user's
-point of view, but not yet actually cleared.  If a @samp{CODE} appears
-in parentheses, it may be used to indicate a check number, or the type
-of the posting.  Following these is the payee, or a description of
-the posting.
-
-The format of each following posting is:
-
-@example
-  ACCOUNT  AMOUNT  [; NOTE]
-@end example
-
-Note that there must be at least two spaces between @samp{ACCOUNT} and
-@samp{AMOUNT}.  The @samp{ACCOUNT} may be surrounded by parentheses if it
-is a virtual posting or square brackets if it is a virtual posting that
-must balance.  The @samp{AMOUNT} can be followed by a per-unit
-posting cost, by specifying @samp{@@ AMOUNT}, or a complete
-posting cost with @samp{@@@@ AMOUNT}.  Lastly, the @samp{NOTE} may
-specify an actual and/or effective date for the posting by using
-the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
-@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
-
-@item =
-An automated transaction.  A value expression must appear after the equal
-sign.
-
-After this initial line there should be a set of one or more
-postings, just as if it were normal transaction.  If the amounts of the
-postings have no commodity, they will be applied as modifiers to
-whichever real posting is matched by the value expression.
-
-@item ~
-A period transaction.  A period expression must appear after the tilde.
-
-After this initial line there should be a set of one or more
-postings, just as if it were normal transaction.
-
-@item !
-A line beginning with an exclamation mark denotes a command directive.
-It must be immediately followed by the command word.  The supported
-commands are:
-
-@table @samp
-@item !include
-Include the stated ledger file.
-
-@item !account
-The account name is given is taken to be the parent of all
-postings that follow, until @samp{!end} is seen.
-
-@item !end
-Ends an account block.
-@end table
-
-@item ;
-A line beginning with a colon indicates a comment, and is ignored.
-
-@item Y
-If a line begins with a capital Y, it denotes the year used for all
-subsequent transactions that give a date without a year.  The year should
-appear immediately after the Y, for example: @samp{Y2004}.  This is
-useful at the beginning of a file, to specify the year for that file.
-If all transactions specify a year, however, this command has no effect.
-
-@item P
-Specifies a historical price for a commodity.  These are usually found
-in a pricing history file (see the @option{-Q} option).  The syntax
-is:
-@example
-P DATE SYMBOL PRICE
-@end example
-
-@item N SYMBOL
-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 ($).  It is recommended that
-these pricing options be set in the price database file, which
-defaults to @file{~/.pricedb}.  The syntax for this command is:
-@example
-N SYMBOL
-@end example
-
-@item D AMOUNT
-Specifies the default commodity to use, by specifying an amount in the
-expected format.  The @command{transaction} command will use this commodity
-as the default when none other can be determined.  This command may be
-used multiple times, to set the default flags for different
-commodities; whichever is seen last is used as the default commodity.
-For example, to set US dollars as the default commodity, while also
-setting the thousands flag and decimal flag for that commodity, use:
-@example
-D $1,000.00
-@end example
-
-@item C AMOUNT1 = AMOUNT2
-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:
-@example
-C 1.00 Kb = 1024 bytes
-@end example
-
-@item i, o, b, h
-These four relate to timeclock support, which permits ledger to read
-timelog files.  See the timeclock's documentation for more info on the
-syntax of its timelog files.
-@end table
-
-@node Ledger Tutorial, Ledger in Practice, Quick Reference, Top
-@chapter Ledger Tutorial
-
-This chapter presents a series of recipes, gradually introducing all of
-the command-line features of Ledger.
-
-For the purpose of these examples, assume the environment variable
-@var{LEDGER} is set to the file @file{sample.dat} (which is included
-in the distribution), and that the contents of that file are:
-
-@smallexample
-= /^Expenses:Books/
-  (Liabilities:Taxes)             -0.10
-
-~ Monthly
-  Assets:Bank:Checking          $500.00
-  Income:Salary
-
-2004/05/01 * Checking balance
-  Assets:Bank:Checking        $1,000.00
-  Equity:Opening Balances
-
-2004/05/01 * Investment balance
-  Assets:Brokerage              50 AAPL @@ $30.00
-  Equity:Opening Balances
-
-2004/05/14 * Pay day
-  Assets:Bank:Checking          $500.00
-  Income:Salary
-
-2004/05/27 Book Store
-  Expenses:Books                 $20.00
-  Liabilities:MasterCard
-
-2004/05/27 (100) Credit card company
-  Liabilities:MasterCard         $20.00
-  Assets:Bank:Checking
-@end smallexample
-
-This sample file demonstrates a basic principle of accounting which it
-is recommended you follow: Keep all of your accounts under five parent
-Assets, Liabilities, Income, Expenses and Equity.  It is important to
-do so in order to make sense out of the following examples.
-
-@section Checking balances
-
-Ledger has seven basic commands, but by far the most often used are
-@command{balance} and @command{register}.  To see a summary balance of
-all accounts, use:
-
-@example
-ledger bal
-@end example
-
-@command{bal} is a short-hand for @command{balance}.  This command
-prints out the summary totals of the five parent accounts used in
-@file{sample.dat}:
-
-@smallexample
-           $1,480.00
-             50 AAPL  Assets
-          $-2,500.00  Equity
-              $20.00  Expenses
-            $-500.00  Income
-              $-2.00  Liabilities
---------------------
-          $-1,502.00
-             50 AAPL    
-@end smallexample
-
-None of the child accounts are shown, just the parent account totals.
-We can see that in @samp{Assets} there is $1,480.00, and 50 shares of
-Apple stock.  There is also a negative grand total.  Usually the grand
-total is zero, which means that all accounts balance@footnote{It is
-impossible for accounts not to balance in ledger; it reports an error
-if a posting does not balance}.  In this case, since the 50 shares
-of Apple stock cost $1,500.00 dollars, then these two amounts balance
-each other in the grand total.  The extra $2.00 comes from a virtual
-posting being added by the automatic transaction at the top of the file.
-The transaction is virtual because the account name was surrounded by
-parentheses in an automatic transaction.  Automatic transactions will be
-discussed later, but first let's remove the virtual posting from
-the balance report by using the @option{--real} option:
-
-@example
-ledger --real bal
-@end example
-
-Now the report is:
-
-@smallexample
-           $1,480.00
-             50 AAPL  Assets
-          $-2,500.00  Equity
-              $20.00  Expenses
-            $-500.00  Income
---------------------
-          $-1,500.00
-             50 AAPL    
-@end smallexample
-
-Since the liability was a virtual posting, it has dropped from the
-report and we see that the final total is balanced.
-
-But we only know that it balances because @file{sample.dat} is quite
-simple, and we happen to know that the 50 shares of Apple stock cost
-$1,500.00.  We can verify that things really balance by reporting the
-Apple shares in terms of their cost, instead of their quantity.  To do
-this requires the @option{--basis}, or @option{-B}, option:
-
-@example
-ledger --real -B bal
-@end example
-
-This command reports:
-
-@smallexample
-           $2,980.00  Assets
-          $-2,500.00  Equity
-              $20.00  Expenses
-            $-500.00  Income
-@end smallexample
-
-With the basis cost option, the grand total has disappeared, as it is
-now zero.  The confirms that the cost of everything balances to zero,
-@emph{which must always be true}.  Reporting the real basis cost
-should never yield a remainder@footnote{If it ever does, then
-generated postings are involved, which can be removed using
-@option{--actual}}.
-
-@subsection Sub-account balances
-
-The totals reported by the balance command are only the topmost parent
-accounts.  To see the totals of all child accounts as well, use the
-@option{-s} option:
-
-@example
-ledger --real -B -s bal
-@end example
-
-This reports:
-
-@smallexample
-           $2,980.00  Assets
-           $1,480.00    Bank:Checking
-           $1,500.00    Brokerage
-          $-2,500.00  Equity:Opening Balances
-              $20.00  Expenses:Books
-            $-500.00  Income:Salary
-@end smallexample
-
-This shows that the @samp{Assets} total is made up from two child
-accounts, but that the total for each of the other accounts comes from
-one child account.
-
-Sometimes you may have a lot of children, nested very deeply, but only
-want to report the first two levels.  This can be done with a display
-predicate, using a value expression.  In the value expression,
-@code{T} represents the reported total, and @code{l} is the display
-level for the account:
-
-@example
-ledger --real -B -d "T&l<=2" bal
-@end example
-
-This reports:
-
-@smallexample
-           $2,980.00  Assets
-           $1,480.00    Bank
-           $1,500.00    Brokerage
-          $-2,500.00  Equity:Opening Balances
-              $20.00  Expenses:Books
-            $-500.00  Income:Salary
-@end smallexample
-
-Instead of reporting @samp{Bank:Checking} as a child of @samp{Assets},
-it report only @samp{Bank}, since that account is a nesting level of
-2, while @samp{Checking} is at level 3.
-
-To review the display predicate used---@code{T&l<=2}---this rather
-terse expression means: Display an account only if it has a non-zero
-total (@code{T}), and its nesting level is less than or equal to 2
-(@code{l<=2}).
-
-@subsection Specific account balances
-
-While reporting the totals for all accounts can be useful, most often
-you will want to check the balance of a specific account or accounts.
-To do this, put one or more account names after the balance command.
-Since these names are really regular expressions, you can use partial
-names if you wish:
-
-@example
-ledger bal checking
-@end example
-
-Reports:
-
-@smallexample
-           $1,480.00  Assets:Bank:Checking
-@end smallexample
-
-Any number of names may be used:
-
-@example
-ledger bal checking broker liab
-@end example
-
-Reports:
-
-@smallexample
-           $1,480.00  Assets:Bank:Checking
-             50 AAPL  Assets:Brokerage
-              $-2.00  Liabilities
-@end smallexample
-
-In this case no grand total is reported, because you are asking for
-specific account balances.
-
-For those comfortable with regular expressions, any Perl regexp is
-allowed:
-
-@example
-ledger bal ^assets.*checking ^liab
-@end example
-
-Reports:
-
-@smallexample
-           $1,480.00  Assets:Bank:Checking
-              $-2.00  Liabilities:Taxes
-@end smallexample
-
-@section The register report
-
-While the @command{balance} command can be very handy for checking
-account totals, by far the most powerful of Ledger's reporting tools
-is the @command{register} command.  In fact, internally both commands
-use the same logic, but report the results differently:
-@command{balance} shows the summary totals, while @command{register}
-reports each posting and how it contributes to that total.
-
-Paradoxically, the most basic form of @command{register} is almost
-never used, since it displays every posting:
-
-@example
-ledger reg
-@end example
-
-@command{reg} is a short-hand for @command{register}.  This command
-reports:
-
-@smallexample
-2004/05/01 Checking balance     Assets:Bank:Checking      $1,000.00    $1,000.00
-                                Equity:Opening Balan..   $-1,000.00            0
-2004/05/01 Investment balance   Assets:Brokerage            50 AAPL      50 AAPL
-                                Equity:Opening Balan..   $-1,500.00   $-1,500.00
-                                                                         50 AAPL
-2004/05/14 Pay day              Assets:Bank:Checking        $500.00   $-1,000.00
-                                                                         50 AAPL
-                                Income:Salary              $-500.00   $-1,500.00
-                                                                         50 AAPL
-2004/05/27 Book Store           Expenses:Books               $20.00   $-1,480.00
-                                                                         50 AAPL
-                                Liabilities:MasterCard      $-20.00   $-1,500.00
-                                                                         50 AAPL
-                                (Liabilities:Taxes)          $-2.00   $-1,502.00
-                                                                         50 AAPL
-2004/05/27 Credit card company  Liabilities:MasterCard       $20.00   $-1,482.00
-                                                                         50 AAPL
-                                Assets:Bank:Checking        $-20.00   $-1,502.00
-                                                                         50 AAPL
-@end smallexample
-
-This rather verbose output shows every account posting in
-@file{sample.dat}, and how it affects the running total.  The final
-total is identical to what we saw with the plain @command{balance}
-command.  To see how things really balance, we can use @samp{--real
--B}, just as we did with @command{balance}:
-
-@example
-ledger --real -B reg
-@end example
-
-Reports:
-
-@smallexample
-2004/05/01 Checking balance     Assets:Bank:Checking      $1,000.00    $1,000.00
-                                Equity:Opening Balan..   $-1,000.00            0
-2004/05/01 Investment balance   Assets:Brokerage          $1,500.00    $1,500.00
-                                Equity:Opening Balan..   $-1,500.00            0
-2004/05/14 Pay day              Assets:Bank:Checking        $500.00      $500.00
-                                Income:Salary              $-500.00            0
-2004/05/27 Book Store           Expenses:Books               $20.00       $20.00
-                                Liabilities:MasterCard      $-20.00            0
-2004/05/27 Credit card company  Liabilities:MasterCard       $20.00       $20.00
-                                Assets:Bank:Checking        $-20.00            0
-@end smallexample
-
-Here we see that everything balances to zero in the end, as it must.
-
-@subsection Specific register queries
-
-The most common use of the register command is to summarize
-postings based on the account(s) they affect.  Using
-@file{sample.dat} as as example, we could look at all book purchases
-using:
-
-@example
-ledger reg books
-@end example
-
-Reports:
-
-@smallexample
-2004/05/29 Book Store           Expenses:Books               $20.00       $20.00
-@end smallexample
-
-If a double-dash (@samp{--}) occurs in the list of regular
-expressions, any following arguments are matched against payee names,
-instead of account names:
-
-@example
-ledger reg ^liab -- credit
-@end example
-
-Reports:
-
-@smallexample
-2004/05/29 Credit card company  Liabilities:MasterCard       $20.00       $20.00
-@end smallexample
-
-There are many reporting options for tailoring which postings are
-found, and also how to summarize the various amounts and totals that
-result.  These are plumbed in greater depth below.
-
-@section Selecting postings
-
-Although the easiest way to use the register is to report all the
-postings affecting a set of accounts, it can often result in more
-information than you want.  To cope with an ever-growing amount of
-data, there are several options which can help you pinpoint your
-report to include just the postings that interest you most.  This is
-called the ``calculation'' phase of Ledger.  All of its related
-options are documented under @option{--help-calc}.
-
-@subsection By date
-
-@c  -c, --current          show only current and past transactions (not future)
-
-@option{--current}(@option{-c}) displays transactions occurring on or
-before the current date.  Any transaction recorded for a future date will be
-ignored, as if it had not been seen.  This is useful if you happen to
-pre-record transactions, but still wish to view your balances in terms of
-what is available today.
-
-@c  -b, --begin DATE       set report begin date
-@c  -e, --end DATE         set report end date
-
-@option{--begin DATE} (@option{-b DATE}) limits the report to only
-those transactions occurring on or after @var{DATE}.  The running total in
-the register will start at zero with the first posting, even if
-there are earlier transactions.
-
-To limit the display only, but still add earlier postings to the
-running total, use the display expression @samp{-d 'd>=[DATE]'}):
-
-@example
-ledger --basis -b may -d 'd>=[5/14]' reg ^assets
-@end example
-
-Reports:
-
-@smallexample
-2004/05/14 Pay day              Assets:Bank:Checking        $500.00    $3,000.00
-2004/05/27 Credit card company  Assets:Bank:Checking        $-20.00    $2,980.00
-@end smallexample
-
-In this example, the displayed postings start from @samp{5/14},
-but the calculated total starts from the beginning of @samp{may}.
-
-@option{--end DATE} (@option{-e DATE}) states when reporting should
-end, both calculation and display.  The ending date is inclusive.
-
-The @var{DATE} argument to the @option{-b} and @option{-e} options can
-be rather flexible.  Assuming the current date to be November 15,
-2004, then all of the following are equivalent:
-
-@example
-ledger -b oct bal
-ledger -b "this oct" bal
-ledger -b 2004/10 bal
-ledger -b 10 bal
-ledger -b last bal
-ledger -b "last month" bal
-@end example
-
-@c  -p, --period STR       report using the given period
-@c      --period-sort EXPR sort each report period's transactions by EXPR
-
-To constrain the report to a specific time period, use
-@option{--period} (@option{-p}).  A time period may have both a
-beginning and an end, or neither, as well as a specified interval.
-Here are a few examples:
-
-@example
-ledger -p 2004 bal
-ledger -p august bal
-ledger -p "from aug to oct" bal
-ledger -p "daily from 8/1 to 8/15" bal
-ledger -p "weekly since august" bal
-ledger -p "monthly from feb to oct" bal
-ledger -p "quarterly in 2004" bal
-ledger -p yearly bal
-@end example
-
-See @ref{Period expressions} for more on syntax.  Also, all of the
-options @option{-b}, @option{-e} and @option{-p} may be used together,
-but whatever information occurs last takes priority.  An example of
-such usage (in a script, perhaps) would be:
-
-@example
-ledger -b 2004 -e 2005 -p monthly reg ^expenses
-@end example
-
-This command is identical to:
-
-@example
-ledger -p "monthly in 2004" reg ^expenses
-@end example
-
-The postings within a period may be sorted using
-@option{--period-sort}, which takes a value expression.  This is
-similar to the @option{--sort} option, except that it sorts within
-each period transaction, rather than sorting all postings in the report.
-See the documentation on @option{--sort} below for more details.
-
-@subsection By status
-
-By default, all regular postings are included in each report.  To
-limit the report to certain kinds of postings, use one or more of
-the following options:
-
-@table @option
-@item -C, --cleared
-Consider only cleared postings.
-@item -U, --uncleared
-Consider only uncleared and pending postings.
-@item -R, --real
-Consider only real (non-virtual) postings.
-@item -L, --actual
-Consider only actual (non-automated) postings.
-@end table
-
-Cleared postings are indicated by an asterix placed just before
-the payee name in a posting.  The meaning of this flag is up to
-the user, but typically it means that a transaction has been seen on a
-financial statement.  Pending postings use an exclamation mark in
-the same position, but are mainly used only by reconciling software.
-Uncleared postings are for things like uncashed checks, credit
-charges that haven't appeared on a statement yet, etc.
-
-Real postings are all non-virtual postings, where the account
-name is not surrounded by parentheses or square brackets.  Virtual
-postings are useful for showing a transfer of money that never
-really happened, like money set aside for savings without actually
-transferring it from the parent account.
-
-Actual postings are those not generated, either as part of an
-automated transaction, or a budget or forecast report.  A useful of when you
-might like to filter out generated postings is with a budget:
-
-@example
-ledger --budget --actual reg ^expenses
-@end example
-
-This command outputs all postings affecting a budgeted account,
-but without subtracting the budget amount (because the generated
-postings are suppressed with @option{--actual}).  The report shows
-how much you actually spent on budgeted items.
-
-@subsection By relationship
-
-@c  -r, --related          calculate report using related postings
-
-Normally, a register report includes only the postings that match
-the regular expressions specified after the command word.  For
-example, to report all expenses:
-
-@example
-ledger reg ^expenses
-@end example
-
-This reports:
-
-@smallexample
-2004/05/29 Book Store           Expenses:Books               $20.00       $20.00
-@end smallexample
-
-Using @option{--related} (@option{-r}) reports the postings that
-did not match your query, but only in transactions that otherwise would
-have matched.  This has the effect of indicating where money came
-from, or when to:
-
-@example
-ledger -r reg ^expenses
-@end example
-
-Reports:
-
-@smallexample
-2004/05/29 Book Store           Liabilities:MasterCard       $20.00       $20.00
-@end smallexample
-
-@subsection By budget
-
-@c      --budget           generate budget transactions based on FILE
-
-There is more information about budgeting and forecasting in
-@ref{Budgeting and forecasting}.  Basically, if you have any period
-transactions in your ledger file, you can use these options.  A period
-transaction looks like:
-
-@example
-~ Monthly
-  Assets:Bank:Checking         $500.00
-  Income:Salary
-@end example
-
-The difference from a regular transaction is that the first line begins with
-a tilde (~), and instead of a payee there's a period expression
-(@ref{Period expressions}).  Otherwise, a period transaction is in every
-other way the same as a regular transaction.
-
-With such a transaction in your ledger file, the @option{--budget} option
-will report only postings that match a budgeted account.  Using
-@file{sample.dat} from above:
-
-@example
-ledger --budget reg ^income
-@end example
-
-Reports:
-
-@smallexample
-2004/05/01 Budget transaction         Income:Salary               $500.00      $500.00
-2004/05/14 Pay day              Income:Salary              $-500.00            0
-@end smallexample
-
-The final total is zero, indicating that the budget matched exactly
-for the reported period.  Budgeting is most often helpful with period
-reporting; for example, to show monthly budget results use
-@option{--budget -p monthly}.
-
-@c      --add-budget       show all postings plus the budget
-@c      --unbudgeted       show only unbudgeted postings
-
-The @option{--add-budget} option reports all matching postings in
-addition to budget postings; while @option{--unbudgeted} shows
-only those that don't match a budgeted account.  To summarize:
-
-@table @option
-@item --budget
-Show postings matching budgeted accounts.
-@item --unbudgeted
-Show postings matching unbudgeted accounts.
-@item --add-budget
-Show both budgeted and unbudgeted postings together (i.e., add the
-generated budget postings to the regular report).
-@end table
-
-@c      --forecast EXPR    generate forecast transactions while EXPR is true
-
-A report with the @option{--forecast} option will add budgeted
-postings while the specified value expression is true.  For
-example:
-
-@example
-ledger --forecast 'd<[2005] reg ^income
-@end example
-
-Reports:
-
-@smallexample
-2004/05/14 Pay day              Income:Salary              $-500.00     $-500.00
-2004/12/01 Forecast transaction       Income:Salary              $-500.00   $-1,000.00
-2005/01/01 Forecast transaction       Income:Salary              $-500.00   $-1,500.00
-@end smallexample
-
-The date this report was made was November 5, 2004; the reason the
-first forecast transaction is in December is that forecast transactions are only
-added for the future, and they only stop after the value expression
-has matched at least once, which is why the January transaction appears.  A
-forecast report can be very useful for determining when money will run
-out in an account, or for projecting future cash flow:
-
-@example
-ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp
-@end example
-
-This reports balances projected income against projected expenses,
-showing the resulting total in yearly intervals until 2008.  For the
-case of @file{sample.dat}, which has no budgeted expenses, the result
-of the above command (in November 2004) is:
-
-@smallexample
-2004/01/01 - 2004/12/31         Income:Salary            $-1,000.00   $-1,000.00
-                                Expenses:Books               $20.00     $-980.00
-2005/01/01 - 2005/12/31         Income:Salary            $-6,000.00   $-6,980.00
-2006/01/01 - 2006/12/31         Income:Salary            $-6,000.00  $-12,980.00
-2007/01/01 - 2007/12/31         Income:Salary            $-6,000.00  $-18,980.00
-2008/01/01 - 2008/01/01         Income:Salary              $-500.00  $-19,480.00
-@end smallexample
-
-@subsection By value expression
-
-@c  -l, --limit EXPR       calculate only postings matching EXPR
-
-Value expressions can be quite complex, and are treated more fully in
-@ref{Value expressions}.  They can be used for limiting a report with
-@option{--limit} (@option{-l}).  The following command report income
-since august, but expenses since october:
-
-@example
-ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg
-@end example
-
-The basic form of this value expression is @samp{(A&B)|(A&B)}.  The
-@samp{A} in each part matches against an account name with
-@samp{/name/}, while each @samp{B} part compares the date of the
-posting (@samp{d}) with a specified month.  The resulting report
-will contain only postings which match the value expression.
-
-@c  -t, --amount EXPR      use EXPR to calculate the displayed amount
-@c  -T, --total EXPR       use EXPR to calculate the displayed total
-
-Another use of value expressions is to calculate the amount reported
-for each line of a register report, or for computing the subtotal of
-each account shown in a balance report.  This example divides each
-posting amount by two:
-
-@example
-ledger -t 'a/2' reg ^exp
-@end example
-
-The @option{-t} option doesn't affect the running total, only how the
-posting amount is displayed.  To change the running total, use
-@option{-T}.  In that case, you will likely want to use the total
-(@samp{O}) instead of the amount (@samp{a}):
-
-@example
-ledger -T 'O/2' reg ^exp
-@end example
-
-@section Massaging register output
-
-Even after filtering down your data to just the postings you're
-interested in, the default reporting method of one posting per
-line is often still too much.  To combat this complexity, it is
-possible to ask Ledger to report the details to you in many different
-forms, summarized in various ways.  This is the ``display'' phase of
-Ledger, and is documented under @option{--help-disp}.
-
-@subsection Summarizing
-
-@c  -n, --collapse         register: collapse transactions with multiple postings
-
-When multiple postings relate to a single transaction, they are reported
-as part of that transaction.  For example, in the case of @file{sample.dat}:
-
-@example
-ledger reg -- book
-@end example
-
-Reports:
-
-@smallexample
-2004/05/29 Book Store           Expenses:Books               $20.00       $20.00
-                                Liabilities:MasterCard      $-20.00            0
-                                (Liabilities:Taxes)          $-2.00       $-2.00
-@end smallexample
-
-All three postings are part of one transaction, and as such the transaction
-details are printed only once.  To report every transaction on a single
-line, use @option{-n} to collapse transactions with multiple postings:
-
-@example
-ledger -n reg -- book
-@end example
-
-Reports:
-
-@smallexample
-2004/05/29 Book Store           <Total>                      $-2.00       $-2.00
-@end smallexample
-
-In the balance report, @option{-n} causes the grand total not to be
-displayed at the bottom of the report.
-
-@c  -s, --subtotal         balance: show sub-accounts; other: show subtotals
-
-If an account occurs more than once in a report, it is possible to
-combine them all and report the total per-account, using @option{-s}.
-For example, this command:
-
-@example
-ledger -B reg ^assets
-@end example
-
-Reports:
-
-@smallexample
-2004/05/01 Checking balance     Assets:Bank:Checking      $1,000.00    $1,000.00
-2004/05/01 Investment balance   Assets:Brokerage          $1,500.00    $2,500.00
-2004/05/14 Pay day              Assets:Bank:Checking        $500.00    $3,000.00
-2004/05/27 Credit card company  Assets:Bank:Checking        $-20.00    $2,980.00
-@end smallexample
-
-But if the @option{-s} option is added, the result becomes:
-
-@smallexample
-2004/05/01 - 2004/05/29         Assets:Bank:Checking      $1,480.00    $1,480.00
-                                Assets:Brokerage          $1,500.00    $2,980.00
-@end smallexample
-
-When account subtotaling is used, only one transaction is printed, and the
-date and name reflect the range of the combined postings.
-
-@c  -P, --by-payee         show summarized totals by payee
-
-With @option{-P}, postings relating to the same payee are
-combined.  In this case, the date of the combined transaction is that of the
-latest posting.
-
-@c  -x, --comm-as-payee    set commodity name as the payee, for reporting
-
-@option{-x} changes the payee name for each posting to be the same
-as the commodity it uses.  This can be especially useful combined with
-other options, like @option{-P}.  For example:
-
-@example
-ledger -Px reg ^assets
-@end example
-
-Reports:
-
-@smallexample
-2004/05/29 $                    Assets:Bank:Checking      $1,480.00    $1,480.00
-2004/05/01 AAPL                 Assets:Brokerage            50 AAPL    $1,480.00
-                                                                         50 AAPL
-@end smallexample
-
-This reports shows the subtotal for each commodity held, and where it
-is located.  To see the basis cost, or initial investment, add
-@option{-B}.  Applied to the example above:
-
-@smallexample
-2004/05/29 $                    Assets:Bank:Checking      $1,480.00    $1,480.00
-2004/05/01 AAPL                 Assets:Brokerage          $1,500.00    $2,980.00
-@end smallexample
-
-@c  -E, --empty            balance: show accounts with zero balance
-
-The only other options which affect summarized totals is @option{-E},
-which works only in the balance report.  In this case, it shows
-matching accounts with a zero a balance, which are ordinarily
-excluded.  This can be useful to see all the accounts involved in a
-report, even if some have no total.
-
-@subsection Quick periods
-
-Although the @option{-p} option (also @option{--period}) is much more
-versatile, there are other options to make the most common period
-reports easier:
-
-@table @option
-@item -W, --weekly
-Show weekly sub-totals.  Same as @samp{-p weekly}.
-@item -M, --monthly
-Show monthly sub-totals.  Same as @samp{-p monthly}.
-@item -Y, --yearly
-Show yearly sub-totals.  Same as @samp{-p yearly}.
-@end table
-
-@c      --dow              show a days-of-the-week report
-
-There is one kind of period report that cannot be done with
-@option{-p}.  This is the @option{--dow}, or ``days of the week''
-report, which shows summarized totals for each day of the week.  The
-following examples shows a ``day of the week'' report of income and
-expenses:
-
-@example
-ledger --dow reg ^inc ^exp
-@end example
-
-Reports:
-
-@smallexample
-2004/05/27 Thursdays            Expenses:Books               $20.00       $20.00
-2004/05/14 Fridays              Income:Salary              $-500.00     $-480.00
-@end smallexample
-
-@subsection Ordering and width
-
-@c  -S, --sort EXPR        sort report according to the value expression EXPR
-
-The postings displayed in a report are shown in the same order as
-they appear in the ledger file.  To change the order and sort a
-report, use the @option{--sort} option.  @option{--sort} takes a value
-expression to determine the value to sort against, making it possible
-to sort according to complex criteria.  Here are some simple and
-useful examples:
-
-@example
-ledger --sort d reg ^exp    # sort by date
-ledger --sort t reg ^exp    # sort by amount total
-ledger --sort -t reg ^exp   # reverse sort by amount total
-ledger --sort Ut reg ^exp   # sort by abs amount total
-@end example
-
-For the balance report, you will want to use @samp{T} instead of
-@samp{t}:
-
-@example
-ledger --sort T reg ^exp    # sort by amount total
-ledger --sort -T reg ^exp   # reverse sort by amount total
-ledger --sort UT reg ^exp   # sort by abs amount total
-@end example
-
-The @option{--sort} options sorts all postings in a report.  If
-periods are used (such as @option{--monthly}), this can get somewhat
-confusing.  In that case, you'll probably want to sort within periods
-using @option{--period-sort} instead of @option{--sort}.
-
-@c  -w, --wide             for the default register report, use 132 columns
-
-And if the register seems too cramped, and you have a lot of screen
-real estate, you can use @option{-w} to format the report within 132
-acolumns, instead of 80.  You are more likely then to see full payee
-and account names, as well as properly formatted totals when
-long-named commodities are used.
-
-If you want only the first or last N transactions to be printed---which can
-be very useful for viewing the last 10 transactions in your checking
-account, while also showing the cumulative balance from all
-transactions---use the @option{--head} and/or @option{--tail} options.  The
-two options may be used simultaneously, for example:
-
-@example
-ledger --tail 20 reg checking
-@end example
-
-If the output from your command is very long, Ledger can output the
-data to a pager utility, such as @command{more} or @command{less}:
-
-@example
-ledger --pager /usr/bin/less reg checking
-@end example
-
-@subsection Averages and percentages
-
-@c  -A, --average          report average posting amount
-
-To see the running total changed to a running average, use
-@option{-A}.  The final posting's total will be the overall
-average of all displayed postings.  The works in conjunction with
-period reporting, so that you can see your monthly average expenses
-with:
-
-@example
-ledger -AM  reg ^expenses:food
-ledger -AMn reg ^expenses
-@end example
-
-This works in the balance report too:
-
-@example
-ledger -AM  bal ^expenses:food
-ledger -AMs bal ^expenses
-@end example
-
-@c  -D, --deviation        report deviation from the average
-
-The @option{-D} option changes the running average into a deviation
-from the running average.  This only makes sense in the register
-report, however.
-
-@example
-ledger -DM reg ^expenses:food
-@end example
-
-@c  -%, --percentage       report balance totals as a percentile of the parent
-
-In the balance report only, @option{-%} changes the reported totals
-into a percentage of the parent account.  This kind of report is
-confusing if negative amounts are involved, and doesn't work at all if
-multiple commodities occur in an account's history.  It has a somewhat
-limited usefulness, therefore, but in certain cases it can be handy,
-such as reviewing overall expenses:
-
-@example
-ledger -%s -S T bal ^expenses
-@end example
-
-@subsection Reporting total data
-
-@c      --totals           in the "xml" report, include running total
-
-Normally in the @command{xml} report, only posting amounts are
-printed.  To include the running total under a @samp{<total>} tag, use
-@option{--totals}.  This does not affect any other report.
-
-@c  -j, --amount-data      print only raw amount data (useful for scripting)
-@c  -J, --total-data       print only raw total data
-
-In the register report only, the output can be changed with
-@option{-j} to show only the date and the amount---without
-commodities.  This only makes sense if a single commodity appears in
-the report, but can be quite useful for scripting, or passing the data
-to Gnuplot.  To show only the date and running total, use @option{-J}.
-
-@subsection Display by value expression
-
-@c  -d, --display EXPR     display only postings matching EXPR
-
-With @option{-d} you can decide which postings (or accounts in the
-balance report) are displayed, according to a value expression.  The
-computed total is not affected, only the display.  This can be very
-useful for shortening a report without changing the running total:
-
-@example
-ledger -d 'd>=[last month]' reg checking
-@end example
-
-This command shows the checking account's register, beginning from
-last month, but with the running total reflecting the entire history
-of the account.
-
-@subsection Change report format
-
-@c  -y, --date-format STR  use STR as the date format (default: %Y/%m/%d)
-
-When dates are printed in any report, the default format is
-@samp{%Y/%m/%d}, which yields dates of the form @samp{YYYY/mm/dd}.
-This can be changed with @option{-y}, whose argument is a
-@code{strftime} string---see your system's C library documentation for
-the allowable codes.  Mostly you will want to use @samp{%Y}, @samp{%m}
-and @samp{%d}, in whatever combination is convenient for your locale.
-
-@c  -F, --format STR       use STR as the format; for each report type, use:
-@c      --balance-format      --register-format       --print-format
-@c      --plot-amount-format  --plot-total-format     --equity-format
-@c      --prices-format       --wide-register-format
-
-To change the format of the entire reported line, use @option{-F}.  It
-supports quite a large number of options, which are all documented in
-@ref{Format strings}.  In addition, each specific kind of report
-(except for @command{xml}) can be changed using one of the following
-options:
-
-@table @option
-@item --balance-format
-@command{balance} report.  Default:
-@smallexample
-%20T  %2_%-a\n
-@end smallexample
-
-@item --register-format
-@command{register} report.  Default:
-@smallexample
-%D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n
-@end smallexample
-
-@item --print-format
-@command{print} report.  Default:
-@smallexample
-%D  %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n
-@end smallexample
-
-@item --plot-amount-format
-@command{register} report when @option{-j} (plot amount) is used.  Default:
-@smallexample
-%D %(St)\n
-@end smallexample
-
-@item --plot-total-format
-@command{register} report when @option{-J} (plot total) is used.  Default:
-@smallexample
-%D %(ST)\n
-@end smallexample
-
-@item --equity-format
-@command{equity} report.  Default:
-@smallexample
-\n%D %Y%C%P\n    %-34W  %12o%n\n%/    %-34W  %12o%n\n
-@end smallexample
-
-@item --prices-format
-@command{prices} report.  Default:
-@smallexample
-\n%D %Y%C%P\n%/    %-34W  %12t\n
-@end smallexample
-
-@item --wide-register-format
-@command{register} report when @option{-w} (wide) is used.  Default:
-@smallexample
-%D  %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n
-@end smallexample
-@end table
-
-@section Standard queries
-
-If your ledger file uses the standard top-level accounts: Assets,
-Liabilities, Income, Expenses, Equity: then the following queries will
-enable you to generate some typical accounting reports from your data.
-
-Your @emph{net worth} can be determined by balancing assets against
-liabilities:
-
-@example
-ledger bal ^assets ^liab
-@end example
-
-By removing long-term investment and loan accounts, you can see your
-current net liquidity (or liquid net worth):
-
-@example
-ledger bal ^assets ^liab -retirement -brokerage -loan
-@end example
-
-Balancing expenses against income yields your @emph{cash flow}, or net
-profit/loss:
-
-@example
-ledger bal ^exp ^inc
-@end example
-
-In this case, if the number is positive it means you spent more than
-you earned during the report period.
-
-@c ----------------------------------------------------------------------
-
-The most often used command is the ``balance'' command:
-
-@example
-export LEDGER=/home/johnw/doc/ledger.dat
-ledger balance
-@end example
-
-Here I've set my Ledger environment variable to point to where my
-ledger file is hiding.  Thereafter, I needn't specify it again.
-
-@section Reporting balance totals
-
-The balance command prints out the summarized balances of all my
-top-level accounts, excluding sub-accounts.  In order to see the
-balances for a specific account, just specify a regular expression
-after the balance command:
-
-@example
-ledger balance expenses:food
-@end example
-
-This will show all the money that's been spent on food, since the
-beginning of the ledger.  For food spending just this month
-(September), use:
-
-@example
-ledger -p sep balance expenses:food
-@end example
-
-Or maybe you want to see all of your assets, in which case the -s
-(show sub-accounts) option comes in handy:
-
-@example
-ledger -s balance ^assets
-@end example
-
-To exclude a particular account, use a regular expression with a
-leading minus sign.  The following will show all expenses, but without
-food spending:
-
-@example
-ledger balance expenses -food
-@end example
-
-@section Reporting percentages
-
-There is no built-in way to report posting amounts or account
-balances in terms of percentages
-
-@node Ledger in Practice,  , Ledger Tutorial, Top
-@chapter Ledger in Practice
-
-@menu
-* Stating where money goes::    
-* Assets and Liabilities::      
-* Typical queries::             
-* Budgeting and forecasting::   
-* Commodities and Currencies::  
-* Accounts and Inventories::    
-* Understanding Equity::        
-* Dealing with Petty Cash::     
-* Working with multiple funds and accounts::  
-* Archiving previous years::    
-* Virtual postings::        
-* Automated postings::      
-* Using Emacs to Keep Your Ledger::  
-* Using GnuCash to Keep Your Ledger::  
-* Using timeclock to record billable time::  
-* Using XML::                   
-@end menu
-
-@node Stating where money goes, Assets and Liabilities, Ledger in Practice, Ledger in Practice
-@section Stating where money goes
-
-Accountants will talk of ``credits'' and ``debits'', but the meaning
-is often different from the layman's understanding.  To avoid
-confusion, Ledger uses only subtractions and additions, although the
-underlying intent is the same as standard accounting principles.
-
-Recall that every posting will involve two or more accounts.
-Money is transferred from one or more accounts to one or more other
-accounts.  To record the posting, an amount is @emph{subtracted}
-from the source accounts, and @emph{added} to the target accounts.
-
-In order to write a Ledger transaction correctly, you must determine where
-the money comes from and where it goes to.  For example, when you are
-paid a salary, you must add money to your bank account and also
-subtract it from an income account:
-
-@smallexample
-9/29  My Employer
-    Assets:Checking                           $500.00
-    Income:Salary                            $-500.00
-@end smallexample
-
-Why is the Income a negative figure?  When you look at the balance
-totals for your ledger, you may be surprised to see that Expenses are
-a positive figure, and Income is a negative figure.  It may take some
-getting used to, but to properly use a general ledger you must think
-in terms of how money moves.  Rather than Ledger ``fixing'' the minus
-signs, let's understand why they are there.
-
-When you earn money, the money has to come from somewhere.  Let's call
-that somewhere ``society''.  In order for society to give you an
-income, you must take money away (withdraw) from society in order to
-put it into (make a payment to) your bank.  When you then spend that
-money, it leaves your bank account (a withdrawal) and goes back to
-society (a payment).  This is why Income will appear negative---it
-reflects the money you have drawn from society---and why Expenses will
-be positive---it is the amount you've given back.  These additions and
-subtractions will always cancel each other out in the end, because you
-don't have the ability to create new money: it must always come from
-somewhere, and in the end must always leave.  This is the beginning of
-economy, after which the explanation gets terribly difficult.
-
-Based on that explanation, here's another way to look at your balance
-report: every negative figure means that that account or person or
-place has less money now than when you started your ledger; and every
-positive figure means that that account or person or place has more
-money now than when you started your ledger.  Make sense?
-
-@node Assets and Liabilities, Typical queries, Stating where money goes, Ledger in Practice
-@section Assets and Liabilities
-
-Assets are money that you have, and Liabilities are money that you
-owe.  ``Liabilities'' is just a more inclusive name for Debts.
-
-An Asset is typically increased by transferring money from an Income
-account, such as when you get paid.  Here is a typical transaction:
-
-@smallexample
-2004/09/29  My Employer
-    Assets:Checking               $500.00
-    Income:Salary
-@end smallexample
-
-Money, here, comes from an Income account belonging to ``My
-Employer'', and is transferred to your checking account.  The money is
-now yours, which makes it an Asset.
-
-Liabilities track money owed to others.  This can happen when you
-borrow money to buy something, or if you owe someone money.  Here is
-an example of increasing a MasterCard liability by spending money with
-it:
-
-@smallexample
-2004/09/30  Restaurant
-    Expenses:Dining                $25.00
-    Liabilities:MasterCard
-@end smallexample
-
-The Dining account balance now shows $25 spent on Dining, and a
-corresponding $25 owed on the MasterCard---and therefore shown as
-$-25.00.  The MasterCard liability shows up as negative because it
-offsets the value of your assets.
-
-The combined total of your Assets and Liabilities is your net worth.
-So to see your current net worth, use this command:
-
-@example
-ledger balance ^assets ^liabilities
-@end example
-
-Relatedly, your Income accounts show up negative, because they
-transfer money @emph{from} an account in order to increase your
-assets.  Your Expenses show up positive because that is where the
-money went to.  The combined total of Income and Expenses is your cash
-flow.  A positive cash flow means you are spending more than you make,
-since income is always a negative figure.  To see your current cash
-flow, use this command:
-
-@example
-ledger balance ^income ^expenses
-@end example
-
-Another common question to ask of your expenses is: How much do I
-spend each month on X?  Ledger provides a simple way of displaying
-monthly totals for any account.  Here is an example that summarizes
-your monthly automobile expenses:
-
-@example
-ledger -M register expenses:auto
-@end example
-
-This assumes, of course, that you use account names like
-@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.
-
-@subsection Tracking reimbursable expenses
-
-Sometimes you will want to spend money on behalf of someone else,
-which will eventually get repaid.  Since the money is still ``yours'',
-it is really an asset.  And since the expenditure was for someone
-else, you don't want it contaminating your Expenses reports.  You will
-need to keep an account for tracking reimbursements.
-
-This is fairly easy to do in ledger.  When spending the money, spend
-it @emph{to} your Assets:Reimbursements, using a different account for
-each person or business that you spend money for.  For example:
-
-@smallexample
-2004/09/29  Circuit City
-    Assets:Reimbursements:Company XYZ     $100.00
-    Liabilities:MasterCard
-@end smallexample
-
-This shows $100.00 spent on a MasterCard at Circuit City, with the
-expense was made on behalf of Company XYZ.  Later, when Company XYZ
-pays the amount back, the money will transfer from that reimbursement
-account back to a regular asset account:
-
-@smallexample
-2004/09/29  Company XYZ
-    Assets:Checking                       $100.00
-    Assets:Reimbursements:Company XYZ
-@end smallexample
-
-This deposits the money owed from Company XYZ into a checking account,
-presumably because they paid the amount back with a check.
-
-But what to do if you run your own business, and you want to keep
-track of expenses made on your own behalf, while still tracking
-everything in a single ledger file?  This is more complex, because you
-need to track two separate things: 1) The fact that the money should
-be reimbursed to you, and 2) What the expense account was, so that you
-can later determine where your company is spending its money.
-
-This kind of posting is best handled with mirrored postings in
-two different files, one for your personal accounts, and one for your
-company accounts.  But keeping them in one file involves the same
-kinds of postings, so those are what is shown here.  First, the
-personal transaction, which shows the need for reimbursement:
-
-@smallexample
-2004/09/29  Circuit City
-    Assets:Reimbursements:Company XYZ     $100.00
-    Liabilities:MasterCard
-@end smallexample
-
-This is the same as above, except that you own Company XYZ, and are
-keeping track of its expenses in the same ledger file.  This transaction
-should be immediately followed by an equivalent transaction, which shows the
-kind of expense, and also notes the fact that $100.00 is now payable
-to you:
-
-@smallexample
-2004/09/29  Circuit City
-    Company XYZ:Expenses:Computer:Software      $100.00
-    Company XYZ:Accounts Payable:Your Name
-@end smallexample
-
-This second transaction shows that Company XYZ has just spent $100.00 on
-software, and that this $100.00 came from Your Name, which must be
-paid back.
-
-These two transactions can also be merged, to make things a little clearer.
-Note that all amounts must be specified now:
-
-@smallexample
-2004/09/29  Circuit City
-    Assets:Reimbursements:Company XYZ         $100.00
-    Liabilities:MasterCard                   $-100.00
-    Company XYZ:Expenses:Computer:Software    $100.00
-    Company XYZ:Accounts Payable:Your Name   $-100.00
-@end smallexample
-
-To ``pay back'' the reimbursement, just reverse the order of
-everything, except this time drawing the money from a company asset,
-paying it to accounts payable, and then drawing it again from the
-reimbursement account, and paying it to your personal asset account.
-It's easier shown than said:
-
-@smallexample
-2004/10/15  Company XYZ
-    Assets:Checking                           $100.00
-    Assets:Reimbursements:Company XYZ        $-100.00
-    Company XYZ:Accounts Payable:Your Name    $100.00
-    Company XYZ:Assets:Checking              $-100.00
-@end smallexample
-
-And now the reimbursements account is paid off, accounts payable is
-paid off, and $100.00 has been effectively transferred from the
-company's checking account to your personal checking account.  The
-money simply ``waited''---in both @samp{Assets:Reimbursements:Company
-XYZ}, and @samp{Company XYZ:Accounts Payable:Your Name}---until such
-time as it could be paid off.
-
-The value of tracking expenses from both sides like that is that you
-do not contaminate your personal expense report with expenses made on
-behalf of others, while at the same time making it possible to
-generate accurate reports of your company's expenditures.  It is more
-verbose than just paying for things with your personal assets, but it
-gives you a very accurate information trail.
-
-The advantage to keep these doubled transactions together is that they
-always stay in sync.  The advantage to keeping them apart is that it
-clarifies the transfer's point of view.  To keep the postings in
-separate files, just separate the two transactions that were joined above.
-For example, for both the expense and the pay-back shown above, the
-following four transactions would be created.  Two in your personal ledger
-file:
-
-@smallexample
-2004/09/29  Circuit City
-    Assets:Reimbursements:Company XYZ     $100.00
-    Liabilities:MasterCard               $-100.00
-
-2004/10/15  Company XYZ
-    Assets:Checking                       $100.00
-    Assets:Reimbursements:Company XYZ    $-100.00
-@end smallexample
-
-And two in your company ledger file:
-
-@smallexample
-!account Company XYZ
-
-2004/09/29  Circuit City
-    Expenses:Computer:Software            $100.00
-    Accounts Payable:Your Name           $-100.00
-
-2004/10/15  Company XYZ
-    Accounts Payable:Your Name            $100.00
-    Assets:Checking                      $-100.00
-
-!end
-@end smallexample
-
-(Note: The @samp{!account} above means that all accounts mentioned in
-the file are children of that account.  In this case it means that all
-activity in the file relates to Company XYZ).
-
-After creating these transactions, you will always know that $100.00 was
-spent using your MasterCard on behalf of Company XYZ, and that Company
-XYZ spent the money on computer software and paid it back about two
-weeks later.
-
-@node Typical queries, Budgeting and forecasting, Assets and Liabilities, Ledger in Practice
-@section Typical queries
-
-A query such as the following shows all expenses since last
-October, sorted by total:
-
-@example
-ledger -b "last oct" -s -S T bal ^expenses
-@end example
-
-From left to right the options mean: Show transactions since October, 2003;
-show all sub-accounts; sort by the absolute value of the total; and
-report the balance for all expenses.
-
-@subsection Reporting monthly expenses
-
-The following query makes it easy to see monthly expenses, with each
-month's expenses sorted by the amount:
-
-@example
-ledger -M --period-sort t reg ^expenses
-@end example
-
-Now, you might wonder where the money came from to pay for these
-things.  To see that report, add @option{-r}, which shows the
-``related account'' postings:
-
-@example
-ledger -M --period-sort t -r reg ^expenses
-@end example
-
-But maybe this prints too much information.  You might just want to
-see how much you're spending with your MasterCard.  That kind of query
-requires the use of a display predicate, since the postings
-calculated must match @samp{^expenses}, while the postings
-displayed must match @samp{mastercard}.  The command would be:
-
-@example
-ledger -M -r -d /mastercard/ reg ^expenses
-@end example
-
-This query says: Report monthly subtotals; report the ``related
-account'' postings; display only related postings whose
-account matches @samp{mastercard}, and base the calculation on
-postings matching @samp{^expenses}.
-
-This works just as well for report the overall total, too:
-
-@example
-ledger -s -r -d /mastercard/ reg ^expenses
-@end example
-
-The @option{-s} option subtotals all postings, just as @option{-M}
-subtotaled by the month.  The running total in both cases is off,
-however, since a display expression is being used.
-
-@subsection Visualizing with Gnuplot
-
-If you have @command{Gnuplot} installed, you can graph any of the
-above register reports.  The script to do this is included in the
-ledger distribution, and is named @file{scripts/report}.  Install
-@file{report} anywhere along your @env{PATH}, and then use
-@command{report} instead of @command{ledger} when doing a register
-report.  The only thing to keep in mind is that you must specify
-@option{-j} or @option{-J} to indicate whether Gnuplot should plot the
-amount, or the running total.  For example, this command plots total
-monthly expenses made on your MasterCard.
-
-@example
-report -j -M -r -d /mastercard/ reg ^expenses
-@end example
-
-The @command{report} script is a very simple Bourne shell script, that
-passes a set of scripted commands to Gnuplot.  Feel free to modify the
-script to your liking, since you may prefer histograms to line plots,
-for example.
-
-@subsubsection Typical plots
-
-Here are some useful plots:
-
-@smallexample
-report -j -M reg ^expenses         # monthly expenses
-report -J reg checking             # checking account balance
-report -J reg ^income ^expenses    # cash flow report
-
-# net worth report, ignoring non-$ postings
-
-report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
-
-# net worth report starting last February.  the use of a display
-# predicate (-d) is needed, otherwise the balance will start at
-# zero, and thus the y-axis will not reflect the true balance
-
-report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
-@end smallexample
-
-The last report uses both a calculation predicate (@option{-l}) and a
-display predicate (@option{-d}).  The calculation predicates limits
-the report to postings whose amount is greater than $1 (which can
-only happen if the posting amount is in dollars).  The display
-predicate limits the transactions @emph{displayed} to just those since last
-February, even those transactions from before then will be computed as part
-of the balance.
-
-@node Budgeting and forecasting, Commodities and Currencies, Typical queries, Ledger in Practice
-@section Budgeting and forecasting
-
-@subsection Budgeting
-
-Keeping a budget allows you to pay closer attention to your income and
-expenses, by reporting how far your actual financial activity is from
-your expectations.
-
-To start keeping a budget, put some period transactions at the top of your
-ledger file.  A period transaction is almost identical to a regular transaction,
-except that it begins with a tilde and has a period expression in
-place of a payee.  For example:
-
-@smallexample
-~ Monthly
-  Expenses:Rent               $500.00
-  Expenses:Food               $450.00
-  Expenses:Auto:Gas           $120.00
-  Expenses:Insurance          $150.00
-  Expenses:Phone              $125.00
-  Expenses:Utilities          $100.00
-  Expenses:Movies              $50.00
-  Expenses                    $200.00  ; all other expenses
-  Assets
-
-~ Yearly
-  Expenses:Auto:Repair        $500.00
-  Assets
-@end smallexample
-
-These two period transactions give the usual monthly expenses, as well as
-one typical yearly expense.  For help on finding out what your average
-monthly expense is for any category, use a command like:
-
-@example
-ledger -p "this year" -MAs bal ^expenses
-@end example
-
-The reported totals are the current year's average for each account.
-
-Once these period transactions are defined, creating a budget report is as
-easy as adding @option{--budget} to the command-line.  For example, a
-typical monthly expense report would be:
-
-@example
-ledger -M reg ^exp
-@end example
-
-To see the same report balanced against your budget, use:
-
-@example
-ledger --budget -M reg ^exp
-@end example
-
-A budget report includes only those accounts that appear in the
-budget.  To see all expenses balanced against the budget, use
-@option{--add-budget}.  You can even see only the unbudgeted expenses
-using @option{--unbudgeted}:
-
-@example
-ledger --unbudgeted -M reg ^exp
-@end example
-
-You can also use these flags with the @command{balance} command.
-
-@subsection Forecasting
-
-Sometimes it's useful to know what your finances will look like in the
-future, such as determining when an account will reach zero.  Ledger
-makes this easy to do, using the same period transactions as are used for
-budgeting.  An example forecast report can be generated with:
-
-@example
-ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
-@end example
-
-This report continues outputting postings until the running total
-is greater than $-500.00.  A final posting is always output, to
-show you what the total afterwards would be.
-
-Forecasting can also be used with the balance report, but by date
-only, and not against the running total:
-
-@example
-ledger --forecast "d<[2010]" bal ^assets ^liabilities
-@end example
-
-@node Commodities and Currencies, Accounts and Inventories, Budgeting and forecasting, Ledger in Practice
-@section Commodities and Currencies
-
-Ledger makes no assumptions about the commodities you use; it only
-requires that you specify a commodity.  The commodity may be any
-non-numeric string that does not contain a period, comma, forward
-slash or at-sign.  It may appear before or after the amount, although
-it is assumed that symbols appearing before the amount refer to
-currencies, while non-joined symbols appearing after the amount refer
-to commodities.  Here are some valid currency and commodity
-specifiers:
-
-@example
-$20.00         ; currency: twenty US dollars
-40 AAPL        ; commodity: 40 shares of Apple stock
-60 DM          ; currency: 60 Deutsch Mark
-£50            ; currency: 50 British pounds
-50 EUR         ; currency: 50 Euros (or use appropriate symbol)
-@end example
-
-Ledger will examine the first use of any commodity to determine how
-that commodity should be printed on reports.  It pays attention to
-whether the name of commodity was separated from the amount, whether
-it came before or after, the precision used in specifying the amount,
-whether thousand marks were used, etc.  This is done so that printing
-the commodity looks the same as the way you use it.
-
-An account may contain multiple commodities, in which case it will
-have separate totals for each.  For example, if your brokerage account
-contains both cash, gold, and several stock quantities, the balance
-might look like:
-
-@smallexample
-  $200.00
-100.00 AU
-  AAPL 40
- BORL 100
- FEQTX 50  Assets:Brokerage
-@end smallexample
-
-This balance report shows how much of each commodity is in your
-brokerage account.
-
-Sometimes, you will want to know the current street value of your
-balance, and not the commodity totals.  For this to happen, you must
-specify what the current price is for each commodity.  The price can
-be any commodity, in which case the balance will be computed in terms
-of that commodity.  The usual way to specify prices is with a price
-history file, which might look like this:
-
-@smallexample
-P 2004/06/21 02:18:01 FEQTX $22.49
-P 2004/06/21 02:18:01 BORL $6.20
-P 2004/06/21 02:18:02 AAPL $32.91
-P 2004/06/21 02:18:02 AU $400.00
-@end smallexample
-
-Specify the price history to use with the @option{--price-db} option,
-with the @option{-V} option to report in terms of current market
-value:
-
-@example
-ledger --price-db prices.db -V balance brokerage
-@end example
-
-The balance for your brokerage account will be reported in US dollars,
-since the prices database uses that currency.
-
-@smallexample
-$40880.00  Assets:Brokerage
-@end smallexample
-
-You can convert from any commodity to any other commodity.  Let's say
-you had $5000 in your checking account, and for whatever reason you
-wanted to know many ounces of gold that would buy, in terms of the
-current price of gold:
-
-@example
-ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking
-@end example
-
-Although the total expression appears complex, it is simply saying
-that the reported total should be in multiples of AU units, where the
-quantity is the account total divided by the price of one AU.  Without
-the initial multiplication, the reported total would still use the
-dollars commodity, since multiplying or dividing amounts always keeps
-the left value's commodity.  The result of this command might be:
-
-@smallexample
-14.01 AU  Assets:Checking
-@end smallexample
-
-@subsection Commodity price histories
-
-Whenever a commodity is purchased using a different commodity (such as
-a share of common stock using dollars), it establishes a price for
-that commodity on that day.  It is also possible, by recording price
-details in a ledger file, to specify other prices for commodities at
-any given time.  Such price transactions might look like those below:
-
-@smallexample
-P 2004/06/21 02:17:58 TWCUX $27.76
-P 2004/06/21 02:17:59 AGTHX $25.41
-P 2004/06/21 02:18:00 OPTFX $39.31
-P 2004/06/21 02:18:01 FEQTX $22.49
-P 2004/06/21 02:18:02 AAPL $32.91
-@end smallexample
-
-By default, ledger will not consider commodity prices when generating
-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.
-
-@subsection Commodity equivalencies
-
-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.
-
-For example, you might have the following two postings, one which
-transfers an hour of time into a @samp{Billable} account, and another
-which decreases the same account by ten minutes.  The resulting report
-will indicate that fifty minutes remain:
-
-@smallexample
-2005/10/01 Work done for company
-    Billable:Client                 1h
-    Project:XYZ
-    
-2005/10/02 Return ten minutes to the project
-    Project:XYZ                    10m
-    Billable:Client
-@end smallexample
-
-Reporting the balance for this ledger file produces:
-
-@smallexample
-       50.0m  Billable:Client
-      -50.0m  Project:XYZ
-@end smallexample
-
-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,
-megabytes, and more:
-
-@smallexample
-C 1.00 Kb = 1024 b
-C 1.00 Mb = 1024 Kb
-C 1.00 Gb = 1024 Mb
-C 1.00 Tb = 1024 Gb
-@end smallexample
-
-Each of these definitions correlates a commodity (such as @samp{Kb})
-and a default precision, with a certain quantity of another commodity.
-In the above example, kilobytes are reporetd 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
-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
-the larger commodity is used.
-
-@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Ledger in Practice
-@section Accounts and Inventories
-
-Since Ledger's accounts and commodity system is so flexible, you can
-have accounts that don't really exist, and use commodities that no one
-else recognizes.  For example, let's say you are buying and selling
-various items in EverQuest, and want to keep track of them using a
-ledger.  Just add items of whatever quantity you wish into your
-EverQuest account:
-
-@smallexample
-9/29  Get some stuff at the Inn
-    Places:Black's Tavern                   -3 Apples
-    Places:Black's Tavern                   -5 Steaks
-    EverQuest:Inventory
-@end smallexample
-
-Now your EverQuest:Inventory has 3 apples and 5 steaks in it.  The
-amounts are negative, because you are taking @emph{from} Black's
-Tavern in order to add to your Inventory account.  Note that you don't
-have to use @samp{Places:Black's Tavern} as the source account.  You
-could use @samp{EverQuest:System} to represent the fact that you
-acquired them online.  The only purpose for choosing one kind of
-source account over another is for generate more informative reports
-later on.  The more you know, the better analysis you can perform.
-
-If you later sell some of these items to another player, the transaction
-would look like:
-
-@smallexample
-10/2  Sturm Brightblade
-    EverQuest:Inventory                     -2 Steaks
-    EverQuest:Inventory                     15 Gold
-@end smallexample
-
-Now you've turned 2 steaks into 15 gold, courtesy of your customer,
-Sturm Brightblade.
-
-@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Ledger in Practice
-@section Understanding Equity
-
-The most confusing transaction in any ledger will be your equity account---
-because starting balances can't come out of nowhere.
-
-When you first start your ledger, you will likely already have money
-in some of your accounts.  Let's say there's $100 in your checking
-account; then add a transaction to your ledger to reflect this amount.
-Where will money come from?  The answer: your equity.
-
-@smallexample
-10/2  Opening Balance
-    Assets:Checking                         $100.00
-    Equity:Opening Balances
-@end smallexample
-
-But what is equity?  You may have heard of equity when people talked
-about house mortgages, as ``the part of the house that you own''.
-Basically, equity is like the value of something.  If you own a car
-worth $5000, then you have $5000 in equity in that car.  In order to
-turn that car (a commodity) into a cash flow, or a credit to your bank
-account, you will have to debit the equity by selling it.
-
-When you start a ledger, you are probably already worth something.
-Your net worth is your current equity.  By transferring the money in
-the ledger from your equity to your bank accounts, you are crediting
-the ledger account based on your prior equity.  That is why, when you
-look at the balance report, you will see a large negative number for
-Equity that never changes: Because that is what you were worth (what
-you debited from yourself in order to start the ledger) before the
-money started moving around.  If the total positive value of your
-assets is greater than the absolute value of your starting equity, it
-means you are making money.
-
-Clear as mud?  Keep thinking about it.  Until you figure it out, put
-@samp{-Equity} at the end of your balance command, to remove the
-confusing figure from the total.
-
-@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Ledger in Practice
-@section Dealing with Petty Cash
-
-Something that stops many people from keeping a ledger at all is the
-insanity of tracking small cash expenses.  They rarely generate a
-receipt, and there are often a lot of small postings, rather than
-a few large ones, as with checks.
-
-One solution is: don't bother.  Move your spending to a debit card,
-but in general ignore cash.  Once you withdraw it from the ATM, mark
-it as already spent to an @samp{Expenses:Cash} category:
-
-@smallexample
-2004/03/15 ATM
-    Expenses:Cash                      $100.00
-    Assets:Checking
-@end smallexample
-
-If at some point you make a large cash expense that you want to track,
-just ``move'' the amount of the expense from @samp{Expenses:Cash} into
-the target account:
-
-@smallexample
-2004/03/20 Somebody
-    Expenses:Food                       $65.00
-    Expenses:Cash
-@end smallexample
-
-This way, you can still track large cash expenses, while ignoring all
-of the smaller ones.
-
-@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Ledger in Practice
-@section Working with multiple funds and accounts
-
-There are situations when the accounts you're tracking are different
-between your clients and the financial institutions where money is
-kept.  An example of this is working as the treasurer for a religious
-institution.  From the secular point of view, you might be working
-with three different accounts:
-
-@itemize
-@item Checking
-@item Savings
-@item Credit Card
-@end itemize
-
-From a religious point of view, the community expects to divide its
-resources into multiple ``funds'', from which it makes purchases or
-reserves resources for later:
-
-@itemize
-@item School fund
-@item Building fund
-@item Community fund
-@end itemize
-
-The problem with this kind of setup is that when you spend money, it
-comes from two or more places at once: the account and the fund.  And
-yet, the correlation of amounts between funds and accounts is rarely
-one-to-one.  What if the school fund has @samp{$500.00}, but
-@samp{$400.00} of that comes from Checking, and @samp{$100.00} from
-Savings?
-
-Traditional finance packages require that the money reside in only one
-place.  But there are really two ``views'' of the data: from the
-account point of view and from the fund point of view -- yet both sets
-should reflect the same overall expenses and cash flow.  It's simply
-where the money resides that differs.
-
-This situation can be handled one of two ways.  The first is using
-virtual postings to represent the fact that money is moving to and
-from two kind of accounts at the same time:
-
-@smallexample
-2004/03/20 Contributions
-    Assets:Checking                    $500.00
-    Income:Donations
-
-2004/03/25 Distribution of donations
-    [Funds:School]                     $300.00
-    [Funds:Building]                   $200.00
-    [Assets:Checking]                 $-500.00
-@end smallexample
-
-The use of square brackets in the second transaction ensures that the
-virtual postings balance to zero.  Now money can be spent directly
-from a fund at the same time as money is drawn from a physical
-account:
-
-@smallexample
-2004/03/25 Payment for books (paid from Checking)
-    Expenses:Books                    $100.00
-    Assets:Checking                  $-100.00
-    (Funds:School)                   $-100.00
-@end smallexample
-
-When reports are generated, by default they'll appear in terms of the
-funds.  In this case, you will likely want to mask out your
-@samp{Assets} account, because otherwise the balance won't make much
-sense:
-
-@example
-ledger bal -^Assets
-@end example
-
-If the @option{--real} option is used, the report will be in terms of
-the real accounts:
-
-@example
-ledger --real bal
-@end example
-
-If more asset accounts are needed as the source of a posting, just
-list them as you would normally, for example:
-
-@smallexample
-2004/03/25 Payment for books (paid from Checking)
-    Expenses:Books                    $100.00
-    Assets:Checking                   $-50.00
-    Liabilities:Credit Card           $-50.00
-    (Funds:School)                   $-100.00
-@end smallexample
-
-The second way of tracking funds is to use transaction codes.  In this
-respect the codes become like virtual accounts that embrace the entire
-set of postings.  Basically, we are associating a transaction with a
-fund by setting its code.  Here are two transactions that desposit money
-into, and spend money from, the @samp{Funds:School} fund:
-
-@smallexample
-2004/03/25 (Funds:School) Donations
-    Assets:Checking                   $100.00
-    Income:Donations
-
-2004/04/25 (Funds:School) Payment for books
-    Expenses:Books                     $50.00
-    Assets:Checking
-@end smallexample
-
-Note how the accounts now relate only to the real accounts, and any
-balance or registers reports will reflect this.  That the transactions
-relate to a particular fund is kept only in the code.
-
-How does this become a fund report?  By using the
-@option{--code-as-payee} option, you can generate a register report
-where the payee for each posting shows the code.  Alone, this is
-not terribly interesting; but when combined with the
-@option{--by-payee} option, you will now see account subtotals for any
-postings related to a specific fund.  So, to see the current
-monetary balances of all funds, the command would be:
-
-@smallexample
-ledger --code-as-payee -P reg ^Assets
-@end smallexample
-
-Or to see a particular funds expenses, the @samp{School} fund in this
-case:
-
-@smallexample
-ledger --code-as-payee -P reg ^Expenses -- School
-@end smallexample
-
-Both approaches yield different kinds of flexibility, depending on how
-you prefer to think of your funds: as virtual accounts, or as tags
-associated with particular transactions.  Your own tastes will decide which
-is best for your situation.
-
-@node Archiving previous years, Virtual postings, Working with multiple funds and accounts, Ledger in Practice
-@section Archiving previous years
-
-After a while, your ledger can get to be pretty large.  While this
-will not slow down the ledger program much---it's designed to process
-ledger files very quickly---things can start to feel ``messy''; and
-it's a universal complaint that when finances feel messy, people avoid
-them.
-
-Thus, archiving the data from previous years into their own files can
-offer a sense of completion, and freedom from the past.  But how to
-best accomplish this with the ledger program?  There are two commands
-that make it very simple: @command{print}, and @command{equity}.
-
-Let's take an example file, with data ranging from year 2000 until
-2004.  We want to archive years 2000 and 2001 to their own file,
-leaving just 2003 and 2004 in the current file.  So, use
-@command{print} to output all the earlier transactions to a file called
-@file{ledger-old.dat}:
-
-@smallexample
-ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat
-@end smallexample
-
-To delete older data from the current ledger file, use @command{print}
-again, this time specifying year 2002 as the starting date:
-
-@example
-ledger -f ledger.dat -b 2002 print > x
-mv x ledger.dat
-@end example
-
-However, now the current file contains @emph{only} postings from
-2002 onward, which will not yield accurate present-day balances,
-because the net income from previous years is no longer being tallied.
-To compensate for this, we must append an equity report for the old
-ledger at the beginning of the new one:
-
-@example
-ledger -f ledger-old.dat equity > equity.dat
-cat equity.dat ledger.dat > x
-mv x ledger.dat
-rm equity.dat
-@end example
-
-Now the balances reported from @file{ledger.dat} are identical to what
-they were before the data was split.
-
-How often should you split your ledger?  You never need to, if you
-don't want to.  Even eighty years of data will not slow down ledger
-much---and that's just using present day hardware!  Or, you can keep
-the previous and current year in one file, and each year before that
-in its own file.  It's really up to you, and how you want to organize
-your finances.  For those who also keep an accurate paper trail, it
-might be useful to archive the older years to their own files, then
-burn those files to a CD to keep with the paper records---along with
-any electronic statements received during the year.  In the arena of
-organization, just keep in mind this maxim: Do whatever keeps you
-doing it.
-
-@node Virtual postings, Automated postings, Archiving previous years, Ledger in Practice
-@section Virtual postings
-
-A virtual posting is when you, in your mind, see money as moving
-to a certain place, when in reality that money has not moved at all.
-There are several scenarios in which this type of tracking comes in
-handy, and each of them will be discussed in detail.
-
-To enter a virtual posting, surround the account name in
-parentheses.  This form of usage does not need to balance.  However,
-if you want to ensure the virtual posting balances with other
-virtual postings in the same transaction, use square brackets.  For
-example:
-
-@smallexample
-10/2 Paycheck
-    Assets:Checking                        $1000.00
-    Income:Salary                         $-1000.00
-    (Debt:Alimony)                          $200.00
-@end smallexample
-
-In this example, after receiving a paycheck an alimony debt is
-increased---even though no money has moved around yet.
-
-@smallexample
-10/2  Paycheck
-    Assets:Checking                        $1000.00
-    Income:Salary                         $-1000.00
-    [Savings:Trip]                          $200.00
-    [Assets:Checking]                      $-200.00
-@end smallexample
-
-In this example, $200 has been deducted from checking toward savings
-for a trip.  It will appear as though the money has been moved from
-the account into @samp{Savings:Trip}, although no money has actually
-moved anywhere.
-
-When balances are displayed, virtual postings will be factored in.
-To view balances without any virtual balances factored in, using the
-@option{-R} flag, for ``reality''.
-
-@node Automated postings, Using Emacs to Keep Your Ledger, Virtual postings, Ledger in Practice
-@section Automated postings
-
-As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets.
-It is similar to tithing for Jews and Christians, or to Zakát for
-Muslims.  The exact details of computing Huqúqu'lláh are somewhat
-complex, but if you have further interest, please consult the Web.
-
-Ledger makes this otherwise difficult law very easy.  Just set up an
-automated posting at the top of your ledger file:
-
-@smallexample
-; This automated transaction will compute Huqúqu'lláh based on this
-; journal's postings.  Any that match will affect the
-; Liabilities:Huququ'llah account by 19% of the value of that
-; posting.
-
-= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
-  (Liabilities:Huququ'llah)               0.19
-@end smallexample
-
-This automated posting works by looking at each posting in the
-ledger file.  If any match the given value expression, 19% of the
-posting's value is applied to the @samp{Liabilities:Huququ'llah}
-account.  So, if $1000 is earned from @samp{Income:Salary}, $190 is
-added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent,
-$190 is subtracted.  The ultimate balance of Huqúqu'lláh reflects how
-much is owed in order to fulfill one's obligation to Huqúqu'lláh.
-When ready to pay, just write a check to cover the amount shown in
-@samp{Liabilities:Huququ'llah}.  That transaction would look like:
-
-@smallexample
-2003/01/01 (101) Baha'i Huqúqu'lláh Trust
-    Liabilities:Huququ'llah          $1,000.00
-    Assets:Checking
-@end smallexample
-
-That's it.  To see how much Huqúq is currently owed based on your
-ledger transactions, use:
-
-@example
-ledger balance Liabilities:Huquq
-@end example
-
-This works fine, but omits one aspect of the law: that Huquq is only
-due once the liability exceeds the value of 19 mithqáls of gold (which
-is roughly 2.22 ounces).  So what we want is for the liability to
-appear in the balance report only when it exceeds the present day
-value of 2.22 ounces of gold.  This can be accomplished using the
-command:
-
-@smallexample
-ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab
-@end smallexample
-
-With this command, the current price for gold is downloaded, and the
-Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces
-of gold.  If you wish the liability to be reflected in the parent
-subtotal either way, use this instead:
-
-@smallexample
-ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab
-@end smallexample
-
-In some cases, you may wish to refer to the account of whichever
-posting matched your automated transaction's value expression.  To do
-this, use the special account name @samp{$account}:
-
-@smallexample
-= /^Some:Long:Account:Name/
-  [$account]  -0.10
-  [Savings]    0.10
-@end smallexample
-
-This example causes 10% of the matching account's total to be deferred
-to the @samp{Savings} account---as a balanced virtual posting,
-which may be excluded from reports by using @option{--real}.
-
-@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated postings, Ledger in Practice
-@section Using Emacs to Keep Your Ledger
-
-In the Ledger tarball is an Emacs module, @file{ledger.el}.  This
-module makes the process of keeping a text ledger much easier for
-Emacs users.  I recommend putting this at the top of your ledger file:
-
-@example
-; -*-ledger-*-
-@end example
-
-And this in your @file{.emacs} file, after copying @file{ledger.el} to
-your @file{site-lisp} directory:
-
-@example
-(load "ledger")
-@end example
-
-Now when you edit your ledger file, it will be in
-@command{ledger-mode}.  @command{ledger-mode} adds these commands:
-
-@table @strong
-@item C-c C-a
-For quickly adding new transactions based on the form of older ones (see
-previous section).
-
-@item C-c C-c
-Toggles the ``cleared'' flag of the posting under point.
-
-@item C-c C-d
-Delete the transaction under point.
-
-@item C-c C-r
-Reconciles an account by displaying the postings in another
-buffer, where simply hitting the spacebar will toggle the pending flag
-of the posting in the ledger.  Once all the appropriate
-postings have been marked, press C-c C-c in the reconcile buffer
-to ``commit'' the reconciliation, which will mark all of the transactions
-as cleared, and display the new cleared balance in the minibuffer.
-
-@item C-c C-m
-Set the default month for new transactions added with C-c C-a.  This is
-handy if you have a large number of postings to enter from a
-previous month.
-
-@item C-c C-y
-Set the default year for new transactions added with C-c C-a.  This is
-handy if you have a large number of postings to enter from a
-previous year.
-@end table
-
-Once you enter the reconcile buffer, there are several key commands
-available:
-
-@table @strong
-@item RET
-Visit the ledger file transaction corresponding to the reconcile transaction.
-
-@item C-c C-c
-Commit the reconcialation.  This marks all of the marked postings
-as ``cleared'', saves the ledger file, and then displays the new
-cleared balance.
-
-@item C-l
-Refresh the reconcile buffer by re-reading postings from the
-ledger data file.
-
-@item SPC
-Toggle the posting under point as cleared.
-
-@item a
-Add a new transaction to the ledger data file, and refresh the reconcile
-buffer to include its postings (if the transaction is added to the same
-account as the one being reconciled).
-
-@item d
-Delete the transaction related to the posting under point.  Note: This
-may result in multiple postings being deleted.
-
-@item n
-Move to the next line.
-
-@item p
-Move to the previous line.
-
-@item C-c C-r
-@item r
-Attempt to auto-reconcile the postings to the entered balance.  If
-it can do so, it will mark all those postings as pending that
-would yield the specified balance.
-
-@item C-x C-s
-@item s
-Save the ledger data file, and show the current cleared balance for
-the account being reconciled.
-
-@item q
-Quit the reconcile buffer.
-@end table
-
-There is also an @command{emacs} command which can be used to output
-reports in a format directly @code{read}-able from Emacs Lisp.
-
-@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Ledger in Practice
-@section Using GnuCash to Keep Your Ledger
-
-The Ledger tool is fast and simple, but it offers no custom method for
-actually editing the ledger.  It assumes you know how to use a text
-editor, and like doing so.  There is, at least, an Emacs mode that
-makes editing Ledger's data files much easier.
-
-You are also free to use GnuCash to maintain your ledger, and the
-Ledger program for querying and reporting on the contents of that
-ledger.  It takes a little longer to parse the XML data format that
-GnuCash uses, but the end result is identical.
-
-Then again, why would anyone use a Gnome-centric, multi-megabyte
-behemoth to edit their data, and only a one megabyte binary to query
-it?
-
-@node Using timeclock to record billable time, Using XML, Using GnuCash to Keep Your Ledger, Ledger in Practice
-@section Using timeclock to record billable time
-
-The timeclock tool makes it easy to track time events, like clocking
-into and out of a particular job.  These events accumulate in a
-timelog file.
-
-Each in/out event may have an optional description.  If the ``in''
-description is a ledger account name, these in/out pairs may be viewed
-as virtual postings, adding time commodities (hours) to that
-account.
-
-For example, the command-line version of the timeclock tool could be
-used to begin a timelog file like:
-
-@example
-export TIMELOG=$HOME/.timelog
-ti ClientOne category
-sleep 10
-to waited for ten seconds
-@end example
-
-The @file{.timelog} file now contains:
-
-@smallexample
-i 2004/10/06 15:21:00 ClientOne  category
-o 2004/10/06 15:21:10 waited for ten seconds
-@end smallexample
-
-Ledger parses this directly, as if it had seen the following transaction:
-
-@smallexample
-2004/10/06 category
-    (ClientOne)      10s
-@end smallexample
-
-In other words, the timelog event pair is seen as adding 0.00277h (ten
-seconds) worth of time to the @samp{ClientOne} account.  This would be
-considered billable time, which later could be invoiced and credited
-to accounts receivable:
-
-@smallexample
-2004/11/01 (INV#1) ClientOne, Inc.
-    Receivable:ClientOne       $0.10
-    ClientOne              -0.00277h @@ $35.00
-@end smallexample
-
-The above posting converts the clocked time into an invoice for
-the time spent, at an hourly rate of $35.  Once the invoice is paid,
-the money is deposited from the receivable account into a checking
-account:
-
-@smallexample
-2004/12/01 ClientOne, Inc.
-    Assets:Checking            $0.10
-    Receivable:ClientOne
-@end smallexample
-
-And now the time spent has been turned into hard cash in the checking
-account.
-
-The advantage to using timeclock and invoicing to bill time is that
-you will always know, by looking at the balance report, exactly how
-much unbilled and unpaid time you've spent working for any particular
-client.
-
-I like to @samp{!include} my timelog at the top of my company's
-accounting ledger, with the attached prefix @samp{Billable}:
-
-@smallexample
-; -*-ledger-*-
-
-; This is the ledger file for my company.  But first, include the
-; timelog data, entering all of the time events within the umbrella
-; account "Billable".
-
-!account Billable
-!include /home/johnw/.timelog
-!end
-
-; Here follows this fiscal year's postings for the company.
-
-2004/11/01 (INV#1) ClientOne, Inc.
-    Receivable:ClientOne           $0.10
-    Billable:ClientOne         -0.00277h @@ $35.00
-
-2004/12/01 ClientOne, Inc.
-    Assets:Checking                $0.10
-    Receivable:ClientOne
-@end smallexample
-
-@node Using XML,  , Using timeclock to record billable time, Ledger in Practice
-@section Using XML
-
-By default, Ledger uses a human-readable data format, and displays its
-reports in a manner meant to be read on screen.  For the purpose of
-writing tools which use Ledger, however, it is possible to read and
-display data using XML.  This section documents that format.
-
-The general format used for Ledger data is:
-
-@smallexample
-<?xml version="1.0"?>
-<ledger>
-  <xact>...</xact>
-  <xact>...</xact>
-  <xact>...</xact>...
-</ledger>
-@end smallexample
-
-The data stream is enclosed in a @samp{ledger} tag, which contains a
-series of one or more transactions.  Each @samp{xact} describes the transaction
-and contains a series of one or more postings:
-
-@smallexample
-<xact>
-  <en:date>2004/03/01</en:date>
-  <en:cleared/>
-  <en:code>100</en:code>
-  <en:payee>John Wiegley</en:payee>
-  <en:postings>
-    <posting>...</posting>
-    <posting>...</posting>
-    <posting>...</posting>...
-  </en:postings>
-</xact>
-@end smallexample
-
-The date format for @samp{en:date} is always @samp{YYYY/MM/DD}.  The
-@samp{en:cleared} tag is optional, and indicates whether the
-posting has been cleared or not.  There is also an
-@samp{en:pending} tag, for marking pending postings.  The
-@samp{en:code} and @samp{en:payee} tags both contain whatever text the
-user wishes.
-
-After the initial transaction data, there must follow a set of postings
-marked with @samp{en:postings}.  Typically these postings will
-all balance each other, but if not they will be automatically balanced
-into an account named @samp{<Unknown>}.
-
-Within the @samp{en:postings} tag is a series of one or more
-@samp{posting}'s, which have the following form:
-
-@smallexample
-<posting>
-  <tr:account>Expenses:Computer:Hardware</tr:account>
-  <tr:amount>
-    <value type="amount">
-      <amount>
-        <commodity flags="PT">$</commodity>
-        <quantity>90.00</quantity>
-      </amount>
-    </value>
-  </tr:amount>
-</posting>
-@end smallexample
-
-This is a basic posting.  It may also be begin with
-@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual
-and auto-generated postings.  Then follows the @samp{tr:account}
-tag, which contains the full name of the account the posting is
-related to.  Colons separate parent from child in an account name.
-
-Lastly follows the amount of the posting, indicated by
-@samp{tr:amount}.  Within this tag is a @samp{value} tag, of which
-there are four different kinds, each with its own format:
-
-@enumerate
-@item boolean
-@item integer
-@item amount
-@item balance
-@end enumerate
-
-The format of a boolean value is @samp{true} or @samp{false}
-surrounded by a @samp{boolean} tag, for example:
-
-@smallexample
-<boolean>true</boolean>
-@end smallexample
-
-The format of an integer value is the numerical value surrounded by an
-@samp{integer} tag, for example:
-
-@smallexample
-<integer>12036</integer>
-@end smallexample
-
-The format of an amount contains two members, the commodity and the
-quantity.  The commodity can have a set of flags that indicate how to
-display it.  The meaning of the flags (all of which are optional) are:
-
-@table @strong
-@item P
-The commodity is prefixed to the value.
-@item S
-The commodity is separated from the value by a space.
-@item T
-Thousands markers are used to display the amount.
-@item E
-The format of the amount is European, with period used as a thousands
-marker, and comma used as the decimal point.
-@end table
-
-The actual quantity for an amount is an integer of arbitrary size.
-Ledger uses the GNU multi-precision math library to handle such
-values.  The XML format assumes the reader to be equally capable.
-Here is an example amount:
-
-@smallexample
-<value type="amount">
-  <amount>
-    <commodity flags="PT">$</commodity>
-    <quantity>90.00</quantity>
-  </amount>
-</value>
-@end smallexample
-
-Lastly, a balance value contains a series of amounts, each with a
-different commodity.  Unlike the name, such a value does need to
-balance.  It is called a balance because it sums several amounts.  For
-example:
-
-@smallexample
-<value type="balance">
-  <balance>
-    <amount>
-      <commodity flags="PT">$</commodity>
-      <quantity>90.00</quantity>
-    </amount>
-    <amount>
-      <commodity flags="TE">DM</commodity>
-      <quantity>200.00</quantity>
-    </amount>
-  </balance>
-</value>
-@end smallexample
-
-That is the extent of the XML data format used by Ledger.  It will
-output such data if the @command{xml} command is used, and can read
-the same data.
-
-@chapter Random things
-
-Whenever a commodity is exchanged for another in a posting, one of the
-two is considered @emph{primary}, and the other secondary.
-Primariness of a commodity is remembered, since the @option{--market}
-option only renders balances into secondary commodities, never
-primaries.  To render primaries, use the @option{--exchange=COMMODITY}
-option.
-
-In all of the following examples, the P commodity is considered primary
-and the S is secondary (the P at the beginning of the line indicates a
-price-setting directive):
-
-@smallexample
-2009/01/01 Sample 1a
-    Assets:Brokerage:Stocks                100 S
-    Assets:Brokerage:Cash                 -100 P
-
-P 2009/01/15 00:00:00 S 2 P
-
-2009/02/01 Sample 2a
-    Assets:Brokerage:Stocks                100 S @@ 1 P
-    Assets:Brokerage:Cash
-
-P 2009/02/01 00:00:00 S 4 P
-
-2009/03/01 Sample 3a
-    Assets:Brokerage:Stocks                100 S @@@@ 100 P
-    Assets:Brokerage:Cash
-
-P 2009/03/01 00:00:00 S 8 P
-
-2009/04/01 Sample 4a
-    Assets:Brokerage:Cash                  100 P
-    Assets:Brokerage:Stocks               -100 S @{1 P@}
-
-P 2009/04/01 00:00:00 S 16 P
-@end smallexample
-
-@chapter Anatomy of a journal file
-
-Everything begins with a journal file---the anatomy of which is covered
-in detail in chapter one.  To review: a @emph{journal} contains one or
-more @emph{transactions}, each of which refers to two or more
-@emph{postings}.  A @emph{posting} specifies that a given
-@emph{amount} is added to, or subtracted from, an @emph{account}.
-(@emph{Accounts} may be nested hierarchically by separating the elements
-using a colon).  Lastly, an @emph{amount} is a figure representing a
-given @emph{quantity} of a @emph{commodity}.  Here follows a review of
-these terms, which are all used extensively throughout this chapter:
-
-@table @emph
-@item journal
-A journal is a data file containing a series of transactions.
-
-@item transaction
-a transaction relates a group of two or more postings, with the absolute
-constraint that the total sum of a transaction's postings must equal
-zero.  That is, every transaction in a journal must @emph{balance} to zero.
-
-@item posting
-Postings record how commodities are moved between accounts.  If you
-spent money on a movie ticket, for example, such a transaction would have two
-postings: One to show how the money was taken from your wallet, and
-another to show how it was applied to your movie expenses.
-
-@item account
-An account 
-
-@item amount
-
-@item quantity
-
-@item commodity
-@end table
-
-@chapter Example accounting practices
-
-@chapter Generating useful reports
-
-Once you have a journal file representing a recent history of your
-finances, the next step is to generate reports in order to give richer
-meaning to this data.  For example: Where do you spend your money?  Do
-you have enough to cover upcoming expenses?  Are you creating or losing
-net worth?  Are your investment performing well?  All of these questions
-can be answered easily with Ledger---if you know how to ask them.
-
-Preparing complex reports is not a simple task, but neither is it a
-difficult one.  All that's required is a proper understanding of how
-Ledger views your data, and how it prepares it for reporting.
-
-After Ledger reads a journal file, it creates an in-memory
-representation reflecting the order and composition of those transactions.
-
-@chapter Value expressions
-
-@chapter Format strings
-
-@chapter Extensions in Python
-
-@chapter The design of Ledger
-
-The following sections discuss how Ledger is architected, from the
-ground up, and will show how to use the various parts of the Ledger
-library from your own scripts.  Ledger essentially follows five steps in
-reporting data to the user:
-
-@enumerate
-@item Parse journal file into an internal representation
-@item Perform any implied math within the journal file
-@item ``Face'' this internal representation as a virtual document
-@item Apply a series of transforms to the virtual document
-@item Display the virtual document using a formatting command
-@end enumerate
-
-The calculations in step two are specified by the user, such as when a
-posting's value might contain mathematical operators.  The
-calculations in step four are implied in the transformations, for
-example when the @option{--average} option is used.
-
-At the core, however, Ledger is basically a sophisticated calculator
-with special knowledge about commoditized values.  It knows what you
-mean if you add ten dollars to twenty euros, and later ask for the
-balance of that particular account.  So it follows that first we must
-discuss how Ledger deals with math, and from there move on to describing
-how the steps above are achieved.
-
-@section Numerics
-
-@subsection Basic amounts
-
-The most fundamental type in Ledger is the amount, which may or may
-not have a commodity attached to it.  First, we'll deal with the bare
-case, just to show how the amount type works.  In C++, most all of
-Ledger's internal types end in @code{_t}; in Python, the same type
-name is used, but the @code{_t} suffix is dropped.  Examples of usage
-in both languages will be presented throughout.
-
-
-
-amount_t
-commodity_t
-updater_t
-datetime_t
-balance_t
-balance_pair_t
-value_t
-valexpr_t
-format_t
-mask_t
-
-@section Journal Representation
-
-journal_t
-account_t
-xact_t
-post_t
-parser_t
-
-@section Reporting
-
-@section Terminal Interface
-
-@section General Utility
-
-@c data: foo
-@smallexample
-2004/05/01 * Checking balance
-    Assets:Bank:Checking                           $1,000.00
-    Equity:Opening Balances
-@end smallexample
-
-@c smex utility-1: $LEDGER -f $foo bal
-@smallexample
-           $1,000.00  Assets:Bank:Checking
-          $-1,000.00  Equity:Opening Balances
---------------------
-                   0
-@end smallexample
-
-@bye