diff options
Diffstat (limited to 'doc/ledger-mode.texi')
| -rw-r--r-- | doc/ledger-mode.texi | 224 |
1 files changed, 182 insertions, 42 deletions
diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi index 8ab8e11d..b76cb309 100644 --- a/doc/ledger-mode.texi +++ b/doc/ledger-mode.texi @@ -89,6 +89,7 @@ reports and much more... * The Ledger Buffer:: * The Reconcile Buffer:: * The Report Buffer:: +* Scheduling Transactions:: * Customizing Ledger-mode:: * Generating Ledger Regression Tests:: * Embedding Example results in Ledger Documentation:: @@ -118,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 @@ -174,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 @@ -217,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 @@ -230,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 @@ -246,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 @@ -272,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 @@ -326,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 @@ -368,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 @@ -420,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 @@ -435,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 @@ -466,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 @@ -592,7 +632,7 @@ the ledger buffer are left in that state when the account is switched. If for some reason during reconciliation your target amount changes, type @kbd{t} and enter the new target value. -@node The Report Buffer, Customizing Ledger-mode, The Reconcile Buffer, Top +@node The Report Buffer, Scheduling Transactions, The Reconcile Buffer, Top @chapter The Report Buffer @menu @@ -601,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 @@ -637,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 @@ -666,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: @@ -693,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 @@ -738,7 +791,87 @@ 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 Customizing Ledger-mode, Generating Ledger Regression Tests, The Report Buffer, Top +@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 ``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 @var{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 @@ -809,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 @@ -881,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 @@ -996,3 +1131,8 @@ Work in Progress. @printindex ky @bye + +@c Local Variables: +@c mode: texinfo +@c TeX-master: t +@c End: |