Move ledger-mode.texi to its own history

1 files changed, 1193 insertions, 0 deletions

diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi
new file mode 100644
index 0000000..8ff284b
--- /dev/null
+++ b/doc/ledger-mode.texi
@@ -0,0 +1,1193 @@
+\input texinfo  @c -*-texinfo-*-
+
+@setfilename ledger-mode.info
+@settitle Ledger: Command-Line Accounting
+
+@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with
+@c a prefix arg).  This updates the node pointers, which texinfmt.el
+@c needs.
+
+@copying
+
+Copyright @copyright{} 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:
+
+@itemize
+
+@item
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+@item
+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.
+
+@item
+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.
+
+@end itemize
+
+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
+
+@dircategory Major Modes
+@direntry
+* Ledger Mode: (ledger-mode).           Command-Line Accounting
+@end direntry
+
+@documentencoding UTF-8
+
+@iftex
+@finalout
+@end iftex
+
+@titlepage
+@title Ledger Mode
+@subtitle Emacs Support For Version 3.0 of Ledger
+@author Craig Earls
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+
+@node Top, Introduction to Ledger-mode, (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...
+
+@end ifnottex
+
+@menu
+* Introduction to Ledger-mode::
+* The Ledger Buffer::
+* The Reconcile Buffer::
+* The Report Buffer::
+* Scheduling Transactions::
+* Customizing Ledger-mode::
+* Generating Ledger Regression Tests::
+* Embedding Example results in Ledger Documentation::
+* Hacking Ledger-mode::
+* Concept Index::
+* Command & Variable Index::
+* Keystroke Index::
+@end menu
+
+@node Introduction to Ledger-mode, The Ledger Buffer, Top, 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
+@cindex 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}, or
+@file{~/.Aquamacs/Preferences.el}).
+
+@lisp
+(autoload 'ledger-mode "ledger-mode" "A major mode for Ledger" t)
+(add-to-list 'load-path
+             (expand-file-name "/path/to/ledger/source/lisp/"))
+(add-to-list 'auto-mode-alist '("\\.ledger$" . ledger-mode))
+@end lisp
+
+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
+@cindex menu
+
+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
+@cindex 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::
+* Narrowing::
+@end menu
+
+@node Quick Add, Reconciliation, Quick Demo, Quick Demo
+@subsection Quick Add
+@kindex C-c TAB
+@kindex C-c C-a
+
+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
+transactions are repetitions of earlier transactions.
+
+In the @file{demo.ledger} buffer enter a date using the correct
+format. Then type the first few characters of another payee in the
+@file{demo.ledger} buffer.  Type @kbd{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 use the ledger @command{xact} command, by either
+typing @kbd{C-c C-a} or using @samp{Add Transaction} menu entry. Then
+typing a close match to the payee. Ledger-mode will call @command{ledger
+xact} with the data you enter and place the transaction in the proper
+chronological place in the ledger.
+
+If you need to add a lot of transactions that are not near your current
+date you can set the current year and month so that using @samp{Add
+Transaction} will prompt you with a more convenient month and year.  To
+set the month type @kbd{C-c RET} and enter the month you want.  @kbd{C-c
+C-y} will prompt you for the year.  These settings only effect the
+@samp{Add Transaction} command.
+
+@node Reconciliation, Reports, Quick Add, Quick Demo
+@subsection Reconciliation
+@kindex C-c C-r
+@kindex SPC
+@kindex C-c C-c
+@kindex q
+
+The biggest task of maintaining a ledger is ensuring that it matches the
+outside world.  This process is called reconciliation (@pxref{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 @kbd{C-c C-r}.  If cursor is on an
+account, Ledger-mode will propose this account, or in the Minibuffer,
+will prompt for an account to reconcile.  Hit @kbd{RET} if you are happy
+with proposed account, or enter @samp{Checking} as example.
+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 @samp{1710}.
+Note that Ledger-mode assumes your are using @samp{$} (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 @kbd{SPC} 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 @samp{$0}.  End the reconciliation by typing @kbd{C-c C-c}.  This
+saves the @file{demo.ledger} buffer and marks the transactions and
+finally cleared.  Type @kbd{q} to close out the reconciliation buffer.
+
+@node Reports, Narrowing, Reconciliation, Quick Demo
+@subsection Reports
+@kindex C-c C-o C-r
+@kindex C-c C-c
+
+The real power of Ledger is in it reporting capabilities.  Reports can
+be run and displayed in a separate Emacs buffer.  In the
+@file{demo.ledger} buffer, type @kbd{C-c C-o C-r}.  In the Minibuffer
+Emacs will prompt for a report name.  There are a few built-in reports,
+and you can add any report you need @xref{Adding and Editing Reports}.
+
+In the Minibuffer type @samp{account}.  When prompted for an account
+type @samp{checking}.  In a buffer named @file{*Ledger Report*}, you
+will see a Ledger register report. You can move around the buffer, with
+the point on a transaction, type @kbd{RET}.  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 @kbd{C-c C-o C-r}.  When prompted for
+a report to run, type @samp{bal}, and a balance report of all accounts
+will be shown.
+
+@node Narrowing,  , Reports, Quick Demo
+@subsection Narrowing
+@kindex C-c C-f
+@kindex C-c C-g
+
+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 @command{occur} mode functionality.  Typing
+@kbd{C-c C-f} and entering any regex in the Minibuffer will show only
+transactions that match the regex.  The regex can be on any field, or
+amount.  Use @kbd{C-c C-g} after editing transactions to re-apply the
+current regex.  Cancel the narrowing by typing @kbd{C-c C-f} again.
+
+@node The Ledger Buffer, The Reconcile Buffer, Introduction to Ledger-mode, Top
+@chapter The Ledger Buffer
+
+@menu
+* Adding Transactions::
+* Copying Transactions::
+* Editing Amounts::
+* Marking Transactions::
+* Formatting Transactions::
+* Deleting Transactions::
+* Sorting Transactions::
+* Narrowing Transactions::
+@end menu
+
+
+@node Adding Transactions, Copying Transactions, The Ledger Buffer, The Ledger Buffer
+@section Adding Transactions
+@findex ledger-post-auto-adjust-amounts
+@findex ledger-post-amount-alignment-column
+@kindex TAB
+@cindex transaction, adding
+
+Beyond the two ways of quickly adding transactions (@pxref{Quick Add})
+Ledger-mode assists you by providing robust @kbd{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 @kbd{TAB} will cycle through the
+possible completions.
+
+Ledger-mode can also help you keep your amounts aligned.  Setting
+@option{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 @option{ledger-post-amount-alignment-column},
+which defaults to @samp{52}. @xref{Ledger Post Customization Group}.
+
+@menu
+* Setting a Transactions Effective Date::
+* Quick Balance Display::
+@end menu
+
+@node Setting a Transactions Effective Date, Quick Balance Display, Adding Transactions, Adding Transactions
+@subsection Setting a Transactions Effective Date
+@kindex C-c C-t
+@cindex effective date
+
+Ledger provides for adding information to a transaction that add details
+to the dates.  For example, you can specify when the transaction was
+entered, when the transaction was cleared, or when individual postings
+were cleared.
+Ledger-mode refers to these additional dates as @emph{effective} dates.
+To set the effective date of a transaction, place the point in the first
+line of a transaction and type @kbd{C-c C-t}.  The effective date will
+be added to the transaction.  To set the effective date for an
+individual posting, place point in the posting and type @kbd{C-c C-t} and
+the effective date for that posting will be added at the end of the
+posting.
+
+@node Quick Balance Display,  , Setting a Transactions Effective Date, Adding Transactions
+@subsection Quick Balance Display
+@kindex C-c C-p
+@cindex balance
+
+You will often want to quickly check the balance of an account.  The
+easiest way it to position point on the account you are interested in,
+and type @kbd{C-c C-p}.  The Minibuffer will ask you to verify the name
+of the account you want, if it is already correct hit @kbd{RET}, then
+the balance of the account will be displayed in the Minibuffer.
+
+@node Copying Transactions, Editing Amounts, Adding Transactions, The Ledger Buffer
+@section Copying Transactions
+@kindex C-c C-k
+@cindex transaction, copying
+
+An easy way to copy a transaction is to type @kbd{C-c C-k} or menu entry
+@samp{Copy Trans at Point}. You will be prompted the new date for the
+copied transaction, and after having confirmed with @kbd{RET}, new
+transaction will be inserted at @emph{date} position in buffer.
+
+@node Editing Amounts, Marking Transactions, Copying Transactions, The Ledger Buffer
+@section Editing Amounts
+@kindex C-c C-b
+@kindex y
+@cindex Calc
+@cindex GNU Emacs Calculator
+@cindex transaction, editing amounts
+
+GNU Emacs Calculator, aka @samp{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
+@command{Calc}. With the point anywhere in the same line as a posting,
+typing @kbd{C-c C-b} will bring up the @file{Calc} buffer, and push the
+current amount for the posting onto the top of the @command{Calc} stack.
+Perform any calculations you need to arrive at the final value, then
+type @kbd{y} to yank the value at the top of stack back into the ledger
+buffer.  Note: @command{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 @command{Calc},
+but it cannot intercept the value being yanked form the @command{Calc}
+stack, so decimal-comma users will have to manually replace the period
+with a comma.
+
+@node Marking Transactions, Formatting Transactions, Editing Amounts, The Ledger Buffer
+@section Marking Transactions
+@cindex transaction, marking
+@cindex uncleared
+@cindex pending
+@cindex cleared
+
+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 @emph{pending},
+but Ledger-mode uses 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
+
+@kindex C-c C-c
+@kindex C-c C-e
+
+Typing @kbd{C-c C-c}, depending where is the point, will clear the
+complete transaction, or an individual posting. This places an asterisk
+@samp{*} prior to the payee for the complete transaction, or prior to
+the account for an individual posting. When point is inside
+a transaction, specifically on an individual posting, you can still
+clear the complete transaction by typing @kbd{C-c C-e}.
+
+@node Formatting Transactions, Deleting Transactions, Marking Transactions, The Ledger Buffer
+@section Formatting Transactions
+@cindex transaction, formatting
+
+When editing a transaction, liberal use of the @kbd{TAB} key can keep
+the transaction well formatted.  If you want to have Ledger-mode cleanup
+the formatting of a transaction you can use @samp{Align Transaction} or
+@samp{Align Region} from the menu bar.
+
+The menu item @samp{Clean-up Buffer} sorts all transactions in the buffer
+by date, removes extraneous empty lines and aligns every transaction.
+
+
+@node Deleting Transactions, Sorting Transactions, Formatting Transactions, The Ledger Buffer
+@section Deleting Transactions
+@kindex C-c C-d
+@cindex transaction, deleting
+
+Along with normal buffer editing methods to delete text, Ledger-mode
+provides an easy way to delete the transaction under point: @kbd{C-c
+C-d}.  The advantage to using this method is that the complete
+transaction operation is in the undo buffer.
+
+@node Sorting Transactions, Narrowing Transactions, Deleting Transactions, The Ledger Buffer
+@section Sorting Transactions
+@kindex C-c C-s
+@cindex transaction, sorting
+
+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.  Either using @samp{Sort Region} menu
+entry or typing @kbd{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 @samp{YYYY/MM/DD} which easily sorts.
+
+Note, there is a menu entry @samp{Sort Buffer} to sort the entire
+buffer.  Special transactions like automated transaction, will be moved
+in the sorting process and may not function correctly afterwards.  For
+this reason there is no key sequence.
+
+You can limit the allowed sort region by using embedded Ledger-mode
+markup within your ledger.  For example:
+
+@example
+<<< information to not sort >>>
+
+; Ledger-mode: Start sort
+
+<<< transactions to sort >>>
+
+; Ledger-mode: End sort
+
+<<< information to not sort >>>
+@end example
+
+You can use menu entries @samp{Mark Sort Beginning} to insert start and
+@samp{Mark Sort End} to insert end markers.  These functions will
+automatically delete old markers and put new new marker at point.
+
+@node Narrowing Transactions,  , Sorting Transactions, The Ledger Buffer
+@section Narrowing Transactions
+@kindex C-c C-f
+@kindex C-c C-g
+@cindex transaction, narrowing
+@cindex transaction, display filtering
+
+Often 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 handled by Ledger, Ledger-mode provides a rapid way of
+narrowing what is displayed in the buffer in a way that is simpler than
+the Ledger register command.
+
+Based on the Emacs Occur mode by Alexey Veretennikov, Ledger-occur hides
+all transactions that do @emph{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 @samp{.37}, you can
+do that (I don't know why, but hey, whatever ever floats you aerostat).
+
+Using @kbd{C-c C-f} or the @samp{Narrow to Regex} menu entry, enter a
+regular expression in the Minibuffer.  Ledger-mode will hide all other
+transactions.  For details of the regular expression syntax, see your
+Emacs documentation.  A few examples using the @file{demo.ledger} are
+given here:
+
+@table @samp
+
+@item Groceries
+Show only transactions that have a posting to the @samp{Groceries}
+account.
+
+@item ^2011/01
+Show only transactions occurring in January of 2011.
+
+@item ^2011/.*/25
+Show only transactions occurring on the 25th of the month in 2011.
+
+@item auto
+Show only transactions with payees or accounts or comments containing.
+@samp{auto}
+
+@item harley$
+Show only transactions with any line ending with @samp{harley}.
+
+@end table
+
+To show back all transactions simply invoke @samp{Narrow to Regex} or
+@kbd{C-c C-f} again.
+
+If you've edited some transactions after narrowing such that they would
+no longer match the regular expression, you can refresh the narrowed
+view using @kbd{C-c C-g}.
+
+@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::
+* Finalize 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
+@cindex reconciliation, basics
+
+Even in this relatively 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 @emph{clear}.  That is the
+root of the difference between @emph{obligating} funds and
+@emph{expending} funds.  Obligation says you have agreed to pay it, the
+expenditure 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
+@findex ledger-reconcile-default-commodity
+@kindex C-c C-r
+@cindex reconciliation, starting
+
+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
+on-line transaction history.  It also helps immensely to know the final
+cleared balance you are aiming for.
+
+Use menu @samp{Reconcile Account} or keyboard shortcut @kbd{C-c C-r} to
+start reconciliation.
+
+If cursor is on an account, Ledger-mode will propose this account, or in
+the Minibuffer, will prompt for an account to reconcile. Hit @kbd{RET}
+if you are happy with proposed account, or enter @samp{Checking} as
+example. Ledger-mode is not particular about what you enter for the
+account.  You can leave it blank and @file{*Reconcile*} buffer will show
+you @emph{all} uncleared transactions.
+
+After you enter the account enter the target amount. It is helpful to
+enter an amount with a commodity. You can also leave it blank, you will
+be able to clear transactions but not benefit from balance calculations.
+It assumes initially that you are using @samp{$} (USD) as your default
+commodity.  If you are working in a different currency you can change
+the default in variable @option{ledger-reconcile-default-commodity} to
+whatever you need.  If you work in multiple commodities simply enter the
+commoditized amount (for example @samp{340 VSDX}, for 340 shares of
+VSDX).
+
+Ledger-mode reconcile cannot currently reconcile accounts that 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
+@kindex SPC
+@cindex reconciliation, transaction marking
+
+The @file{*Reconcile*} buffer will show all the uncleared transactions
+that meet the criteria set in the regex.  By default uncleared
+transactions are shown in red.  When you have verified that
+a transaction has been correctly and completely recorded by the opposing
+party, mark the transaction as pending using the @kbd{SPC} bar.
+Continue this process until you agree with the opposing party and the
+difference from your target is zero.
+
+@node Edit Transactions During Reconciliation, Finalize Reconciliation, Mark Transactions Pending, The Reconcile Buffer
+@section Edit Transactions during Reconciliation
+@kindex RET
+@kindex C-c C-c
+@cindex reconciliation, transaction editing
+
+If you find errors during reconciliation.  You can visit the transaction
+under point in the @file{*Reconcile*} buffer by hitting the @kbd{RET}
+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 Finalize Reconciliation, Adding and Deleting Transactions during Reconciliation, Edit Transactions During Reconciliation, The Reconcile Buffer
+@section Finalize Reconciliation
+@cindex reconciliation, finalizing
+@kindex C-c C-c
+@kindex q
+
+Once you have marked all transactions as pending and the cleared balance
+is correct.  Finish the reconciliation by typing @kbd{C-c C-c}.  This
+marks all pending transactions as cleared and saves the ledger buffer.
+
+Type @kbd{q} to close out the reconciliation buffer. If variable
+@var{ledger-reconcile-finish-force-quit} is set, the reconciliation
+buffer will be killed automatically after @kbd{C-c C-c}.
+
+@node Adding and Deleting Transactions during Reconciliation, Changing Reconciliation Account, Finalize Reconciliation, The Reconcile Buffer
+@section Adding and Deleting Transactions during Reconciliation
+@kindex a
+@kindex d
+@cindex reconciliation, transaction adding and deleting
+
+While reconciling, you may find new transactions that need to be entered
+into your ledger.  Simply type @kbd{a} to bring up the quick add for the
+ledger buffer.
+
+Typing @kbd{d} will delete the transaction under point in the
+@file{*Reconcile*} buffer from the ledger buffer.
+
+@node Changing Reconciliation Account, Changing Reconciliation Target, Adding and Deleting Transactions during Reconciliation, The Reconcile Buffer
+@section Changing Reconciliation Account
+@kindex g
+@cindex reconciliation, account changing
+
+You can conveniently switch the account being reconciled by typing
+@kbd{g}, and entering a new account to reconcile.  This simply restarts
+the reconcile process. Any transactions that were marked @emph{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
+@kindex t
+@cindex reconciliation, target changing
+
+If for some reason during reconciliation your target amount changes,
+type @kbd{t} and enter the new target value.
+
+@node The Report Buffer, Scheduling Transactions, 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
+@kindex C-c C-o C-r
+@kindex C-c C-o C-g
+@kindex C-c C-o C-a
+@cindex report, running
+
+The real power behind 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.
+
+Typing @kbd{C-c C-o C-r} or using menu @samp{Run Report} prompts
+for the name of a saved report.  The built-in reports are:
+
+@table @var
+
+@item bal
+Produce a balance reports of all accounts.
+
+@item reg
+Produce a register report of all transactions.
+
+@item payee
+Prompt for a payee, then produce a register report of all transactions
+involving that payee.
+
+@item account
+Prompt for an account, then produce a register report of all
+transactions involving that account.
+
+@end table
+
+While viewing reports you can easily switch back and forth between the
+ledger buffer and the @file{*Ledger Report*} buffer.  In @file{*Ledger
+Report*} buffer, typing @kbd{RET} will take you to that transaction in
+the ledger buffer.  While in the ledger buffer @kbd{C-c C-o C-g} returns
+you to the @file{*Ledger Report*} buffer.
+
+By default Ledger-mode will refresh the report buffer when the ledger
+buffer is saved.  If you want to rerun the report at another time
+@kbd{C-c C-o C-a}.  This is useful if you have other programs altering
+your ledger file outside of Emacs.
+
+
+@node Adding and Editing Reports, Reversing Report Order, Running Basic Reports, The Report Buffer
+@section Adding and Editing Reports
+@findex ledger-reports
+@kindex M-1 C-c C-o C-r
+@kindex S
+@kindex C-c C-o C-e
+@kindex e
+@cindex report, adding and editing
+
+@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 provide a prefix argument to the run-report command.  For example,
+type @kbd{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
+@kbd{RET}, the report will be run, but it will not be permanently saved.
+If you want to save it, type @kbd{S} in 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 typing @kbd{C-c C-o C-e} or using
+@samp{Edit Report} menu in the ledger buffer, or typing @kbd{e} in the
+@file{*Ledger Report*} buffer.  This takes you to the Emacs
+customization window for the Ledger Reports variables.  Use the widgets
+to delete the report you want removed.
+
+Typing @kbd{C-c C-o C-s} will prompt for a name and save the current
+report.
+
+@node Expansion Formats, Make Report Transactions Active, Adding and Editing Reports, Adding and Editing Reports
+@subsection Expansion Formats
+@cindex report, custom variable
+
+It is sometimes 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 entered at runtime by the user.  The
+built-in report @var{account} does exactly that, using a variable
+expansion to prompt the user for the account to use.  There are four
+variables that can be expanded to run a report:
+
+@table @var
+
+@item ledger-file
+Returns the file to be operated on.
+
+@item payee
+Prompts for a payee.
+
+@item account
+Prompt for an account.
+
+@item tagname
+Prompt for a meta-data tag name.
+
+@item tagvalue
+Prompt for a meta-data 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
+transactions from a user-determined account with a particular meta-data
+tag value, you specify the following command line:
+
+@example
+ledger -f %(ledger-file) reg %(account) \
+  --limit \"tag('my-tag') =~/%(value)/\"
+@end example
+
+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
+@cindex report, custom command
+
+In a large register report it is convenient to be able to jump to the
+source transaction.  Ledger-mode will automatically include source
+information in every register file that doesn't contain
+a @option{--subtotal} option. It does this by adding
+@option{--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
+@kindex R
+@cindex report, order reversing
+
+Often, banks show their on-line transaction histories with the most
+recent transaction at the top.  Ledger itself cannot do a sensible
+ledger report in reverse chronological 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 @kbd{R} in the @file{*Ledger
+Report*} buffer and it will reverse the order of the transactions and
+maintain the proper mathematical sense.
+
+@node Scheduling Transactions, Customizing Ledger-mode, The Report Buffer, Top
+@chapter Scheduling Transactions
+
+The Ledger program provides for automating transactions but these
+transaction aren't @emph{real}, they only exist inside a ledger session and
+are not reflected in the actual data file.  Many transactions are very
+repetitive, but may vary slightly in the date they occur on, or the
+amount.  Some transactions are weekly, monthly, quarterly or annually.
+Ledger mode provides a way to schedule upcoming transaction with a
+flexible scheduler that allows you to specify the transactions in a
+separate ledger file and calculate the upcoming occurrences of those
+transactions.  You can then copy the transactions into your live data
+file.
+
+@menu
+* Specifying Upcoming Transactions::
+@end menu
+
+@node Specifying Upcoming Transactions,  , Scheduling Transactions, Scheduling Transactions
+@section Specifying Upcoming Transactions
+
+The format for specifying transactions is identical to Ledger's file
+format with the exception of the date field.  The data field is modified
+by surrounding it with brackets and using wild cards and special
+characters to specify when the transactions should appear.
+
+@menu
+* Transactions that occur on specific dates::
+* Transactions that occur on specific days::
+@end menu
+
+@node Transactions that occur on specific dates, Transactions that occur on specific days, Specifying Upcoming Transactions, Specifying Upcoming Transactions
+@subsection Transactions that occur on specific dates
+
+Many times you will enter repetitive transactions that occur on the same
+day of the month each month.  These can be specified using a wild card
+in the year and month with a fixed date in the day.  The following entry
+specifies a transaction that occurs on the first and fifteenth of every
+month in every year.
+@example
+[*/*/1,15] Paycheck
+    Income:Job       $1000.00
+    Assets:Checking
+@end example
+
+Some transactions do not occur every month.  Comma separated lists of
+the months, or @samp{E} for even, or @samp{O} for odd number months can
+also be specified.  The following entry specifies a bi-monthly
+exterminator bill that occurs in the even months:
+@example
+[*/E/01]  Exterminator
+    Expenses:Home   $100.00
+    Assets:Checking
+@end example
+
+@node Transactions that occur on specific days,  , Transactions that occur on specific dates, Specifying Upcoming Transactions
+@subsection Transactions that occur on specific days
+
+Some transactions occur every relative to the day of the week rather
+than the date of the month.  For example, many people are paid every two
+weeks without regard to the day of the month.  Other events may occur on
+specific days regardless of the date.  For example the following
+transactions creates a transaction every other Thursday:
+
+@example
+[2014/11/27+2Th]  Paycheck
+    Income:Job       $1000.00
+    Assets:Checking
+@end example
+
+It is necessary to specify a starting date in order for this type of
+recurrence relation to be specified.  The day names are two character
+codes that default to Mo, Tu, We, Th, Fr, Sa, Su, for Monday, Tuesday,
+Wednesday, Thursday, Friday, Saturday, Sunday respectively.  You can
+change the codes to something more convenient for your locale by
+customizing the ledger @option{ledger-schedule-week-days}. They must be two
+characters long.
+
+
+
+@node Customizing Ledger-mode, Generating Ledger Regression Tests, Scheduling Transactions, 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 configured through the Emacs customization menus, or
+specified in your Emacs initialization file.  The complete list of
+options is shown below. To change the option using the Emacs
+customization menu, simply chose customize in the Options menu and look
+for Ledger under the data options.  Alternately you can choose
+@samp{Customize Specific Group} and enter @samp{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
+@cindex customization, ledger-mode
+
+@ftable @option
+
+@item ledger-occur-use-face-shown
+If non-nil, use a custom face for transactions shown in
+@option{ledger-occur} mode using @option{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 transaction under point using
+@option{ledger-font-highlight-face}.
+
+@end ftable
+
+@node Ledger Reconcile Customization Group, Ledger Report Customization Group, Ledger Customization Group, Customization Variables
+@subsection Ledger Reconcile Customization Group
+@cindex customization, reconcile
+
+@ftable @option
+
+@item ledger-recon-buffer-name
+Name to use for reconciliation buffer. Defaults to @file{*Reconcile*}.
+
+@item ledger-narrow-on-reconcile
+If t, limit transactions shown in main buffer to those matching
+the reconcile regex.
+
+@item ledger-buffer-tracks-reconcile-buffer
+If t, then when the cursor is moved to a new transaction in the
+@file{*Reconcile*} buffer. Then that transaction will be shown in its
+source buffer.
+
+@item ledger-reconcile-force-window-bottom
+If t, make the @file{*Reconcile*} window appear along the bottom
+of the register window and resize.
+
+@item ledger-reconcile-toggle-to-pending
+If t, then toggle between uncleared and pending @samp{!}. If
+false toggle between uncleared and cleared @samp{*}.
+
+@item ledger-reconcile-default-date-format
+Date format for the reconcile buffer. Defaults to
+@option{ledger-default-date-format}.
+
+@item ledger-reconcile-target-prompt-string
+Prompt for recon target. Defaults to "Target amount for reconciliation ".
+
+@item ledger-reconcile-buffer-header
+Header string for the reconcile buffer. If non-nil, the name of the
+account being reconciled will be substituted into the '%s'.  If nil, no
+header will be displayed.  Defaults to "Reconciling account %s\n\n".
+
+@item ledger-reconcile-buffer-line-format
+Format string for the ledger reconcile posting format.  Available fields
+are date, status, code, payee, account, amount.  The format for each
+field is %WIDTH(FIELD), WIDTH can be preceded by a minus sign which mean
+to left justify and pad the field.  WIDTH is the minimum number of
+characters to display; if string is longer, it is not truncated unless
+@option{ledger-reconcile-buffer-payee-max-chars} or
+@option{ledger-reconcile-buffer-account-max-chars} is defined.  Defaults to
+"%(date)s %-4(code)s %-50(payee)s %-30(account)s %15(amount)s\n"
+
+@item ledger-reconcile-buffer-payee-max-chars
+If positive, truncate payee name right side to max number of characters.
+
+@item ledger-reconcile-buffer-account-max-chars
+If positive, truncate account name left side to max number of characters.
+
+@item ledger-reconcile-sort-key
+Key for sorting reconcile buffer. Possible values are '(date)',
+'(amount)', '(payee)' or '(0)' for no sorting, i.e. using
+ledger file order. Defaults to '(0)'.
+
+@item ledger-reconcile-insert-effective-date nil
+If t, prompt for effective date when clearing transactions during
+reconciliation.
+
+@item ledger-reconcile-finish-force-quit nil
+If t, will force closing reconcile window after @kbd{C-c C-c}.
+
+@end ftable
+
+@node Ledger Report Customization Group, Ledger Faces Customization Group, Ledger Reconcile Customization Group, Customization Variables
+@subsection Ledger Report Customization Group
+@cindex customization, report
+
+@ftable @option
+
+@item ledger-reports
+Definition of reports to run.
+
+@item ledger-report-format-specifiers
+An alist mapping ledger report format specifiers to implementing
+functions.
+
+@end ftable
+
+@node Ledger Faces Customization Group, Ledger Post Customization Group, Ledger Report Customization Group, Customization Variables
+@subsection Ledger Faces Customization Group
+@cindex customization, faces
+
+Ledger Faces: Ledger-mode highlighting
+
+@ftable @option
+
+@item ledger-font-uncleared-face
+Default face for Ledger.
+
+@item ledger-font-cleared-face
+Default face for cleared @samp{*} transactions.
+
+@item ledger-font-highlight-face
+Default face for transaction under point.
+
+@item ledger-font-pending-face
+Default face for pending @samp{!} 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-account-cleared-face
+Face for cleared Ledger accounts.
+
+@item ledger-font-posting-account-pending-face
+Face for Ledger pending accounts.
+
+@item ledger-font-posting-amount-face
+Face for Ledger amounts.
+
+@item ledger-occur-narrowed-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 @file{*Reconcile*} buffer.
+
+@item ledger-font-reconciler-cleared-face
+Default face for cleared @samp{*} transactions in the @file{*Reconcile*}
+buffer.
+
+@item ledger-font-reconciler-pending-face
+Default face for pending @samp{!} transactions in the @file{*Reconcile*}
+buffer.
+
+@item ledger-font-report-clickable-face
+FIXME
+
+@end ftable
+
+@node Ledger Post Customization Group, Ledger Exec Customization Group, Ledger Faces Customization Group, Customization Variables
+@subsection Ledger Post Customization Group
+@cindex customization, post
+
+Ledger Post:
+
+@ftable @option
+
+@item ledger-post-auto-adjust-amounts
+If non-nil, then automatically align amounts to column specified in
+@option{ledger-post-amount-alignment-column}.
+
+@item ledger-post-amount-alignment-column
+The column Ledger-mode uses to align amounts.
+
+@item ledger-default-acct-transaction-indent
+Default indentation for account transactions in an entry.
+
+@item ledger-post-use-completion-engine
+Which completion engine to use: @var{iswitchb}, @var{ido}, or built-in.
+
+@item ledger-post-use-ido
+
+@end ftable
+
+@node Ledger Exec Customization Group, Ledger Test Customization Group, Ledger Post Customization Group, Customization Variables
+@subsection Ledger Exec Customization Group
+@cindex customization, executable
+
+Ledger Exec: Interface to the Ledger command-line accounting program.
+
+@ftable @option
+
+@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 ftable
+
+@node Ledger Test Customization Group, Ledger Texi Customization Group, Ledger Exec Customization Group, Customization Variables
+@subsection Ledger Test Customization Group
+@cindex customization, test
+
+@ftable @option
+
+@item ledger-source-directory
+Directory where the Ledger sources are located.
+
+@item ledger-test-binary
+Directory where the debug binary.
+
+@end ftable
+
+@node Ledger Texi Customization Group,  , Ledger Test Customization Group, Customization Variables
+@subsection Ledger Texi Customization Group
+@cindex customization, texi
+
+@ftable @option
+
+@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
+@samp{--args-only --columns 80}.
+
+@end ftable
+
+@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, Concept Index, Embedding Example results in Ledger Documentation, Top
+@chapter Hacking Ledger-mode
+
+Work in Progress.
+
+@node Concept Index, Command & Variable Index, Hacking Ledger-mode, Top
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Command & Variable Index, Keystroke Index, Concept Index, Top
+@unnumbered Command & Variable Index
+
+@printindex fn
+
+@node Keystroke Index,  , Command & Variable Index, Top
+@unnumbered Keystroke Index
+
+@printindex ky
+
+@bye
+
+@c Local Variables:
+@c mode: texinfo
+@c TeX-master: t
+@c End: