summaryrefslogtreecommitdiff
path: root/doc/ledger-mode.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ledger-mode.texi')
-rw-r--r--doc/ledger-mode.texi202
1 files changed, 157 insertions, 45 deletions
diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi
index c8af96cb..b76cb309 100644
--- a/doc/ledger-mode.texi
+++ b/doc/ledger-mode.texi
@@ -119,9 +119,9 @@ 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/"))
-(load "ledger-mode")
(add-to-list 'auto-mode-alist '("\\.ledger$" . ledger-mode))
@end lisp
@@ -175,6 +175,13 @@ 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
@@ -218,10 +225,10 @@ 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 another buffer you will see a Ledger register
-report. You can move around the buffer, with the point on a transaction,
-type @kbd{C-c C-c}. Ledger-mode will take you directly to that
-transaction in the @file{demo.ledger} buffer.
+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
@@ -231,13 +238,15 @@ 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.
+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
@@ -247,17 +256,12 @@ amount.
* Copying Transactions::
* Editing Amounts::
* Marking Transactions::
+* Formatting Transactions::
* Deleting Transactions::
* Sorting Transactions::
* Narrowing Transactions::
@end menu
-@c TODO
-@c Describe also:
-@c - Align Region
-@c - Set effective date C-c C-t
-@c - Set Year C-c C-t
-@c - Set Month C-c RET
@node Adding Transactions, Copying Transactions, The Ledger Buffer, The Ledger Buffer
@section Adding Transactions
@@ -273,17 +277,35 @@ 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 in alignment. Setting
+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 Quick Balance Display, , Adding Transactions, Adding Transactions
+@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
@@ -327,7 +349,7 @@ 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, Deleting Transactions, Editing Amounts, The Ledger Buffer
+@node Marking Transactions, Formatting Transactions, Editing Amounts, The Ledger Buffer
@section Marking Transactions
@cindex transaction, marking
@cindex uncleared
@@ -369,7 +391,20 @@ point in a transaction. This places an asterisk @samp{*} after the
date. Clearing individual postings is done by typing @kbd{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
+@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
@@ -421,6 +456,7 @@ 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
@@ -436,12 +472,11 @@ 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
-@ref{(emacs)Regexps, Syntax of Regular Expressions} or
-@ref{(elisp)Regular Expressions, Regular Expressions}. A few examples
-using the @file{demo.ledger} are given here:
+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
@@ -467,6 +502,10 @@ Show only transactions with any line ending with @samp{harley}.
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
@@ -602,22 +641,18 @@ type @kbd{t} and enter the new target value.
* Reversing Report Order::
@end menu
-@c TODO Describe also:
-@c - Goto Report C-c C-o C-g
-@c - Re-run Report C-c C-o C-a
-@c - Save Report C-c C-o C-s
-@c - Kill Report C-c C-o C-k
-
@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{Ledger Run Report} prompt
+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
@@ -638,6 +673,18 @@ 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
@@ -667,18 +714,21 @@ 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 Reports} menu in the ledger buffer, or typing @kbd{e} in the
+@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, enter at runtime by the user. The
+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:
@@ -694,9 +744,11 @@ Prompts for a payee.
@item account
Prompt for an account.
-@c FIXME : is it 'value' or 'tag' for '@item value' just below?
-@item value
-Prompt for a tag value.
+@item tagname
+Prompt for a meta-data tag name.
+
+@item tagvalue
+Prompt for a meta-data tag value.
@end table
@@ -742,14 +794,14 @@ maintain the proper mathematical sense.
@node Scheduling Transactions, Customizing Ledger-mode, The Report Buffer, Top
@chapter Scheduling Transactions
-The Ledger program provide for automating transactions but these
+The Ledger program provides for automating transactions but these
transaction aren't ``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 occurences of those
+separate ledger file and calculate the upcoming occurrences of those
transactions. You can then copy the transactions into your live data
file.
@@ -757,13 +809,66 @@ file.
* Specifying Upcoming Transactions::
@end menu
-@node Specifying Upcoming Transactions
+@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 to specity free
-months or years.
+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 @var{ledger-schedule-week-days}. They must be two
+characters long.
+
@node Customizing Ledger-mode, Generating Ledger Regression Tests, Scheduling Transactions, Top
@@ -837,11 +942,11 @@ the reconcile regex.
@item ledger-buffer-tracks-reconcile-buffer
If non-nil, then when the cursor is moved to a new transaction in the
-reconcile window.
+@file{*Reconcile*} window.
@item ledger-reconcile-force-window-bottom
-If non-nil, make the reconcile window appear along the bottom of the
-register window and resize.
+If non-nil, make the @file{*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 @samp{!}. If
@@ -909,13 +1014,15 @@ Default face for Ledger occur mode shown transactions.
Face for Ledger comments.
@item ledger-font-reconciler-uncleared-face
-Default face for uncleared transactions in the reconcile window.
+Default face for uncleared transactions in the @file{*Reconcile*} buffer.
@item ledger-font-reconciler-cleared-face
-Default face for cleared @samp{*} transactions in the reconcile window.
+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 reconcile window.
+Default face for pending @samp{!} transactions in the @file{*Reconcile*}
+buffer.
@item ledger-font-report-clickable-face
FIXME
@@ -1024,3 +1131,8 @@ Work in Progress.
@printindex ky
@bye
+
+@c Local Variables:
+@c mode: texinfo
+@c TeX-master: t
+@c End: