Rearranged the sources a bit.

1 files changed, 3960 insertions, 0 deletions

diff --git a/docs/ledger.texi b/docs/ledger.texi
new file mode 100644
index 00000000..bd42a3b0
--- /dev/null
+++ b/docs/ledger.texi
@@ -0,0 +1,3960 @@
+\input texinfo  @c -*-texinfo-*-
+
+@setfilename ledger.info
+@settitle Ledger: Command-Line Accounting
+
+@dircategory User Applications
+@copying
+Copyright (c) 2003-2006, 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 iso-8859-1
+
+@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::                
+* Running Ledger::              
+* Keeping a ledger::            
+* Using XML::                   
+@end menu
+
+@node Introduction, Running Ledger, 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 transactions,
+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
+transaction 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.
+The entry might look like this:
+
+@smallexample
+9/29  BAL  Pacific Bell              $-200.00   $-200.00
+           Equity:Opening Balances    $200.00
+9/29  BAL  Checking                   $100.00    $100.00
+           Equity:Opening Balances   $-100.00
+9/29  100  Pacific Bell                $23.00    $223.00
+           Checking                   $-23.00     $77.00
+@end smallexample
+
+The first line shows a payment to Pacific Bell for $23.00.  Because
+there is no ``balance'' in a general ledger---it's always zero---we
+write in the total balance of all payments to ``Pacific Bell'', which
+now is $223.00 (previously the balance was $200.00).  This is done by
+looking at the last entry for ``Pacific Bell'' in the ledger, adding
+$23.00 to that amount, and writing the total in the balance column.
+And the money came from ``Checking''---a withdrawal of $23.00---which
+leaves the ending balance in ``Checking'' at $77.00.  This is a very
+manual procedure; but that's where computers come in...
+
+The transaction 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 transaction 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
+transactions.  If a transaction does not balance, Ledger displays an
+error and indicates the incorrect transaction.@footnote{In some
+special cases, it automatically balances this entry 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 entries.
+
+And just for the sake of example---as a starting point for those who
+want to dive in head-first---here are the ledger entries from above,
+formatting as the ledger program wishes to see them:
+
+@smallexample
+2004/09/29 Pacific Bell
+     Payable:Pacific Bell            $-200.00
+     Equity:Opening Balances
+
+2004/09/29 Checking
+     Accounts:Checking                $100.00
+     Equity:Opening Balances
+
+2004/09/29 Pacific Bell
+     Payable:Pacific Bell              $23.00
+     Accounts: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
+
+@menu
+* Building the program::        
+* Getting help::                
+@end menu
+
+@node Building the program, Getting help, Introduction, Introduction
+@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
+
+@node Getting help,  , Building the program, Introduction
+@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 Running Ledger, Keeping a ledger, Introduction, Top
+@chapter Running Ledger
+
+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 transactions matching those regular
+expressions.  For the @command{entry} command, the arguments have a
+special meaning, described below.
+
+The regular expressions arguments always match the account name that a
+transaction refers to.  To match on the payee of the entry 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
+* Usage overview::              
+* Commands::                    
+* Options::                     
+* Format strings::              
+* Value expressions::           
+* Period expressions::          
+* File format::                 
+* Some typical queries::        
+* Budgeting and forecasting::   
+@end menu
+
+@node Usage overview, Commands, Running Ledger, Running Ledger
+@section Usage overview
+
+Before getting into the details of how to run Ledger, it will be
+easier to introduce the features in the context of their typical
+usage.  To that end, this section 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.
+
+@subsection 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 transaction 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
+transaction being added by the automatic entry at the top of the file.
+The entry is virtual because the account name was surrounded by
+parentheses in an automatic entry.  Automatic entries will be
+discussed later, but first let's remove the virtual transaction 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 transaction, it has dropped from the
+report and we see that 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 transactions are involved, which can be removed using
+@option{--actual}}.
+
+@subsubsection 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
+account, 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}).
+
+@subsubsection 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
+
+@subsection 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 transaction and how it contributes to that total.
+
+Paradoxically, the most basic form of @command{register} is almost
+never used, since it displays every transaction:
+
+@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 transaction 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.
+
+@subsubsection Specific register queries
+
+The most common use of the register command is to summarize
+transactions 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 transactions are
+found, and also how to summarize the various amounts and totals that
+result.  These are plumbed in greater depth below.
+
+@subsection Selecting transactions
+
+Although the easiest way to use the register is to report all the
+transactions 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 exactly the transactions that interest you most.  This is
+called the ``calculation'' phase of Ledger.  All of its related
+options are documented under @option{--help-calc}.
+
+@subsubsection By date
+
+@c  -c, --current          show only current and past entries (not future)
+
+@option{--current}(@option{-c}) displays entries occurring on or
+before the current date.  Any entry recorded for a future date will be
+ignored, as if it had not been seen.  This is useful if you happen to
+pre-record entries, 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 entries occurring on or after @var{DATE}.  The running total in
+the register will start at zero with the first transaction, even if
+there are earlier entries.
+
+To limit the display only, but still add earlier transactions 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 transactions 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 entries 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 transactions 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 entry, rather than sorting all transactions in the report.
+See the documentation on @option{--sort} below for more details.
+
+@subsubsection By status
+
+By default, all regular transactions are included in each report.  To
+limit the report to certain kinds of transactions, use one or more of
+the following options:
+
+@table @option
+@item -C, --cleared
+Consider only cleared transactions.
+@item -U, --uncleared
+Consider only uncleared and pending transactions.
+@item -R, --real
+Consider only real (non-virtual) transactions.
+@item -L, --actual
+Consider only actual (non-automated) transactions.
+@end table
+
+Cleared transactions are indicated by an asterix placed just before
+the payee name in a transaction.  The meaning of this flag is up to
+the user, but typically it means that an entry has been seen on a
+financial statement.  Pending transactions use an exclamation mark in
+the same position, but are mainly used only by reconciling software.
+Uncleared transactions are for things like uncashed checks, credit
+charges that haven't appeared on a statement yet, etc.
+
+Real transactions are all non-virtual transactions, where the account
+name is not surrounded by parentheses or square brackets.  Virtual
+transactions 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 transactions are those not generated, either as part of an
+automated entry, or a budget or forecast report.  A useful of when you
+might like to filter out generated transactions is with a budget:
+
+@example
+ledger --budget --actual reg ^expenses
+@end example
+
+This command outputs all transactions affecting a budgeted account,
+but without subtracting the budget amount (because the generated
+transactions are suppressed with @option{--actual}).  The report shows
+how much you actually spent on budgeted items.
+
+@subsubsection By relationship
+
+@c  -r, --related          calculate report using related transactions
+
+Normally, a register report includes only the transactions 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 transactions that
+did not match your query, but only in entries 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
+
+@subsubsection By budget
+
+@c      --budget           generate budget entries based on FILE
+
+There is more information about budgeting and forecasting in
+@ref{Budgeting and forecasting}.  Basically, if you have any period
+entries in your ledger file, you can use these options.  A period
+entry looks like:
+
+@example
+~ Monthly
+  Assets:Bank:Checking         $500.00
+  Income:Salary
+@end example
+
+The difference from a regular entry 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 entry is in every
+other way the same as a regular entry.
+
+With such an entry in your ledger file, the @option{--budget} option
+will report only transactions that match a budgeted account.  Using
+@file{sample.dat} from above:
+
+@example
+ledger --budget reg ^income
+@end example
+
+Reports:
+
+@smallexample
+2004/05/01 Budget entry         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 transactions plus the budget
+@c      --unbudgeted       show only unbudgeted transactions
+
+The @option{--add-budget} option reports all matching transactions in
+addition to budget transactions; while @option{--unbudgeted} shows
+only those that don't match a budgeted account.  To summarize:
+
+@table @option
+@item --budget
+Show transactions matching budgeted accounts.
+@item --unbudgeted
+Show transactions matching unbudgeted accounts.
+@item --add-budget
+Show both budgeted and unbudgeted transactions together (i.e., add the
+generated budget transactions to the regular report).
+@end table
+
+@c      --forecast EXPR    generate forecast entries while EXPR is true
+
+A report with the @option{--forecast} option will add budgeted
+transactions 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 entry       Income:Salary              $-500.00   $-1,000.00
+2005/01/01 Forecast entry       Income:Salary              $-500.00   $-1,500.00
+@end smallexample
+
+The date this report was made was November 5, 2004; the reason the
+first forecast entry is in december is that forecast entries are only
+added for the future, and they only stop after the value expression
+has matched at least once, which is why the January entry 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
+
+@subsubsection By value expression
+
+@c  -l, --limit EXPR       calculate only transactions 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
+transaction (@samp{d}) with a specified month.  The resulting report
+will contain only transactions 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
+transaction 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
+transaction 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
+
+@subsection Massaging register output
+
+Even after filtering down your data to just the transactions you're
+interested in, the default reporting method of one transaction 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}.
+
+@subsubsection Summarizing
+
+@c  -n, --collapse         register: collapse entries with multiple transactions
+
+When multiple transactions relate to a single entry, they are reported
+as part of that entry.  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 transactions are part of one entry, and as such the entry
+details are printed only once.  To report every entry on a single
+line, use @option{-n} to collapse entries with multiple transactions:
+
+@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 entry is printed, and the
+date and name reflect the range of the combined transactions.
+
+@c  -P, --by-payee         show summarized totals by payee
+
+With @option{-P}, transactions relating to the same payee are
+combined.  In this case, the date of the combined entry is that of the
+latest transaction.
+
+@c  -x, --comm-as-payee    set commodity name as the payee, for reporting
+
+@option{-x} changes the payee name for each transaction 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.
+
+@subsubsection 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 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
+
+@subsubsection Ordering and width
+
+@c  -S, --sort EXPR        sort report according to the value expression EXPR
+
+The transactions 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 transactions 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 entries to be printed---which can
+be very useful for viewing the last 10 entries in your checking
+account, while also showing the cumulative balance from all
+entries---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
+
+@subsubsection Averages and percentages
+
+@c  -A, --average          report average transaction amount
+
+To see the running total changed to a running average, use
+@option{-A}.  The final transaction's total will be the overall
+average of all displayed transactions.  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
+
+@subsubsection Reporting total data
+
+@c      --totals           in the "xml" report, include running total
+
+Normally in the @command{xml} report, only transaction 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}.
+
+@subsubsection Display by value expression
+
+@c  -d, --display EXPR     display only transactions matching EXPR
+
+With @option{-d} you can decide which transactions (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.
+
+@subsubsection 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
+
+@subsection 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.
+
+@subsection 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
+
+@subsection Reporting percentages
+
+There is no built-in way to report transaction amounts or account
+balances in terms of percentages
+
+@node Commands, Options, Usage overview, Running Ledger
+@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 transactions 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
+transactions that match.  Very useful for hunting down a particular
+transaction.
+
+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 entries 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
+transactions 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 entries contained
+within that file will be output, and not an included entries (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
+transaction.
+
+@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 transactions
+ ...)                   ; list of entries
+@end example
+
+@subsection equity
+
+The @command{equity} command prints out accounts balances as if they
+were entries.  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 entry
+
+The @command{entry} commands simplifies the creation of new entries.
+It works on the principle that 80% of all transactions are variants of
+earlier transactions.  Here's how it works:
+
+Say you currently have this transaction 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{entry} command you can type:
+
+@example
+ledger entry 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 transaction matching the regular expression
+@samp{viva}, and assuming that any accounts or amounts specified will
+be similar to that earlier transaction.  If Ledger does not succeed in
+generating a new entry, 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{entry}, which simplifies the task of adding a new entry
+to your ledger.  It launches @command{vi} to confirm that the entry
+looks appropriate.
+
+Here are a few more examples of the @command{entry} command, assuming
+the above journal entry:
+
+@example
+ledger entry 4/9 viva 11.50
+ledger entry 4/9 viva 11.50 checking # (from `checking')
+ledger entry 4/9 viva food 11.50 tips 8
+ledger entry 4/9 viva food 11.50 tips 8 cash
+ledger entry 4/9 viva food $11.50 tips $8 cash
+ledger entry 4/9 viva dining "DM 11.50"
+@end example
+
+@node Options, Format strings, Commands, Running Ledger
+@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.
+
+@menu
+* Basic options::               
+* Report filtering::            
+* Output customization::        
+* Commodity reporting::         
+* Environment variables::       
+@end menu
+
+@node Basic options, Report filtering, Options, Options
+@subsection Basic options
+
+These are the most basic command options.  Most likely, the user will
+want to set them using @ref{Environment variables}, 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.  FILE may also be a list of
+file names separated by colons.  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
+transactions, but it may contain option settings.  To specify options
+in the init file, use the same syntax as the command-line.  Here's an
+example init file:
+
+@smallexample
+--price-db ~/finance/.pricedb
+
+; ~/.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 transactions are assumed to relate to.
+
+@node Report filtering, Output customization, Basic options, Options
+@subsection Report filtering
+
+These options change which transactions affect the outcome of a
+report, in ways other than just using regular expressions:
+
+@option{--current}(@option{-c}) displays only entries occurring on or
+before the current date.
+
+@option{--begin DATE} (@option{-b DATE}) constrains the report to
+entries on or after @var{DATE}.  Only entries 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 entry.  (Note: This
+is different from using @option{--display} to constrain what is
+displayed).
+
+@option{--end DATE} (@option{-e DATE}) constrains the report so that
+entries 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 entries within each
+period separately, making it easy to see weekly, monthly, quarterly,
+etc., transaction 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 transactions 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 transactions whose entry
+has been marked ``cleared'' (by placing an asterix to the right of the
+date).
+
+@option{--uncleared} (@option{-U}) displays only transactions whose
+entry 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 transactions, not
+virtual.  (A virtual transaction is indicated by surrounding the
+account name with parentheses or brackets; see the section on using
+virtual transactions for more information).
+
+@option{--actual} (@option{-L}) displays only actual transactions, and
+not those created due to automated transactions.
+
+@option{--related} (@option{-r}) displays transactions that are
+related to whichever transactions 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 entries having a related transaction.
+For example, if a file had this entry:
+
+@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 transactions related to the
+transaction 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 transactions
+meet your budget.  @option{--add-budget} also shows unbudgeted
+transactions, 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 transactions
+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.
+
+@node Output customization, Commodity reporting, Report filtering, Options
+@subsection Output customization
+
+These options affect only the output, but not which transactions are
+used to create it:
+
+@option{--collapse} (@option{-n}) causes entries in a
+@command{register} report with multiple transactions to be collapsed
+into a single, subtotaled entry.
+
+@option{--subtotal} (@option{-s}) causes all entries in a
+@command{register} report to be collapsed into a single, subtotaled
+entry.
+
+@option{--by-payee} (@option{-P}) reports subtotals by payee.
+
+@option{--comm-as-payee} (@option{-x}) changes the payee of every
+transaction to be the commodity used in that transaction.  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 transaction totals by the
+week.  The week begins on whichever day of the week begins the month
+containing that transaction.  To set a specific begin date, use a
+period string, such as @samp{weekly from DATE}.  @option{--monthly}
+(@option{-M}) reports transaction totals by month; @option{--yearly}
+(@option{-Y}) reports transaction totals by year.  For more complex
+period, using the @option{--period} option described above.
+
+@option{--dow} reports transactions 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 entries to be printed.  This
+is different from using the command-line utility @command{head}, which
+would limit to the first N transactions.  @option{--tail} outputs only
+the last N entries.  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 entries 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 transaction
+value.
+
+@option{--deviation} (@option{-D}) reports each transaction'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 output 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 output nothing but the date and totals column,
+without commodities.
+
+@option{--display EXPR} (@option{-d EXPR}) limits which transactions
+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 transactions, against a running balance which
+includes all transaction 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 transactions 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
+
+@node Commodity reporting, Environment variables, Output customization, Options
+@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 transactions.
+
+@item -V, --market
+Reports the last known market value for all commodities.
+
+@item -g, --performance
+Reports the net gain/loss for each transaction in a @command{register}
+report.
+
+@item -G --gain
+Reports the net gain/loss for all commodities in the report that have
+a price history.
+@end table
+
+@node Environment variables,  , Commodity reporting, Options
+@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
+@end example
+
+@node Format strings, Value expressions, Options, Running Ledger
+@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 transaction 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     An entry'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 transaction'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 entry's data was read.
+
+@item B
+Inserts the beginning character position of that entry within the file.
+
+@item b
+Inserts the beginning line of that entry within the file.
+
+@item E
+Inserts the ending character position of that entry within the file.
+
+@item e
+Inserts the ending line of that entry 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 entry has an
+effective date, in which case it prints
+@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
+
+@item X
+If a transaction 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 transactions have the same state.
+
+@item C
+Inserts the checking number for an entry, in parentheses, followed by
+a space; if none was specified, nothing is inserted.
+
+@item P
+Inserts the payee related to a transaction.
+
+@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
+transaction's state @emph{if the entry's transaction 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 transaction's amount.  This is
+used by the print report.  In some cases, this inserts nothing; in
+others, it inserts the transaction 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 transaction, 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 transaction, if one exists.
+
+@item /
+The @samp{%/} construct is special.  It separates a format string
+between what is printed for the first transaction of an entry, and
+what is printed for all subsequent transactions.  If not used, the
+same format string is used for all transactions.
+@end table
+
+@node Value expressions, Period expressions, Format strings, Running Ledger
+@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
+transactions 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 transactions.
+@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 entries are printed.  For example, the following
+command shows only entries from the beginning of the current month,
+while still calculating the running balance based on all entries:
+
+@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 entries in the register.  The following,
+simpler command is similar, but totals only the displayed
+transactions:
+
+@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 transactions, and sometimes the account affected by a
+transaction.  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 Transaction/account details
+
+@table @code
+@item d
+A transaction's date, as the number of seconds past the epoch.  This
+is always ``today'' for an account.
+
+@item a
+The transaction's amount; the balance of an account, without
+considering children.
+
+@item b
+The cost of a transaction; the cost of an account, without its
+children.
+
+@item v
+The market value of a transaction, or an account without its children.
+
+@item g
+The net gain (market value minus cost basis), for a transaction 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 transaction, or the count of transactions affecting an
+account.
+
+@item X
+1 if a transaction's entry has been cleared, 0 otherwise.
+
+@item R
+1 if a transaction is not virtual, 0 otherwise.
+
+@item Z
+1 if a transaction is not automated, 0 otherwise.
+@end table
+
+@subsubsection Calculated totals
+
+@table @code
+@item O
+The total of all transactions seen so far, or the total of an account
+and all its children.
+
+@item N
+The total count of transactions affecting an account and all its
+children.
+
+@item B
+The total cost of all transactions seen so far; the total cost of an
+account and all its children.
+
+@item V
+The market value of all transactions 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
+transactions, 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 transaction, this will match against the account affected by the
+transaction.
+
+@item //REGEXP/
+@item p/REGEXP/
+A regular expression that matches against an entry's payee name.
+
+@item ///REGEXP/
+@item w/REGEXP/
+A regular expression that matches against an account's base name.  If
+a transaction, this will match against the account affected by the
+transaction.
+
+@item c/REGEXP/
+A regular expression that matches against the entry code (the text
+that occurs between parentheses before the payee name).
+
+@item e/REGEXP/
+A regular expression that matches against a transaction'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 Period expressions, File format, Value expressions, Running Ledger
+@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 File format, Some typical queries, Period expressions, Running Ledger
+@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 an entry.  It may be followed
+by any number of lines, each beginning with whitespace, to denote the
+entry's account transactions.  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 entry is ``cleared'', which can mean whatever the user
+wants it t omean.  If @samp{!} appears after the date, it indicates d
+the entry 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 transaction.  Following these is the payee, or a description of
+the transaction.
+
+The format of each following transaction is:
+
+@example
+  ACCOUNT  AMOUNT  [; NOTE]
+@end example
+
+The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
+transactions, or square brackets if it is a virtual transactions that
+must balance.  The @samp{AMOUNT} can be followed by a per-unit
+transaction cost, by specifying @samp{@ AMOUNT}, or a complete
+transaction cost with @samp{@@ AMOUNT}.  Lastly, the @samp{NOTE} may
+specify an actual and/or effective date for the transaction by using
+the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
+@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
+
+@item =
+An automated entry.  A value expression must appear after the equal
+sign.
+
+After this initial line there should be a set of one or more
+transactions, just as if it were normal entry.  If the amounts of the
+transactions have no commodity, they will be applied as modifiers to
+whichever real transaction is matched by the value expression.
+
+@item ~
+A period entry.  A period expression must appear after the tilde.
+
+After this initial line there should be a set of one or more
+transactions, just as if it were normal entry.
+
+@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
+transactions 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 entries 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 entries 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{entry} 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 Some typical queries, Budgeting and forecasting, File format, Running Ledger
+@section Some 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 entries 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'' transactions:
+
+@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 transactions
+calculated must match @samp{^expenses}, while the transactions
+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'' transactions; display only related transactions whose
+account matches @samp{mastercard}, and base the calculation on
+transactions 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 transactions, 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-$ transactions
+
+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 transactions whose amount is greater than $1 (which can
+only happen if the transaction amount is in dollars).  The display
+predicate limits the entries @emph{displayed} to just those since last
+February, even those entries from before then will be computed as part
+of the balance.
+
+@node Budgeting and forecasting,  , Some typical queries, Running Ledger
+@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 entries at the top of your
+ledger file.  A period entry is almost identical to a regular entry,
+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 entries 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 entries 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 entries 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 transactions until the running total
+is greater than $-500.00.  A final transaction 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 Keeping a ledger, Using XML, Running Ledger, Top
+@chapter Keeping a ledger
+
+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 entry 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 entry 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 entries.
+
+For example, you do not need to tell Ledger about the accounts you
+use.  Any time Ledger sees a transaction 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
+transaction.
+
+Here is the Pacific Bell example from above, given as a Ledger
+transaction:
+
+@smallexample
+9/29 (100) 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 (100) Pacific Bell
+    Expenses:Utilities:Phone                   $23.00
+    Assets:Checking
+@end smallexample
+
+For this entry, Ledger will figure out that $-23.00 must come from
+@samp{Assets:Checking} in order to balance the entry.
+
+@menu
+* Stating where money goes::    
+* Assets and Liabilities::      
+* Commodities and Currencies::  
+* Accounts and Inventories::    
+* Understanding Equity::        
+* Dealing with Petty Cash::     
+* Working with multiple funds and accounts::  
+* Archiving previous years::    
+* Virtual transactions::        
+* Automated transactions::      
+* Using Emacs to Keep Your Ledger::  
+* Using GnuCash to Keep Your Ledger::  
+* Using timeclock to record billable time::  
+@end menu
+
+@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger
+@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 transaction will involve two or more accounts.
+Money is transferred from one or more accounts to one or more other
+accounts.  To record the transaction, an amount is @emph{subtracted}
+from the source accounts, and @emph{added} to the target accounts.
+
+In order to write a Ledger entry 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 that when you started your ledger.  Make sense?
+
+@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger
+@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 entry:
+
+@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 transaction is best handled with mirrored transactions 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 transactions, so those are what is shown here.  First, the
+personal entry, 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 entry
+should be immediately followed by an equivalent entry, 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 entry 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 entries 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 entries 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 transactions in
+separate files, just separate the two entries that were joined above.
+For example, for both the expense and the pay-back shown above, the
+following four entries 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 entries, 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 Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger
+@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 entries 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 transactions, 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, Keeping a ledger
+@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 entry
+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, Keeping a ledger
+@section Understanding Equity
+
+The most confusing entry 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 an entry 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, Keeping a ledger
+@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 transactions, 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, Keeping a ledger
+@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 transactions 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 entry ensures that the
+virtual transactions 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 transaction, 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 entry codes.  In this
+respect the codes become like virtual accounts that embrace the entire
+set of transactions.  Basically, we are associating an entry with a
+fund by setting its code.  Here are two entries 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 entries
+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 transaction 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
+transactions 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 entries.  Your own tastes will decide which
+is best for your situation.
+
+@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Keeping a ledger
+@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 entries 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} transactions 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 transactions, Automated transactions, Archiving previous years, Keeping a ledger
+@section Virtual transactions
+
+A virtual transaction 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 transaction, surround the account name in
+parentheses.  This form of usage does not need to balance.  However,
+if you want to ensure the virtual transaction balances with other
+virtual transactions in the same entry, 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 transactions will be factored in.
+To view balances without any virtual balances factored in, using the
+@option{-R} flag, for ``reality''.
+
+@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Keeping a ledger
+@section Automated transactions
+
+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 transaction at the top of your ledger file:
+
+@smallexample
+; This automated entry will compute Huqúqu'lláh based on this
+; journal's transactions.  Any that match will affect the
+; Liabilities:Huququ'llah account by 19% of the value of that
+; transaction.
+
+= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
+  (Liabilities:Huququ'llah)               0.19
+@end smallexample
+
+This automated transaction works by looking at each transaction in the
+ledger file.  If any match the given value expression, 19% of the
+transaction'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 entry 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 entries, 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
+transaction matched your automated entry'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 transaction,
+which may be excluded from reports by using @option{--real}.
+
+@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Keeping a ledger
+@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 entries based on the form of older ones (see
+previous section).
+
+@item C-c C-c
+Toggles the ``cleared'' flag of the transaction under point.
+
+@item C-c C-d
+Delete the entry under point.
+
+@item C-c C-r
+Reconciles an account by displaying the transactions in another
+buffer, where simply hitting the spacebar will toggle the pending flag
+of the transaction in the ledger.  Once all the appropriate
+transactions have been marked, press C-c C-c in the reconcile buffer
+to ``commit'' the reconciliation, which will mark all of the entries
+as cleared, and display the new cleared balance in the minibuffer.
+
+@item C-c C-m
+Set the default month for new entries added with C-c C-a.  This is
+handy if you have a large number of transactions to enter from a
+previous month.
+
+@item C-c C-y
+Set the default year for new entries added with C-c C-a.  This is
+handy if you have a large number of transactions 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 entry corresponding to the reconcile entry.
+
+@item C-c C-c
+Commit the reconcialation.  This marks all of the marked transactions
+as ``cleared'', saves the ledger file, and then displays the new
+cleared balance.
+
+@item C-l
+Refresh the reconcile buffer by re-reading transactions from the
+ledger data file.
+
+@item SPC
+Toggle the transaction under point as cleared.
+
+@item a
+Add a new entry to the ledger data file, and refresh the reconcile
+buffer to include its transactions (if the entry is added to the same
+account as the one being reconciled).
+
+@item d
+Delete the entry related to the transaction under point.  Note: This
+may result in multiple transactions 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 transactions to the entered balance.  If
+it can do so, it will mark all those transactions 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, Keeping a ledger
+@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.  Perhaps an Emacs mode will appear someday
+soon to make editing Ledger's data files much easier.
+
+Until then, you are 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, 35 megabyte behemoth
+to edit their data, and a one megabyte binary to query it?
+
+@node Using timeclock to record billable time,  , Using GnuCash to Keep Your Ledger, Keeping a ledger
+@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 transactions, 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 entry:
+
+@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 transaction 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 transactions 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,  , Keeping a ledger, Top
+@chapter 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 chapter documents that format.
+
+The general format used for Ledger data is:
+
+@smallexample
+<?xml version="1.0"?>
+<ledger>
+  <entry>...</entry>
+  <entry>...</entry>
+  <entry>...</entry>...
+</ledger>
+@end smallexample
+
+The data stream is enclosed in a @samp{ledger} tag, which contains a
+series of one or more entries.  Each @samp{entry} describes the entry
+and contains a series of one or more transactions:
+
+@smallexample
+<entry>
+  <en:date>2004/03/01</en:date>
+  <en:cleared/>
+  <en:code>100</en:code>
+  <en:payee>John Wiegley</en:payee>
+  <en:transactions>
+    <transaction>...</transaction>
+    <transaction>...</transaction>
+    <transaction>...</transaction>...
+  </en:transactions>
+</entry>
+@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
+transaction has been cleared or not.  There is also an
+@samp{en:pending} tag, for marking pending transactions.  The
+@samp{en:code} and @samp{en:payee} tags both contain whatever text the
+user wishes.
+
+After the initial entry data, there must follow a set of transactions
+marked with @samp{en:transactions}.  Typically these transactions will
+all balance each other, but if not they will be automatically balanced
+into an account named @samp{<Unknown>}.
+
+Within the @samp{en:transactions} tag is a series of one or more
+@samp{transaction}'s, which have the following form:
+
+@smallexample
+<transaction>
+  <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>
+</transaction>
+@end smallexample
+
+This is a basic transaction.  It may also be begin with
+@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual
+and auto-generated transactions.  Then follows the @samp{tr:account}
+tag, which contains the full name of the account the transaction is
+related to.  Colons separate parent from child in an account name.
+
+Lastly follows the amount of the transaction, 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 as long as the @file{expat} library was available
+when Ledger was built.
+
+@bye