Merge branch 'ledger-mode-documentation' into next

Conflicts:
	lisp/ldg-commodities.el

11 files changed, 859 insertions, 39 deletions

diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi
new file mode 100644
index 00000000..9b2c1262
--- /dev/null
+++ b/doc/ledger-mode.texi
@@ -0,0 +1,736 @@
+\input texinfo  @c -*-texinfo-*-
+@setfilename ledger3.info
+@settitle Ledger: Command-Line Accounting
+
+@dircategory Major Modes
+@copying
+Copyright (c) 2013, Craig Earls.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+- Neither the name of New Artisans LLC nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+@end copying
+
+@documentencoding UTF-8
+
+@iftex
+@finalout
+@end iftex
+
+
+@titlepage
+@title Ledger Mode
+@subtitle Emacs Support For Version 3.0 of Ledger
+@author Craig Earls
+@end titlepage
+
+@direntry
+* Ledger Mode: (ledger-mode).           Command-Line Accounting
+@end direntry
+
+@contents
+
+@ifnottex
+@node Top, Copying, (dir), (dir)
+@top Overview
+Ledger is a command line accounting tool that provides double-entry
+accounting based on a text journal.  It provides no bells or whistles,
+and returns the user to the days before user interfaces were even a
+1twinkling in their father's CRT.
+
+Ledger Mode assists you in maintaining input files for Ledger, running
+reports and much more...
+@c @insertcopying
+@end ifnottex
+
+@menu
+* Copying::                     
+* Introduction to Ledger Mode::  
+* The Ledger Buffer::           
+* The Reconcile Buffer::        
+* The Report Buffer::           
+* Customizing Ledger-mode::     
+* Generating Ledger Regression Tests::  
+* Embedding Example results in Ledger Documentation::  
+* Hacking Ledger-mode::         
+@end menu
+
+@node Copying, Introduction to Ledger Mode, Top, Top
+@chapter Copying
+@insertcopying
+
+@node Introduction to Ledger Mode, The Ledger Buffer, Copying, Top
+@chapter Introduction to Ledger Mode
+@menu
+* Quick Installation::          
+* Menus::                       
+* Quick Demo::                  
+@end menu
+
+@node Quick Installation, Menus, Introduction to Ledger Mode, Introduction to Ledger Mode
+@section Quick Installation
+
+The emacs lisp source for Ledger-mode is included with the source
+distribution of Ledger.  It is entirely included in the @file{lisp}
+subdirectory. To use ledger mode include the following in your emacs
+initialization file (@file{~/.emacs}, @file{~/.emacs.d/init.el},
+@file{~/.Aquamacs/Preferences.el} 
+
+@smallexample
+(add-to-list 'load-path (expand-file-name "/path/to/ledger/source/lisp/"))
+(load "ldg-new")
+(add-to-list 'auto-mode-alist '("\\.ledger$" . ledger-mode))
+@end smallexample
+
+This sets up Emacs to automatically recognize files that end with
+@file{.ledger} and start Ledger mode.  Nothing else should be required
+as long as the ledger command line utility is properly installed.
+
+@node Menus, Quick Demo, Quick Installation, Introduction to Ledger Mode
+@section Menus
+
+The vast majority of Ledger-mode functionality is available from the
+Emacs menu system.  The keystrokes are shown in the menu to help you
+learn the faster keyboard methods.
+
+@node Quick Demo,  , Menus, Introduction to Ledger Mode
+@section Quick Demo
+
+Load the demo file @file{demo.ledger} from the Ledger source
+@file{test/input} directory.  The ledger will be loaded and font
+highlighted.  At this point you could manually edit transactions and run
+Ledger from a convenient command line.
+
+@menu
+* Quick Add::                   
+* Reconciliation::              
+* Reports::                     
+* Folding::                     
+@end menu
+
+@node Quick Add, Reconciliation, Quick Demo, Quick Demo
+@subsection Quick Add
+
+As simple as the ledger transaction format is, it can still be daunting
+to add many transactions manually.  Ledger provides two way to add
+transactions with minimal typing. Both are based on the idea that most
+tranactions are repretitions of earlier transactions.
+
+In the @file{demo.ledger} buffer enter a date using the correct
+format. The tpye the first few characters of another payee in the
+@file{demo.ledger} buffer.  Type @code{C-c TAB}.  Ledger-mode will
+search for a Payee that has the same beginning and copy the rest of the
+transaction to you new entry.
+
+Additionally you can ust the ledger xact command, by typing @code{C-c
+C-a} then typing a close match to the payee. Ledger mode will call
+@code{ledger xact} with the data you enter and place the transaction in
+the proper chronological place in the ledger.
+
+@node Reconciliation, Reports, Quick Add, Quick Demo
+@subsection Reconciliation
+
+The biggest task of maintaining a ledger is ensuring the it matches the
+outside world.  This process is called reconciliation (@xref{Basics of
+Reconciliation}) and can be quite onerous.  Ledger mode attempts to make
+it as painless as possible.
+
+In the @file{demo.ledger} buffer type @code{C-c C-r}.  Emacs will prompt
+for an account to reconcile in the mini-buffer.  Enter @code{Checking}.
+Emacs will then prompt for a target value.  The target value is the
+amount you want the cleared transactions in the buffer to total.
+Normally this would be the ending value from your bank statement, or the
+latest value in your on-line transaction summary.  Enter @code{1710}.
+Note that Ledger-mode assumes your are using $ (USD) as your default
+commodity, this can be easily changed in the customization
+variables. @xref{Ledger-mode Customization}
+
+You now see a list of uncleared transactions in a buffer below the
+@file{demo.ledger} buffer.  Touching the space bar will mark a
+transaction as pending and display the current cleared (and pending)
+balance, along with the difference remaining to meet your target. Clear
+the first three transactions, and you will see the difference to target
+reach $0.  End the reconcilitation by typing @code{C-c C-c}.  This saves
+the demo.ledger buffer and marks the transactions and finally cleared.
+Type @code{q} to close out the reconciliation buffer.
+
+@node Reports, Folding, Reconciliation, Quick Demo
+@subsection Reports
+
+The real power of Ledger is in it reporting capabilities.  Reports can
+be run and displayed in a spearate Emacs buffer.  In the
+@file{demo.ledger} buffer, type @code{C-c C-o C-r}.  In the mini-buffer
+Emacs will prompt for a report name.  There are a few built-in reports,
+and you can add any report you need @xref{Adding New Reports}.
+
+In the mini-buffer type @code{account}.  When prompted for an account
+type @code{checking}.  In another buffer you will see a Ledger register
+report. You can move around the buffer, with the point on a transaction,
+type @code{C-c C-c}.  Ledger mode will take you directly to that
+transaction in the @file{demo.ledger} buffer.  
+
+Another built-in report is the balance report.  In the
+@file{demo.ledger} buffer, type @code{C-c C-o C-r}.  When prompted for a
+report to run, type @code{bal}, and a balance report of all accounts
+will be shown.
+
+@node Folding,  , Reports, Quick Demo
+@subsection Folding
+
+A ledger file can get very large.  It can be helpful to collapse the buffer
+to display only the transactions you are interested in.  Ledger-mode
+copies the @code{occur} mode functionality.  Typing @code{C-c C-f} and
+entering any regex in the mini-buffer will show only transactions that
+match the regex.  The regex can be on any field, or amount.
+
+@node The Ledger Buffer, The Reconcile Buffer, Introduction to Ledger Mode, Top
+@chapter The Ledger Buffer
+@menu
+* Adding Transactions::         
+* Editing Amounts::             
+* Marking Transactions::        
+* Deleting Transactions::       
+* Sorting Transactions::        
+* Hiding Transactions::         
+@end menu
+
+@node Adding Transactions, Editing Amounts, The Ledger Buffer, The Ledger Buffer
+@section Adding Transactions
+
+Beyond the two ways of quickly adding transactions (@pxref{Quick Add})
+Ledger-mode assists you by providing robust @code{TAB} completion for
+payees and accounts.  Ledger-mode will scan the existing buffer for
+payees and accounts. Included files are not currently included in the
+completion scan. Repeatedly hitting @code{TAB} will cycle through the
+possible completions.
+
+Ledger mode can also help you keep your amounts in alignment.  Setting
+@code{ledger-post-auto-adjust-amounts} to true tells Ledger-mode to
+automatically place any amounts such that their last digit is aligned to
+the column specified by @code{ledger-post-amount-alignment-column},
+which defautls to 52. @xref{Ledger Post Customization Group}
+
+@node Editing Amounts, Marking Transactions, Adding Transactions, The Ledger Buffer
+@section Editing Amounts
+GNU Calc is a very powerful Reverse Polish Notation calculator built
+into all recent version of Emacs.  Ledger-mode makes it easy to
+calculate values for amount by integrating GNU Calc. With the point
+anywhere in the same line as a posting, typing @code{C-c C-b} will
+bring up the Calc buffer, and push the current amount for the posting
+onto the top of the Calc stack.  Perform any calculations you ened to
+arrive at the final vlaue, then type @code{y} to ynk the value at the
+top of stack back into the ledger buffer.  Note: GNU Calc does not
+directly support commas as decimal separators.  Ledger mode will
+translate values from decimal-comma format to decimal-period format for
+use in Calc, but it cannot intercept the value being yanked form the
+Calc stack, so decimal-comma users will have to manually replace the
+period with a comma.
+
+
+@node Marking Transactions, Deleting Transactions, Editing Amounts, The Ledger Buffer
+@section Marking Transactions
+Ledger considers transaction or posting to be in one of three states:
+uncleared, cleared, and pending.  For calculation Ledger ignores these
+states unless specifically instructed to use them.  Ledger-mode assigns
+some additional meaning to the states:
+@itemize
+@item Uncleared.
+No state.  This is equivalent to sticking a check in the mail.  It has
+been obligated, but not been cashed by the recipient.  It could also
+apply to credit/debit card transactions that have not been cleared into
+your account balance.  You bank may call these transactions 'pending',
+but Ledger-mode usues a slightly different meaning.
+@item Pending.
+Ledger-mode's reconciliation function see pending transactions as an
+intermediate step in reconciling an account.  When doing a
+reconciliation (@pxref{Reconciliation}), marking a transaction as
+pending means that you have seen the transaction finally recorded by the
+recipient, but you have not completely reconciled the account.
+@item Cleared.
+The transaction has been completely recognized by all parties to the transaction.
+@end itemize
+
+Clearing complete transactions is done by typing @code{C-c C-e} with
+point in a transaction.  This places an asterisk (@code{*}) after the
+date.  Clearing individual postings is done by typing @code{C-c C-c}
+while in a posting. This places an asterisk prior to the posting.
+
+@node Deleting Transactions, Sorting Transactions, Marking Transactions, The Ledger Buffer
+@section Deleting Transactions
+Along with normal buffer editing methods to delete text, Ledger mode
+provides an easy way to delete the transaction under point: @code{C-c
+C-d}.  The advantage to using this method is that the complete
+transaction operation is in the undo buffer.
+
+@node Sorting Transactions, Hiding Transactions, Deleting Transactions, The Ledger Buffer
+@section Sorting Transactions
+
+As you operating on the Ledger files, they may become disorganized.  For
+the most part, Ledger doesn't care, but our human brains prefer a bit of
+order.  Sorting the transactions in a buffer into chronological order
+can help bring order to chaos.  Ledger sort (@code C-c C-s) will sort
+all of the transactions in a region by date.  Ledger-mode isn't
+particularly smart about handling dates and it simply sorts the
+transactions using the string at the beginning of the transaction.  So,
+you should use the preferred ISO 8601 standard date format @code{YYYY/MM/DD}
+which easily sorts.
+
+Note, there is a menu entry to sort the entire buffer.  Special
+transactions like automated transactsion, will be moved in the sorting
+process and may not fucntion correctly afterwards.  For this reason
+there is no key sequence.
+
+@node Hiding Transactions,  , Sorting Transactions, The Ledger Buffer
+@section Hiding Transactions
+
+Ofen times you will want to run Ledger register reports just to look at
+a specific set of transactions.  If you don't need the running total
+calculation hadnled by Ledger, Ledger-mode provides a rapid way of
+narrowing what is displayed in the buffer in a way that is sipler than
+the Ledger register command.  
+
+Based on the Emacs Occur mode by Alexey Veretennikov, Ledger-occur hides
+all transactions that do NOT meet a specific regular expression.  The
+regular expression can match on any part of the transaction.  If you
+want to find all transactions whose amount ends in .37, you can do that
+( I don't know why, but hey, whatever ever flaots you aerostat).
+
+Using @code(C-c C-f) or the @code{Hide Xacts} menu entry, enter a
+regualr expression in the minbuffer.  Ledger-mode will hide all oter
+transactions.  For details of the regualr expression syntax, see the
+Emacs Manual or the Emac Elisp Reference Manual.  A few examples using
+the @file{demo.ledger} are given here:
+
+@table @samp
+@item Groceries
+Show only transactions that have a posting to the `Groceries' account.
+@item ^2011/01
+Show only transactions occuring in January of 2011.
+@item ^2011/.*/25
+Show only transactions occuring on the 25th of the month in 2011
+@item .*ore
+Show only transaction with payeees or accounts ending in `ore'
+@end table
+
+To show all transactions simply invoke @code{Hide Xacts} or @code{C-c
+C-f} again.
+
+@node The Reconcile Buffer, The Report Buffer, The Ledger Buffer, Top
+@chapter The Reconcile Buffer
+@menu
+* Basics of Reconciliation::    
+* Starting a Reconciliation::   
+* Mark Transactions Pending::   
+* Edit Transactions During Reconciliation::  
+* Finialize Reconciliation::    
+* Adding and Deleting Transactions during Reconciliation::  
+* Changing Reconciliation Account::  
+* Changing Reconciliation Target::  
+@end menu
+
+@node Basics of Reconciliation, Starting a Reconciliation, The Reconcile Buffer, The Reconcile Buffer
+@section Basics of Reconciliation
+
+Even in this relativley modern era, financial transactions do not happen
+instantaneously, unless you are paying cash.  When you swipe your debit
+card the money may take several days to actually come out of your
+account, or a check may take several days to ``clear''.  That is the
+root of the difference between ``obligating'' funds and ``expending''
+funds.  Obligation says you have agreed to pay it, the expnediture
+doesn't happen until the money actually leaves your account. Or in the
+case of receiving payment, you have an account receivable until the
+money has actually made it to you.
+
+After an account has been reconciled you have verified that all the
+transactions in that account have been correctly recorded and all
+parties agree. 
+
+@node Starting a Reconciliation, Mark Transactions Pending, Basics of Reconciliation, The Reconcile Buffer
+@section Starting a Reconciliation
+
+To start reconciling an account you must have a target, both the
+transactions that you know about and the transactions the bank knows
+about.  You can get this from a monthly statement, or from checking your
+online transaction history.  It also helps immensely to know the final
+cleared balance you are aiming for.
+
+Use menu @code{Reconcile Account} or @code{C-c C-r} and enter the
+account you wish to reconcile in the mini-buffer.  Ledger-mode is not
+particular about what you enter for the account.  You can leave it blank
+and Reconcile Mode will show you ALL uncleared transactions.  After you
+enter the account enter the target amount.  Ledger expects you to enter
+an amount with a commodity.  It assumes initially that you are using $
+(USD) as your default commodity.  If you are working in a difference
+currency you can change the default in variable
+@code(ledger-reconcile-default-commodity) to whatever you need.  If you
+work in multiple commodities simply enter the commoditized amount (for
+example @code{340 VSDX}, for 340 shares of VSDX).  
+
+Ledger-mode reconcile cannot currently reconcile accounts the have
+multiple commodities, such as brokerage accounts. You may use
+reconciliation mode to clear transactions, but balance calculations will
+not display the complete list of commodities.
+
+@node Mark Transactions Pending, Edit Transactions During Reconciliation, Starting a Reconciliation, The Reconcile Buffer
+@section Mark Transactions Pending
+
+The @file{*Reconcile*} buffer will show all the uncleared transactions
+that meeting the criteria set in the regex.  By default uncleared
+transactions are shown in red.  When you have verified that a
+transaction ahs been correctly and compeltely recorded by the opposing
+party, mark the transaction as pending using the space bar.  Continue
+this process until you agree with the opposing party and the difference
+from your target is zero.
+
+@node Edit Transactions During Reconciliation, Finialize Reconciliation, Mark Transactions Pending, The Reconcile Buffer
+@section Edit Transactions during Reconciliation 
+
+If you find errors during reconciliation.  You can visit the transaction
+under point in the @file{*Reconcile*} buffer by hitting the @code{enter}
+key.  This will take you to the transaction in the Ledger buffer.  When
+you have finished editing the transaction saving the buffer will
+automatically return you to the @file{*Reconcile*} buffer and you can
+mark the transaction if appropriate.
+
+@node Finialize Reconciliation, Adding and Deleting Transactions during Reconciliation, Edit Transactions During Reconciliation, The Reconcile Buffer
+@section Finalize Reconciliation
+
+Once you have marked all transactions as pending and the cleared balance
+is correct.  Finish the reconciliation by typing @code{C-c C-c}.  This
+marks all pending transaction as cleared and saves the ledger buffer.
+
+@node Adding and Deleting Transactions during Reconciliation, Changing Reconciliation Account, Finialize Reconciliation, The Reconcile Buffer
+@section Adding and Deleting Transactions during Reconciliation
+
+While reconciling, you may find new transactions that need to be entered
+into your ledger.  Simply type @code{a} to bring up the quick add for
+the ledger buffer.
+
+Typing @code{d} will delete the transaction under point in the
+@file{*Reconcile*} buffer form the ledger buffer.
+
+@node Changing Reconciliation Account, Changing Reconciliation Target, Adding and Deleting Transactions during Reconciliation, The Reconcile Buffer
+@section Changing Reconciliation Account
+
+You can conveniently switch the account being reconciled by typing
+@code{g}, and entering a new account to reconcile.  This simply restarts
+teh reconcile process. Any transactions that were marked `pending' in
+the ledger buffer are left in that state when the account is switched.
+
+@node Changing Reconciliation Target,  , Changing Reconciliation Account, The Reconcile Buffer
+@section Changing Reconciliation Target
+
+If for some reason during reconciliation your target amount changes,
+type @code{t} and enter the new target value.
+
+
+@node The Report Buffer, Customizing Ledger-mode, The Reconcile Buffer, Top
+@chapter The Report Buffer
+@menu
+* Running Basic Reports::       
+* Adding and Editing Reports::  
+* Reversing Report Order::      
+@end menu
+
+@node Running Basic Reports, Adding and Editing Reports, The Report Buffer, The Report Buffer
+@section Running Reports
+The real popwer behing Ledger is in its amazing reporting capability.
+Ledger-mode provides easy facility to run reports directly from emacs.
+It has four reports built-in and facilities for adding custom reports.
+
+Typeing @code{C-c C-o C-r} or using menu @code{Ledger Run Report} prompt
+for the name of a saved report.  The built-in reports are:
+@table @samp
+@item bal
+Produce a balance reports of all accounts.
+@item reg
+Produce a register report of all transactions.
+@item payee
+Prompt for a payee, the produce a register report of all transaction
+involving that payee.
+@item account
+Prompt for an account, the produce a register report of all transaction
+involving that account.
+@end table
+
+
+@node Adding and Editing Reports, Reversing Report Order, Running Basic Reports, The Report Buffer
+@section Adding and Editing Reports
+@menu
+* Expansion Formats::           
+* Make Report Transactions Active::  
+@end menu
+
+If you type a report name that Ledger-mode doesn't recognize it will
+prompt you for a ledger command line to run.  That command is
+automatically saved with the name given and you can re-run it at any
+time.
+
+There are two ways to edit the command line for a report. The first is
+to privide a prefix argument to the run-report command.  For example,
+type @code{M-1 C-c C-o C-r}. This will prompt you for the report name,
+then present the report command line to be edited.  When you hit enter,
+the report will be run, but it will not be permanently saved.  If you
+want to save it, type @code{S} in the the @file{*Ledger Report*} buffer you
+will have the option to give it a new name, or overwrite the old report.
+
+Deleting reports is accomplished by type @code{C-c C-o C-e} Edit Reports
+in the ledger buffer, or typing @code{E} in the @file{*Ledger Report*}
+buffer.  This takes you to the emacs customization window for the
+@code{ledger-reports} variable.  Use the widgets to delete the report
+you want removed.
+
+@node Expansion Formats, Make Report Transactions Active, Adding and Editing Reports, Adding and Editing Reports
+@subsection Expansion Formats
+
+It is sometime convenient to leave room to customize a report without
+saving the command line every time.  For example running a register
+report for a specific account, enter at runtime by the user.  The
+built-in report @file{account} does exactly that, using a variable
+expansion to prompt the user for the account to use.  There are four
+variable that can be expanded to run a report:
+
+@table @samp
+@item ledger-file
+Returns the file to be operated on.
+@item payee
+Prompts for a payee.
+@item account
+Prompt for an account.
+@item value
+Prompt for a tag value.
+@end table
+
+You can use these expansion values in your ledger report commands.  For
+example, if you wanted to specify a register report the displayed
+trnasactions from a user-determined account with a particular meta-data
+tag value, you specify the following command line:
+@smallexample
+ledger -f %(ledger-file) reg %(account)  --limit \"tag('my-tag') =~
+/%(value)/\"
+@end smallexample
+
+@noindent Note how the double-quotes are escaped with back-slashes.
+
+@node Make Report Transactions Active,  , Expansion Formats, Adding and Editing Reports
+@subsection Make Report Transactions Active
+
+In a large register report it is convenient to be anle to jump to the
+source transaction.  Ledger-mode will automatically include source
+information in every register file that doesn't contain a
+@code{--subtotal} option. It does this by adding a
+@code{--prepend-format='%(filename):%(beg_line):'} to the register
+report command-line you specify.  You should never have to see this, but
+if there is an error in your ledger output this additional information
+may not get stripped out of the visible report.
+
+@node Reversing Report Order,  , Adding and Editing Reports, The Report Buffer
+@section Reversing Report Order
+
+Often, banks show their online transaction historyies with the most recent
+transaction at the top.  Ledger itself cannot do a sensible ledger
+report in reverse chronoligcal order, if you sort on reverse date the
+calculation will also run in the opposite direction.  If you want to
+compare a ledger register report to a bank report with the most recent
+transactions at the top, type R in the @file{*Ledger Report*} buffer and
+it will reverse the order of the transactions and maintain the proper
+mathematical sense.
+
+
+@node Customizing Ledger-mode, Generating Ledger Regression Tests, The Report Buffer, Top
+@chapter Customizing Ledger-mode
+@menu
+* Ledger-mode Customization::   
+* Customization Variables::     
+@end menu
+
+@node Ledger-mode Customization, Customization Variables, Customizing Ledger-mode, Customizing Ledger-mode
+@section Ledger-mode Customization
+
+Ledger-mode has several options available for configuration.  All
+options can be configure through the Emacs customization menus, or
+specified in your Emacs initialization file.  The complete list of
+options is show below. To change the option using the Emacs
+customization menu, simply choe customize in the Options menu and look
+for Ledger under the data options.  Alternately you can choose
+``Customize Specific Group'' and enger ``Ledger'' as the group.
+
+@node Customization Variables,  , Ledger-mode Customization, Customizing Ledger-mode
+@section Customization Variables
+
+@menu
+* Ledger Customization Group::  
+* Ledger Reconcile Customization Group::  
+* Ledger Report Customization Group::  
+* Ledger Faces Customization Group::  
+* Ledger Post Customization Group::  
+* Ledger Exec Customization Group::  
+* Ledger Test Customization Group::  
+* Ledger Texi Customization Group::  
+@end menu
+
+@node Ledger Customization Group, Ledger Reconcile Customization Group, Customization Variables, Customization Variables
+@subsection Ledger Customization Group
+@table @code
+@item ledger-default-acct-transaction-indent
+   Default indentation for account transactions in an entry.
+@item ledger-occur-use-face-unfolded
+   If non-nil use a custom face for xacts shown in `ledger-occur' mode using @code{ledger-occur-xact-face}.
+@item ledger-clear-whole-transactions
+   If non-nil, clear whole transactions, not individual postings.
+@item ledger-highlight-xact-under-point
+   If non-nil highlight xact under point using @code{ledger-font-highlight-face}.
+@end table
+
+@node Ledger Reconcile Customization Group, Ledger Report Customization Group, Ledger Customization Group, Customization Variables
+@subsection Ledger Reconcile Customization Group
+
+@table @code
+@item ledger-reconcile-default-commodity
+The default commodity for use in target calculations in ledger
+reconcile.  Defaults to $ (USD)
+@item ledger-recon-buffer-name
+   Name to use for reconciliation window.
+@item ledger-fold-on-reconcile
+   If non-nil, limit transactions shown in main buffer to those matching the
+   reconcile regex.
+@item ledger-buffer-tracks-reconcile-buffer
+   If non-nil, then when the cursor is moved to a new xact in the recon
+   window.
+@item ledger-reconcile-force-window-bottom
+   If non-nil, make the reconcile window appear along the bottom of the
+   register window and resize.
+@item ledger-reconcile-toggle-to-pending
+   If non-nil, then toggle between uncleared and pending (@code{!}). If false
+   toggle between unlceared and cleared (@code{*})
+@end table
+
+@node Ledger Report Customization Group, Ledger Faces Customization Group, Ledger Reconcile Customization Group, Customization Variables
+@subsection Ledger Report Customization Group
+
+@table @code
+@item ledger-reports
+   Definition of reports to run.
+@item ledger-report-format-specifiers
+   An alist mapping ledger report format specifiers to implementing functions.  
+@end table
+
+
+@node Ledger Faces Customization Group, Ledger Post Customization Group, Ledger Report Customization Group, Customization Variables
+@subsection Ledger Faces Customization Group 
+Ledger Faces : Ledger mode highlighting
+@table @code
+@item ledger-font-uncleared-face
+Default face for Ledger
+@item ledger-font-cleared-face
+Default face for cleared (*) transactions
+@item ledger-font-highlight-face
+Default face for transaction under point
+@item ledger-font-pending-face
+Default face for pending (!) transactions
+@item ledger-font-other-face
+Default face for other transactions
+@item ledger-font-posting-account-face
+Face for Ledger accounts
+@item ledger-font-posting-amount-face
+Face for Ledger amounts
+@item ledger-occur-folded-face
+Default face for Ledger occur mode hidden transactions
+@item ledger-occur-xact-face
+Default face for Ledger occur mode shown transactions
+@item ledger-font-comment-face
+Face for Ledger comments
+@item ledger-font-reconciler-uncleared-face
+Default face for uncleared transactions in the reconcile window
+@item ledger-font-reconciler-cleared-face
+Default face for cleared (*) transactions in the reconcile window
+@item ledger-font-reconciler-pending-face
+Default face for pending (!) transactions in the reconcile window
+@item ledger-font-report-clickable-face
+Default face for pending (!) transactions in the reconcile window
+@end table
+
+@node Ledger Post Customization Group, Ledger Exec Customization Group, Ledger Faces Customization Group, Customization Variables
+@subsection Ledger Post Customization Group
+Ledger Post : 
+@table @code
+@item ledger-post-auto-adjust-amounts
+If non-nil, then automatically align amounts to column specified in
+@code{ledger-post-amount-alignment-column}
+@item ledger-post-amount-alignment-column
+The column Ledger-mode uses to align amounts
+@item ledger-post-use-completion-engine
+Which completion engine to use, iswitchb, ido, or built-in
+@item ledger-post-use-ido
+@end table
+
+@node Ledger Exec Customization Group, Ledger Test Customization Group, Ledger Post Customization Group, Customization Variables
+@subsection Ledger Exec Customization Group
+
+Ledger Exec : Interface to the Ledger command-line accounting program.
+
+@table @code
+@item ledger-binary-path
+Path to the ledger executable.
+@item ledger-init-file-name
+Location of the ledger initialization file. nil if you don't have one
+@end table
+
+
+@node Ledger Test Customization Group, Ledger Texi Customization Group, Ledger Exec Customization Group, Customization Variables
+@subsection Ledger Test Customization Group
+@table @code
+@item ledger-source-directory
+   Directory where the Ledger sources are located.
+@item ledger-test-binary
+   Directory where the debug binary.
+@end table
+
+@node Ledger Texi Customization Group,  , Ledger Test Customization Group, Customization Variables
+@subsection Ledger Texi Customization Group
+
+@table @code
+@item ledger-texi-sample-doc-path 
+Location for sample data to be used in texi tests, defaults to @file{~/ledger/doc/sample.dat}
+@item ledger-texi-normalization-args 
+texi normalization for producing ledger output, defaults to ``@code{--args-only --columns 80}''
+@end table
+
+@node Generating Ledger Regression Tests, Embedding Example results in Ledger Documentation, Customizing Ledger-mode, Top
+@chapter Generating Ledger Regression Tests
+
+Work in Progress.
+
+@node Embedding Example results in Ledger Documentation, Hacking Ledger-mode, Generating Ledger Regression Tests, Top
+@chapter Embedding Example results in Ledger Documentation
+
+Work in Progress.
+
+@node Hacking Ledger-mode,  , Embedding Example results in Ledger Documentation, Top
+@chapter Hacking Ledger-mode
+
+Work in Progress.
+@bye
diff --git a/lisp/ldg-commodities.el b/lisp/ldg-commodities.el
index 004d4f56..c5500785 100644
--- a/lisp/ldg-commodities.el
+++ b/lisp/ldg-commodities.el
@@ -29,7 +29,7 @@
 (defcustom ledger-reconcile-default-commodity "$"
   "The default commodity for use in target calculations in ledger reconcile."
   :type 'string
-  :group 'ledger)
+  :group 'ledger-reconcile)
 
 (defun ledger-split-commodity-string (str)
   "Split a commoditized amount into two parts"
diff --git a/lisp/ldg-exec.el b/lisp/ldg-exec.el
index af5dd3a8..d62fd419 100644
--- a/lisp/ldg-exec.el
+++ b/lisp/ldg-exec.el
@@ -38,7 +38,7 @@
 (defcustom ledger-binary-path "ledger"
   "Path to the ledger executable."
   :type 'file
-  :group 'ledger)
+  :group 'ledger-exec)
 
 (defun ledger-exec-ledger (input-buffer &optional output-buffer &rest args)
   "Run Ledger using INPUT-BUFFER and optionally capturing output in OUTPUT-BUFFER with ARGS."
diff --git a/lisp/ldg-init.el b/lisp/ldg-init.el
index fbb4b838..72317088 100644
--- a/lisp/ldg-init.el
+++ b/lisp/ldg-init.el
@@ -24,7 +24,7 @@
 
 (defcustom ledger-init-file-name "~/.ledgerrc"
   "Location of the ledger initialization file. nil if you don't have one"
-  :group 'ledger)
+  :group 'ledger-exec)
 
 (defvar ledger-environment-alist nil)
 
diff --git a/lisp/ldg-occur.el b/lisp/ldg-occur.el
index c3f04c5d..1561d6f8 100644
--- a/lisp/ldg-occur.el
+++ b/lisp/ldg-occur.el
@@ -35,7 +35,7 @@
 (defconst ledger-occur-overlay-property-name 'ledger-occur-custom-buffer-grep)
 
 (defcustom ledger-occur-use-face-unfolded t
-  "If non-nil use a custom face for xacts shown in `ledger-occur' mode."
+  "If non-nil, use a custom face for xacts shown in `ledger-occur' mode using ledger-occur-xact-face."
   :type 'boolean
   :group 'ledger)
 (make-variable-buffer-local 'ledger-occur-use-face-unfolded)
diff --git a/lisp/ldg-post.el b/lisp/ldg-post.el
index 14c3c55f..de28a8a9 100644
--- a/lisp/ldg-post.el
+++ b/lisp/ldg-post.el
@@ -28,7 +28,7 @@
 ;;; Code:
 
 (defgroup ledger-post nil
-  ""
+  "Options for controlling how Ledger-mode deals with postings and completion"
   :group 'ledger)
 
 (defcustom ledger-post-auto-adjust-amounts nil
@@ -37,19 +37,17 @@
   :group 'ledger-post)
 
 (defcustom ledger-post-amount-alignment-column 52
-  "If non-nil, ."
+  "The column Ledger-mode attempts to align amounts to."
   :type 'integer
   :group 'ledger-post)
 
-(defcustom ledger-post-use-iswitchb nil
-  "If non-nil, ."
-  :type 'boolean
-  :group 'ledger-post)
-
-(defcustom ledger-post-use-ido nil
-  "If non-nil, ."
-  :type 'boolean
-  :group 'ledger-post)
+(defcustom ledger-post-use-completion-engine :built-in
+  "Which completion engine to use, :iswitchb or :ido chose those engines,
+:built-in uses built-in Ledger-mode completion"
+   :type '(radio (const :tag "built in completion" :built-in) 
+	   (const :tag "ido completion" :ido) 
+	   (const :tag "iswitchb completion" :iswitchb) )
+   :group 'ledger-post)
 
 (defun ledger-post-all-accounts ()
   "Return a list of all accounts in the buffer."
@@ -73,13 +71,13 @@
 PROMPT is a string to prompt with.  CHOICES is a list of
    strings to choose from."
   (cond
-    (ledger-post-use-iswitchb
+    ((eq ledger-post-use-completion-engine :iswitchb)
      (let* ((iswitchb-use-virtual-buffers nil)
 	    (iswitchb-make-buflist-hook
 	     (lambda ()
 	       (setq iswitchb-temp-buflist choices))))
        (iswitchb-read-buffer prompt)))
-    (ledger-post-use-ido
+    ((eq ledger-post-use-completion-engine :ido)
      (ido-completing-read prompt choices))
     (t
      (completing-read prompt choices))))
@@ -114,7 +112,7 @@ PROMPT is a string to prompt with.  CHOICES is a list of
 
 (defun ledger-next-amount (&optional end)
   "Move point to the next amount, as long as it is not past END."
-  (when (re-search-forward "\\(  \\|\t\\| \t\\)[ \t]*-?\\([A-Z$€£]+ *\\)?\\(-?[0-9,]+?\\)\\(.[0-9]+\\)?\\( *[A-Z$€£]+\\)?\\([ \t]*@@?[^\n;]+?\\)?\\([ \t]+;.+?\\)?$" (marker-position end) t)
+  (when (re-search-forward "\\(  \\|\t\\| \t\\)[ \t]*-?\\([A-Z$€£]+ *\\)?\\(-?[0-9,]+?\\)\\(.[0-9]+\\)?\\( *[A-Z$€£]+\\)?\\([ \t]*@@?[^\n;]+?\\)?\\([ \t]+;.+?\\|[ \t]*\\)?$" (marker-position end) t)
     (goto-char (match-beginning 0))
     (skip-syntax-forward " ")
     (- (or (match-end 4)
diff --git a/lisp/ldg-reconcile.el b/lisp/ldg-reconcile.el
index 6a9d05fd..6093f9df 100644
--- a/lisp/ldg-reconcile.el
+++ b/lisp/ldg-reconcile.el
@@ -23,7 +23,7 @@
 
 
 ;;; Commentary:
-;; 
+;; Code to handle reconciling Ledger files wiht outside sources
 
 ;;; Code:
 
@@ -32,31 +32,35 @@
 (defvar ledger-acct nil)
 (defvar ledger-target nil)
 
+(defgroup ledger-reconcile nil
+   "Options for Ledger-mode reconciliation"
+  :group 'ledger)
+
 (defcustom ledger-recon-buffer-name "*Reconcile*"
   "Name to use for reconciliation window."
-  :group 'ledger)
+  :group 'ledger-reconcile)
 
 (defcustom ledger-fold-on-reconcile t
   "If t, limit transactions shown in main buffer to those matching the reconcile regex."
   :type 'boolean
-  :group 'ledger)
+  :group 'ledger-reconcile)
 
 (defcustom ledger-buffer-tracks-reconcile-buffer t
   "If t, then when the cursor is moved to a new xact in the recon window.
 Then that transaction will be shown in its source buffer."
   :type 'boolean
-  :group 'ledger)
+  :group 'ledger-reconcile)
 
 (defcustom ledger-reconcile-force-window-bottom nil
   "If t make the reconcile window appear along the bottom of the register window and resize."
   :type 'boolean
-  :group 'ledger)
+  :group 'ledger-reconcile)
 
 (defcustom ledger-reconcile-toggle-to-pending t
   "If true then toggle between uncleared and pending.
 reconcile-finish will mark all pending posting cleared."
    :type 'boolean
-   :group 'ledger)
+   :group 'ledger-reconcile)
 
 
 (defun ledger-reconcile-get-balances ()
diff --git a/lisp/ldg-report.el b/lisp/ldg-report.el
index 4db58494..0aa91ac0 100644
--- a/lisp/ldg-report.el
+++ b/lisp/ldg-report.el
@@ -28,6 +28,11 @@
 (eval-when-compile
   (require 'cl))
 
+(defgroup ledger-report nil
+  "Customization option for the Report buffer"
+  :group 'ledger
+)
+
 (defcustom ledger-reports
   '(("bal" "ledger -f %(ledger-file) bal")
     ("reg" "ledger -f %(ledger-file) reg")
@@ -46,7 +51,7 @@ in that variable for more information on the behavior of each
 specifier."
   :type '(repeat (list (string :tag "Report Name")
 		  (string :tag "Command Line")))
-  :group 'ledger)
+  :group 'ledger-report)
 
 (defcustom ledger-report-format-specifiers
   '(("ledger-file" . ledger-report-ledger-file-format-specifier)
@@ -58,7 +63,7 @@ specifier."
 The function is called with no parameters and expected to return the
 text that should replace the format specifier."
   :type 'alist
-  :group 'ledger)
+  :group 'ledger-report)
 
 (defvar ledger-report-buffer-name "*Ledger Report*")
 
diff --git a/lisp/ldg-test.el b/lisp/ldg-test.el
index 7667a05e..dbba9546 100644
--- a/lisp/ldg-test.el
+++ b/lisp/ldg-test.el
@@ -19,15 +19,19 @@
 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 ;; MA 02111-1307, USA.
 
-(defcustom ledger-source-directory "~/src/ledger"
-  "Directory where the Ledger sources are located."
-  :type 'directory
+(defgroup ledger-test nil
+  "Definitions for the Ledger testing framework"
   :group 'ledger)
 
-(defcustom ledger-test-binary "~/Products/ledger/debug/ledger"
+(defcustom ledger-source-directory "~/ledger/"
   "Directory where the Ledger sources are located."
+  :type 'directory
+  :group 'ledger-test)
+
+(defcustom ledger-test-binary "/Products/ledger/debug/ledger"
+  "Directory where the Ledger debug binary is located."
   :type 'file
-  :group 'ledger)
+  :group 'ledger-test)
 
 (defun ledger-test-org-narrow-to-entry ()
   (outline-back-to-heading)
diff --git a/lisp/ldg-texi.el b/lisp/ldg-texi.el
index 53e050ce..84ba34c2 100644
--- a/lisp/ldg-texi.el
+++ b/lisp/ldg-texi.el
@@ -19,9 +19,19 @@
 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 ;; MA 02111-1307, USA.
 
-(defvar ledger-path "/Users/johnw/bin/ledger")
-(defvar ledger-sample-doc-path "/Users/johnw/src/ledger/doc/sample.dat")
-(defvar ledger-normalization-args "--args-only --columns 80")
+(defgroup ledger-texi nil
+"Options for working on Ledger texi documentation"
+:group 'ledger)
+
+(defcustom ledger-texi-sample-doc-path "~/ledger/doc/sample.dat"
+"Location for sample data to be used in texi tests"
+:type 'file
+:group 'ledger-texi)
+
+(defcustom ledger-texi-normalization-args "--args-only --columns 80"
+"texi normalization for producing ledger output"
+:type 'string
+:group 'ledger-texi)
 
 (defun ledger-update-test ()
   (interactive)
@@ -92,10 +102,10 @@
 
 (defun ledger-texi-expand-command (command data-file)
   (if (string-match "\\$LEDGER" command)
-      (replace-match (format "%s -f \"%s\" %s" ledger-path
-                             data-file ledger-normalization-args) t t command)
-      (concat (format "%s -f \"%s\" %s " ledger-path
-		      data-file ledger-normalization-args) command)))
+      (replace-match (format "%s -f \"%s\" %s" ledger-binary-path
+                             data-file ledger-texi-normalization-args) t t command)
+      (concat (format "%s -f \"%s\" %s " ledger-binary-path
+		      data-file ledger-texi-normalization-args) command)))
 
 (defun ledger-texi-invoke-command (command)
   (with-temp-buffer (shell-command command t (current-buffer))
@@ -122,7 +132,7 @@
       (let ((section (match-string 1))
             (example-name (match-string 2))
             (command (match-string 3)) expanded-command
-            (data-file ledger-sample-doc-path)
+            (data-file ledger-texi-sample-doc-path)
             input output)
         (goto-char (match-end 0))
         (forward-line)
diff --git a/test/input/demo.ledger b/test/input/demo.ledger
new file mode 100644
index 00000000..dbf47c2a
--- /dev/null
+++ b/test/input/demo.ledger
@@ -0,0 +1,63 @@
+2010/12/01 * Checking balance
+  Assets:Checking                   $1,000.00
+  Equity:Opening Balances
+
+2010/12/20 * Organic Co-op
+  Expenses:Food:Groceries             $ 37.50  ; [=2011/01/01]
+  Expenses:Food:Groceries             $ 37.50  ; [=2011/02/01]
+  Expenses:Food:Groceries             $ 37.50  ; [=2011/03/01]
+  Expenses:Food:Groceries             $ 37.50  ; [=2011/04/01]
+  Expenses:Food:Groceries             $ 37.50  ; [=2011/05/01]
+  Expenses:Food:Groceries             $ 37.50  ; [=2011/06/01]
+  Assets:Checking                   $ -225.00
+
+2010/12/28 Acme Mortgage
+  Liabilities:Mortgage:Principal    $  200.00
+  Expenses:Interest:Mortgage        $  500.00
+  Expenses:Escrow                   $  300.00
+  * Assets:Checking                $ -1000.00
+
+2011/01/02 Grocery Store
+  Expenses:Food:Groceries             $ 65.00
+  * Assets:Checking
+
+2011/01/05 Employer
+  * Assets:Checking                 $ 2000.00
+  Income:Salary
+
+2011/01/14 Bank
+  ; Regular monthly savings transfer
+  Assets:Savings                     $ 300.00
+  Assets:Checking
+
+2011/01/19 Grocery Store
+  Expenses:Food:Groceries             $ 44.00 ; hastag: not block
+  Assets:Checking
+
+2011/01/25 Bank
+  ; Transfer to cover car purchase
+  Assets:Checking                  $ 5,500.00
+  Assets:Savings
+  ; :nobudget:
+
+2011/01/25 Tom's Used Cars
+  Expenses:Auto                    $ 5,500.00
+  ; :nobudget:
+  Assets:Checking
+
+2011/01/27 Book Store
+  Expenses:Books                       $20.00
+  Liabilities:MasterCard
+
+2011/04/25 Tom's Used Cars
+  Expenses:Auto                    $ 5,500.00
+  ; :nobudget:
+  Assets:Checking
+
+2011/04/27 Bookstore
+  Expenses:Books                       $20.00
+  Assets:Checking
+
+2011/12/01 Sale
+  Assets:Checking                     $ 30.00
+  Income:Sales