Updated developer section

1 files changed, 366 insertions, 316 deletions

diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index ac0208bd..be7d7e98 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -77,8 +77,8 @@ twinkling in their father's CRT.
 * Budgeting and Forecasting::   
 * Value Expressions::           
 * Format Strings::              
-* Ledger for Developers::       
 * Extending with Python::       
+* Ledger for Developers::       
 * Major Changes from version 2.6::  
 * Example Data File::           
 * Miscellaneous Notes::         
@@ -4093,7 +4093,6 @@ of the balance.
 * Primary Financial Reports::   Reports in other formats:: Reports about
 * Reports in other Formats::    
 * Reports about your Journals::  
-* Developer Commands::          
 @end menu
 
 @node Primary Financial Reports, Reports in other Formats, Reporting Commands, Reporting Commands
@@ -4774,7 +4773,7 @@ by Ledger.  This is useful for generating and tidying up pricedb
 database files.
 
 
-@node Reports about your Journals, Developer Commands, Reports in other Formats, Reporting Commands
+@node Reports about your Journals,  , Reports in other Formats, Reporting Commands
 @section Reports about your Journals
 
 @menu
@@ -4879,199 +4878,6 @@ macbook-2:$
 
 
 
-@node Developer Commands,  , Reports about your Journals, Reporting Commands
-@section Developer Commands
-@menu
-* echo::                        
-* reload::                      
-* source::                      
-* Debug Options::               
-* Pre-commands::                
-@end menu
-
-@node echo, reload, Developer Commands, Developer Commands
-@subsection @command{echo}
-This command simply echos its argument back to the output.
-
-
-@node reload, source, echo, Developer Commands
-@subsection @command{reload}
-Forces ledger to reload any journal files.  This function exists to
-support external programs controlling a running ledger process and does
-nothing for a command line user.
-
-@node source, Debug Options, reload, Developer Commands
-@subsection @command{source}
-The @code{source} command take a journal file as an argument and parses
-it checking for errors, no other reports are generated, and no other
-arguments are necessary.  Ledger will return success if no errors are
-found.
-
-@node Debug Options, Pre-commands, source, Developer Commands
-@subsection Debug Options
-
-These options are primarily for Ledger developers, but may be of some
-use to a user trying something new.
-
-@table @code
-  @item --args-only
-ignore init
-files and environment variables for the ledger run.
-
-@item --verify
-enable additional assertions during run-time. This causes a significant
-slowdown.  When combined with @code{--debug} ledger will produce
-memory trace information.
-
-@item --debug "argument"
-If Ledger has been built with debug options this will provide extra data
-during the run.  The following are the available arguments to debug:
-
-@multitable @columnfractions .32 .43 .27
-@item @code{account.display}             @tab @code{expr.calc.when}                   @tab @code{org.next_amount}        
-@item @code{accounts.sorted}             @tab @code{expr.compile}                     @tab @code{org.next_total}         
-@item @code{amount.convert}              @tab @code{filters.changed_value}            @tab @code{parser.error}           
-@item @code{amount.is_zero}              @tab @code{filters.changed_value.rounding}   @tab @code{pool.commodities}       
-@item @code{amount.parse}                @tab @code{filters.collapse}                 @tab @code{post.assign}            
-@item @code{amount.price}                @tab @code{filters.forecast}                 @tab @code{python.init}            
-@item @code{amount.truncate}             @tab @code{filters.revalued}                 @tab @code{python.interp}          
-@item @code{amount.unround}              @tab @code{format.abbrev}                    @tab @code{query.mask}             
-@item @code{amounts.commodities}         @tab @code{format.expr}                      @tab @code{report.predicate}       
-@item @code{amounts.refs}                @tab @code{generate.post}                    @tab @code{scope.symbols}          
-@item @code{archive.journal}             @tab @code{generate.post.string}             @tab @code{textual.include}        
-@item @code{auto.columns}                @tab @code{item.meta}                        @tab @code{textual.parse}          
-@item @code{budget.generate}             @tab @code{ledger.read}                      @tab @code{timelog}                
-@item @code{commodity.annotated.strip}   @tab @code{ledger.validate}                  @tab @code{times.epoch}            
-@item @code{commodity.annotations}       @tab @code{lookup}                           @tab @code{times.interval}         
-@item @code{commodity.compare}           @tab @code{lookup.account}                   @tab @code{times.parse}            
-@item @code{commodity.download}          @tab @code{mask.match}                       @tab @code{value.sort}             
-@item @code{commodity.prices.add}        @tab @code{memory.counts}                    @tab @code{value.storage.refcount} 
-@item @code{commodity.prices.find}       @tab @code{memory.counts.live}               @tab @code{xact.extend}            
-@item @code{convert.csv}                 @tab @code{memory.debug}                     @tab @code{xact.extend.cleared}    
-@item @code{csv.mappings}                @tab @code{op.cons}                          @tab @code{xact.extend.fail}       
-@item @code{csv.parse}                   @tab @code{op.memory}                        @tab @code{xact.finalize}         
-@item @code{draft.xact}                  @tab @code{option.args}                           
-@item @code{expr.calc}                   @tab @code{option.names}                          
-@end multitable 
-
-@item --trace INTEGER_TRACE_LEVEL
-Enable tracing.  The integer specifies the level of trace desired:   
-@multitable @columnfractions .3 .7
-@item @code{LOG_OFF} @tab 0
-@item @code{LOG_CRIT} @tab 1
-@item @code{LOG_FATAL} @tab 2
-@item @code{LOG_ASSERT} @tab 3
-@item @code{LOG_ERROR} @tab 4
-@item @code{LOG_VERIFY} @tab 5
-@item @code{LOG_WARN} @tab 6
-@item @code{LOG_INFO} @tab 7
-@item @code{LOG_EXCEPT} @tab 8
-@item @code{LOG_DEBUG} @tab 9
-@item @code{LOG_TRACE} @tab 10
-@item @code{LOG_ALL} @tab 11
-@end multitable
-
-@item --verbose
-Print detailed information on the execution of Ledger.
-
-@item --version
-Print version information and exit.
-@end table
-
-@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.
-@table @code
-@item args
-evaluate the given arguments against the following model transaction:
-@smallexample
-2004/05/27 Book Store
-    ; This note applies to all postings. :SecondTag:
-    Expenses:Books                 20 BOOK @@ $10
-    ; Metadata: Some Value
-    ; Typed:: $100 + $200
-    ; :ExampleTag:
-    ; Here follows a note describing the posting.
-    Liabilities:MasterCard        $-200.00
-@end smallexample
-@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.
-@item format "FORMATTING"
-Print details of how ledger uses the given formatting description and
-apply it against a model transaction.
-@item generate
-Randomly generates syntactically valid Ledger data from a seed.  Used by the
-GenerateTests harness for development testing
-@item parse <VALUE EXPR>
-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
-20:22:21 ~/ledger (next)> ledger period "this year"
---- Period expression tokens ---
-TOK_THIS: this
-TOK_YEAR: year
-END_REACHED: <EOF>
-
---- Before stabilization ---
-   range: in year 2011
-
---- After stabilization ---
-   range: in year 2011
-   start: 11-Jan-01
-  finish: 12-Jan-01
-
---- Sample dates in range (max. 20) ---
- 1: 11-Jan-01
-@end smallexample
-@item query
-evaluate the given query and report how Ledger interprets it against the
-model transaction:
-
-@smallexample
-20:25:42 ~/ledger (next)> ledger query "/Book/"
---- Input arguments ---
-("/Book/")
-
---- Context is first posting of the following transaction ---
-2004/05/27 Book Store
-    ; This note applies to all postings. :SecondTag:
-    Expenses:Books                 20 BOOK @@ $10
-    ; Metadata: Some Value
-    ; Typed:: $100 + $200
-    ; :ExampleTag:
-    ; Here follows a note describing the posting.
-    Liabilities:MasterCard        $-200.00
-
---- Input expression ---
-(account =~ /Book/)
-
---- Text as parsed ---
-(account =~ /Book/)
-
---- Expression tree ---
-0x7fd639c0da40    O_MATCH (1)
-0x7fd639c10170     IDENT: account (1)
-0x7fd639c10780     VALUE: /Book/ (1)
-
---- Compiled tree ---
-0x7fd639c10520    O_MATCH (1)
-0x7fd639c0d6c0     IDENT: account (1)
-0x7fd639c0d680      FUNCTION (1)
-0x7fd639c10780     VALUE: /Book/ (1)
-
---- Calculated value ---
-true
-@end smallexample
-@item template
-Shows the insertion template that a @code{draft} or @code{xact} sub-command generates.
-This is a debugging command.
-@end table
 
 @node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top
 @chapter Command-line Syntax
