diff options
| -rw-r--r-- | doc/ledger-mode.texi | 1193 |
1 files changed, 0 insertions, 1193 deletions
diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi deleted file mode 100644 index 8ff284b1..00000000 --- a/doc/ledger-mode.texi +++ /dev/null @@ -1,1193 +0,0 @@ -\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: |