Merge branch 'release/v3.0.0-20120426'

3 files changed, 2001 insertions, 758 deletions

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 33750741..d59d3f82 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NUMBER         = 3.0
 # If a relative path is entered, it will be relative to the location 
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc
+OUTPUT_DIRECTORY       = %builddir%/doc
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
 # 4096 sub-directories (in 2 levels) under the output directory of each output 
@@ -1415,7 +1415,7 @@ DIRECTORY_GRAPH        = YES
 # generated by dot. Possible values are png, jpg, or gif
 # If left blank png will be used.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = jpg
 
 # The tag DOT_PATH can be used to specify the path where the dot tool can be 
 # found. If left blank, it is assumed the dot tool can be found in the path.
diff --git a/doc/ledger.1 b/doc/ledger.1
index 5a3bd6db..b96e4a7d 100644
--- a/doc/ledger.1
+++ b/doc/ledger.1
@@ -1,4 +1,4 @@
-.Dd June 22, 2010
+.Dd March 23, 2012
 .Dt ledger 1
 .Sh NAME
 .Nm ledger
@@ -32,6 +32,11 @@ or command loop, allowing several commands to be executed against the same
 dataset without reparsing.
 .Pp
 The following is a complete list of reporting commands accepted by Ledger:
+.Bl -tag -width accounts
+.It Nm accounts Oo Ar report-query Oc
+Lists all accounts for postings matching the
+.Ar report-query .
+.El
 .Pp
 .Bl -tag -width balance
 .It Nm balance Oo Ar report-query Oc
@@ -76,6 +81,12 @@ A special balance report which adds two extra columns: the cleared balance for
 each account, and the date of the most recent cleared posting in that account.
 For this accounting to be meaningful, the cleared flag must be set on at least
 one posting.  See the manual for more information.
+.It Nm commodities Oo Ar report-query Oc
+Lists all commodities for postings matching the
+.Ar report-query .
+.It Nm convert
+Reads data from a CSV (comma-separated values) file and generates Ledger
+transactions.
 .It Nm csv Oo Ar report-query Oc
 Report of postings matching the
 .Ar report-query
@@ -112,11 +123,19 @@ in a special account called
 .Li Equity:Opening Balances .
 The purpose of this report is to close the books for a prior year, while using
 these equity transactions to carry forward those balances.
+.It Nm org
+Produces a journal file suitable for use in the Emacs org mode.
+.It Nm payees Oo Ar report-query Oc
+Lists all payees for postings matching the
+.Ar report-query .
+.It Nm pricemap
+Produces a file which can be used to generate a graph with graphviz showing
+the relationship of commodities in the Ledger file.
 .It Nm prices Oo Ar report-query Oc
 Reports prices for all commodities in postings matching the
 .Ar report-query .
 The prices are reported with the granularity of a single day.
-.It Nm pricesdb Oo Ar report-query Oc
+.It Nm pricedb Oo Ar report-query Oc
 Reports prices for all commodities in postings matching the
 .Ar report-query .
 Prices are reported down to the second, using the same format as the
@@ -163,6 +182,7 @@ Show any gains (or losses) in commodity values over time.
 Only show the top
 .Ar number
 postings.
+.It Fl \-historical Pq Fl H
 .It Fl \-invert
 Invert the value of amounts shown.
 .It Fl \-market Pq Fl V
@@ -230,6 +250,13 @@ This command requires that Python support be active.  If so, it starts up an
 HTTP server listening for requests on port 9000.  This provides an alternate
 interface to creating and viewing reports.  Note that this is very much a
 work-in-progress, and will not be fully functional until a later version.
+.It Nm select Oo Ar sql-query Oc
+List all postings matching the
+.Ar sql-query .
+This command allows to generate SQL-like queries.
+.It Nm source
+Parses a journal file and checks it for errors. Ledger will return success
+if no errors are found.
 .It Nm stats Oo Ar report-query Oc
 Provides summary information about all the postings matching
 .Ar report-query .
@@ -263,13 +290,14 @@ transactions they are contained in.  See the manual for more information.
 .It Fl \-account Ar STR
 .It Fl \-account-width Ar INT
 .It Fl \-actual Pq Fl L
-.It Fl \-actual-dates
 .It Fl \-add-budget
 .It Fl \-amount Ar EXPR Pq Fl t
 .It Fl \-amount-data Pq Fl j
 .It Fl \-amount-width Ar INT
 .It Fl \-anon
 .It Fl \-args-only
+.It Fl \-auto-match
+.It Fl \-aux-date
 .It Fl \-average Pq Fl A
 .It Fl \-balance-format Ar FMT
 .It Fl \-base
@@ -280,6 +308,7 @@ transactions they are contained in.  See the manual for more information.
 .It Fl \-budget-format Ar FMT
 .It Fl \-by-payee Pq Fl P
 .It Fl \-cache Ar FILE
+.It Fl \-check-payees
 .It Fl \-cleared Pq Fl C
 .It Fl \-cleared-format Ar FMT
 .It Fl \-collapse Pq Fl n
@@ -297,6 +326,8 @@ See
 .It Fl \-date-format Ar DATEFMT Pq Fl y
 .It Fl \-datetime-format Ar FMT
 .It Fl \-date-width Ar INT
+.It Fl \-day-break
+.It Fl \-dc
 .It Fl \-debug Ar STR
 .It Fl \-decimal-comma
 .It Fl \-depth Ar INT
@@ -306,12 +337,12 @@ See
 .It Fl \-display-total Ar EXPR
 .It Fl \-dow
 .It Fl \-download
-.It Fl \-effective
 .It Fl \-empty Pq Fl E
 .It Fl \-end Pq Fl e
 .It Fl \-equity
 .It Fl \-exact
 .It Fl \-exchange Ar COMM Oo , COMM, ... Oc Pq Fl X
+.It Fl \-explicit
 .It Fl \-file Ar FILE
 .It Fl \-first Ar INT
 See
@@ -335,6 +366,7 @@ See
 .It Fl \-help-calc
 .It Fl \-help-comm
 .It Fl \-help-disp
+.It Fl \-immediate
 .It Fl \-import Ar STR
 .It Fl \-init-file Ar FILE
 .It Fl \-inject Ar STR
@@ -346,8 +378,8 @@ See
 .It Fl \-leeway Ar INT Pq Fl Z
 .It Fl \-limit Ar EXPR Pq Fl l
 .It Fl \-lot-dates
+.It Fl \-lot-notes
 .It Fl \-lot-prices
-.It Fl \-lot-tags
 .It Fl \-lots
 .It Fl \-lots-actual
 .It Fl \-market Pq Fl V
@@ -356,6 +388,7 @@ See
 .It Fl \-meta-width Ar INT
 .It Fl \-monthly Pq Fl M
 .It Fl \-no-color
+.It Fl \-no-pager
 .It Fl \-no-rounding
 .It Fl \-no-titles
 .It Fl \-no-total
@@ -366,10 +399,12 @@ See
 .It Fl \-pager Ar STR
 .It Fl \-payee
 .It Fl \-payee-width Ar INT
+.It Fl \-pedantic
 .It Fl \-pending
 .It Fl \-percent Pq Fl \%
 .It Fl \-period Ar PERIOD Pq Fl p
 .It Fl \-period-sort
+.It Fl \-permissive
 .It Fl \-pivot Ar STR
 .It Fl \-plot-amount-format Ar FMT
 .It Fl \-plot-total-format Ar FMT
@@ -382,6 +417,7 @@ See
 .Fl \-leeway .
 .It Fl \-prices-format Ar FMT
 .It Fl \-pricedb-format Ar FMT
+.It Fl \-primary-date
 .It Fl \-quantity Pq Fl O
 .It Fl \-quarterly
 .It Fl \-raw
@@ -396,6 +432,7 @@ appeared in the original journal file.
 .It Fl \-revalued
 .It Fl \-revalued-only
 .It Fl \-revalued-total Ar EXPR
+.It Fl \-rich-data
 .It Fl \-seed Ar INT
 .It Fl \-script
 .It Fl \-sort Ar EXPR Pq Fl S
@@ -405,6 +442,7 @@ appeared in the original journal file.
 .It Fl \-strict
 .It Fl \-subtotal Pq Fl s
 .It Fl \-tail Ar INT
+.It Fl \-time-report
 .It Fl \-total Ar EXPR
 .It Fl \-total-data Pq Fl J
 .It Fl \-total-width Ar INT
@@ -416,8 +454,10 @@ appeared in the original journal file.
 .It Fl \-unrealized-gains
 .It Fl \-unrealized-losses
 .It Fl \-unround
+.It Fl \-value-expr Ar EXPR
 .It Fl \-verbose
 .It Fl \-verify
+.It Fl \-verify-memory
 .It Fl \-version
 .It Fl \-weekly Pq Fl W
 .It Fl \-wide Pq Fl w
diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index 9d709748..30d7d5a4 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -45,7 +45,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 @titlepage
 @title Ledger: Command-Line Accounting
 @subtitle For Version 3.0 of Ledger
-@subtitle Draft Manual Time-stamp: <2011-12-16 21:23 (cpearls)> 
 @author John Wiegley
 @end titlepage
 
@@ -71,13 +70,14 @@ twinkling in their father's CRT.
 * Ledger Tutorial ::            
 * Principles of Accounting::    
 * Keeping a Journal::           
+* Transactions ::               
 * Building Reports::            
 * Reporting Commands::          
 * Command-line Syntax::         
 * Budgeting and Forecasting::   
 * Value Expressions::           
 * Format Strings::              
-* Journal File Format::         
+* Ledger for Developers::       
 * Extending with Python::       
 * Major Changes from version 2.6::  
 * Example Data File::           
@@ -114,9 +114,11 @@ fat.  Think of it as the Bran Muffin of accounting tools.
 To use it, you need to start keeping a journal.  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 journal,
-so we'll describe double-entry accounting in terms of that.  If you use
-another GUI accounting program like GNUCash, the vast majority of its
-functionality is geared towards helping you keep a journal.
+so we'll describe double-entry accounting in terms of that.  
+
+@c If you use
+@c another GUI accounting program like GNUCash, the vast majority of its
+@c functionality is geared towards helping you keep a journal.
 
 A checkbook journal records debits (subtractions, or withdrawals) and
 credits (additions, or deposits) with reference to a single account:
@@ -261,14 +263,6 @@ can be searched directly from the command line using the following
 options:
 @option{ledger --help} bring up this entire manual in your tty.
 