@@ -7241,7 +7047,7 @@ Useful specifying a date in plain terms.  For example, you could say
 @item @code{value_date } @tab @code{} @tab 
 @end multitable
 
-@node Format Strings, Ledger for Developers, Value Expressions, Top
+@node Format Strings, Extending with Python, Value Expressions, Top
 @chapter Format Strings
 
 @menu
@@ -7667,15 +7473,172 @@ line number in @code{filename} where posting's entry for posting ends, abbreviat
 
 
 
+@node Extending with Python, Ledger for Developers, Format Strings, 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
+`@code{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
 
-@node Ledger for Developers, Extending with Python, Format Strings, Top
+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 Ledger for Developers, Major Changes from version 2.6, Extending with Python, Top
 @chapter Ledger for Developers
 
 @menu
 * Internal Design::             
 * Journal File Format::         
+* Developer Commands::          
+* Ledger Development Environment::  
 @end menu
 
 @node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers
@@ -7902,7 +7865,7 @@ 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
+@node Journal File Format, Developer Commands, Internal Design, Ledger for Developers
 @section Journal File Format for Developers
 
 This chapter offers a complete description of the journal data format,
@@ -8168,163 +8131,250 @@ 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, 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.
-
+@node Developer Commands, Ledger Development Environment, Journal File Format, Ledger for Developers
+@section Developer Commands
 @menu
-* Basic data traversal::        
-* Raw vs. Cooked::              
-* Queries::                     
-* Embedded Python::             
-* Amounts::                     
+* echo::                        
+* reload::                      
+* source::                      
+* Debug Options::               
+* Pre-commands::                
 @end menu
 
-@node Basic data traversal, Raw vs. Cooked, Extending with Python, Extending with Python
-@section Basic data traversal
+@node echo, reload, Developer Commands, Developer Commands
+@subsection @command{echo}
+This command simply echos its argument back to the output.
 
-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
-`@code{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.
+@node reload, source, echo, Developer Commands
+@subsection @command{reload}
+Forces ledger to reload any journal files.  This function exists to
+support external programs controlling a running ledger process and does
+nothing for a command line user.
 
-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.
+@node source, Debug Options, reload, Developer Commands
+@subsection @command{source}
+The @code{source} command take a journal file as an argument and parses
+it checking for errors, no other reports are generated, and no other
+arguments are necessary.  Ledger will return success if no errors are
+found.
 
-Here is how you would traverse all the postings in your data file:
-@smallexample
+@node Debug Options, Pre-commands, source, Developer Commands
+@subsection Debug Options
 
-   import ledger
+These options are primarily for Ledger developers, but may be of some
+use to a user trying something new.
 
-   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
+@table @code
+  @item --args-only
+ignore init
+files and environment variables for the ledger run.
 
-@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python
-@section Raw vs. Cooked
+@item --verify
+enable additional assertions during run-time. This causes a significant
+slowdown.  When combined with @code{--debug} ledger will produce
+memory trace information.
 
-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:
+@item --debug "argument"
+If Ledger has been built with debug options this will provide extra data
+during the run.  The following are the available arguments to debug:
 
-@smallexample
-   = true
-       (Assets:Cash)    $100
+@multitable @columnfractions .32 .43 .27
+@item @code{account.display}             @tab @code{expr.calc.when}                   @tab @code{org.next_amount}        
+@item @code{accounts.sorted}             @tab @code{expr.compile}                     @tab @code{org.next_total}         
+@item @code{amount.convert}              @tab @code{filters.changed_value}            @tab @code{parser.error}           
+@item @code{amount.is_zero}              @tab @code{filters.changed_value.rounding}   @tab @code{pool.commodities}       
+@item @code{amount.parse}                @tab @code{filters.collapse}                 @tab @code{post.assign}            
+@item @code{amount.price}                @tab @code{filters.forecast}                 @tab @code{python.init}            
+@item @code{amount.truncate}             @tab @code{filters.revalued}                 @tab @code{python.interp}          
+@item @code{amount.unround}              @tab @code{format.abbrev}                    @tab @code{query.mask}             
+@item @code{amounts.commodities}         @tab @code{format.expr}                      @tab @code{report.predicate}       
+@item @code{amounts.refs}                @tab @code{generate.post}                    @tab @code{scope.symbols}          
+@item @code{archive.journal}             @tab @code{generate.post.string}             @tab @code{textual.include}        
+@item @code{auto.columns}                @tab @code{item.meta}                        @tab @code{textual.parse}          
+@item @code{budget.generate}             @tab @code{ledger.read}                      @tab @code{timelog}                
+@item @code{commodity.annotated.strip}   @tab @code{ledger.validate}                  @tab @code{times.epoch}            
+@item @code{commodity.annotations}       @tab @code{lookup}                           @tab @code{times.interval}         
+@item @code{commodity.compare}           @tab @code{lookup.account}                   @tab @code{times.parse}            
+@item @code{commodity.download}          @tab @code{mask.match}                       @tab @code{value.sort}             
+@item @code{commodity.prices.add}        @tab @code{memory.counts}                    @tab @code{value.storage.refcount} 
+@item @code{commodity.prices.find}       @tab @code{memory.counts.live}               @tab @code{xact.extend}            
+@item @code{convert.csv}                 @tab @code{memory.debug}                     @tab @code{xact.extend.cleared}    
+@item @code{csv.mappings}                @tab @code{op.cons}                          @tab @code{xact.extend.fail}       
+@item @code{csv.parse}                   @tab @code{op.memory}                        @tab @code{xact.finalize}         
+@item @code{draft.xact}                  @tab @code{option.args}                           
+@item @code{expr.calc}                   @tab @code{option.names}                          
+@end multitable 
 
-   2012-03-01 KFC
-       Expenses:Food    $100
-       Assets:Credit
-@end smallexample
+@item --trace INTEGER_TRACE_LEVEL
+Enable tracing.  The integer specifies the level of trace desired:   
+@multitable @columnfractions .3 .7
+@item @code{LOG_OFF} @tab 0
+@item @code{LOG_CRIT} @tab 1
+@item @code{LOG_FATAL} @tab 2
+@item @code{LOG_ASSERT} @tab 3
+@item @code{LOG_ERROR} @tab 4
+@item @code{LOG_VERIFY} @tab 5
+@item @code{LOG_WARN} @tab 6
+@item @code{LOG_INFO} @tab 7
+@item @code{LOG_EXCEPT} @tab 8
+@item @code{LOG_DEBUG} @tab 9
+@item @code{LOG_TRACE} @tab 10
+@item @code{LOG_ALL} @tab 11
+@end multitable
 
+@item --verbose
+Print detailed information on the execution of Ledger.
 
-In this case, the @emph{raw} regular transaction in this file is:
+@item --version
+Print version information and exit.
+@end table
 
+@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.
+@table @code
+@item args
+evaluate the given arguments against the following model transaction:
 @smallexample
-   2012-03-01 KFC
-       Expenses:Food    $100
-       Assets:Credit
+2004/05/27 Book Store
+    ; This note applies to all postings. :SecondTag:
+    Expenses:Books                 20 BOOK @@ $10
+    ; Metadata: Some Value
+    ; Typed:: $100 + $200
+    ; :ExampleTag:
+    ; Here follows a note describing the posting.
+    Liabilities:MasterCard        $-200.00
 @end smallexample
-
-While the @emph{cooked} form is:
-
+@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.
+@item format "FORMATTING"
+Print details of how ledger uses the given formatting description and
+apply it against a model transaction.
+@item generate
+Randomly generates syntactically valid Ledger data from a seed.  Used by the
+GenerateTests harness for development testing
+@item parse <VALUE EXPR>
+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
-   2012-03-01 KFC
-       Expenses:Food    $100
-       Assets:Credit   $-100
-       (Assets:Cash)    $100
-@end smallexample
+20:22:21 ~/ledger (next)> ledger period "this year"
+--- Period expression tokens ---
+TOK_THIS: this
+TOK_YEAR: year
+END_REACHED: <EOF>
 
-So the easy way to think about raw vs. cooked is that raw is the unprocessed
-data, and cooked has had all considerations applied.
+--- Before stabilization ---
+   range: in year 2011
 
-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:
+--- After stabilization ---
+   range: in year 2011
+   start: 11-Jan-01
+  finish: 12-Jan-01
 
-@smallexample
-   for post in ledger.read_journal("sample.dat").query("food"):
-       print "Transferring %s to/from %s" % (post.amount, post.account)
+--- Sample dates in range (max. 20) ---
+ 1: 11-Jan-01
 @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:
+@item query
+evaluate the given query and report how Ledger interprets it against the
+model transaction:
 
 @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
+20:25:42 ~/ledger (next)> ledger query "/Book/"
+--- Input arguments ---
+("/Book/")
 
-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.
+--- Context is first posting of the following transaction ---
+2004/05/27 Book Store
+    ; This note applies to all postings. :SecondTag:
+    Expenses:Books                 20 BOOK @@ $10
+    ; Metadata: Some Value
+    ; Typed:: $100 + $200
+    ; :ExampleTag:
+    ; Here follows a note describing the posting.
+    Liabilities:MasterCard        $-200.00
 
-@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python
-@section Queries
+--- Input expression ---
+(account =~ /Book/)
 
-The Journal.query() method accepts every argument you can specify on the
-command-line, including --options.
+--- Text as parsed ---
+(account =~ /Book/)
 
-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.
+--- Expression tree ---
+0x7fd639c0da40    O_MATCH (1)
+0x7fd639c10170     IDENT: account (1)
+0x7fd639c10780     VALUE: /Book/ (1)
 
-@node Embedded Python, Amounts, Queries, Extending with Python
-@section Embedded Python
+--- Compiled tree ---
+0x7fd639c10520    O_MATCH (1)
+0x7fd639c0d6c0     IDENT: account (1)
+0x7fd639c0d680      FUNCTION (1)
+0x7fd639c10780     VALUE: /Book/ (1)
 
-Can you embed Python into your data files using the 'python' directive:
+--- Calculated value ---
+true
+@end smallexample
+@item template
+Shows the insertion template that a @code{draft} or @code{xact} sub-command generates.
+This is a debugging command.
+@end table
 
-@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))
+@node Ledger Development Environment,  , Developer Commands, Ledger for Developers
+@section Ledger Development Environment
 
