reorganise the manual roughly into intro, reference, and detailed examples

1 files changed, 1127 insertions, 1127 deletions

diff --git a/doc/ledger.texi b/doc/ledger.texi
index 9dc1ba4b..8e886477 100644
--- a/doc/ledger.texi
+++ b/doc/ledger.texi
@@ -61,12 +61,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 @menu
 * Introduction::                
-* Running Ledger::              
-* Keeping a ledger::            
-* Using XML::                   
+* Using Ledger::                
+* Ledger in Practice::          
 @end menu
 
-@node Introduction, Running Ledger, Top, Top
+@node Introduction, Using Ledger, Top, Top
 @chapter Introduction
 
 Ledger is an accounting tool with the moxie to exist.  It provides no
@@ -223,8 +222,8 @@ https://lists.sourceforge.net/lists/listinfo/ledger-discuss
 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
+@node Using Ledger, Ledger in Practice, Introduction, Top
+@chapter Using Ledger
 
 Ledger has a very simple command-line interface, named---enticing
 enough---@command{ledger}.  It supports a few reporting commands, and
@@ -258,7 +257,6 @@ However, none of them are required to use the basic reporting
 commands.
 
 @menu
-* Usage overview::              
 * Commands::                    
 * Options::                     
 * Format strings::              
@@ -269,1101 +267,7 @@ commands.
 * 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
+@node Commands, Options, Using Ledger, Using Ledger
 @section Commands
 
 @subsection balance
@@ -1511,7 +415,7 @@ 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
+@node Options, Format strings, Commands, Using Ledger
 @section Options
 
 With all of the reports, command-line options are useful to modify the
@@ -1890,7 +794,7 @@ option settings in the file @file{~/.ledgerrc}, for example:
 --cache /tmp/.mycache
 @end example
 
-@node Format strings, Value expressions, Options, Running Ledger
+@node Format strings, Value expressions, Options, Using Ledger
 @section Format strings
 
 Format strings may be used to change the output format of reports.
@@ -2038,7 +942,7 @@ 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
+@node Value expressions, Period expressions, Format strings, Using Ledger
 @section Value expressions
 
 Value expressions are an expression language used by Ledger to
@@ -2261,7 +1165,7 @@ 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
+@node Period expressions, File format, Value expressions, Using Ledger
 @section Period expressions
 
 A period expression indicates a span of time, or a reporting interval,
@@ -2348,7 +1252,7 @@ last oct
 weekly last august
 @end example
 
-@node File format, Some typical queries, Period expressions, Running Ledger
+@node File format, Some typical queries, Period expressions, Using Ledger
 @section File format
 
 The ledger file format is quite simple, but also very flexible.  It
@@ -2478,7 +1382,7 @@ 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
+@node Some typical queries, Budgeting and forecasting, File format, Using Ledger
 @section Some typical queries
 
 A query such as the following shows all expenses since last
@@ -2583,7 +1487,7 @@ 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
+@node Budgeting and forecasting,  , Some typical queries, Using Ledger
 @section Budgeting and forecasting
 
 @subsection Budgeting
@@ -2671,8 +1575,8 @@ only, and not against the running total:
 ledger --forecast "d<[2010]" bal ^assets ^liabilities
 @end example
 
-@node Keeping a ledger, Using XML, Running Ledger, Top
-@chapter Keeping a ledger
+@node Ledger in Practice,  , Using Ledger, Top
+@chapter Ledger in Practice
 
 The most important part of accounting is keeping a good ledger.  If
 you have a good ledger, tools can be written to work whatever
@@ -2726,6 +1630,7 @@ For this entry, Ledger will figure out that $-23.00 must come from
 @samp{Assets:Checking} in order to balance the entry.
 
 @menu
+* Usage overview::              
 * Stating where money goes::    
 * Assets and Liabilities::      
 * Commodities and Currencies::  
@@ -2739,9 +1644,1104 @@ For this entry, Ledger will figure out that $-23.00 must come from
 * Using Emacs to Keep Your Ledger::  
 * Using GnuCash to Keep Your Ledger::  
 * Using timeclock to record billable time::  
+* Using XML::                   
 @end menu
 
-@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger
+@node Usage overview, Stating where money goes, Ledger in Practice, Ledger in Practice
+@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 Stating where money goes, Assets and Liabilities, Usage overview, Ledger in Practice
 @section Stating where money goes
 
 Accountants will talk of ``credits'' and ``debits'', but the meaning
@@ -2791,7 +2791,7 @@ 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
+@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Ledger in Practice
 @section Assets and Liabilities
 
 Assets are money that you have, and Liabilities are money that you
@@ -3006,7 +3006,7 @@ 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
+@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Ledger in Practice
 @section Commodities and Currencies
 
 Ledger makes no assumptions about the commodities you use; it only
@@ -3172,7 +3172,7 @@ 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
+@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Ledger in Practice
 @section Accounts and Inventories
 
 Since Ledger's accounts and commodity system is so flexible, you can
@@ -3210,7 +3210,7 @@ would look like:
 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
+@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Ledger in Practice
 @section Understanding Equity
 
 The most confusing entry in any ledger will be your equity account---
@@ -3249,7 +3249,7 @@ 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
+@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Ledger in Practice
 @section Dealing with Petty Cash
 
 Something that stops many people from keeping a ledger at all is the
@@ -3280,7 +3280,7 @@ the target account:
 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
+@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Ledger in Practice
 @section Working with multiple funds and accounts
 
 There are situations when the accounts you're tracking are different
@@ -3416,7 +3416,7 @@ 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
+@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Ledger in Practice
 @section Archiving previous years
 
 After a while, your ledger can get to be pretty large.  While this
@@ -3476,7 +3476,7 @@ 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
+@node Virtual transactions, Automated transactions, Archiving previous years, Ledger in Practice
 @section Virtual transactions
 
 A virtual transaction is when you, in your mind, see money as moving
@@ -3517,7 +3517,7 @@ 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
+@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Ledger in Practice
 @section Automated transactions
 
 As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets.
@@ -3595,7 +3595,7 @@ 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
+@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Ledger in Practice
 @section Using Emacs to Keep Your Ledger
 
 In the Ledger tarball is an Emacs module, @file{ledger.el}.  This
@@ -3698,7 +3698,7 @@ Quit the reconcile buffer.
 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
+@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Ledger in Practice
 @section Using GnuCash to Keep Your Ledger
 
 The Ledger tool is fast and simple, but it offers no custom method for
@@ -3715,7 +3715,7 @@ Then again, why would anyone use a Gnome-centric, multi-megabyte
 behemoth to edit their data, and only a one megabyte binary to query
 it?
 
-@node Using timeclock to record billable time,  , Using GnuCash to Keep Your Ledger, Keeping a ledger
+@node Using timeclock to record billable time, Using XML, Using GnuCash to Keep Your Ledger, Ledger in Practice
 @section Using timeclock to record billable time
 
 The timeclock tool makes it easy to track time events, like clocking
@@ -3806,13 +3806,13 @@ accounting ledger, with the attached prefix @samp{Billable}:
     Receivable:ClientOne
 @end smallexample
 
-@node Using XML,  , Keeping a ledger, Top
-@chapter Using XML
+@node Using XML,  , Using timeclock to record billable time, Ledger in Practice
+@section Using XML
 
 By default, Ledger uses a human-readable data format, and displays its
 reports in a manner meant to be read on screen.  For the purpose of
 writing tools which use Ledger, however, it is possible to read and
-display data using XML.  This chapter documents that format.
+display data using XML.  This section documents that format.
 
 The general format used for Ledger data is: