sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Started detailed emacs ledger mode section

Browse source
This commit is contained in:
Craig Earls 2011-11-15 20:34:20 -07:00 • committed by John Wiegley
parent 28f5cf0bfd
commit 7df0db9c0e
1 changed files with 212 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

225
doc/ledger3.texi
View file

@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@titlepage @titlepage
@title Ledger: Command-Line Accounting @title Ledger: Command-Line Accounting
@subtitle For Version 3.0 of Ledger @subtitle For Version 3.0 of Ledger
@subtitle Draft Manual Time-stamp: <2011-11-14 20:19 (cpearls)> @subtitle Draft Manual Time-stamp: <2011-11-15 13:51 (cpearls)>
@author John Wiegley @author John Wiegley
@end titlepage @end titlepage
@ -1472,6 +1472,7 @@ posting.
* Advanced Transactions:: * Advanced Transactions::
* File Format:: * File Format::
* Archiving Previous Years :: * Archiving Previous Years ::
* Using emacs::
@end menu @end menu
@node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal @node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal
@ -2370,7 +2371,7 @@ syntax of its timelog files.
@end table @end table
@node Archiving Previous Years , , File Format, Keeping a Journal @node Archiving Previous Years , Using emacs, File Format, Keeping a Journal
@section Archiving Previous Years @section Archiving Previous Years
@ -2429,7 +2430,204 @@ any electronic statements received during the year. In the arena of
organization, just keep in mind this maxim: Do whatever keeps you organization, just keep in mind this maxim: Do whatever keeps you
doing it. doing it.
@node Using emacs, , Archiving Previous Years , Keeping a Journal
@section Using emacs to Maintain Your Journal
@cindex emacs
@menu
* running ledger-mode::
* Working with entries::
* Reconciling accounts::
* Generating Reports::
@end menu
@node running ledger-mode, Working with entries, Using emacs, Using emacs
@subsection Running ledger-mode
Journal files are simple free text files easily modifed by any text
editor. A special mode for emacs is included with the source
distribution.
@cindex emacs .emacs file
To use the emacs mopy, copy the several lisp files from the source lisp
directory your your @file{site-lisp} directoy and add the following line
to your @file{.emacs} (or equivalent, @file{~/Aquamacs/Preferences.el}
for Aquamacs on Mac OS X)
@smallexample
(load "ledger")
@end smallexample
To trigger ledger mode when you visit a journal file, the first line of
each of your journal files should be:
@smallexample
; -*-ledger-*-
@end smallexample
To enter ledger-mode on a new file, type M-x ledger-mode.
Once you have loaded a Journal file into emacs, you have several
commands available to make entering, clearing and reconciling
transactions and producing reports:
@cindex emacs commands
@table @code
@item C-i or <TAB>
auto complete entry
@item C-c C-a
add a new entry, based on previous entries
@item C-c C-e
toggle cleared status of an entire entry
@item C-c C-c
toggle cleared status of an individual posting
@item C-c C-y
set default year for entry mode
@item C-c C-m
set default month for entry mode
@item C-c C-r
reconcile uncleared entries related to an account
@item C-c C-d
delete the current entry
@item C-c C-s
sort all entries in the journal by date. Drop comments outside of entries
@item C-c C-o C-r
run a ledger report
@item C-C C-o C-g
goto the ledger report buffer
@item C-c C-o C-e
edit the defined ledger reports
@item C-c C-o C-s
save a report definition based on the current report
@item C-c C-o C-a
rerun a ledger report
@item C-c C-o C-k
kill the ledger report buffer
@end table
@menu
* Working with entries::
* Reconciling accounts::
* Generating Reports::
@end menu
@node Working with entries, Reconciling accounts, running ledger-mode, Using emacs
@subsection Working with entries
@menu
* Manual Entry Support::
* Automagically Adding new entries::
* Clearing Transactions::
@end menu
@node Manual Entry Support, Automagically Adding new entries, Working with entries, Working with entries
@subsubsection Manual Entry Support
@cindex <TAB> completion
@cindex autocompletion
@cindex misspelled accounts treated as new
In most financial programs, some sort of autocompletion is avaiable to
save typing and improve accuracy. Ledger doesn't leave you hanging,
@code{ledger-mode} provides tab completion on all portions of an entry.
Type a portion of the payee and hit <TAB>, and @code{ledger-mode} will
suggest a completion. When filling in the account type the first few
letters followed by a <TAB> and the account will be filled in. For
example typing @samp{Ex<TAB>Au<TAB>F<TAB>} would yield
@samp{Expenses:Auto:Fuel} if you had previously used that account in
this journal. If there are more than one account with similar starting,
hitting <TAB> multiple times will iterate through them. This is a good
habit to get in to prevent misspellings of accounts. Remember Ledger
does not validate the names of payees or account so a misspelled account
will be interpreted as a new account by ledger.
@node Automagically Adding new entries, Clearing Transactions, Manual Entry Support, Working with entries
@subsubsection Automagically Adding new entries
@cindex new transactions in emacs
@cindex emacs, adding new transactions
@code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry
and xact}) from within emacs. When typed, the minibuffer will appear
with the current year and month, waiting for you to enter the day and
the payee. Ledger will generate a new entry based on the most recent
entry for that payee, using the amount and accounts from that
transaction. If you have a new amount simply type the amount after the
payee. For example, if your journal contains an entry
@smallexample
2011/11/25 Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
@noindent and you type @samp{C-c C-a}, the mini-buffer will appear showing the
current year and month. If you complete the minibuffer entry by typing
@smallexample
Entry: 2011/11/28 viva food 34 tip 7 <enter>
@end smallexample
@noindent emacs will add the following entry to your journal:
@smallexample
2011/11/30 Viva Italiano
Expenses:Food $34.00
Expenses:Tips $7.00
Liabilities:MasterCard
@end smallexample
@noindent Notice that the entry will appear at the correct place in the journal
ordered by date, not necessarily at the bottom of the file.
@node Clearing Transactions, , Automagically Adding new entries, Working with entries
@subsubsection Clearing Transactions and Postings
@cindex clearing transactions in emacs
@cindex emacs, clear transaction
@code{C-c C-e} will place an asterisk after the date in the current
transaction. The tells ledger the transaction has been cleared through
your bank (or whatever else you want the concept to mean)
@smallexample
2011/11/25 Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
@noindent becomes
@smallexample
2011/11/25 * Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
If, for some reason you need to clear a specific posting in the
transaction you can type @samp{C-c C-c} and the posting at point will be
toggled.
@node Reconciling accounts, Generating Reports, Working with entries, Using emacs
@subsection Reconciling accounts
In the reconcile buffer, use SPACE to toggle the cleared status of a
transaction, C-x C-s to save changes (to the ledger file as well).
@node Generating Reports, , Reconciling accounts, Using emacs
@subsection Generating Reports
The ledger reports command asks the user to select a report to run then
creates a report buffer containing the results of running the associated
command line. Its' behavior is modified by a prefix argument which,
when given, causes the generated command line that will be used to
create the report to be presented for editing before the report is
actually run. Arbitrary unnamed command lines can be run by specifying
an empty name for the report. The command line used can later be named
and saved for future use as a named report from the generated reports
buffer.
In a report buffer, the following keys are available:
@table @code
@item (space)
scroll up
@item e
edit the defined ledger reports
@item s
save a report definition based on the current report
@item q
quit the report (return to ledger buffer)
@item r
redo the report
@item k
kill the report buffer
@end table
@node Command-line Syntax, Reporting Commands, Keeping a Journal, Top @node Command-line Syntax, Reporting Commands, Keeping a Journal, Top
@ -2880,21 +3078,23 @@ a price history.
@end table @end table
Often you will be more interested in the value of your entire holdings, in Often you will be more interested in the value of your entire holdings,
your preferred currency. It might be nice to know you hold 10,000 shares in your preferred currency. It might be nice to know you hold 10,000
of PENNY, but you are more interested in whether or not that is worth shares of PENNY, but you are more interested in whether or not that is
$1000.00 or $10,000.00. However, the current day value of a commodity can worth $1000.00 or $10,000.00. However, the current day value of a
mean different things to different people, depending on the accounts commodity can mean different things to different people, depending on
involved, the commodities, the nature of the transactions, etc. the accounts involved, the commodities, the nature of the transactions,
etc.
When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that
some or all of the commodities be valuated as of today (or whatever some or all of the commodities be valuated as of today (or whatever
@samp{--now} is set to). But what does such a valuation mean? This @samp{--now} is set to). But what does such a valuation mean? This
meaning is governed by the presence of a @samp{VALUE} metadata meaning is governed by the presence of a @samp{VALUE} metadata property,
property, whose content is an expression used to compute that value. whose content is an expression used to compute that value.
If no VALUE property is specified, each posting is assumed to have a default, If no VALUE property is specified, each posting is assumed to have a
as if you'd specified a global, automated transaction as follows: default, as if you'd specified a global, automated transaction as
follows:
@smallexample @smallexample
= expr true = expr true
@ -2949,7 +3149,6 @@ posting or transaction, by overriding these general defaults using
specific metadata: specific metadata:
@smallexample @smallexample
2010-12-26 Example 2010-12-26 Example
Expenses:Food $20 Expenses:Food $20
; Just to be silly, always valuate *these* $20 as 30 DM, no matter what ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what