diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CMakeLists.txt | 2 | ||||
| -rw-r--r-- | doc/NEWS | 27 | ||||
| -rw-r--r-- | doc/ledger-mode.texi | 1193 | ||||
| -rw-r--r-- | doc/ledger.1 | 16 | ||||
| -rw-r--r-- | doc/ledger3.texi | 278 |
5 files changed, 228 insertions, 1288 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index e463c721..d8242eeb 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -42,7 +42,7 @@ if (BUILD_DOCS) find_program(TEX tex) find_program(MAN2HTML man2html) find_program(GROFF groff) - set(ledger_info_files ledger3.texi ledger-mode.texi) + set(ledger_info_files ledger3.texi) if (NOT MAKEINFO) message(WARNING "Could not find makeinfo. Info version of documentation cannot be built.") @@ -1,5 +1,32 @@ Ledger NEWS +* 3.1.2 + +- Increased maximum length for regex from 255 to 4095 (bug #981). + +- Initialize periods from from/since clause rather than earliest + transaction date (bug #1159). + +- Check balance assertions against the amount after the posting (bug #1147). + +- Allow balance assertions with multiple posts to same account (bug #1187). + +- Fixed period duration of "every X days" and similar statements (bug #370). + +- Option --force-color does not require --color anymore (bug #1109). + +- Added quoted_rfc4180 to allow CVS output with RFC 4180 compliant quoting. + +- Python: Removed double quotes from Unicode values. + +- Emacs Lisp files have been moved to https://github.com/ledger/ledger-mode + +- Fixed build under MSYS (32-bit). + +- Fixed build under Cygwin. + +- Various documentation improvements + * 3.1.1 - Added a --no-revalued option 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: diff --git a/doc/ledger.1 b/doc/ledger.1 index ffc7decf..fc4dd3c0 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -1,4 +1,4 @@ -.Dd March 23, 2012 +.Dd February 16, 2017 .Dt LEDGER 1 .Os .Sh NAME @@ -6,8 +6,8 @@ .Nd Command-line, double-entry account reporting tool .Sh SYNOPSIS .Nm -.Op Ar command .Op Ar options +.Op Ar command .Op Ar arguments .Sh DESCRIPTION .Nm @@ -111,9 +111,8 @@ The synonym is also accepted. .It Ic emacs Oo Ar query Oc Output posting and transaction data in a format readily consumed by the Emacs -editor, in a series of Lisp forms. This is used by the -.Pa ledger.el -Emacs mode to process reporting data from +editor, in a series of Lisp forms. This is used by the Emacs ledger-mode to +process reporting data from .Nm . .It Ic equity Oo Ar report-query Oc Print a transaction with a series of postings that balance current totals for @@ -215,6 +214,9 @@ Note that a comma-separated list of expressions is allowed, in which case each sorting term is used in order to determine the final ordering. For example, to search by date and then amount, one would use: .Dl ledger reg --sort 'date, amount' +The sort order may be controlled with the '-' sign. For example, to sort in +reverse chronological order: +.Dl ledger reg --sort '-date' .It Fl \-tail Ar number Only show the last .Ar number @@ -1284,6 +1286,10 @@ for values that have a per-unit cost. Surround .Ar expression with double-quotes. +.It Fn quoted_rfc4180 expression +Surround +.Ar expression +with double-quotes, compatible with rfc 4180. .It Sy real .\" Is there a difference between real and actual? Return true if the transaction is real, i.e not a automated or virtual diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 5e266253..45afe1ae 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -111,7 +111,7 @@ @copying -Copyright @copyright{} 2003–2015, John Wiegley. All rights reserved. +Copyright @copyright{} 2003--2018, John Wiegley. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are @@ -179,7 +179,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 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 -twinkling in their father's CRT. +twinkling in their fathers' CRTs. @end ifnottex @@ -212,6 +212,7 @@ twinkling in their father's CRT. * Fat-free Accounting:: * Building the program:: * Getting help:: +* Third-Party Ledger Tutorials:: @end menu @node Fat-free Accounting, Building the program, Introduction to Ledger, Introduction to Ledger @@ -400,7 +401,7 @@ options. You can run `make check` to confirm the result, and `make install` to install. If these intructions do not work for you can check the `INSTALL.md` in the source directory for more up do date build instructions. -@node Getting help, , Building the program, Introduction to Ledger +@node Getting help, , Building the program, Introduction to Ledger @section Getting help @findex help @@ -417,6 +418,23 @@ join the Ledger mailing list at You can also find help in the @code{#ledger} channel on the IRC server @code{irc.freenode.net}. +@node Third-Party Ledger Tutorials, , Getting help, Introduction to Ledger +@section Third-Party Ledger Tutorials + +There are plenty of people using Ledger for accounting applications. +Some have documented how they use Ledger's features to solve their +accounting problems. + +Once such tutorial, specifically designed for non-profit charities that seek +to use Ledger, can be found at +@url{https://k.sfconservancy.org/npo-ledger-cli} (with a copy on GitHub also +available at @url{https://github.com/conservancy/npo-ledger-cli/}). If +you're looking for information about how to use Ledger's tagging system to +handle invoicing, track expenses by program targets, and other such concepts, +you might find the tutorial useful. (Some of the auditor reporting scripts +that relate to the aformentioned Ledger setup can be found +@var{contrib/non-profit-audit-reports/} in Ledger's own source repository.) + @node Ledger Tutorial, Principles of Accounting with Ledger, Introduction to Ledger, Top @chapter Ledger Tutorial @cindex tutorial @@ -1078,7 +1096,7 @@ $40880.00 Assets:Brokerage You can convert from any commodity to any other commodity. Let's say you had $5000 in your checking account, and for whatever reason you -wanted to know many ounces of gold that would buy, in terms of the +wanted to know how many ounces of gold that would buy, in terms of the current price of gold: @smallexample @@ -1255,7 +1273,7 @@ worth $5000, then you have $5000 in equity in that car. In order to turn that car (a commodity) into a cash flow, or a credit to your bank account, you will have to debit the equity by selling it. -When you start a ledger, you are probably already worth something. +When you start a ledger, you probably already have a net worth. Your net worth is your current equity. By transferring the money in the ledger from your equity to your bank accounts, you are crediting the ledger account based on your prior equity. That is why, when you @@ -1339,7 +1357,7 @@ account point of view and from the fund point of view---yet both sets should reflect the same overall expenses and cash flow. It's simply where the money resides that differs. -This situation can be handled one of two ways. The first is using +This situation can be handled in one of two ways. The first is using virtual postings to represent the fact that money is moving to and from two kind of accounts at the same time: @@ -1490,13 +1508,14 @@ nature of your transactions. For example, you do not need to tell Ledger about the accounts you use. Any time Ledger sees a posting involving an account it knows nothing about, it will create it@footnote{This also means if you -misspell an account it will end up getting counted separately from what -you intended. The provided Emacs major mode provides for automatically -filling in account names.}. If you use a commodity that is new to -Ledger, it will create that commodity, and determine its display -characteristics (placement of the symbol before or after the amount, -display precision, etc.) based on how you used the commodity in the -posting. +misspell an account it will end up getting counted separately from +what you intended. An Emacs major mode +@uref{https://github.com/ledger/ledger-mode/, ledger-mode} provides +tab completion for automatically filling in account names.}. If you +use a commodity that is new to Ledger, it will create that commodity, +and determine its display characteristics (placement of the symbol +before or after the amount, display precision, etc.) based on how you +used the commodity in the posting. @menu * The Most Basic Entry:: @@ -1976,7 +1995,7 @@ amount using the @samp{(( ))} commodity annotation. 2012-03-07 KFC Expenses:Food7 1 CAD - Assets:Cas7 + Assets:Cash7 2012-03-08 XACT Expenses:Food8 $1 @@ -2236,6 +2255,41 @@ Would result in all postings going into @samp{Personal:Expenses:Groceries} and @samp{Personal:Assets:Checking} until an @samp{end apply account} directive was found. +@item apply fixed +@findex fixed +@cindex fixated prices +@c instance_t::fixed_directive in textual.cc + +A fixed block is used to set fixated prices (@pxref{Fixated prices and +costs}) for a series of transactions. It's purely a typing saver, for +use when entering many transactions with fixated prices. + +Thus, the following: + +@smallexample @c input:validate +apply fixed CAD $0.90 +2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD + Expenses:Food 15.50 CAD + +2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD + Expenses:Food 25.75 CAD +end apply fixed +@end smallexample + +is equivalent to this: + +@smallexample @c input:validate +2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD @{=$0.90@} + Expenses:Food 15.50 CAD @{=$0.90@} + +2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD @{=$0.90@} + Expenses:Food 25.75 CAD @{=$0.90@} +@end smallexample + @item alias @findex alias @cindex account, alias @@ -2383,6 +2437,7 @@ commodity $ note American Dollars format $1,000.00 nomarket + alias USD default @end smallexample @@ -2397,6 +2452,9 @@ provide the ``canonical'' representation. The @code{nomarket} sub-directive states that the commodity's price should never be auto-downloaded. +The @code{alias} sub-directive states that any commodity matching this +symbol is to use the commodity declared in this block. + The @code{default} sub-directive marks this as the ``default'' commodity. @item define @@ -2417,59 +2475,18 @@ The posting will have a cost of $400. @item end @findex end @c instance_t::end_directive in textual.cc -Closes block commands like @code{tag} or @code{comment}. +Closes block commands like @code{apply} or @code{comment}. @item expr @findex expr @c instance_t::expr_directive in textual.cc -@item fixed -@findex fixed -@cindex fixated prices -@c instance_t::fixed_directive in textual.cc - -A fixed block is used to set fixated prices (@pxref{Fixated prices and -costs}) for a series of transactions. It's purely a typing saver, for -use when entering many transactions with fixated prices. - -Thus, the following: - -@smallexample @c input:validate -fixed CAD $0.90 -2012-04-10 Lunch in Canada - Assets:Wallet -15.50 CAD - Expenses:Food 15.50 CAD - -2012-04-11 Second day Dinner in Canada - Assets:Wallet -25.75 CAD - Expenses:Food 25.75 CAD -endfixed CAD -@end smallexample - -is equivalent to this: - -@smallexample @c input:validate -2012-04-10 Lunch in Canada - Assets:Wallet -15.50 CAD @{=$0.90@} - Expenses:Food 15.50 CAD @{=$0.90@} - -2012-04-11 Second day Dinner in Canada - Assets:Wallet -25.75 CAD @{=$0.90@} - Expenses:Food 25.75 CAD @{=$0.90@} -@end smallexample - -Note that ending a @code{fixed} is done differently than other -directives, as @code{fixed} is closed with an @code{endfixed} (i.e., -there is @emph{no space} between @code{end} and @code{fixed}). - -For the moment, users may wish to study -@uref{http://bugs.ledger-cli.org/show_bug.cgi?id=789, Bug Report 789} -before using the @code{fixed} directive in production. - @item include @findex include @c instance_t::include_directive in textual.cc -Include the stated file as if it were part of the current file. +Include the stated file as if it were part of the current file. The file +name can contain a wildcard (@samp{*}) to refer to multiple files (e.g. +@samp{bank/*.ledger}). @item payee @findex payee @@ -2714,14 +2731,17 @@ that make it very simple: @command{print}, and @command{equity}. Let's take an example file, with data ranging from year 2000 until 2004. We want to archive years 2000 and 2001 to their own file, -leaving just 2003 and 2004 in the current file. So, use -@command{print} to output all the earlier transactions to a file -called @file{ledger-old.dat}: +leaving 2002--2004 in the current file. So, use @command{print} to +output all the earlier transactions to a file called +@file{ledger-old.dat}: @smallexample -$ ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat +$ ledger -f ledger.dat -b 2000 -e 2002 print > ledger-old.dat @end smallexample +Note that @option{-e} limits output to transactions @emph{before} the +date specified. + To delete older data from the current ledger file, use @command{print} again, this time specifying year 2002 as the starting date: @@ -2892,7 +2912,7 @@ you a place to put those codes: A transaction can have a ``state'': cleared, pending, or uncleared. The default is uncleared. To mark a transaction cleared, put an asterisk -@samp{*} before the payee, after the date or code: +@samp{*} after the date, before the code or payee: @smallexample @c input:validate 2012-03-10 * KFC @@ -2950,7 +2970,7 @@ You can mark individual postings as cleared or pending, in case one @section Transaction notes After the payee, and after at least one tab or two spaces (or a space -and a tab, which Ledger calls a ``hard separator''), you may +and a tab), which Ledger calls a ``hard separator'', you may introduce a note about the transaction using the @samp{;} character: @smallexample @c input:validate @@ -3052,7 +3072,7 @@ used as the payee name for that posting. This affects the This is useful when for example you deposit 4 checks at a time to the bank. On the bank statement, there is just one amount @samp{$400}, but -you can specify from whom each check came from, as shown by example +you can specify from whom each check came, as shown by example below: @smallexample @c input:9B43E57 @@ -3210,6 +3230,45 @@ A balance assertion has this general form: This simply asserts that after subtracting $20.00 from Assets:Cash, that the resulting total matches $500.00. If not, it is an error. +The assertion has an effect only on the specified commodity. If an account has +multiple commodities, then only the one asserted is verified: + +@smallexample +2012-03-10 KFC New York + Expenses:Food $20.00 + Assets:Cash $-20.00 = $500.00 + +2012-03-11 KFC Montreal + Expenses:Food 15.00 CAD + Assets:Cash -15.00 CAD = $500.00 +@end smallexample + +In this case, the amount in USD of cash (which has not changed) is validated. +Nothing is asserted about the current amount of Canadian dollars in @samp{Asset:Cash}. + +@subsubsection Special assertion value 0 + +The only value that can be asserted without a commodity is @samp{0}. +This results in a cross-commodities assertion, which makes it possible to +assert that an account is totally empty. + +@smallexample +2012-03-09 Fill Wallet + Revenue $20.00 + Revenue 15.00 CAD + Assets:Cash + +2012-03-10 KFC New York + Expenses:Food $20.00 + Assets:Cash $-20.00 + +2012-03-11 KFC Montreal + Expenses:Food 15.00 CAD + Assets:Cash -15.00 CAD = 0 +@end smallexample + +The last transaction will assert that we are out of cash of any sort. + @node Balance assignments, Resetting a balance, Balance assertions, Balance verification @subsection Balance assignments @@ -3238,7 +3297,7 @@ adjustment transaction using balance assignments: Equity:Adjustments @end smallexample -Since the second posting is also null, it's value will become the +Since the second posting is also null, its value will become the inverse of whatever amount is generated for the first posting. This is the only time in ledger when more than one posting's amount @@ -3501,7 +3560,7 @@ But this does not do what you might expect: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 @@ -3527,11 +3586,11 @@ following two transactions are equivalent: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage 10 AAPL @{$50.00@} - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 @end smallexample However, note that what you see in some reports may differ, for @@ -3542,15 +3601,16 @@ sensitive to this difference. @node Fixated prices and costs, Lot dates, Prices versus costs, Transactions @section Fixated prices and costs -If you buy a stock last year, and ask for its value today, Ledger will -consult its price database to see what the most recent price for that -stock is. You can short-circuit this lookup by ``fixing'' the price -at the time of a transaction. This is done using @samp{@{=AMOUNT@}}: +If you bought a stock last year, and ask for its value today, Ledger +will consult its price database to see what the most recent price for +that stock is. You can short-circuit this lookup by ``fixing'' the +price at the time of a transaction. This is done using +@samp{@{=AMOUNT@}}: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @{=$50.00@} - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 @end smallexample These 10 AAPL will now always be reported as being worth $50, no @@ -3566,7 +3626,7 @@ fixated prices by way of the cost: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @@ =$50.00 - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 @end smallexample This is the same as the previous transaction, with the same caveats @@ -6234,11 +6294,25 @@ Specify the format to use for the @command{budget} report (@pxref{Format Strings}). The default is: @smallexample -"%(justify(scrub(display_total), 20, -1, true, color))" +"%(justify(scrub(get_at(display_total, 0)), 12, -1, true, color))" +" %(justify(-scrub(get_at(display_total, 1)), 12, " +" 12 + 1 + 12, true, color))" +" %(justify(scrub(get_at(display_total, 1) + " +" get_at(display_total, 0)), 12, " +" 12 + 1 + 12 + 1 + 12, true, color))" +" %(ansify_if(" +" justify((get_at(display_total, 1) ? " +" (100% * quantity(scrub(get_at(display_total, 0)))) / " +" -quantity(scrub(get_at(display_total, 1))) : 0), " +" 5, -1, true, false)," +" magenta if (color and get_at(display_total, 1) and " +" (abs(quantity(scrub(get_at(display_total, 0))) / " +" quantity(scrub(get_at(display_total, 1)))) >= 1))))" " %(!options.flat ? depth_spacer : \"\")" -"%-(ansify_if(partial_account(options.flat), blue if color))\n%/" -"%$1\n%/" -"--------------------\n" +"%-(ansify_if(partial_account(options.flat), blue if color))\n" +"%/%$1 %$2 %$3 %$4\n%/" +"%(prepend_width ? \" \" * int(prepend_width) : \"\")" +"------------ ------------ ------------ -----\n" @end smallexample @item --by-payee @@ -7581,7 +7655,9 @@ option settings in the file @file{~/.ledgerrc} one option per line, for example: @c TODO use @var below A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: +or both. Ledger's end dates are always exclusive, imagine the date is +followed by 00:00:00 time. They are instants in time not entire days. +The full syntax is: @smallexample [INTERVAL] [BEGIN] [END] @@ -8122,6 +8198,19 @@ posting. A regular expression that matches against the transaction code (the text that occurs between parentheses before the payee). +@item expr any(KEYWORD =~ /REGEX/) +The @command{any} keyword is used to specify that at least one posting of +the transaction must match the expression in brackets. For example, +@samp{ledger -f d reg expr "any(account =~ /Assets:/)"} can be used to +display all transactions which involve at least one @samp{Assets:} +account. + +@item expr all(KEYWORD =~ /REGEX/) +The @command{all} keyword is used to specify that all postings of a +transactions must match the expression in brackets. For example, +@samp{ledger -f d reg expr "all(account =~ /Assets:/)"} can be used to +display all transactions where all accounts are @samp{Assets:}. + @end table The @command{query} command can be used to see how Ledger interprets @@ -8340,7 +8429,7 @@ Return the quantity of @var{value} for values that have a per-unit cost. @end defun @defun quoted expression -Surround @var{expression} with double-quotes. +Surround @var{expression} with double-quotes. If expression contains a double-quote, it will be escaped with a backslash. @smallexample @c command:EAD8AA7,with_input:3406FC1 $ ledger -f expr.dat --format "%(quoted(account)) %(quoted(amount))\n" reg @end smallexample @@ -8350,6 +8439,17 @@ $ ledger -f expr.dat --format "%(quoted(account)) %(quoted(amount))\n" reg @end smallexample @end defun +@c @defun quoted_rfc4180 expression +@c Surround @var{expression} with double-quotes, compliant with RFC 4180. If expression contains a double-quote, it will be represented with two double-quotes. +@c @smallexample @c command:EAD8AA7,with_input:3406FC1 +@c $ ledger -f expr.dat --format "%(quoted_rfc4180(account)) %(quoted_rfc4180(amount))\n" reg +@c @end smallexample +@c @smallexample @c output:EAD8AA7 +@c "Assets:Cash" "¤ -123,45" +@c "Expenses:Office Supplies" "¤ 123,45" +@c @end smallexample +@c @end defun + @defun round @value{FIXME:UNDOCUMENTED} @end defun @@ -8935,7 +9035,7 @@ day of the month (dd), zero padded up to 10. day of the month (dd), no leading zero up to 10. @item %j -day of year, zero padded 000–366. +day of year, zero padded 000--366. @item %u day of week starting with Monday (1), i.e. @code{mtwtfss} 3. @@ -8986,16 +9086,16 @@ Additional date format parameters which can be used: @table @code @item %U -week number Sunday as first day of week, ranging 01–53. +week number Sunday as first day of week, ranging 01--53. @item %W -week number Monday as first day of week, ranging 01–53. +week number Monday as first day of week, ranging 01--53. @item %V -week of the year, ranging 01–53. +week of the year, ranging 01--53. @item %C -century, ranging 00–99. +century, ranging 00--99. @item %D yields @code{%m/%d/%y} as in @samp{02/10/10}. @@ -9095,7 +9195,7 @@ Even if you don't create a session manually, one is created for you by the top-level interface functions. The Session is where objects live like the Commodities that Amounts refer to. -The make a Session useful, you must read a Journal into it, using the +To make a Session useful, you must read a Journal into it, using the function `@code{read_journal}`. This reads Ledger data from the given file, populates a Journal object within the current Session, and returns a reference to that Journal object. @@ -9168,7 +9268,7 @@ looking at its @code{xact} member: last_xact = None for post in ledger.read_journal("sample.dat").query(""): if post.xact != last_xact: - for post in post.xact.posts: + for post in post.xact.posts(): print "Transferring %s to/from %s" % (post.amount, post.account) last_xact = post.xact |