|
|
|
|
@ -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
|
Craig Earls