-@option{ledger --help-info} brings up help on how to use the info system.
-
-@option{ledger --help-comm  concept} searches the manual index and brings up pages associated with `concept'.
-
-@option{ledger --help-calc} brings up the value expressions chapter of this manual (@pxref{Value Expressions}).
-
-@option{ledger --help-disp} brings up the Format Strings chapter of this manual (@pxref{Format Strings}).
-
 If you need help on how to use Ledger, or run into problems, you can
 join the Ledger mailing list at the following Web address:
 
@@ -347,7 +341,8 @@ Ledger will generate:
            $ -243.60
 @end smallexample
 
-@noindent Showing you the balance of all accounts.  Options and search terms can pare this down to show only the accounts you want.
+@noindent Showing you the balance of all accounts.  Options and search terms can pare 
+this down to show only the accounts you want.
 
 A more useful report is to show only your Assets and Liabilities:
 
@@ -494,6 +489,7 @@ cannot display any currency symbols other than dollar signs ($).
 * Reporting Commands Quick Reference::  
 * Basic Options Quick Reference::  
 * Report Filtering Quick Reference::  
+* Error Checking and Calculation Options::  
 * Output Customization Quick Reference::  
 * Grouping Options::            
 * Commodity Reporting Quick Reference::  
@@ -528,7 +524,7 @@ cannot display any currency symbols other than dollar signs ($).
 @item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings
 @end multitable
  
-@node Report Filtering Quick Reference, Output Customization Quick Reference, Basic Options Quick Reference, Command Line Quick Reference
+@node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference
 @subsection Report Filtering
 @multitable @columnfractions .1 .25 .65
 @item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@@ -538,6 +534,7 @@ cannot display any currency symbols other than dollar signs ($).
 @item @code{-p STR} @tab @code{--period} @tab Set report period to STR
 @item @code{ } @tab @code{--period-sort} @tab Sort postings within each period
 @item @code{-C} @tab @code{--cleared} @tab Display only cleared postings
+@item @code{} @tab @code{--dc} @tab Display register or balance in debit/credit format
 @item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings
 @item @code{-R} @tab @code{--real} @tab Display only real postings
 @item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated
@@ -551,14 +548,25 @@ cannot display any currency symbols other than dollar signs ($).
 @item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports
 @end multitable
 
-@node Output Customization Quick Reference, Grouping Options, Report Filtering Quick Reference, Command Line Quick Reference
+@node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference
+@subsection  Error Checking and Calculation Options
+
+@multitable @columnfractions .1 .25 .65
+@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
+@item @code{} @tab @code{--strict} @tab  accounts, tags or commodities not previously declared will cause warnings
+@item @code{} @tab @code{--pedantic} @tab accounts, tags or commodities not previously declared will cause errors
+@item @code{} @tab @code{--check-payees} @tab enable strict and pedantic checking for payees as well as accounts, commodities and tags.
+@item @code{} @tab @code{--immediate} @tab instructs ledger to evaluate calculations immediately rather than lazily
+@end multitable
+
+
+@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference
 @subsection Output Customization
 @multitable @columnfractions .15 .4 .45
 @item @strong{Short} @tab @strong{Long} @tab @strong{Description}
 @item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings
 @item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal
 @item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee
-@item @code{-x} @tab @code{--comm-as-payee} @tab Change the payee of every posting to be the commodity used in that posting
 @item @code{-E} @tab @code{--empty} @tab Include empty accounts in report
 @item @code{-W} @tab @code{--weekly} @tab Report posting totals by week
 @item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year
@@ -639,7 +647,7 @@ cannot display any currency symbols other than dollar signs ($).
 Accounting is simply tracking your money.  It can range from nothing,
 and just waiting for automatic overdraft protection to kick in, or not,
 to a full blown double entry accounting system.  Ledger accomplishes the
-latter.  With ledger you can handle your personal finances or you
+latter.  With ledger you can handle your personal finances or your
 businesses.  Double-entry accounting scales.  
 @cindex double-entry accounting
 
@@ -896,7 +904,7 @@ file:
 And two in your company ledger file:
 
 @smallexample
-!account Company XYZ
+apply account Company XYZ
 
 2004/09/29  Circuit City
     Expenses:Computer:Software            $100.00
@@ -906,10 +914,10 @@ And two in your company ledger file:
     Accounts Payable:Your Name            $100.00
     Assets:Checking                      $-100.00
 
-!end
+end apply account
 @end smallexample
 
-(Note: The @samp{!account} above means that all accounts mentioned in
+(Note: The @samp{apply 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).
 
@@ -1336,7 +1344,7 @@ associated with particular transactions.  Your own tastes will decide which
 is best for your situation.
 
 
-@node Keeping a Journal, Building Reports, Principles of Accounting, Top
+@node Keeping a Journal, Transactions , Principles of Accounting, Top
 @chapter Keeping a Journal
 
 The most important part of accounting is keeping a good journal.  If you
@@ -1374,8 +1382,8 @@ posting.
 * Structuring Your Accounts::   
 * Commenting on your journal::  
 * Currency and Commodities::    
-* Advanced Transactions::       
-* File Format::                 
+* Keeping it Consistent::       
+* Journal Format::              
 * Archiving Previous Years ::   
 * Using Emacs::                 
 @end menu
@@ -1422,7 +1430,7 @@ indented by at least one space.  If you omit the leading spaces in the
 account lines Ledger will generate an error.  There must be at least two
 spaces, or a tab, between the amount and the account.  If you do not
 have adequate separation between the amount and the account Ledger will
-give an error and stop calculating}
+give an error and stop calculating.}
 
 
 @node Starting up, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
@@ -1536,9 +1544,9 @@ There are several forms of comments within a transaction, for example:
 @noindent  The first comment is global and Ledger will not attach it to any specific
 transactions.  The comments within the transaction must all start with `;'s and are
 preserved as part of the transaction.  The `:'s indicate meta-data and tags 
-(@pxref{Transaction Notes and Tags}).
+(@pxref{Metadata}).
 
-@node Currency and Commodities, Advanced Transactions, Commenting on your journal, Keeping a Journal
+@node Currency and Commodities, Keeping it Consistent, Commenting on your journal, Keeping a Journal
 @section Currency and Commodities
 
 @cindex currency
@@ -1604,6 +1612,7 @@ since we haven't told ledger to convert commodities.
 * Naming Commodities::          
 * Buying and Selling Stock::    
 * Fixing Lot Prices::           
+* Complete control over commodity pricing::  
 @end menu
 
 @node Naming Commodities, Buying and Selling Stock, Currency and Commodities, Currency and Commodities
@@ -1655,7 +1664,7 @@ The @{$30.00@} is a lot price.  You can also use a lot date,
 [2004/05/01], or both, in case you have several lots of the same
 price/date and your taxation model is based on longest-held-first.
 
-@node Fixing Lot Prices,  , Buying and Selling Stock, Currency and Commodities
+@node Fixing Lot Prices, Complete control over commodity pricing, Buying and Selling Stock, Currency and Commodities
 @subsection Fixing Lot Prices
 @cindex fixing lot prices
 @cindex consumable commodity pricing
@@ -1703,499 +1712,59 @@ both exist, you ask?  To support things like this:
          Assets:Checking
 @end smallexample
 
-This transaction says that you bought 11 gallons priced at $2.29 per  
+This transaction says that you bought 11 gallons priced at $2.299 per  
 gallon at a @strong{cost to you} of $2.30 per gallon.  Ledger auto-generates  
 a balance posting in this case to Equity:Capital Losses to reflect the  
-11 cent difference, which is then balanced by Assets:Checking because  
+1.1 cent difference, which is then balanced by Assets:Checking because  
 its amount is null. 
 
+@node Complete control over commodity pricing,  , Fixing Lot Prices, Currency and Commodities
+@subsection Complete control over commodity pricing
 
+@node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal
+@section Keeping it Consistent
 
+Sometimes Ledger's flexibility can lead to difficulties.  Using a
+freeform text editor to enter transactions makes it easy to keep the
+data, but also easy to enter accounts or payees inconsistently or with
+spelling errors.
 
-@node Advanced Transactions, File Format, Currency and Commodities, Keeping a Journal
-@section Advanced Transactions
-@menu
-* Transaction Notes and Tags::  
-* Multiple Account Transactions::  
-* Virtual Transactions::        
-* Automatic Transactions::      
-* Checking Balances and Reconciliations::  
-* Effective Dates::             
-* Periodic Transactions::       
-* Recording Commodity Lot Prices::  
-@end menu
-
-@node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions
-@subsection Transaction Notes and Tags
-
-Ledger 3.0 supports entry and transaction ``notes'', which may  
-contain new meta-data and tag markers.  Here's an example:
-@cindex meta-data
-@cindex tags
-
-@smallexample
-   2004/05/27 (100) Credit card company
-       ; This is an entry note!
-       ; Sample: Value
-       Liabilities:MasterCard         $20.00
-       ; This is a transaction note!
-       ; Sample: Another Value
-       ; :MyTag:
-       Assets:Bank:Checking
-       ; :AnotherTag:
-@end smallexample
-
-An indented paragraph starting with `;' is parsed as a persistent note  
-for its preceding category.  These notes will get printed back to you  
-with the ``print'' command.  They are accessible to value expressions  
-using the ``note'' variable.
-
-Further, any occurrence of ``:foo:'' in a note will cause a meta-data tag  
-for "foo" to be registered for that entry.  You can then search for  
-such transactions using:
-@findex %
-@cindex tags
-@smallexample
-   ledger reg %foo
-   ledger reg tag foo
-@end smallexample
-
-@cindex setting the value of a tag
-@cindex value tags
- 
-Also, if any word in the note ends (but does not start) with a colon,  
-the remainder of that line will be taken to be the meta-data value for  
-that tag.  That is:
-
-@smallexample
-   ; :foo:bar:baz:  <-- These are three tags
-   ; name: value    <-- this is a tag with a value
-@end smallexample
-@cindex searching for tags
-@cindex tags, searching for
-Tags with value can be searched for just like tags.  In addition, you  
-can further limit your tag search by looking for only those tags that  
-have specific values:
-
-@smallexample
-   ledger reg %name=value
-   ledger reg tag name=value
-@end smallexample
-@findex group-by "tag('foo')"
-@cindex group by tags
-The group-by and sort functions also support tags:
-@smallexample
-ledger --group-by "tag('foo')" bal 
-@end smallexample
-Will produce a balance summary of all transaction with tag `foo' group
-by transactions with the same value for `foo'.
-
-@smallexample
-ledger reg --sort "tag('foo')" %foo
-@end smallexample
-Produces a register view with the transaction have tag `foo' sorted by
-the tags value.
-
-Comments that occur before an entry, or which starts at column zero, are
-always ignored and are neither searched nor printed back.
-
-If a posting comment is a date (with brackets), it modifies the date for that posting:
-@smallexample
-2010/02/01 Sample
-  Assets:Bank  $400.00
-  Income:Check  $-400.00 ; [2010/01/01]
-@end smallexample
-You can use meta-data to override the payee field for individual postings within a transaction: (source)
-@cindex overriding payee using meta-data
-@cindex meta-data, overriding payee
-@smallexample 
-2010/06/17 Sample
-  Assets:Bank  $400.00
-  Income:Check1  $-100.00 ; Payee: Person One
-  Income:Check2  $-100.00 ; Payee: Person Two
-  Income:Check3  $-100.00 ; Payee: Person Three
-  Income:Check4  $-100.00 ; Payee: Person Four
-@end smallexample
-Meta-data are normally strings, but you can create meta-data of other types:
-
-@smallexample 
-2010/06/17 Sample
-  Assets:Bank  $400.00
-  Income:Check1  $-100.00
-  ; Date:: [2010/09/01]
-  ; Amount:: $100.00
-@end smallexample
-(Note that this Date tag is not the same as the posting date.)
-
-@cindex @@tag directive
-@cindex tags, applying to several transactions.
-You apply a tag or tags to a group of transactions by surrounding them with a @code{@@tag ... @@end tag} block.
-For example, if you wanted a
-conceptual ``page'' of transactions relating to business trip to
-Chicago, you could do this:
-
-@smallexample
- @@tag Location: Chicago
- @@tag Purpose: Business
-
- ... transactions go here
-
- @@end tag 
- @@end tag
-@end smallexample
-It would be as if you'd applied "; Location: Chicago", etc., to every transaction.
-
-@node Multiple Account Transactions, Virtual Transactions, Transaction Notes and Tags, Advanced Transactions
-@subsection Multiple Account Transactions
-
-Often times a transaction needs to be split across several accounts.
-This is trivially simple in a Ledger journal:
-
-@cindex splitting transactions across accounts
-@cindex transactions, splitting across accounts
-@smallexample
-2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck
-    Income:Taxable:Acme Bytepumps Inc.     $-2500.00
-    Assets:Brokerage:Checking                $175.00
-    Assets:Investments:401K Deferred         $250.00
-    Expenses:Tax:Medicare                     $36.25
-    Expenses:Tax:Federal Tax                 $200.00
-    Expenses:Tax:State Tax                    $20.00
-    Expenses:Insurance:Life                   $18.75
-    Assets:Credit Union:Joint Checking     
-@end smallexample
-
-This is an example of a paycheck entry.  The money comes @strong{out} of your
-income account, and is spent into several other accounts.  The last line
-doesn't require an amount, as ledger will automatically balance the
-transaction (it will be $1800 into the Joint Checking account)
-
-
-@node Virtual Transactions, Automatic Transactions, Multiple Account Transactions, Advanced Transactions
-@subsection Virtual Transactions
-
-
-A virtual posting is when you, in your mind, see money as moving
-to a certain place, when in reality that money has not moved at all.
-There are several scenarios in which this type of tracking comes in
-handy, and each of them will be discussed in detail.
-
-To enter a virtual posting, surround the account name in
-parentheses.  This form of usage does not need to balance.  However,
-if you want to ensure the virtual posting balances with other
-virtual postings in the same transaction, use square brackets.  For
-example:
-
-@smallexample
-10/2 Paycheck
-    Assets:Checking                        $1000.00
-    Income:Salary                         $-1000.00
-    (Debt:Alimony)                          $200.00
-@end smallexample
-
-In this example, after receiving a paycheck an alimony debt is
-increased---even though no money has moved around yet.
-
-@smallexample
-10/2  Paycheck
-    Assets:Checking                        $1000.00
-    Income:Salary                         $-1000.00
-    [Savings:Trip]                          $200.00
-    [Assets:Checking]                      $-200.00
-@end smallexample
-
-In this example, $200 has been deducted from checking toward savings
-for a trip.  It will appear as though the money has been moved from
-the account into @samp{Savings:Trip}, although no money has actually
-moved anywhere.
-
-When balances are displayed, virtual postings will be factored in.
-To view balances without any virtual balances factored in, using the
-@option{-R} flag, for ``reality''.
-
-
-@node Automatic Transactions, Checking Balances and Reconciliations, Virtual Transactions, Advanced Transactions
-@subsection Automatic 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 posting at the top of your ledger file:
-
-@smallexample
-; This automated transaction will compute Huqúqu'lláh based on this
-; journal's postings.  Any that match will affect the
-; Liabilities:Huququ'llah account by 19% of the value of that posting.
-
-= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
-  (Liabilities:Huququ'llah)               0.19
-@end smallexample
-
-This automated posting works by looking at each posting in the
-ledger file.  If any match the given value expression, 19% of the
-posting's value is applied to the @samp{Liabilities:Huququ'llah}
-account.  So, if $1000 is earned from @samp{Income:Salary}, $190 is
-added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent,
-$190 is subtracted.  The ultimate balance of Huqúqu'lláh reflects how
-much is owed in order to fulfill one's obligation to Huqúqu'lláh.
-When ready to pay, just write a check to cover the amount shown in
-@samp{Liabilities:Huququ'llah}.  That transaction would look like:
-
-@smallexample
-2003/01/01 (101) Baha'i Huqúqu'lláh Trust
-    Liabilities:Huququ'llah          $1,000.00
-    Assets:Checking
-@end smallexample
-
-That's it.  To see how much Huqúq is currently owed based on your
-ledger transactions, use:
-
-@smallexample
-ledger balance Liabilities:Huquq
-@end smallexample
-
-This works fine, but omits one aspect of the law: that Huqúq is only
-due once the liability exceeds the value of 19 mithqáls of gold (which
-is roughly 2.22 ounces).  So what we want is for the liability to
-appear in the balance report only when it exceeds the present day
-value of 2.22 ounces of gold.  This can be accomplished using the
-command:
-
-@smallexample
-ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab
-@end smallexample
-
-With this command, the current price for gold is downloaded, and the
-Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces
-of gold.  If you wish the liability to be reflected in the parent
-subtotal either way, use this instead:
-
-@smallexample
-ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab
-@end smallexample
-
-In some cases, you may wish to refer to the account of whichever
-posting matched your automated transaction's value expression.  To do
-this, use the special account name @samp{$account}:
-
-@smallexample
-= /^Some:Long:Account:Name/
-  [$account]  -0.10
-  [Savings]    0.10
-@end smallexample
-
-This example causes 10% of the matching account's total to be deferred
-to the @samp{Savings} account---as a balanced virtual posting,
-which may be excluded from reports by using @option{--real}.
-
-Automated transactions can use the full range of value expressions in
-their predicate.  If you wanted to specify a transaction only occur to
-certain accounts that meet certain value criteria you could specify:
-
-@smallexample
-= /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000)
-  Expenses:Tax  0.27
-@end smallexample
-In this case, @samp{amount} is tied to the amount of the posting being
-tested.
-
-But, wait! There's more!
-
-@cindex Tax Bracket automation
-@cindex value expressions in automatic transactions
-
-In the short example above we calculated the taxes due for income within
-a certain bracket.  But in reality this calculation is more difficult.
-There are different rates for different marginal incomes and those taxes
-are not easily described by a simple multiplicative coefficient.
-Automated transactions can use value expressions in their postings to
-determine the amounts.  So to expand the example above for a three tax
-bracket system we could enter:
-
+In order to combat inconsistency you can define allowable accounts and
+or payees.  For simplicity, create a separate text file and enter define
+accounts a payees like
 @smallexample
-= /Employees:.*:Payroll$/ and expr (amount < $10000.00)
-  (Expenses:Tax)  0.1
-= /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 )
-  (Expenses:Tax)  ($1000.00 + .15 * (amount - $10000.00))
-= /Employees:.*:Payroll$/ and expr (amount > $100000.00)
-  (Expenses:Tax)  ($13500.00 + .20 * (amount-$100000.00))
-@end smallexample
-
-@node Checking Balances and Reconciliations, Effective Dates, Automatic Transactions, Advanced Transactions
-@subsection Forcing balances and Reconciling Accounts
-
-
-Ledger has a feature for ensuring known past balances.  Here's
-an example entry:
-@cindex forcing a balance
-@cindex balance verification
-@smallexample
-   2008/11/26 (Interest) EXTND INS SWEEP ACCT(FDIC-INS)
-       * Assets:Brokerage                 $0.07 = $970.64
-       Income:Interest                   $-0.07
-@end smallexample
-
-What this says is that as of 11/26/08 (bank perspective), the
-Assets:Brokerage account was known to equal $970.64.  It @strong{must}
-equal this amount at this point in the Ledger file, or there will be a
-balancing error.
-
-If you reconcile bank statements you can enter the reconciliation and
-link to a file (if you have it)
-@cindex statement reconciliation
-@cindex reconcile statements
-
-@smallexample
-2009/12/01 Foo
-    Assets:Checking    $10.00
-    Equity
-
-2009/12/10 Reconciled statement dated 2009/12/08
-    ; Link: [[file:statements/checking/2009-12.pdf][2009-12.pdf]]
-    [Assets:Checking]    = $10.00
-@end smallexample
-
-@node Effective Dates, Periodic Transactions, Checking Balances and Reconciliations, Advanced Transactions
-@subsection Effective Dates
-@cindex effective dates
-
-In the real world transactions do not take place instantaneously.
-Purchases can take several days to post to a bank account. And you may
-pay ahead for something for which you want to distribute costs.  With
-Ledger you can control every aspect of the timing of a transaction.
-
-Say you're in business.  If you bill a customer, you can enter
-something like
-@cindex effective date of invoice
-@smallexample
-2008/01/01=2008/01/14 Client invoice  ;  estimated date you'll be paid
-  Assets:Accounts Receivable            $100.00
-  Income: Client name
-@end smallexample
-@noindent Then, when you receive the payment, you change it to
-
-@smallexample
-2008/01/01=2008/01/15 Client invoice ;  actual date money received
-  Assets:Accounts Receivable            $100.00
-  Income: Client name
-@end smallexample
-@noindent and add something like
-
-@smallexample
-2008/01/15 Client payment
-  Assets:Checking                       $100.00
-  Assets:Accounts Receivable
+account Expenses
+account Expenses:Utilities
+...
 @end smallexample
-Now
-
+Using the @samp{--strict} option will cause Ledger to complain if any accounts are not previously defined:
 @smallexample
-  ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
+15:27:39 ~/ledger (next) > ledger bal --strict
+Warning: "FinanceData/Master.dat", line 6: Unknown account 'Liabilities:Tithe Owed'
+Warning: "FinanceData/Master.dat", line 8: Unknown account 'Liabilities:Tithe Owed'
+Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities:Domestic'
 @end smallexample
-@noindent gives you your accrued income in the first two weeks of the year, and
-@smallexample
-  ledger --effective --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
-@end smallexample
-@noindent gives you your cash basis income in the same two weeks.
-
-Another use is distributing costs out in time. As an example, suppose
-you just prepaid into a local vegetable co-op that sustains you through
-the winter.  It cost $225 to join the program, so you write a check.
-You don't want your October grocery budget to be blown because you bought
-food ahead, however.  What you really want is for the money to be evenly
-distributed over the next six months so that your monthly budgets
-gradually take a hit for the vegetables you'll pick up from the co-op,
-even though you've already paid for them.
 
+If you have a large Ledger register already created use the @samp{accounts} command to get started:
 @smallexample
-2008/10/16 * (2090) Bountiful Blessings Farm
-    Expenses:Food:Groceries                  $ 37.50  ; [=2008/10/01]
-    Expenses:Food:Groceries                  $ 37.50  ; [=2008/11/01]
-    Expenses:Food:Groceries                  $ 37.50  ; [=2008/12/01]
-    Expenses:Food:Groceries                  $ 37.50  ; [=2009/01/01]
-    Expenses:Food:Groceries                  $ 37.50  ; [=2009/02/01]
-    Expenses:Food:Groceries                  $ 37.50  ; [=2009/03/01]
-    Assets:Checking 
+ledger accounts >> Accounts.dat
 @end smallexample
 
-This entry accomplishes this.  Every month until you'll start with an
-automatic $37.50 deficit like you should, while your checking account
-really knows that it debited $225 this month.
-
-
-@node Periodic Transactions, Recording Commodity Lot Prices, Effective Dates, Advanced Transactions
-@subsection Periodic Transactions
-
-A periodic transaction starts with a ~ followed by a period expression.
-Periodic transactions are used for budgeting and forecasting only, they
-have no effect without the @samp{--budget} option specified.
-
-See @ref{Budgeting and Forecasting} for examples and details.
+@noindent You will have to edit this file to add the @samp{account} directive.
 
-@node Recording Commodity Lot Prices,  , Periodic Transactions, Advanced Transactions
-@subsection Recording Commodity Lot Prices
-
-If you are tracking investments it is often necessary to keep track of
-specific purchases of a commodity bought at difference prices.  These
-specific purchases are referred to as ``lots''.  Tracking lots using ledger
-requires some additional info in the journal as well as additional
-command-line options when generating reports.
-
-Say you want to record purchase of two separate lots of ACME, then sell
-some shares.  The correct way to do this is:
-
-@smallexample
-2010-09-01 * Buy 2 shares of ACME @@ $100
-   Assets:Broker                                  2 ACME @@ $100.00
-   Assets:Cash
-
-2010-09-10 * Buy 2 share of ACME @@ $110
-   Assets:Broker                                  2 ACME @@ $110.00
-   Assets:Cash
-
-2011-09-20 * Sell 2 shares of ACME @@ $150
-   Assets:Broker                       -1 ACME @{$100.00@} @@ $150.00
-   Assets:Broker                       -1 ACME @{$200.00@} @@ $150.00
-   Assets:Cash
-@end smallexample
-
-To report which lots of commodities you hold, use the
-@samp{--lot-prices} option.  For example, after buying the 2 shares at
-$100 and 1 at $200 it would show you:
-@smallexample
-$ ledger balance --lot-prices Assets:Broker until 2011-09-15
-    2 ACME @{$100.00@}
-    1 ACME @{$200.00@}  Assets:Broker
-@end smallexample
-@noindent without the @samp{--lot-prices} option you would only see the total number of shares you held:
-@smallexample
-$ ledger balance  Assets:Broker until 2011-09-15
-    3 ACME  Assets:Broker
-@end smallexample
-@noindent and after the sale on @samp{2011-09-20} it would show you:
-@smallexample
-$ ledger balance --lot-prices Assets:Broker
-    1 ACME @{$100.00@}  Assets:Broker
-@end smallexample
+@node Journal Format, Archiving Previous Years , Keeping it Consistent, Keeping a Journal
+@section Journal 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.
 
-@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal
-@section File Format for Users
 @menu
-* File Format Intro::           
 * Transaction and Comments::    
 * Command Directives::          
 @end menu
 
-@node File Format Intro, Transaction and Comments, File Format, File Format
-@subsection Introduction
-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.
-
-@node Transaction and Comments, Command Directives, File Format Intro, File Format
+@node Transaction and Comments, Command Directives, Journal Format, Journal Format
 @subsection Transactions and Comments
 The initial character of each line determines what the line means, and
 how it should be interpreted.  Allowable initial characters are:
@@ -2232,7 +1801,7 @@ posting cost, by specifying @samp{@@ AMOUNT}, or a complete
 posting cost with @samp{@@@@ AMOUNT}.  Lastly, the @samp{NOTE} may
 specify an actual and/or effective date for the posting by using
 the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
-@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual Transactions})
+@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual postings})
 
 @item P
 Specifies a historical price for a commodity.  These are usually found
@@ -2249,7 +1818,7 @@ sign.
 After this initial line there should be a set of one or more
 postings, just as if it were normal transaction.  If the amounts of the
 postings have no commodity, they will be applied as modifiers to
-whichever real posting is matched by the value expression(See @pxref{Automatic Transactions}).
+whichever real posting is matched by the value expression(See @pxref{Automated transactions}).
 
 @item ~
 A period transaction.  A period expression must appear after the tilde.
@@ -2268,17 +1837,61 @@ tags can be used to augment the reporting and filtering capabilities of
 Ledger.
 @end table
 
-@node Command Directives,  , Transaction and Comments, File Format
+@node Command Directives,  , Transaction and Comments, Journal Format
 @subsection Command Directives
 
 @table @code
-@item ! @@
-A line beginning with an exclamation mark or an @@ sign denotes a
-command directive.  It must be immediately followed by a command word.
-The supported commands are:
+@item beginning of line
+Command directives must occur at the beginning of a line.  Use of ! and
+@@ is deprecated.
+
+@item account
+
+Pre-declare valid account names.  This only has effect if
+@samp{--strict} or @samp{--pedantic} is used (see below).  The
+@samp{account} directive supports several optional sub-directives, if
+they immediately follow the account directive and if they begin with
+whitespace:
+
+@smallexample
+ account Expenses:Food
+     note This account is all about the chicken!
+     alias food
+     payee ^(KFC|Popeyes)$
+     check commodity == "$"
+     assert commodity == "$"
+     eval print("Hello!")
+     default
+@end smallexample
+
+The @samp{note} sub-directive associates a textual note with the account.  This can
+be accessed later using the @samp{note} valexpr function in any account context.
+
+The @samp{alias} sub-directive, which can occur multiple times, allows the alias to
+be used in place of the full account name anywhere that account names are
+allowed.
+
+The @samp{payee} sub-directive, which can occur multiple times, provides regexps
+that identify the account if that payee is encountered and an account within
+its transaction ends in the name "Unknown".  Example:
+
+@smallexample
+ 2012-02-27 KFC
+     Expenses:Unknown      $10.00  ; Read now as "Expenses:Food"
+     Assets:Cash
+@end smallexample
 
+The @samp{check} and @samp{assert} directives warn or error (respectively) if the given
+value expression evaluates to false within the context of any posting.
 
-@item @@account
+The @samp{eval} directive evaluates the value expression in the context of the
+account at the time of definition.  At the moment this has little value.
+
+The @samp{default} directive specifies that this account should be used as the
+``balancing account'' for any future transactions that contain only a single
+posting.
+
+@item apply account
 @c instance_t::master_account_directive
 Sets the root for all accounts following the directive.  Ledger supports
 a hierarchical tree of accounts.  It may be convenient to keep two
@@ -2288,27 +1901,26 @@ could preface all personal accounts with @code{personal:} and all
 business account with @code{business:}.  You can easily split out large
 groups of transaction without manually editing them using the account
 directive.  For example:
-@smallexample
 
-@@account Personal
+@smallexample
+apply account Personal
 2011/11/15  Supermarket
     Expenses:Groceries
     Assets:Checking
-
 @end smallexample
 
 Would result in all postings going into
 @code{Personal:Expenses:Groceries} and @code{Personal:Assets:hecking}
-until and @code{@@end account}  directive was found.
+until and @code{end apply account}  directive was found.
 
-@item @@alias
+@item alias
 @c instance_t::alias_directive
 Define an alias for an account name.  If you have a deeply nested tree
 of accounts, it may be convenient to define an alias, for example:
 @smallexample
 
-@@alias Dining=Expenses:Entertainment:Dining
-@@alias Checking=Assets:Credit Union:Joint Checking Account
+alias Dining=Expenses:Entertainment:Dining
+alias Checking=Assets:Credit Union:Joint Checking Account
 
 2011/11/28 YummyPalace 
    Dining        $10.00
@@ -2317,32 +1929,32 @@ of accounts, it may be convenient to define an alias, for example:
 @end smallexample
 
 The aliases are only in effect for transactions read in after the alias
-is defined and are effected by @code{@@account} directives that precede
+is defined and are effected by @code{account} directives that precede
 them.
-@item @@assert
+@item assert
 @c instance_t::assert_directive
 An assertion can throw an error if a condition is not met during Ledger's run. 
 
 @smallexample
 
-@@assert <VALUE EXPRESSION BOOLEAN RESULT>
+assert <VALUE EXPRESSION BOOLEAN RESULT>
 
 @end smallexample
 
 
-@item @@bucket
+@item bucket
 @c instance_t::default_account_directive
 Defines the default account to use for balancing transactions.
 Normally, each transaction has at least two postings, which must balance
 to zero.  Ledger allows you to leave one posting with no amount and
 automatically calculate balance the transaction in the posting.  The
-@code{@@bucket} allows you to fill in all postings and automatically
+@code{bucket} allows you to fill in all postings and automatically
 generate an additional posting to the bucket account balancing the
 transaction.  The following example set the @code{Assets:Checking} as
 the bucket:
 @smallexample
 
-@@bucket Assets:Checking
+bucket Assets:Checking
 2011/01/25 Tom's Used Cars
   Expenses:Auto                    $ 5,500.00
 
@@ -2354,13 +1966,13 @@ the bucket:
 
 @end smallexample
 
-@item @@capture
+@item capture
 @c instance_t::account_mapping_directive
 Directs Ledger to replace any account matching a regex with the given
 account. For example:
 
 @smallexample
-@@capture  Expenses:Deductible:Medical  Medical
+capture  Expenses:Deductible:Medical  Medical
 @end smallexample
 
 Would cause any posting with @code{Medical} in it's name to be replaced with
@@ -2370,23 +1982,55 @@ Would cause any posting with @code{Medical} in it's name to be replaced with
 Ledger will display the mapped payees in @code{print} and
 @code{register} reports.
 
-@item @@check
+@item check
 @c instance_t::check_directive in textual.cc
 A check can issue a warning if a condition is not met during Ledger's run. 
 
 @smallexample
 
-@@check <VALUE EXPRESSION BOOLEAN RESULT>
+check <VALUE EXPRESSION BOOLEAN RESULT>
 
 @end smallexample
-@item @@comment
+@item comment
 @c instance_t::comment_directive in textual.cc
-Start a block comment, closed by @code{@@end comment}.
-@item @@define
+Start a block comment, closed by @code{end comment}.
+
+@item commodity
+Pre-declare commodity names.  This only has effect if @samp{--strict} or
+@samp{--pedantic} is used (see below).
+
+ commodity $
+ commodity CAD
+
+The @samp{commodity} directive supports several optional sub-directives, if they
+immediately follow the commodity directive and if they begin with whitespace:
+
+@smallexample
+ commodity $
+   note American Dollars
+   format $1,000.00
+   nomarket
+   default
+@end smallexample
+
+The @samp{note} sub-directive associates a textual note with the commodity.  At
+present this has no value other than documentation.
+
+The @samp{format} directive gives you a way to tell Ledger how to format this
+commodity.  In future using this directive will disable Ledger's observation
+of other ways that commodity is used, and will provide the ``canonical''
+representation.
+
+The @samp{nomarket} directive states that the commodity's price should never be
+auto-downloaded.
+
+The @samp{default} directive marks this as the ``default'' commodity.
+
+@item define
 @c instance_t::define_directive in textual.cc
 Allows you to define value expression for future use. For example:
 @smallexample
-@@define var_name=$100
+define var_name=$100
 
 2011/12/01 Test
    Expenses  (var_name*4)
@@ -2394,41 +2038,46 @@ Allows you to define value expression for future use. For example:
 @end smallexample
 
 The posting will have a cost of $400.
-@item @@end
+@item end
 @c instance_t::end_directive in textual.cc
-Closes block commands like @code{@@tag} or @code{@@comment}.
-@item @@expr
+Closes block commands like @code{tag} or @code{comment}.
+@item expr
 @c instance_t::expr_directive in textual.cc
 
-@item @@fixed
+@item fixed
 @c instance_t::fixed_directive in textual.cc
 
-@item @@include
+@item include
 @c instance_t::include_directive in textual.cc
 Include the stated file as if it were part of the current file.
 
-@item @@payee
+@item payee
 @c instance_t::payee_mapping_directive in textual.cc
-Directs Ledger to replace any payee matching a regex with the given
-payee.  You may download transactions from your bank that you want to be
-shortened or altered.  For example, the the payee for the grocery store
-near me is only one character different than the payee if I buy gasoline
-at the grocery story.  I can enter payee mappings that make this very clear:
+The @samp{payee} directive supports one optional sub-directive, if it immediately
+follows the payee directive and if it begins with whitespace:
+
+@smallexample
+ payee KFC
+     alias KENTUCKY FRIED CHICKEN
+@end smallexample
+
+The @samp{alias} directive provides a regexp which, if it matches a parsed payee,
+the declared payee name is substituted:
 
 @smallexample
-@@payee  Supermarket Gas  Supermarket 4
-@@payee  Supermarket Groceries  Supermarket 1
+ 2012-02-27 KENTUCKY FRIED CHICKEN  ; will be read as being 'KFC'
+   ...
 @end smallexample
 
 Ledger will display the mapped payees in @code{print} and
 @code{register} reports.
 
-@item @@tag
+@item apply tag
 @c instance_t::tag_directive in textual.cc
 Allows you to designate a block of transactions and assign the same tag to all.  Tags can have values and may be nested.
 @smallexample
-@@tag hastag
-@@tag nestedtag: true
+apply tag hastag
+apply tag nestedtag: true
 2011/01/25 Tom's Used Cars
   Expenses:Auto                    $ 5,500.00
   ; :nobudget:
@@ -2438,12 +2087,12 @@ Allows you to designate a block of transactions and assign the same tag to all.
   Expenses:Books                       $20.00
   Liabilities:MasterCard
 
-@@end tag nestedtag
+end apply tag nestedtag
 
 2011/12/01 Sale
   Assets:Checking:Business            $ 30.00
   Income:Sales
-@@end tag hastag
+end apply tag hastag
 @end smallexample
 
 @noindent is the equivalent of
@@ -2468,18 +2117,42 @@ Allows you to designate a block of transactions and assign the same tag to all.
   Income:Sales
 @end smallexample
 
-Note that anything following "@code{@@end tag}" is ignored.  placing the
+Note that anything following ``@code{end tag}'' is ignored.  placing the
 name of the tag that is being closed is a simple way to keep track.
 
-@item @@test
+@item tag
+Pre-declares tag names.  This only has effect if @samp{--strict} or
+@samp{--pedantic} is used (see below).
+
+@smallexample
+ tag Receipt
+ tag CSV
+@end smallexample
+
+The 'tag' directive supports two optional sub-directives, if they immediately
+follow the tag directive and if they begin with whitespace:
+
+@smallexample
+ tag Receipt
+   check value =~ /pattern/
+   assert value != "foobar"
+@end smallexample
+
+The @samp{check} and @samp{assert} directives warn or error (respectively) if the given
+value expression evaluates to false within the context of any use of the
+related tag.  In such a context, ``value'' is bound to the value of the tag
+(which may not be a string if typed-metadata is used!).  Such checks or
+assertions are not called if no value is given.
+
+@item test
 @c instance_t::comment_directive in textual.cc
-This is a synonym for @code{@@comment} and must be closed by and @code{@@end} tag.
+This is a synonym for @code{comment} and must be closed by and @code{end} tag.
 
-@item @@year
+@item year
 @c instance_t::year_directive in textual.cc
 Denotes the year used for all subsequent transactions that give a date
 without a year.  The year should appear immediately after the Y, for
-example: @samp{@@year 2004}.  This is useful at the beginning of a file, to
+example: @samp{year 2004}.  This is useful at the beginning of a file, to
 specify the year for that file.  If all transactions specify a year,
 however, this command has no effect.
 
@@ -2491,9 +2164,9 @@ alone, for backwards compatibility with older Ledger versions.
 
 @table @code
 @item A
-See @code{@@bucket}
+See @code{bucket}
 @item Y 
-See @code{@@year}
+See @code{year}
 
 
 @item N SYMBOL
@@ -2532,7 +2205,7 @@ timelog files.  See the timeclock's documentation for more info on the
 syntax of its timelog files.
 @end table
 
-@node Archiving Previous Years , Using Emacs, File Format, Keeping a Journal
+@node Archiving Previous Years , Using Emacs, Journal Format, Keeping a Journal
 @section Archiving Previous Years
 
 
@@ -2792,7 +2465,1112 @@ kill the report buffer
 
 
 
-@node Building Reports, Reporting Commands, Keeping a Journal, Top
+
+@node Transactions , Building Reports, Keeping a Journal, Top
+@chapter  Transactions 
+@menu
+* Basic format::                
+* Eliding amounts::             
+* Auxiliary dates::             
+* Codes::                       
+* Transaction state::           
+* Transaction notes::           
+* Metadata::                    
+* Virtual postings::            
+* Expression amounts::          
+* Balance verification::        
+* Posting cost::                
+* Explicit posting costs::      
+* Posting cost expressions::    
+* Total posting costs::         
+* Virtual posting costs::       
+* Commodity prices::            
+* Prices vs. costs::            
+* Lot dates::                   
+* Lot notes::                   
+* Lot value expressions::       
+* Automated transactions::      
+@end menu
+
+@node Basic format, Eliding amounts, Transactions , Transactions
+@section Basic format
+
+
+The most basic form of transaction is:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash                 $-20.00
+@end smallexample
+
+This transaction has a date, a payee or description, a target account (the
+first posting), and a source account (the second posting).  Each posting
+specifies what action is taken related to that account.
+
+A transaction can have any number of postings:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash                 $-10.00
+       Liabilities:Credit          $-10.00
+@end smallexample
+
+@node Eliding amounts, Auxiliary dates, Basic format, Transactions
+@section  Eliding amounts
+
+The first thing you can do to make things easier is elide amounts.  That is,
+if exactly one posting has no amount specified, Ledger will infer the inverse
+of the other postings' amounts:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash                 $-10.00
+       Liabilities:Credit                   ; same as specifying $-10
+@end smallexample
+
+@noindent If the other postings use multiple commodities, Ledger will copy the empty
+posting N times and fill in the negated values of the various commodities:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Expenses:Tips                 $2.00
+       Assets:Cash              EUR -10.00
+       Assets:Cash              GBP -10.00
+       Liabilities:Credit
+@end smallexample
+
+@noindent This transaction is identical to writing:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Expenses:Tips                 $2.00
+       Assets:Cash              EUR -10.00
+       Assets:Cash              GBP -10.00
+       Liabilities:Credit          $-22.00
+       Liabilities:Credit        EUR 10.00
+       Liabilities:Credit        GBP 10.00
+@end smallexample
+
+@node Auxiliary dates, Codes, Eliding amounts, Transactions
+@section Auxiliary dates
+
+You can associate a second date with a transaction by following the primary
+date with an equals sign:
+
+@smallexample
+   2012-03-10=2012-03-08 KFC
+       Expenses:Food                $20.00
+       Assets:Cash                 $-20.00
+@end smallexample
+
+What this auxiliary date means is entirely up to you.  The only use Ledger has
+for it is that if you specify --aux-date, then all reports and calculations
+(including pricing) will use the aux date as if it were the primary date.
+
+@node Codes, Transaction state, Auxiliary dates, Transactions
+@section Codes
+
+A transaction can have a textual "code".  This has no meaning and is only
+displayed by the print command.  Checking accounts often use codes like DEP,
+XFER, etc., as well as check numbers.  This is to give you a place to put
+those codes:
+
+@smallexample
+   2012-03-10 (#100) KFC
+       Expenses:Food                $20.00
+       Assets:Checking
+@end smallexample
+
+@node Transaction state, Transaction notes, Codes, Transactions
+@section Transaction state
+
+A transaction can have a ``state'': cleared, pending, or uncleared.  The default
+is uncleared.  To mark a transaction cleared, put a * before the payee, and
+after date or code:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+@noindent To mark it pending, use a !:
+
+@smallexample
+   2012-03-10 ! KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+What these mean is entirely up to you.  The --cleared option will limits to
+reports to only cleared items, while --uncleared shows both uncleared and
+pending items, and --pending shows only pending items.
+
+I use cleared to mean that I've reconciled the transaction with my bank
+statement, and pending to mean that I'm in the middle of a reconciliation.
+
+
+When you clear a transaction, that's really just shorthand for clearing all of
+its postings.  That is:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+@noindent Is the same as writing:
+
+@smallexample
+   2012-03-10 KFC
+       * Expenses:Food                $20.00
+       * Assets:Cash
+@end smallexample
+
+@noindent You can mark individual postings as cleared or pending, in case one "side" of
+the transaction has cleared, but the other hasn't yet:
+
+@smallexample
+   2012-03-10 KFC
+       Liabilities:Credit            $100.00
+       * Assets:Checking
+@end smallexample
+
+@node Transaction notes, Metadata, Transaction state, Transactions
+@section Transaction notes
+
+After the payee, and after at least one tab or two spaces (or a space
+and a tab, which Ledger calls this a ``hard separator''), you may
+introduce a note about the transaction using the ; character:
+
+@smallexample
+   2012-03-10 * KFC                ; yum, chicken...
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+@noindent Notes can also appear on the next line, so long as that line begins with
+whitespace:
+
+@smallexample
+   2012-03-10 * KFC                ; yum, chicken...
+       ; and more notes...
+       Expenses:Food                $20.00
+       Assets:Cash
+
+   2012-03-10 * KFC
+       ; just these notes...
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+
+A transaction note is shared by all its postings.  This becomes significant
+when querying for metadata (see below).  To specify that a note belongs only
+to one posting, place it after a hard separator after the amount, or on its
+own line preceded by whitespace:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00  ; posting #1 note
+       Assets:Cash
+         ; posting #2 note, extra indentation is optional
+@end smallexample
+
+@node Metadata, Virtual postings, Transaction notes, Transactions
+@section Metadata
+
+One of Ledger's more powerful features is the ability to associate typed
+metadata with postings and transactions (by which I mean all of a
+transaction's postings).  This metadata can be queried, displayed, and used in
+calculations.
+
+The are two forms of metadata: tags and tag/value pairs.
+
+@menu
+* Metadata tags::               
+* Metadata values::             
+* Typed metadata::              
+@end menu
+
+@node Metadata tags, Metadata values, Metadata, Metadata
+@subsection Metadata tags
+
+To tag an item, put any word not containing whitespace between two colons:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+         ; :TAG:
+@end smallexample
+
+You can gang up multiple tags by sharing colons:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+         ; :TAG1:TAG2:TAG3:
+@end smallexample
+
+@node Metadata values, Typed metadata, Metadata tags, Metadata
+@subsection Metadata values
+
+To associate a value with a tag, use the syntax "Key: Value", where the value
+can be any string of characters.  Whitespace is needed after the colon, and
+cannot appear in the Key:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+         ; MyTag: This is just a bogus value for MyTag
+@end smallexample
+
+@node Typed metadata,  , Metadata values, Metadata
+@subsection Typed metadata
+
+If a metadata tag ends in ::, it's value will be parsed as a value expression
+and stored internally as a value rather than as a string.  For example,
+although I can specify a date textually like so:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+         ; AuxDate: 2012/02/30
+@end smallexample
+
+@noindent This date is just a string, and won't be parsed as a date unless its value is
+used in a date-context (at which time the string is parsed into a date
+automatically every time it is needed as a date).  If on the other hand I
+write this:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+         ; AuxDate:: [2012/02/30]
+@end smallexample
+
+@noindent Then it is parsed as a date only once, and during parsing of the journal file,
+which would let me know right away that it is an invalid date.
+
+@node Virtual postings, Expression amounts, Metadata, Transactions
+@section  Virtual postings
+
+Ordinarily, the amounts of all postings in a transaction must balance to zero.
+This is non-negotiable.  It's what double-entry accounting is all about!  But
+there are some tricks up Ledger's sleeve...
+
+You can use virtual accounts to transfer amounts to an account on the sly,
+bypassing the balancing requirement.  The trick is that these postings are not
+considered ``real'', and can be removed from all reports using @samp{--real}.
+
+To specify a virtual account, surround the account name with parentheses:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+       (Budget:Food)               $-20.00
+@end smallexample
+
+If you want, you can state that virtual postings @emph{should} balance against
+one or more other virtual postings by using brackets (which look ``harder'')
+rather than parentheses:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+       [Budget:Food]               $-20.00
+       [Equity:Budgets]             $20.00
+@end smallexample
+
+@node Expression amounts, Balance verification, Virtual postings, Transactions
+@section Expression amounts
+
+An amount is usually a numerical figure with an (optional) commodity, but it
+can also be any value expression.  To indicate this, surround the amount
+expression with parentheses:
+
+@smallexample
+   2012-03-10 * KFC
+       Expenses:Food      ($10.00 + $20.00)  ; Ledger adds it up for you
+       Assets:Cash
+@end smallexample
+
+@node Balance verification, Posting cost, Expression amounts, Transactions
+@section Balance verification
+@menu
+* Balance assertions::          
+* Balance assignments::         
+* Resetting a balance::         
+* Balancing transactions::      
+@end menu
+
+If at the end of a posting's amount (and after the cost too, if there is one)
+there is an equals sign, then Ledger will verify that the total value for that
+account as of that posting matches the amount specified.
+
+There are two forms of this features: balance assertions, and balance
+assignments.
+
+
+@node Balance assertions, Balance assignments, Balance verification, Balance verification
+@subsection Balance assertions
+
+A balance assertion has this general form:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash                 $-20.00 = $500.00
+@end smallexample
+
+This simply asserts that after subtracting $20.00 from Assets:Cash, that the
+resulting total matches $500.00.  If not, it is an error.
+
+@node Balance assignments, Resetting a balance, Balance assertions, Balance verification
+@subsection Balance assignments
+
+A balance assignment has this form:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash                         = $500.00
+@end smallexample
+
+This sets the amount of the second posting to whatever it would need to be for
+the total in Assets:Cash to be $500.00 after the posting.  If the resulting
+amount is not $-20.00 in this case, it is an error.
+
+@node  Resetting a balance, Balancing transactions, Balance assignments, Balance verification
+@subsection  Resetting a balance
+
+Say your book-keeping has gotten a bit out of date, and your Ledger balance no
+longer matches your bank balance.  You can create an adjustment transaction
+using balance assignments:
+
+@smallexample
+   2012-03-10 Adjustment
+       Assets:Cash                         = $500.00
+       Equity:Adjustments
+@end smallexample
+
+Since the second posting is also null, it's value will become the inverse of
+whatever amount is generated for the first posting.
+
+This is the only time in ledger when more than one posting's amount may be
+empty -- and then only because it's not true empty, it is indirectly provided
+by the balance assignment's value.
+
+@node  Balancing transactions,  , Resetting a balance, Balance verification
+@subsection  Balancing transactions
+
+As a consequence of all the above, consider the following transaction:
+
+@smallexample
+   2012-03-10 My Broker
+       [Assets:Brokerage]            = 10 AAPL
+@end smallexample
+
+What this says is: set the amount of the posting to whatever value is needed
+so that Assets:Brokerage contains 10 AAPL.  Then, because this posting must
+balance, ensure that its value is zero.  This can only be true if
+Assets:Brokerage does indeed contain 10 AAPL at that point in the input file.
+
+A balanced virtual transaction is used simply to indicate to Ledger that this
+is not a "real" transaction.  It won't appear in any reports anyway (unless
+you use a register report with --empty).
+
+@node Posting cost, Explicit posting costs, Balance verification, Transactions
+@section Posting cost
+
+When you transfer a commodity from one account to another, sometimes it get
+transformed during the transaction.  This happens when you spend money on gas,
+for example, which transforms dollars into gallons of gasoline, or dollars
+into stocks in a company.
+
+In those cases, Ledger will remember the "cost" of that transaction for you,
+and can use it during reporting in various ways.  Here's an example of a stock
+purchase:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL
+       Assets:Brokerage:Cash       $-500.00
+@end smallexample
+
+This is different from transferring 10 AAPL shares from one account to
+another, in this case you are @emph{exchanging} one commodity for another.  The
+resulting posting cost is $50.00 per share.
+
+@node Explicit posting costs, Posting cost expressions, Posting cost, Transactions
+@section Explicit posting costs
+
+You can make any posting's cost explicit using the @ symbol after the amount
+or amount expression:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL @ $50.00
+       Assets:Brokerage:Cash       $-500.00
+@end smallexample
+
+When you do this, since Ledger can now figure out the balancing amount from
+the first posting's cost, you can elide the other amount:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL @ $50.00
+       Assets:Brokerage:Cash
+@end smallexample
+
+@menu
+* Primary and secondary commodities::  
+@end menu
+
+@node Primary and secondary commodities,  , Explicit posting costs, Explicit posting costs
+@subsection Primary and secondary commodities
+
+It is a general convention within Ledger that the "top" postings in a
+transaction contain the target accounts, while the final posting contains the
+source account.  Whenever a commodity is exchanged like this, the commodity
+moved to the target account is considered "secondary", while the commodity
+used for purchasing and tracked in the cost is "primary".
+
+Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @
+AMOUNT", the commodity used in the second amount is marked "primary".
+
+The only meaning a primary commodity has is that -V flag will never convert a
+primary commodity into any other commodity.  -X still will, however.
+
+@node Posting cost expressions, Total posting costs, Explicit posting costs, Transactions
+@section Posting cost expressions
+
+Just as you can have amount expressions, you can have posting expressions:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL @ ($500.00 / 10)
+       Assets:Brokerage:Cash
+@end smallexample
+
+You can even have both:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             (5 AAPL * 2) @ ($500.00 / 10)
+       Assets:Brokerage:Cash
+@end smallexample
+
+@node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions
+@section Total posting costs
+
+The cost figure following the @ character specifies the @emph{per-unit} price for
+the commodity being transferred.  If you'd like to specify the total cost
+instead, use @@@@:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL @@@@ $500.00
+       Assets:Brokerage:Cash
+@end smallexample
+
+Ledger reads this as if you had written:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL @@@@ ($500.00 / 10)
+       Assets:Brokerage:Cash
+@end smallexample
+
+@node Virtual posting costs, Commodity prices, Total posting costs, Transactions
+@section Virtual posting costs
+
+Normally whenever a commodity exchange like this happens, the price of the
+exchange (such as $50 per share of AAPL, above) is recorded in Ledger's
+internal price history database.  To prevent this from happening in the case
+of an exceptional transaction, surround the @@ or @@@@ with parentheses:
+
+@smallexample
+   2012-03-10 My Brother
+       Assets:Brokerage            1000 AAPL (@@) $1
+       Income:Gifts Received
+@end smallexample
+
+@node Commodity prices, Prices vs. costs, Virtual posting costs, Transactions
+@section Commodity prices
+
+When a transaction occurs that exchange one commodity for another, Ledger
+records that commodity price not only within its internal price database, but
+also attached to the commodity itself.  Usually this fact remains invisible to
+the user, unless you turn on @samp{--lot-prices} to show these hidden price figures.
+
+For example, consider the stock sale given above:
+
+@smallexample
+   2012-03-10 My Broker
+       Assets:Brokerage             10 AAPL @@ $50.00
+       Assets:Brokerage:Cash
+@end smallexample
+
+The commodity transferred into Assets:Brokerage is not actually 10 AAPL, but
+rather 10 AAPL @{$5.00@}.  The figure in braces after the amount is called the
+``lot price''.  It's Ledger's way of remembering that this commodity was
+transferred through an exchange, and that $5.00 was the price of that
+exchange.
+
+This becomes significant if you later sell that commodity again.  For example,
+you might write this:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash
+       Assets:Brokerage            -10 AAPL @@ $75.00
+@end smallexample
+
+And that would be perfectly fine, but how do you track the capital gains on
+the sale?  It could be done with a virtual posting:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash
+       Assets:Brokerage            -10 AAPL @@ $75.00
+       (Income:Capital Gains)      $-250.00
+@end smallexample
+
+But this gets messy since capital gains income is very real, and not quite
+appropriate for a virtual posting.
+
+Instead, if you reference that same hidden price annotation, Ledger will
+figure out that the price of the shares you're selling, and the cost you're
+selling them at, don't balance:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $750.00
+       Assets:Brokerage            -10 AAPL @{$50.00@} @@ $75.00
+@end smallexample
+
+This transaction will fail because the $250.00 price difference between the
+price you bought those shares at, and the cost you're selling them for, does
+not match.  The lot price also identifies which shares you purchased on that
+prior date.
+
+@menu
+* Total commodity prices::      
+@end menu
+
+@node Total commodity prices,  , Commodity prices, Commodity prices
+@subsection Total commodity prices
+
+As a shorthand, you can specify the total price instead of the per-share
+price in doubled braces.  This goes well with total costs, but is not required
+to be used with them:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $750.00
+       Assets:Brokerage            -10 AAPL @{@{$500.00@}@} @@@@ $750.00
+       Income:Capital Gains       $-250.00
+@end smallexample
+
+It should be noted that this is a convenience only for cases where you buy and
+sell whole lots.  The @{@{$500.00@}@} is @emph{not} an attribute of commodity, whereas
+@{$5.00@} is.  In fact, when you write @{@{$500.00@}@}, Ledger just divides that
+value by 10 and sees @{$50.00@}.  So if you use the print command to look at
+this transaction, you'll see the single form in the output.  The double price
+form is a shorthand only.
+
+Plus, it comes with dangers.  This works fine:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage            10 AAPL @ $50.00
+       Assets:Brokerage:Cash       $750.00
+
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{$50.00@} @@ $375.00
+       Income:Capital Gains       $-125.00
+
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{$50.00@} @@ $375.00
+       Income:Capital Gains       $-125.00
+@end smallexample
+
+@noindent But this does not do what you might expect:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage            10 AAPL @ $50.00
+       Assets:Brokerage:Cash       $750.00
+
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{@{$500.00@}@} @@ $375.00
+       Income:Capital Gains       $-125.00
+
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{@{$500.00@}@} @@ $375.00
+       Income:Capital Gains       $-125.00
+@end smallexample
+
+And in cases where the amounts do not divide into whole figure and must be
+rounded, the capital gains figure could be off by a cent.  Use with caution.
+
+@node Prices vs. costs, Lot dates, Commodity prices, Transactions
+@section Prices vs. costs
+
+Because lot pricing provides enough information to infer the cost, the
+following two transactions are equivalent:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage            10 AAPL @ $50.00
+       Assets:Brokerage:Cash       $750.00
+
+   2012-04-10 My Broker
+       Assets:Brokerage            10 AAPL @{$50.00@}
+       Assets:Brokerage:Cash       $750.00
+@end smallexample
+
+However, note that what you see in some reports may differ, for example in the
+print report.  Functionally, however, there is no difference, and neither the
+register nor the balance report are sensitive to this difference.
+
+@section Fixated prices
+
+If you buy a stock last year, and ask for its value today, Ledger will consult
+its price database to see what the most recent price for that stock is.  You
+can short-circuit this lookup by ``fixing'' the price at the time of a
+transaction.  This is done using @{=AMOUNT@}:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage            10 AAPL @{=$50.00@}
+       Assets:Brokerage:Cash       $750.00
+@end smallexample
+
+These 10 AAPL will now always be reported as being worth $50, no matter what
+else happens to the stock in the meantime.
+
+Fixated prices are a special case of using lot valuation expressions (see
+below) to fix the value of a commodity lot.
+
+@menu
+* Fixated costs::               
+@end menu
+
+@node Fixated costs,  , Prices vs. costs, Prices vs. costs
+@subsection Fixated costs
+
+Since price annotations are costs are largely interchangeable and a matter of
+preference, there is an equivalent syntax for specified fixated prices by way
+of the cost:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage            10 AAPL @@ =$50.00
+       Assets:Brokerage:Cash       $750.00
+@end smallexample
+
+This is the same as the previous transaction, with the same caveats found in
+the section ``Prices vs. costs''.
+
+@node Lot dates, Lot notes, Prices vs. costs, Transactions
+@section Lot dates
+
+In addition to lot prices, you can specify lot dates and reveal them with
+@samp{--lot-dates}.  Other than that, however, they have no special meaning to
+Ledger.  They are specified after the amount in square brackets (the same way
+that dates are parsed in value expressions):
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00
+       Income:Capital Gains       $-125.00
+@end smallexample
+
+@node Lot notes, Lot value expressions, Lot dates, Transactions
+@section Lot notes
+
+You can also associate arbitrary notes for your own record keeping in
+parentheses, and reveal them with --lot-notes.  One caveat is that the note
+cannot begin with an @ character, as that would indicate a virtual cost:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@ $375.00
+       Income:Capital Gains       $-125.00
+@end smallexample
+
+You can any combination of lot prices, dates or notes, in any order.  They are
+all optional.
+
+To show all lot information in a report, use @samp{--lots}.
+
+@node Lot value expressions, Automated transactions, Lot notes, Transactions
+@section Lot value expressions
+
+Normally when you ask Ledger to display the values of commodities held, it
+uses a value expression called ``market'' to determine the most recent value
+from its price database -- even downloading prices from the Internet, if -Q
+was specified and a suitable ``getquote'' script is found on your system.
+
+However, you can override this valuation logic by providing a commodity
+valuation expression in doubled parentheses.  This expression must result in
+one of two values: either an amount to always be used as the per-share price
+for that commodity; or a function taking three argument which is called to
+determine that price.
+
+If you use the functional form, you can either specify a function name, or a
+lambda expression.  Here's a function that yields the price as $10 in whatever
+commodity is being requested:
+
+@smallexample
+   define ten_dollars(s, date, t) = market($10, date, t)
+@end smallexample
+
+I can now use that in a lot value expression as follows:
+
+@smallexample
+   2012-04-10 My Broker
+       Assets:Brokerage:Cash       $375.00
+       Assets:Brokerage            -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00
+       Income:Capital Gains       $-125.00
+@end smallexample
+
+Alternatively, I could do the same thing without pre-defining a function by
+using a lambda expression taking three arguments:
+
+@smallexample
+   2012-04-10 My Broker
+       A:B:Cash       $375.00
+       A:B     -5 AAPL @{$50.00@} ((s, d, t -> market($10, date, t))) @@@@ $375.00
+       Income:Capital Gains       $-125.00
+@end smallexample
+
+The arguments passed to these functions have the following meaning:
+
+@itemize
+@item   source 
+        The source commodity string, or an amount object.  If it is a
+        string, the return value must be an amount representing the
+        price of the commodity identified by that string (example: ``$'').
+        If it is an amount, return the value of that amount as a new
+        amount (usually calculated as commodity price times source amount).
+
+@item   date 
+        The date to use for determining the value.  If null, it means no
+        date was specified, which can mean whatever you want it to mean.
+
+@item   target 
+        If not null, a string representing the desired target commodity
+        that the commodity price, or repriced amount, should be valued
+        in.  Note that this string can be a comma-separated list, and
+        that some or all of the commodities in that list may be suffixed
+        with an exclamation mark, to indicate what is being desired.
+@end itemize
+
+In most cases, it is simplest to either use explicit amounts in your valuation
+expressions, or just pass the arguments down to market after modifying them to
+suit your needs.
+
+@node Automated transactions,  , Lot value expressions, Transactions
+@section Automated transactions
+
+An automated transaction is a special kind of transaction which adds its
+postings to other transactions any time one of that other transactions'
+postings matches its predicate.  The predicate uses the same query syntax as
+the Ledger command line.
+
+Consider this posting:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+If I write this automated transaction before it in the file:
+
+@smallexample
+   = expr true
+       Foo                          $50.00
+       Bar                         $-50.00
+@end smallexample
+
+Then the first transaction will be modified during parsing as if I'd written
+this:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Foo                          $50.00
+       Bar                         $-50.00
+       Assets:Cash                 $-20.00
+       Foo                          $50.00
+       Bar                         $-50.00
+@end smallexample
+
+Despite this fancy logic, automated transactions themselves follow most of the
+same rules as regular transactions: their postings must balance (unless you
+use a virtual posting), you can have metadata, etc.
+
+One thing you cannot do, however, is elide amounts in an automated
+transaction.
+
+@menu
+* Amount multipliers::          
+* Accessing the matching posting's amount::  
+* Referring to the matching posting's account::  
+* Applying metadata to every matched posting::  
+* Applying metadata to the generated posting::  
+* State flags::                 
+* Effective Dates::             
+* Periodic Transactions::       
+@end menu
+
+@node Amount multipliers, Accessing the matching posting's amount, Automated transactions, Automated transactions
+@subsection Amount multipliers
+
+As a special case, if an automated transaction's posting's amount (phew) has
+no commodity, it is taken as a multiplier upon the matching posting's cost.
+For example:
+
+@smallexample
+   = expr true
+       Foo                           50.00
+       Bar                          -50.00
+
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+Then the latter transaction turns into this during parsing:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Foo                        $1000.00
+       Bar                       $-1000.00
+       Assets:Cash                 $-20.00
+       Foo                        $1000.00
+       Bar                       $-1000.00
+@end smallexample
+
+@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated transactions
+@subsection Accessing the matching posting's amount
+
+If you use an amount expression for an automated transaction's posting, that
+expression has access to all the details of the matched posting.  For example,
+you can refer to that posting's amount using the ``amount'' value expression
+variable:
+
+@smallexample
+   = expr true
+       (Foo)                  (amount * 2)  ; same as just "2" in this case
+
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+This becomes:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       (Foo)                        $40.00
+       Assets:Cash                 $-20.00
+       (Foo)                       $-40.00
+@end smallexample
+
+@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated transactions
+@subsection Referring to the matching posting's account
+
+Sometimes want to refer to the account that matched in some way within the
+automated transaction itself.  This is done by using the string $account,
+anywhere within the account part of the automated posting:
+
+@smallexample
+   = food
+       (Budget:$account)                10
+
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+Becomes:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       (Budget:Expenses:Food)      $200.00
+       Assets:Cash                 $-20.00
+@end smallexample
+
+@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated transactions
+@subsection Applying metadata to every matched posting
+
+If the automated transaction has a transaction note, that note is copied
+(along with any metadata) to every posting that matches the predicate:
+
+@smallexample
+   = food
+       ; Foo: Bar
+       (Budget:$account)                10
+
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+Becomes:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+         ; Foo: Bar
+       (Budget:Expenses:Food)      $200.00
+       Assets:Cash                 $-20.00
+@end smallexample
+
+@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated transactions
+@subsection Applying metadata to the generated posting
+
+If the automated transaction's posting has a note, that note is carried to the
+generated posting within the matched transaction:
+
+@smallexample
+   = food
+       (Budget:$account)                10
+         ; Foo: Bar
+
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       Assets:Cash
+@end smallexample
+
+Becomes:
+
+@smallexample
+   2012-03-10 KFC
+       Expenses:Food                $20.00
+       (Budget:Expenses:Food)      $200.00
+         ; Foo: Bar
+       Assets:Cash                 $-20.00
+@end smallexample
+
+This is slightly different from the rules for regular transaction notes, in
+that an automated transaction's note does not apply to every posting within
+the automated transaction itself, but rather to every posting it matches.
+
+@node State flags, Effective Dates, Applying metadata to the generated posting, Automated transactions
+@subsection State flags
+
+Although you cannot mark an automated transaction as a whole as cleared or
+pending, you can mark its postings with a * or ! before the account name, and
+that state flag gets carried to the generated posting.
+
+@node Effective Dates, Periodic Transactions, State flags, Automated transactions
+@subsection Effective Dates
+@cindex effective dates
+
+In the real world transactions do not take place instantaneously.
+Purchases can take several days to post to a bank account. And you may
+pay ahead for something for which you want to distribute costs.  With
+Ledger you can control every aspect of the timing of a transaction.
+
+Say you're in business.  If you bill a customer, you can enter
+something like
+@cindex effective date of invoice
+@smallexample
+2008/01/01=2008/01/14 Client invoice  ;  estimated date you'll be paid
+  Assets:Accounts Receivable            $100.00
+  Income: Client name
+@end smallexample
+@noindent Then, when you receive the payment, you change it to
+
+@smallexample
+2008/01/01=2008/01/15 Client invoice ;  actual date money received
+  Assets:Accounts Receivable            $100.00
+  Income: Client name
+@end smallexample
+@noindent and add something like
+
+@smallexample
+2008/01/15 Client payment
+  Assets:Checking                       $100.00
+  Assets:Accounts Receivable
+@end smallexample
+Now
+
+@smallexample
+  ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
+@end smallexample
+@noindent gives you your accrued income in the first two weeks of the year, and
+@smallexample
+  ledger --effective --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
+@end smallexample
+@noindent gives you your cash basis income in the same two weeks.
+
+Another use is distributing costs out in time. As an example, suppose
+you just prepaid into a local vegetable co-op that sustains you through
+the winter.  It cost $225 to join the program, so you write a check.
+You don't want your October grocery budget to be blown because you bought
+food ahead, however.  What you really want is for the money to be evenly
+distributed over the next six months so that your monthly budgets
+gradually take a hit for the vegetables you'll pick up from the co-op,
+even though you've already paid for them.
+
+@smallexample
+2008/10/16 * (2090) Bountiful Blessings Farm
+    Expenses:Food:Groceries                  $ 37.50  ; [=2008/10/01]
+    Expenses:Food:Groceries                  $ 37.50  ; [=2008/11/01]
+    Expenses:Food:Groceries                  $ 37.50  ; [=2008/12/01]
+    Expenses:Food:Groceries                  $ 37.50  ; [=2009/01/01]
+    Expenses:Food:Groceries                  $ 37.50  ; [=2009/02/01]
+    Expenses:Food:Groceries                  $ 37.50  ; [=2009/03/01]
+    Assets:Checking 
+@end smallexample
+
+This entry accomplishes this.  Every month until you'll start with an
+automatic $37.50 deficit like you should, while your checking account
+really knows that it debited $225 this month.
+
+
+@node Periodic Transactions,  , Effective Dates, Automated transactions
+@subsection Periodic Transactions
+
+A periodic transaction starts with a ~ followed by a period expression.
+Periodic transactions are used for budgeting and forecasting only, they
+have no effect without the @samp{--budget} option specified.
+
+See @ref{Budgeting and Forecasting} for examples and details.
+
+
+
+
+
+@node Building Reports, Reporting Commands, Transactions , Top
 @chapter Building Reports
 
 @menu
@@ -2891,17 +3669,17 @@ there are none.  The second looks for any account with ``Bo'', which is
 If you want to know exactly how much you have spent in a particular
 account on a particular payee, the following are equivalent:
 @smallexample
-> ledger balance Auto:Fuel and @@Chevron
+> ledger balance Auto:Fuel and Chevron
 > ledger balance --limit "(account=~/Fuel/) & (payee=~/Chev/)"
 @end smallexample
-@noindent will show you the amount expended on gasoline at Chevron.  The second
-example is the first example of the very power expression language
-available to shape reports.  The first example may be easier to
-remember, but learning to use the second will open up far
-more possibilities.
+@noindent will show you the amount expended on gasoline at Chevron.  
+The second example is the first example of the very power expression
+language available to shape reports.  The first example may be easier to
+remember, but learning to use the second will open up far more
+possibilities.
 
-If you want to exclude specific accounts from the report, you can exclude multiple accounts with
-parentheses: 
+If you want to exclude specific accounts from the report, you can
+exclude multiple accounts with parentheses:
 @smallexample
 ledger -s bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\)
 @end smallexample
@@ -3062,10 +3840,10 @@ current allocation?  Using the balance command and some tricky formatting!
 ledger bal Allocation --current --format "\
                %-17((depth_spacer)+(partial_account))\
                %10(percent(market(display_total), market(parent.total)))\
-               %16(market(display_total))\n" 
+               %16(market(display_total))\n%/" 
 @end smallexample
 
-Which yields:
+@noindent Which yields:
 
 @smallexample
 Allocation          100.00%      $100000.00
@@ -3074,6 +3852,7 @@ Allocation          100.00%      $100000.00
     Domestic         95.31%       $58196.29
     Global            4.69%        $2863.71
 @end smallexample
+
 Let's look at the Ledger invocation a bit closer.  The command above is
 split into lines for clarity.  The first line is very vanilla Ledger
 asking for the current balances of the account in the ``Allocation''
@@ -3088,9 +3867,10 @@ print the partial account name indented by its depth in the tree.  The
 third line is where we calculate and display the percentages.  The
 @code{display_total} command give the values of the total calculated for
 the account in this line.  The @code{parent.total} command gives the
-total for the next level up in the tree.  @code{percent} format their
+total for the next level up in the tree.  @code{percent} formats their
 ratio as a percentage.  The fourth line tells ledger to display the
-current market value of the the line.
+current market value of the the line. The last two characters ``%/''
+tell Ledger what to do for the last line, in this case, nothing.
 
 @cindex plotting
 @cindex GNUplot
@@ -3116,13 +3896,6 @@ 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.
 
-@menu
-* Typical plots::               
-@end menu
-
-@node Typical plots,  , Visualizing with Gnuplot, Visualizing with Gnuplot
-@subsubsection Typical plots
-
 Here are some useful plots:
 
 @smallexample
@@ -3256,7 +4029,7 @@ downloads.  Unfortunately the file formats, aside form the commas, are
 all different.  The ledger convert command tried to help as much as it
 can.
 
-Your banks csv files will have field in different orders from other
+Your banks csv files will have fields in different orders from other
 banks, so there must be a way to tell Ledger what to expect.  Insert a
 line at the beginning of the csv file that describes the fields to Ledger.
 
@@ -3366,14 +4139,12 @@ You can combine multiple source code blocks before executing ledger and
 do all kinds of other wonderful things with Babel (and org).
 
 
-@subsubsection Using Ledger for Accounting in Org-mode with Babel
+@subsection Org-mode with Babel
 
 Using Babel, it is possible to record financial transactions
 conveniently in an org file and subsequently generate the financial
 reports required.
 
-@unnumberedsubsubsec Getting Started
-
 With a recent version of org (7.01+), Ledger support is provided. To use
 it, enable Ledger support. Check the Babel documentation on Worg for
 instructions on how to achieve this but I currently do this directly as
@@ -3406,7 +4177,7 @@ least) in which these can be included:
 
 The first two are described in more detail in this short tutorial. 
 
-@unnumberedsubsubsec Embedded Ledger example with single source block
+@subsubheading Embedded Ledger example with single source block
 
 The easiest, albeit possibly less useful, way in which to use Ledger
 within an org file is to use a single source block to record all Ledger
@@ -3466,7 +4237,7 @@ financial state. Eventually, babel will support passing arguments to
 currently. Instead, we can use the concepts of literary programming, as
 implemented by the noweb features of babel, to help us.
 
-@unnumberedsubsubsec Multiple Ledger source blocks with noweb
+@subsubheading Multiple Ledger source blocks with noweb
 
 The noweb feature of babel allows us to expand references to other code
 blocks within a code block. For Ledger, this can be used to group
@@ -3475,7 +4246,7 @@ transactions together to generate reports.
 
 Using the same transactions used above, we could consider splitting
 these into expenses and income, as follows:
-@unnumberedsubsubsec Income Entries
+@subsubheading Income Entries
 
 The first set of entries relates to income, either monthly pay or
 interest, all typically going into one of my bank accounts. Here, I have
@@ -3502,7 +4273,7 @@ have the :noweb yes babel header argument specified.
   income:salary
 #+end_src
 @end smallexample
-@unnumberedsubsubsec Expenses
+@subsubheading Expenses
 
 The following entries relate to personal expenses, such as rent and
 food. Again, these have all been placed in a single src block but could
@@ -3519,7 +4290,7 @@ have been done individually.
 #+end_src
 @end smallexample
 
-@unnumberedsubsubsec Financial Summaries
+@subsubheading Financial Summaries
 
 Given the ledger entries defined above in the income and expenses code
 blocks, we can now refer to these using the noweb expansion directives,
@@ -3527,7 +4298,7 @@ blocks, we can now refer to these using the noweb expansion directives,
 reports for those transactions. Below are two examples, one to generate
 a balance report and one to generate a register report of all
 transactions.
-@unnumberedsubsubsec An overall balance summary
+@subsubheading An overall balance summary
 
 The overall balance of your account and expenditure with a breakdown
 according to category is specified by passing the :cmdline bal argument
@@ -3569,7 +4340,7 @@ tell Ledger to include sub-accounts in the report.
 :          £-2000.00    salary
 :          £-1300.00    starting balances
 @end smallexample
-@unnumberedsubsubsec Generating a monthly register
+@subsubheading Generating a monthly register
 
 You can also generate a monthly register (the reg command) by executing
 the following src block. This presents a summary of transactions for
@@ -3614,7 +4385,7 @@ the running total of the assets in our ledger.
 : 2010/08/01 - 2010/08/01         assets:bank:chequing      £1000.00    £2653.53
 @end smallexample
 
-@unnumberedsubsubsec Summary
+@subsubheading Summary
 
 This short tutorial shows how Ledger entries can be embedded in a org
 file and manipulated using Babel. However, only simple Ledger features
@@ -3644,8 +4415,8 @@ The general format used for Ledger data is:
 @end smallexample
 
 The data stream is enclosed in a @samp{ledger} tag, which contains a
-series of one or more transactions.  Each @samp{xact} describes the transaction
-and contains a series of one or more postings:
+series of one or more transactions.  Each @samp{xact} describes the
+transaction and contains a series of one or more postings:
 
 @smallexample
 <xact>
@@ -3662,16 +4433,15 @@ and contains a series of one or more postings:
 @end smallexample
 
 The date format for @samp{en:date} is always @samp{YYYY/MM/DD}.  The
-@samp{en:cleared} tag is optional, and indicates whether the
-posting has been cleared or not.  There is also an
-@samp{en:pending} tag, for marking pending postings.  The
-@samp{en:code} and @samp{en:payee} tags both contain whatever text the
-user wishes.
+@samp{en:cleared} tag is optional, and indicates whether the posting has
+been cleared or not.  There is also an @samp{en:pending} tag, for
+marking pending postings.  The @samp{en:code} and @samp{en:payee} tags
+both contain whatever text the user wishes.
 
 After the initial transaction data, there must follow a set of postings
-marked with @samp{en:postings}.  Typically these postings will
-all balance each other, but if not they will be automatically balanced
-into an account named @samp{<Unknown>}.
+marked with @samp{en:postings}.  Typically these postings will all
+balance each other, but if not they will be automatically balanced into
+an account named @samp{<Unknown>}.
 
 Within the @samp{en:postings} tag is a series of one or more
 @samp{posting}'s, which have the following form:
@@ -3870,9 +4640,9 @@ backwards compatibility with Ledger 2.X.
 @node payees,  , entry and xact, Reports about your Journals
 @subsection payees
 The @command{payees} reports all of the unique payees in the journal. To
-filter the payees displayed you must use the @@ prefix:
+filter the payees displayed you must use the  prefix:
 @smallexample
-macbook-2:$ ledger payees '@@Tar.+t'
+macbook-2:$ ledger payees 'Tar.+t'
 El Dorade Restaraunt
 My Big Fat Greek Restaraunt
 Target
@@ -3979,7 +4749,8 @@ Print version information and exit.
 
 @node Pre-commands,  , Debug Options, Developer Commands
 @subsection Pre-Commands
-Pre-commands are useful when you aren't sure how a command or option will work.
+Pre-commands are useful when you aren't sure how a command or option
+will work.
 @table @code
 @item args
 evaluate the given arguments against the following model transaction:
@@ -3996,12 +4767,15 @@ evaluate the given arguments against the following model transaction:
 @item eval
 evaluate the given value expression against the model transaction
 @item expr "LIMIT EXPRESSION"
-Print details of how ledger parses the given limit expression and apply it against a model transaction.
+Print details of how ledger parses the given limit expression and apply
+it against a model transaction.
 @item format "FORMATTING"
-Print details of how ledger uses the given formatting description and apply it against a model transaction.
+Print details of how ledger uses the given formatting description and
+apply it against a model transaction.
 @item generate
 @item parse <VALUE EXPR>
-Print details of how ledger uses the given value expression description and apply it against a model transaction.
+Print details of how ledger uses the given value expression description
+and apply it against a model transaction.
 @item period
 evaluate the given period and report how Ledger interprets it:
 @smallexample
@@ -4023,7 +4797,8 @@ END_REACHED: <EOF>
  1: 11-Jan-01
 @end smallexample
 @item query
-evaluate the given query and report how Ledger interprets it against the model transaction:
+evaluate the given query and report how Ledger interprets it against the
+model transaction:
 
 @smallexample
 20:25:42 ~/ledger (next)> ledger query "/Book/"
@@ -4115,13 +4890,6 @@ However, none of them are required to use the basic reporting
 commands.
 
 
-
-
-
-
-
-
-
 @node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax
 @section Detailed Option Description
 
@@ -4156,23 +4924,12 @@ database.
 @option{--help}
 Displays the info page for ledger.
 
-@option{--help-calc}
-Displays the Value Expression chapter in the info ledger.
-
-@option{--help-comm <ARG>}
-Search the info index for @code{<ARG>}.
-
-@option{--help-disp}
-Displays the Format String chapter in the info ledger.
-
-@option{--help-info}
-Displays the info page for the info reader.
-
 @option{--init-file <PATH>}
 Specifies the location of the init file @file{.ledgerrc}
 
-@option{--options}
-Display the options in effect for this Ledger invocation, along with their values and the source of those values, for example:
+@option{--options} Display the options in effect for this Ledger
+invocation, along with their values and the source of those values, for
+example:
 @smallexample
 14:15:02 > ledger --options bal --cleared -f ~/ledger/test/input/drewr3.dat  
 ===============================================================================
@@ -4219,20 +4976,22 @@ GUIs, which would make use of the different scopes by keeping an
 instance of Ledger running in the background and running multiple
 sessions with multiple reports per session.
 
-@option{--decimal-comma}
-Direct Ledger to parse journals using the European standard comma as decimal separator, vice a period.
+@option{--decimal-comma} Direct Ledger to parse journals using the
+European standard comma as decimal separator, vice a period.
 
-@option{--download}
-Direct Ledger to download prices using the script defined in @code{--getquote}.
+@option{--download} Direct Ledger to download prices using the script
+defined in @code{--getquote}.
 
 @option{--file <PATH>}
 Specify the input file path for this invocation.
 
 @cindex getquote
 @cindex download prices 
-@option{--getquote <PATH>} Tells ledger where to find the user defined script to download prices information.  
-@option{--input-date-format <DATE-FORMAT>}
-Specify the input date format for journal entries. For example, 
+@option{--getquote <PATH>} Tells ledger where to find the user defined
+script to download prices information.
+
+@option{--input-date-format <DATE-FORMAT>} Specify the input date format
+for journal entries. For example,
 @smallexample
 ledger convert Export.csv --input-date-format "%m/%d/%Y"
 @end smallexample
@@ -4241,8 +5000,8 @@ Would convert the @file{Export.csv} file to ledger format, assuming the
 the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}).
 
 
-@option{--master-account <ARGUMENT>}
-Prepends all account names with the argument.
+@option{--master-account <ARGUMENT>} Prepends all account names with the
+argument.
 @smallexample
 21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG
                    0  HUMBUG
@@ -4267,8 +5026,8 @@ Prepends all account names with the argument.
             $ 200.00      Mortgage:Principal
 @end smallexample
 
-@option{--price-db <PATH>}
-Specify the location of the price entry data file.
+@option{--price-db <PATH>} Specify the location of the price entry data
+file.
 
 @option{--price-exp INTEGER_MINUTES} Set the expected freshness of price
 quotes, in minutes. That is, if the last known quote for any commodity
@@ -4305,17 +5064,16 @@ reported. That is, the option @code{--account Personal} would tack
 @code{Personal:} to the beginning of every account reported in a balance
 report or register report.
 
-@option{--account-width <INT>}
-Set the width of the account column in the @code{register} report to @code{N} characters.
+@option{--account-width <INT>} Set the width of the account column in
+the @code{register} report to @code{N} characters.
 
-@option{--actual-dates}
-Show actual dates of transactions (@pxref{Effective Dates}). Also @code{-L}.
+@option{--actual-dates} Show actual dates of transactions
+(@pxref{Effective Dates}). Also @code{-L}.
 
-@option{--actual}
-Report only real transactions, with no automated or virtual transactions used.
+@option{--actual} Report only real transactions, with no automated or
+virtual transactions used.
 
-@option{--add-budget}
-Show only unbudgeted postings.
+@option{--add-budget} Show only unbudgeted postings.
 
 @option{--amount-data} On a register report print only the dates and
 amount of postings.  Useful for graphing and spreadsheet applications.
@@ -4325,37 +5083,35 @@ amount of postings.  Useful for graphing and spreadsheet applications.
 amount (@pxref{Value Expressions}). Using @code{--amount} you can apply
 an arbitrary transformation to the postings.
 
-@option{--amount-width <INT>}
-Set the width in characters of the amount column in the register report.
+@option{--amount-width <INT>} Set the width in characters of the amount
+column in the register report.
 
-@option{--anon}
-anonymizes registry output, mostly for sending in bug reports.
+@option{--anon} anonymizes registry output, mostly for sending in bug
+reports.
 
-@option{--average}
-Print average values over the number of transactions instead of running totals.  
+@option{--average} Print average values over the number of transactions
+instead of running totals.
 
-@option{--balance-format <STR>}
-specifies the format to use for the @code{balance} report (@pxref{Format Strings}).  The default is:
+@option{--balance-format <STR>} specifies the format to use for the
+@code{balance} report (@pxref{Format Strings}).  The default is:
 @smallexample
                "%(justify(scrub(display_total), 20, -1, true, color))"
                "  %(!options.flat ? depth_spacer : \"\")"
                "%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
                "%$1\n%/"
                "--------------------\n"
-
 @end smallexample
 
-@option{--base}
-ASK JOHN
+@option{--base} ASK JOHN
 
-@option{--basis}
-Report the cost basis on all posting
+@option{--basis} Report the cost basis on all posting
 
-@option{--begin <DATE>}
-Specify the start date of all calculations.  Transactions before that date will be ignored.
+@option{--begin <DATE>} Specify the start date of all calculations.
+Transactions before that date will be ignored.
+
+@option{--bold-if <EXPR>} print the entire line in bold if the given
+value expression is true (@pxref{Value Expressions}).
 
-@option{--bold-if <EXPR>}
-print the entire line in bold if the given value expression is true (@pxref{Value Expressions}).
 @smallexample
 ledger reg Expenses --begin Dec --bold-if "amount > 100"
 @end smallexample
@@ -4378,8 +5134,9 @@ accounts in the budget (@pxref{Budgeting and Forecasting}).
 @option{--by-payee <REGEXP>}
 group the register report by payee.
 
-@option{--cleared-format <FORMAT_STRING>}
-specifies the format to use for the @code{cleared} report (@pxref{Format Strings}).  The default is:
+@option{--cleared-format <FORMAT_STRING>} specifies the format to use
+for the @code{cleared} report (@pxref{Format Strings}).  The default is:
+
 @smallexample
         "%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, "
         " true, color))  %(justify(scrub(get_at(total_expr, 1)), 18, "
@@ -4392,26 +5149,26 @@ specifies the format to use for the @code{cleared} report (@pxref{Format Strings
         "----------------    ----------------    ---------\n"
 @end smallexample
 
-@option{--cleared}
-consider only transaction that have been cleared for display and calculation.
+@option{--cleared} consider only transaction that have been cleared for
+display and calculation.
 
+@option{--collapse} By default ledger prints all account in an account
+tree. With @code{--collapse} it print only the top level account
+specified.
 
+@option{--collapse-if-zero} Collapses the account display only if it has
+a zero balance.
 
-@option{--collapse}
-By default ledger prints all account in an account tree. With @code{--collapse} it print only the top level account specified.
-@option{--collapse-if-zero}
-Collapses the account display only if it has a zero balance.
-@option{--color}
-use color is the tty supports it.
+@option{--color} use color is the tty supports it.
 
-@option{--columns <INT>}
-specify the width of the register report in characters.
+@option{--columns <INT>} specify the width of the register report in
+characters.
 
-@option{--count}
-Direct ledger to report the number of items when appended to the commodities, accounts or payees command.
+@option{--count} Direct ledger to report the number of items when
+appended to the commodities, accounts or payees command.
 
-@option{--csv-format}
-specifies the format to use for the @code{csv} report (@pxref{Format Strings}).  The default is:
+@option{--csv-format} specifies the format to use for the @code{csv}
+report (@pxref{Format Strings}).  The default is:
 @smallexample
          "%(quoted(date)),"
          "%(quoted(code)),"
@@ -4428,36 +5185,86 @@ Shorthand for @code{--limit "date <= today"}
 @option{--daily}
 Shorthand for @code{--period "daily"}
 
-@option{--date-format <DATE-FORMAT>}
-specifies format ledger should use to print dates (@pxref{Date and Time Format Codes}).
+@option{--date-format <DATE-FORMAT>} specifies format ledger should use
+to print dates (@pxref{Date and Time Format Codes}).
 
-@option{--date <EXPR>}
-transforms the date of the transaction using @code{EXPR}
+@option{--date <EXPR>} transforms the date of the transaction using
+@code{EXPR}
 
-@option{--date-width <INT>}
-specifies the width, in characters, of the date column in the register report.
+@option{--date-width <INT>} specifies the width, in characters, of the
+date column in the register report.
 
 @option{--datetime-format}
 ASK JOHN
 
+@option{--dc} Display register or balance in debit/credit format
+If you use @samp{--dc} with either the register (reg) or balance (bal) commands, you
+will now get extra columns.  The register goes from this:
+@smallexample
+   12-Mar-10 Employer           Assets:Cash                $100        $100
+                                Income:Employer           $-100           0
+   12-Mar-10 KFC                Expenses:Food               $20         $20
+                                Assets:Cash                $-20           0
+   12-Mar-10 KFC - Rebate       Assets:Cash                  $5          $5
+                                Expenses:Food               $-5           0
+   12-Mar-10 KFC - Food & Reb.. Expenses:Food               $20         $20
+                                Expenses:Food               $-5         $15
+                                Assets:Cash                $-15           0
+@end smallexample
+@noindent To this:
+@smallexample
+   12-Mar-10 Employer       Assets:Cash        $100           0        $100
+                            In:Employer           0        $100           0
+   12-Mar-10 KFC            Expens:Food         $20           0         $20
+                            Assets:Cash           0         $20           0
+   12-Mar-10 KFC - Rebate   Assets:Cash          $5           0          $5
+                            Expens:Food           0          $5           0
+   12-Mar-10 KFC - Food &.. Expens:Food         $20           0         $20
+                            Expens:Food           0          $5         $15
+                            Assets:Cash           0         $15           0
+@end smallexample
+
+@noindent Where the first column is debits, the second is credits, and the third is the
+running total.  Only the running total may contain negative values.
+
+For the balance report without @samp{--dc}:
+
+@smallexample
+                    $70  Assets:Cash
+                    $30  Expenses:Food
+                  $-100  Income:Employer
+   --------------------
+                      0
+@end smallexample
+
+@noindent And with @samp{--dc} it becomes this:
+
+@smallexample
+             $105            $35            $70  Assets:Cash
+              $40            $10            $30  Expenses:Food
+                0           $100          $-100  Income:Employer
+   --------------------------------------------
+             $145           $145              0
+@end smallexample
+
+
 @option{--depth <INT>} limit the depth of the account tree.  In a balance
 report, for example, a @code{--depth 2} statement will print balances
 only for account with two levels, i.e. @code{Expenses:Entertainment} but
 not @code{Expenses:entertainemnt:Dining}. This is a display predicate,
 which means it only affects display, not the total calculations.
 
-@option{--deviation}
- reports each posting’s deviation from the average. It is only mean-
-ingful in the register and prices reports.
+@option{--deviation} reports each posting’s deviation from the
+ average. It is only mean- ingful in the register and prices reports.
 
-@option{--display-amount <EXPR>}
-apply a transform to the @strong{displayed} amount.  This occurs after calculations occur.
+@option{--display-amount <EXPR>} apply a transform to the
+@strong{displayed} amount.  This occurs after calculations occur.
 
 @option{--display <BOOLEAN_EXPR>}
 display lines that satisfy the expression given.
 
-@option{--display-total <EXPR>}
-apply a transform to the @strong{displayed} total.  This occurs after calculations occur.
+@option{--display-total <EXPR>} apply a transform to the
+@strong{displayed} total.  This occurs after calculations occur.
 
 @option{--dow}
 group transactions by the day of the week.
@@ -4482,11 +5289,11 @@ register report.
 @option{--exact}
 ASK JOHN
 
-@option{--exchange <COMMODITY>}
-display values in terms of the given commodity.  The latest available price is used.
+@option{--exchange <COMMODITY>} display values in terms of the given
+commodity.  The latest available price is used.
 
-@option{--flat}
-force the full names of accounts to be used inthe balance report. The balance report will not use an indented tree.
+@option{--flat} force the full names of accounts to be used inthe
+balance report. The balance report will not use an indented tree.
 
 @option{--force-color} output tty color codes even if the tty doesn't
 support them.  Ueful for TTY that don't advertise their capabilities
@@ -4515,8 +5322,9 @@ report.  EXPR can be anything, although most common would be
 @code{"payee"} or @code{"commodity"}.  The @code{tags()} function is
 also useful here.
 
-@option{--group-title-format}
-sets the format for the headers that separate reports section of a grouped report.  Only has effect with a @code{--group-by} register report.
+@option{--group-title-format} sets the format for the headers that
+separate reports section of a grouped report.  Only has effect with a
+@code{--group-by} register report.
 @smallexample
 ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n"
 ------------------------ 7-Eleven             ---------------------
@@ -4540,22 +5348,22 @@ See email from John W.
 @option{--invert}
 Change the sign of all reported values.
 
-@option{--limit <EXPR>}
-Only transactions that satisfy the expression will be considered in the calculation.
+@option{--limit <EXPR>} Only transactions that satisfy the expression
+will be considered in the calculation.
 
 @option{--lot-dates}
 FIX THIS ENTRY
 
-@option{lot-prices}
+@option{--lot-prices}
 FIX THIS ENTRY
 
-@option{lot-tags}
+@option{--lot-tags}
 FIX THIS ENTRY
 
-@option{lots-actual}
+@option{--lots-actual}
 FIX THIS ENTRY
 
-@option{lots}
+@option{--lots}
 FIX THIS ENTRY
 
 @option{market}
@@ -4567,31 +5375,31 @@ FIX THIS ENTRY
 @option{meta-width}
 FIX THIS ENTRY
 
-@option{monthly}
+@option{--monthly}
 FIX THIS ENTRY
 
-@option{no-color}
-FIX THIS ENTRY
+@option{--no-color}
+suppress any color TTY output.
 
-@option{no-rounding}
+@option{--no-rounding}
 FIX THIS ENTRY
 
-@option{no-titles}
+@option{--no-titles}
 FIX THIS ENTRY
 
-@option{no-total}
+@option{--no-total}
 FIX THIS ENTRY
 
-@option{now}
+@option{--now}
 FIX THIS ENTRY
 
 @option{only}
 FIX THIS ENTRY
 
-@option{output}
+@option{--output}
 FIX THIS ENTRY
 
-@option{pager}
+@option{--pager}
 FIX THIS ENTRY
 
 @option{payee}
@@ -4600,8 +5408,8 @@ FIX THIS ENTRY
 @option{payee-width}
 FIX THIS ENTRY
 
-@option{pending}
-FIX THIS ENTRY
+@option{--pending}
+Use only postings tht are marked pending
 
 @option{percent}
 FIX THIS ENTRY
@@ -4609,7 +5417,7 @@ FIX THIS ENTRY
 @option{period}
 FIX THIS ENTRY
 
-@option{pivot}
+@option{--pivot}
 FIX THIS ENTRY
 
 @option{plot-amount-format}
@@ -4636,14 +5444,14 @@ FIX THIS ENTRY
 @option{quantity}
 FIX THIS ENTRY
 
-@option{quarterly}
+@option{--quarterly}
 FIX THIS ENTRY
 
 @option{raw}
 FIX THIS ENTRY
 
-@option{real}
-FIX THIS ENTRY
+@option{--real} Account using only real transactions ignoring virtual
+and automatic transactions.
 
 @option{register-format}
 FIX THIS ENTRY
@@ -4651,16 +5459,16 @@ FIX THIS ENTRY
 @option{related-all}
 FIX THIS ENTRY
 
-@option{related}
-FIX THIS ENTRY
+@option{--related}
+In a register report show the related account.
 
-@option{revalued-only}
+@option{--revalued-only}
 FIX THIS ENTRY
 
-@option{revalued-total}
+@option{--revalued-total}
 FIX THIS ENTRY
 
-@option{revalued}
+@option{--revalued}
 FIX THIS ENTRY
 
 @option{seed}
@@ -4669,20 +5477,21 @@ FIX THIS ENTRY
 @option{sort-all}
 FIX THIS ENTRY
 
-@option{sort}
-FIX THIS ENTRY
+@option{--sort <VEXPR>}
+Sort the register report based on the value expression given to sort
 
-@option{sort-xacts}
+@option{--sort-xacts}
 FIX THIS ENTRY
 
-@option{--start-of-week <INT>}
-Tell ledger to use a particular day of the week to start its ``weekly'' summary. @code{--start-of-week=1}  specifies Monday as the start of the week.
+@option{--start-of-week <INT>} Tell ledger to use a particular day of
+the week to start its ``weekly'' summary. @code{--start-of-week=1}
+specifies Monday as the start of the week.
 
-@option{subtotal}
+@option{--subtotal}
 FIX THIS ENTRY
 
 @option{--tail <INT>}
-FIX THIS ENTRY
+report only the last <INT> entries.  Only useful ona register report.
 
 @option{total-data}
 FIX THIS ENTRY
@@ -4717,8 +5526,8 @@ FIX THIS ENTRY
 @option{--weekly}
 synonymn for @code{--period "weekly"}
 
-@option{--wide}
-lets the register report use 132 columns.  Identical to @code{--columns "132"}
+@option{--wide} lets the register report use 132 columns.  Identical to
+@code{--columns "132"}
 
 @option{yearly}
 synonymn for @code{--period "yearly"}
@@ -4817,7 +5626,7 @@ the right of the date).
 
 @option{--real} (@option{-R}) displays only real postings, not virtual.
 (A virtual posting is indicated by surrounding the account name with
-parentheses or brackets; see @ref{Virtual Transactions} for more
+parentheses or brackets; see @ref{Virtual postings} for more
 information).
 
 @option{--actual} (@option{-L}) displays only actual postings, and
@@ -4928,9 +5737,6 @@ transaction.
 
 @option{--by-payee} (@option{-P}) reports subtotals by payee.
 
-@option{--comm-as-payee} (@option{-x}) changes the payee of every
-posting to be the commodity used in that posting.  This can be
-useful when combined with other options, such as @option{-s}.
 
 @option{--empty} (@option{-E}) includes even empty accounts in the
 @command{balance} report.
@@ -5209,7 +6015,24 @@ balance against itself, and against any AAPL if @samp{--lots} is not
 specified.  But if you do specify @samp{--lot-prices}, for example, then
 it will balance against that specific price for AAPL.
 
+Normally when you use @samp{-X <commodity>} to request that amounts be reported in a
+specific commodity, Ledger uses these values:
+@itemize
+
+@item Register Report
+   For the register report, use the value of that commodity on the date of
+   the posting being reported, with a <Revalued> posting added at the end of
+   today's value is different from the value of the last posting.
+
+@item Balance Report
+   For the balance report, use the value of that commodity as of today.
+@end itemize
 
+You can now specify -H to ask that all valuations for any amount be done
+relative to the date that amount was encountered.
+
+You can also now use -X (and -H) in conjunction with -B and -I, to see
+valuation reports of just your basis costs or lot prices.
 @node Environment Variables,  , Commodity Reporting, Detailed Options Description
 @subsection Environment variables
 
@@ -5683,7 +6506,7 @@ Useful specifying a date in plain terms.  For example, you could say
 @end table
 
 
-@node Format Strings, Journal File Format, Value Expressions, Top
+@node Format Strings, Ledger for Developers, Value Expressions, Top
 @chapter Format Strings
 
 @menu
@@ -6103,9 +6926,240 @@ Additional date format parameters which can be used :
 @option{%F} yields  @code{%Y-%m-%d 2010-02-10}
 
 
+@node Ledger for Developers, Extending with Python, Format Strings, Top
+@chapter Ledger for Developers
+
+@menu
+* Internal Design::             
+* Journal File Format::         
+@end menu
+
+@node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers
+@section Internal Design
+Ledger is developed as a tiered set of functionality, where lower tiers
+know nothing about the higher tiers.  In fact, multiple libraries are
+built during the development the process, and link unit tests to these
+libraries, so that it is a link error for a lower tier to violate this
+modularity.
+
+Those tiers are:
+
+@itemize
+@item Utility code
+
+  There's lots of general utility in Ledger for doing time parsing, using
+  Boost.Regex, error handling, etc.  It's all done in a way that can be
+  reused in other projects as needed.
+
+@item Commoditized Amounts (amount_t, commodity_t and friends)
+
+  An numerical abstraction combining multi-precision rational numbers (via
+  GMP) with commodities.  These structures can be manipulated like regular
+  numbers in either C++ or Python (as Amount objects).
+
+@item Commodity Pool
+
+  Commodities are all owned by a commodity pool, so that future parsing of
+  amounts can link to the same commodity and established a consistent price
+  history and record of formatting details.
+
+@item Balances
+
+  Adds the concept of multiple amounts with varying commodities.  Supports
+  simple arithmetic, and multiplication and division with non-commoditized
+  values.
 
-@node Journal File Format, Extending with Python, Format Strings, Top
-@chapter Journal File Format for Developers
+@item Price history
+
+  Amounts have prices, and these are kept in a data graph which the amount
+  code itself is only dimly aware of (there's three points of access so an
+  amount can query its revalued price on a given date).
+
+@item Values
+
+  Often the higher layers in Ledger don't care if something is an amount or a
+  balance, they just want to add stuff to it or print it.  For this, I
+  created a type-erasure class, value_t/Value, into which many things can be
+  stuffed and then operated on.  They can contain amounts, balances, dates,
+  strings, etc.  If you try to apply an operation between two values that
+  makes no sense (like dividing an amount by a balance), an error occurs at
+  runtime, rather than at compile-time (as would happen if you actually tried
+  to divide an amount_t by a balance_t).
+
+  This is the core data type for the value expression language.
+
+
+
+@item Value expressions
+
+  The next layer up adds functions and operators around the Value concept.
+  This lets you apply transformations and tests to Values at runtime without
+  having to bake it into C++.  The set of functions available is defined by
+  each object type in Ledger (posts, accounts, transactions, etc.), though
+  the core engine knows nothing about these.  At its base, it only knows how
+  to apply operators to values, and how to pass them to and receive them from
+  functions.
+
+@item Query expressions
+
+  Expressions can be onerous to type at the command-line, so there's a
+  shorthand for reporting called "query expressions".  These add no
+  functionality of there own, but are purely translated from the input string
+  (cash) down to the corresponding value expression (account =~ /cash/).
+  This is a convenience layer.
+
+@item Format strings
+
+  Format strings let you interpolate value expressions into string, with the
+  requirement that any interpolated value have a string representation.
+  Really all this does is calculate the value expression in the current
+  report context, call the resulting value's "to_string()" method, and stuffs
+  the result into the output string.  It also provides printf-like behavior,
+  such as min/max width, right/left justification, etc.
+
+@item Journal items
+
+  Next is a base type shared by anything that can appear in a journal: an
+  item_t.  It contains details common to all such parsed entities, like what
+  file and line it was found on, etc.
+
+@item Journal posts
+
+  The most numerous object found in a Journal, postings are a type of item
+  that contain an account, an amount, a cost, and metadata.  There are some
+  other complications, like the account can be marked virtual, the amount
+  could be an expression, etc.
+
+@item Journal transactions
+
+  Postings are owned by transactions, always.  This subclass of item_t knows
+  about the date, the payee, etc.  If a date or metadata tag is requested
+  from a posting and it doesn't have that information, the transaction is
+  queried to see if it can provide it.
+
+@item Journal accounts
+
+  Postings are also shared by accounts, though the actual memory is managed
+  by the transaction.  Each account knows all the postings within it, but
+  contains relatively little information of its own.
+
+@item The Journal object
+
+  Finally, all transactions with their postings, and all accounts, are owned
+  by a journal_t object.  This is the go-to object for querying ad reporting
+  on your data.
+
+@item Textual journal parser
+
+  There is a textual parser, wholly contained in textual.cc, which knows how
+  to parse text into journal objects, which then get "finalized" and added to
+  the journal.  Finalization is the step that enforces the double-entry
+  guarantee.
+
+@item Iterators
+
+  Every journal object is "iterable", and these iterators are defined in
+  iterators.h and iterators.cc.  This iteration logic is kept out of the
+  basic journal objects themselves for the sake of modularity.
+
+@item Comparators
+
+  Another abstraction isolated to its own layer, this class encapsulating the
+  comparison of journal objects, based on whatever value expression the user
+  passed to --sort.
+
+@item Temporaries
+
+  Many reports bring pseudo-journal objects into existence, like postings
+  which report totals in a "<Total>" account.  These objects are created and
+  managed by a temporaries_t object, which gets used in many places by the
+  reporting filters.
+
+@item Option handling
+
+  There is an option handling subsystem used by many of the layers further
+  down.  It makes it relatively easy for me to add new options, and to have
+  those option settings immediately accessible to value expressions.
+
+@item Session objects
+
+  Every journal object is owned by a session, with the session providing
+  support for that object.  In GUI terms, this is the Controller object for
+  the journal Data object, where every document window would be a separate
+  session.  They are all owned by the global scope.
+
+@item Report objects
+
+  Every time you create report output, a report object is created to
+  determine what you want to see.  In the Ledger REPL, a new report object is
+  created every time a command is executed.  In CLI mode, only one report
+  object ever comes into being, as Ledger immediately exits after displaying
+  the results.
+
+@item Reporting filters
+
+  The way Ledger generates data is this: it asks the session for the current
+  journal, and then creates an iterator applied to that journal.  The kind of
+  iterator depends on the type of report.
+
+  This iterator is then walked, and every object yielded from the iterator is
+  passed to an "item handler", whose type is directly related to the type of
+  the iterator.
+
+  There are many, many item handlers, which can be chained together.  Each
+  one receives an item (post, account, xact, etc.), performs some action on
+  it, and then passes it down to the next handler in the chain.  There are
+  filters which compute the running totals; that queue and sort all the input
+  items before playing them back out in a new order; that filter out items
+  which fail to match a predicate, etc.  Almost every reporting feature in
+  Ledger is related to one or more filters.  Looking at filters.h, I see over
+  25 of them defined currently.
+
+@item The filter chain
+
+  How filters get wired up, and in what order, is a complex process based on
+  all the various options specified by the user.  This is the job of the
+  chain logic, found entirely in chain.cc.  It took a really long time to get
+  this logic exactly write, which is why I haven't exposed this layer to the
+  Python bridge yet.
+
+@item Output modules
+
+  Although filters are great and all, in the end you want to see stuff.  This
+  is the job of special "leaf" filters call output modules.  They are
+  implemented just like a regular filter, but they don't have a "next" filter
+  to pass the time on down to.  Instead, they are the end of the line and
+  must do something with the item that results in the user seeing something
+  on their screen or in a file.
+
+@item Select queries
+
+  Select queries know a lot about everything, even though they implement
+  their logic by implementing the user's query in terms of all the other
+  features thus presented.  Select queries have no functionality of their
+  own, they are simple a shorthand to provide access to much of Ledger's
+  functionality via a cleaner, more consistent syntax.
+
+@item The Global Scope
+
+  There is a master object which owns every other objects, and this is
+  Ledger's global scope.  It creates the other objects, provides REPL
+  behavior for the command-line utility, etc.  In GUI terms, this is the
+  Application object.
+
+@item The Main Driver
+
+  This creates the global scope object, performs error reporting, and handles
+  command-line options which must precede even the creation of the global
+  scope, such as --debug.
+@end itemize
+
+And that's Ledger in a nutshell.  All the rest are details, such as which
+value expressions each journal item exposes, how many filters currently exist,
+which options the report and session scopes define, etc.
+
+@node Journal File Format,  , Internal Design, Ledger for Developers
+@section Journal File Format for Developers
 
 This chapter offers a complete description of the journal data format,
 suitable for implementers in other languages to follow.  For users,
@@ -6155,26 +7209,20 @@ amount of the first posting is typically positive.  Consider:
 @menu
 * Comments and meta-data::      
 * Specifying Amounts::          
+* Posting costs::               
+* Primary commodities::         
 @end menu
 
 @node Comments and meta-data, Specifying Amounts, Journal File Format, Journal File Format
-@section Comments and meta-data
-@menu
-* Comments::                    
-* Meta-data::                   
-@end menu
+@subsection Comments and meta-data
 
-@node Comments, Meta-data, Comments and meta-data, Comments and meta-data
-@subsection Comments
 Comments are generally started using a ';'.  However, in order to
 increase compatibility with other text manipulation programs and methods
 three additional comment characters are valid if used at the beginning
 of a line: @code{#}, @code{|}, and @code{*}.
-@node Meta-data,  , Comments, Comments and meta-data
-@subsection Matador
 
-@node Specifying Amounts,  , Comments and meta-data, Journal File Format
-@section Specifying Amounts
+@node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format
+@subsection Specifying Amounts
 @cindex amounts
 The heart of a journal is the amounts it records, and this fact is
 reflected in the diversity of amount expressions allowed.  All of them
@@ -6191,7 +7239,7 @@ spaces between the end of the post and the beginning of the amount
 @end menu
 
 @node Integer Amounts, Commoditized Amounts, Specifying Amounts, Specifying Amounts
-@subsection Integer Amounts
+@subsubsection Integer Amounts
 
 In the simplest form, bare decimal numbers are accepted:
 
@@ -6245,7 +7293,7 @@ always look to their commodity to know what precision they should
 round to, and so use @dfn{commodity precision}.
 
 @node Commoditized Amounts,  , Integer Amounts, Specifying Amounts
-@subsection Commoditized Amounts
+@subsubsection Commoditized Amounts
 
 A @dfn{commoditized amount} is an integer amount which has an
 associated commodity.  This commodity can appear before or after the
@@ -6292,7 +7340,8 @@ does not change how other amounts in that commodity will be displayed.
 
 An example of this is found in cost expressions, covered next.
 
-@section Posting costs
+@node Posting costs, Primary commodities, Specifying Amounts, Journal File Format
+@subsection Posting costs
 
 You have seen how to specify either a commoditized or an integer
 amount for a posting.  But what if the amount you paid for something
@@ -6342,6 +7391,7 @@ postings are involved:
 Here the implied cost is @samp{$57.00}, which is entered into the null
 posting automatically so that the transaction balances.
 
+@node Primary commodities,  , Posting costs, Journal File Format
 @subsection Primary commodities
 
 In every transaction involving more than one commodity, there is
@@ -6374,8 +7424,161 @@ considered a primary.  In fact, when Ledger goes about ensures that
 all transactions balance to zero, it only ever asks this of primary
 commodities.
 
-@node Extending with Python, Major Changes from version 2.6, Journal File Format, Top
+@node Extending with Python, Major Changes from version 2.6, Ledger for Developers, Top
 @chapter Extending with Python
+Python can be used to extend your Ledger
+experience.  But first, a word must be said about Ledger's data model, so that
+other things make sense later.
+
+@menu
+* Basic data traversal::        
+* Raw vs. Cooked::              
+* Queries::                     
+* Embedded Python::             
+* Amounts::                     
+@end menu
+
+@node Basic data traversal, Raw vs. Cooked, Extending with Python, Extending with Python
+@section Basic data traversal
+
+Every interaction with Ledger happens in the context of a Session.  Even if
+you don't create a session manually, one is created for you by the top-level
+interface functions.  The Session is where objects live like the Commodity's
+that Amount's refer to.
+
+The make a Session useful, you must read a Journal into it, using the function
+`@samp{read_journal}`.  This reads Ledger data from the given file, populates a
+Journal object within the current Session, and returns a reference to that
+Journal object.
+
+Within the Journal live all the Transaction's, Posting's, and other objects
+related to your data.  There are also AutomatedTransaction's and
+PeriodicTransaction's, etc.
+
+Here is how you would traverse all the postings in your data file:
+@smallexample
+
+   import ledger
+
+   for xact in ledger.read_journal("sample.dat").xacts:
+       for post in xact.posts:
+           print "Transferring %s to/from %s" % (post.amount, post.account)
+@end smallexample
+
+@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python
+@section Raw vs. Cooked
+
+Ledger data exists in one of two forms: raw and cooked.  Raw objects are what
+you get from a traversal like the above, and represent exactly what was seen
+in the data file.  Consider this journal:
+
+@smallexample
+   = true
+       (Assets:Cash)    $100
+
+   2012-03-01 KFC
+       Expenses:Food    $100
+       Assets:Credit
+@end smallexample
+
+
+In this case, the @emph{raw} regular transaction in this file is:
+
+@smallexample
+   2012-03-01 KFC
+       Expenses:Food    $100
+       Assets:Credit
+@end smallexample
+
+While the @emph{cooked} form is:
+
+@smallexample
+   2012-03-01 KFC
+       Expenses:Food    $100
+       Assets:Credit   $-100
+       (Assets:Cash)    $100
+@end smallexample
+
+So the easy way to think about raw vs. cooked is that raw is the unprocessed
+data, and cooked has had all considerations applied.
+
+When you traverse a Journal by iterating its transactions, you are generally
+looking at raw data.  In order to look at cooked data, you must generate a
+report of some kind by querying the journal:
+
+@smallexample
+   for post in ledger.read_journal("sample.dat").query("food"):
+       print "Transferring %s to/from %s" % (post.amount, post.account)
+@end smallexample
+
+The reason why queries iterate over postings instead of transactions is that
+queries often return only a ``slice'' of the transactions they apply to.  You
+can always get at a matching posting's transaction by looking at its "xact"
+member:
+
+@smallexample
+   last_xact = None
+   for post in ledger.read_journal("sample.dat").query(""):
+       if post.xact != last_xact:
+           for post in post.xact.posts:
+               print "Transferring %s to/from %s" % (post.amount,
+               post.account)
+           last_xact = post.xact
+@end smallexample
+
+This query ends up reporting every cooked posting in the Journal, but does it
+transaction-wise.  It relies on the fact that an unsorted report returns
+postings in the exact order they were parsed from the journal file.
+
+@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python
+@section Queries
+
+The Journal.query() method accepts every argument you can specify on the
+command-line, including --options.
+
+Since a query ``cooks'' the journal it applies to, only one query may be active
+for that journal at a given time.  Once the query object is gone (after the
+for loop), then the data reverts back to its raw state.
+
+@node Embedded Python, Amounts, Queries, Extending with Python
+@section Embedded Python
+
+Can you embed Python into your data files using the 'python' directive:
+
+@smallexample
+   python
+       import so
+       def check_path(path_value):
+           print "%s => %s" % (str(path_value), os.path.isfile(str(path_value)))
+           return os.path.isfile(str(path_value))
+
+   tag PATH
+       assert check_path(value)
+
+   2012-02-29 KFC
+       ; PATH: somebogusfile.dat
+       Expenses:Food                $20
+       Assets:Cash
+@end smallexample
+
+Any Python functions you define this way become immediately available as
+valexpr functions.
+
+@node Amounts,  , Embedded Python, Extending with Python
+@section Amounts
+
+When numbers come from Ledger, like post.amount, the type of the value is
+Amount.  It can be used just like an ordinary number, except that addition
+and subtraction are restricted to amounts with the same commodity.  If you
+need to create sums of multiple commodities, use a Balance.  For example:
+
+@smallexample
+   total = Balance()
+   for post in ledger.read_journal("sample.dat").query(""):
+       total += post.amount
+   print total
+@end smallexample
+
 
 @node Major Changes from version 2.6, Example Data File, Extending with Python, Top
 @chapter Major Changes from version 2.6