-   tag PATH
-       assert check_path(value)
+@menu
+* acrep build configuration tool::  
+* Testing Framework::           
+@end menu
 
-   2012-02-29 KFC
-       ; PATH: somebogusfile.dat
-       Expenses:Food                $20
-       Assets:Cash
-@end smallexample
+@node acrep build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment
+@subsection @code{acprep} build configuration tool
 
-Any Python functions you define this way become immediately available as
-valexpr functions.
+@node Testing Framework,  , acrep build configuration tool, Ledger Development Environment
+@subsection Testing Framework
+Ledger source ships with a farily complete set of tests to verify that
+all is well, and no old errors have been resurfaced.  Tests are run
+individually with @code{ctest}.  All tests can be run using @code{make
+check} or @code{ninja check} depending on which build tool you prefer.
 
-@node Amounts,  , Embedded Python, Extending with Python
-@section Amounts
+Once built, the ledger executable resides under the @file{build}
+subdirectory in the source tree.  Tests are built and stored in the test
+subdirectory for the build.  For example,
+@file{~/ledger/build/ledger/opt/test}.  
 
-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:
+@menu
+* Running Tests::               
+* Writing Tests::               
+@end menu
 
-@smallexample
-   total = Balance()
-   for post in ledger.read_journal("sample.dat").query(""):
-       total += post.amount
-   print total
-@end smallexample
 
+@node Running Tests, Writing Tests, Testing Framework, Testing Framework
+@subsubsection Running Tests
+
+The complete test sweet can be run from the build directory using the
+check option for the build tool you use.  For example, @code{make
+check}.  The entire test suit tast around a minute for the optimized
+built and many times longer for the debug version.  While developing and
+debugging, running individual tests can save a great deal of time.
+
+Individual tests can be run fron the @file{test} subdirectory of the
+build location.  To execute a single test use @code{ctest -V -R regex},
+where the regex mathes the name of the test you want to build.  
+
+There are nearly 300 tests stored under the @file{test} sudirectoro
+tmain source distribution.  They are broken into two broad categories,
+baseline and regression.  To run the @file{5FBF2ED8} test, for example,
+issue @code{ctest -V -R "5FB"}. 
+@node Writing Tests,  , Running Tests, Testing Framework
+@subsubsection Writing Tests
 
-@node Major Changes from version 2.6, Example Data File, Extending with Python, Top
+@node Major Changes from version 2.6, Example Data File, Ledger for Developers, Top
 @chapter Major Changes from version 2.6
 
 @itemize