diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ledger-mode.texi | 74 | ||||
| -rw-r--r-- | doc/ledger3.texi | 2353 |
2 files changed, 1402 insertions, 1025 deletions
diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi index a5d77b1f..3e87d090 100644 --- a/doc/ledger-mode.texi +++ b/doc/ledger-mode.texi @@ -8,6 +8,7 @@ @c needs. @copying + Copyright @copyright{} 2013, Craig Earls. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -15,17 +16,21 @@ 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 @@ -39,6 +44,7 @@ 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 @@ -333,21 +339,25 @@ 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 ``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-e @@ -433,18 +443,24 @@ transactions. For details of the regular expression syntax, see 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 @@ -604,16 +620,21 @@ Typing @kbd{C-c C-o C-r} or using menu @samp{Ledger Run Report} prompt 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 @node Adding and Editing Reports, Reversing Report Order, Running Basic Reports, The Report Buffer @@ -662,15 +683,20 @@ 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. + +@c FIXME : is it 'value' or 'tag' for '@item value' just below? @item value -@c FIXME : is it 'value' or 'tag' for @item above? Prompt for a tag value. + @end table You can use these expansion values in your ledger report commands. For @@ -750,14 +776,18 @@ for Ledger under the data options. Alternately you can choose @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 @@ -765,23 +795,30 @@ If non-nil, highlight transaction under point using @cindex customization, reconcile @ftable @option + @item ledger-reconcile-default-commodity The default commodity for use in target calculations in ledger reconcile. Defaults to @samp{$} (USD). + @item ledger-recon-buffer-name Name to use for reconciliation buffer. Defaults to @file{*Reconcile*}. + @item ledger-narrow-on-reconcile If non-nil, limit transactions shown in main buffer to those matching the reconcile regex. + @item ledger-buffer-tracks-reconcile-buffer If non-nil, then when the cursor is moved to a new transaction in the reconcile window. + @item ledger-reconcile-force-window-bottom If non-nil, make the reconcile window appear along the bottom of the register window and resize. + @item ledger-reconcile-toggle-to-pending If non-nil, then toggle between uncleared and pending @samp{!}. If false toggle between uncleared and cleared @samp{*}. + @end ftable @node Ledger Report Customization Group, Ledger Faces Customization Group, Ledger Reconcile Customization Group, Customization Variables @@ -789,11 +826,14 @@ false toggle between uncleared and cleared @samp{*}. @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 @@ -803,38 +843,55 @@ functions. 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 reconcile window. + @item ledger-font-reconciler-cleared-face Default face for cleared @samp{*} transactions in the reconcile window. + @item ledger-font-reconciler-pending-face Default face for pending @samp{!} transactions in the reconcile window. + @item ledger-font-report-clickable-face FIXME + @end ftable @node Ledger Post Customization Group, Ledger Exec Customization Group, Ledger Faces Customization Group, Customization Variables @@ -844,16 +901,22 @@ FIXME 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 @@ -863,10 +926,13 @@ Which completion engine to use: @var{iswitchb}, @var{ido}, or built-in. 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 @@ -874,10 +940,13 @@ Location of the ledger initialization file. nil if you don't have one. @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 @@ -885,12 +954,15 @@ Directory where the debug binary. @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 diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 482be6ba..05bf4776 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -7,25 +7,43 @@ @c a prefix arg). This updates the node pointers, which texinfmt.el @c needs. +@c | Formating | Indexing | | +@c | | @cindex | concept | +@c | @command | @findex | Ledger CLI Command (like balance) | +@c | @option | @findex | Ledger CLI Option (like --market) | +@c | @var | | Ledger CLI option Variable (like -f FILE) | +@c | | | Ledger file Syntax | +@c | @samp | | Valued example or single char | +@c | @file | | File | +@c | @file | | Program (like ledger, report, acprep) | + +@c Restructuring manual ideas +@c http://beyondgrep.com/documentation/ack-2.04-man.html + @copying -Copyright @copyright{} 2003-2013, John Wiegley. All rights reserved. + +Copyright @copyright{} 2003–2013, 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 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 @@ -39,6 +57,7 @@ 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 User Applications @@ -78,7 +97,7 @@ twinkling in their father's CRT. @menu * Introduction to Ledger:: * Ledger Tutorial:: -* Principles of Accounting:: +* Principles of Accounting with Ledger:: * Keeping a Journal:: * Transactions:: * Building Reports:: @@ -91,10 +110,10 @@ twinkling in their father's CRT. * Extending with Python:: * Ledger for Developers:: * Major Changes from version 2.6:: -* Example Data File:: +* Example Journal File:: * Miscellaneous Notes:: -* Concept Index:: -* Command Index:: +* Concepts Index:: +* Commands & Options Index:: @end menu @node Introduction to Ledger, Ledger Tutorial, Top, Top @@ -102,11 +121,11 @@ twinkling in their father's CRT. @menu * Fat-free Accounting:: -* Building the Program:: -* Getting Help:: +* Building the program:: +* Getting help:: @end menu -@node Fat-free Accounting, Building the Program, Introduction to Ledger, Introduction to Ledger +@node Fat-free Accounting, Building the program, Introduction to Ledger, Introduction to Ledger @section Fat-free Accounting Ledger is an accounting tool with the moxie to exist. It provides no @@ -207,9 +226,9 @@ at Whole Foods Markets you might assign the transactions like this Assets:Checking @end smallexample -In both cases the money goes to the ``Groceries'' account, even though -the payees were different. You can set up your accounts in any way you -choose. +In both cases the money goes to the @samp{Groceries} account, even +though the payees were different. You can set up your accounts in any +way you choose. Enter the beauty of computerized accounting. The purpose of the Ledger program is to make general journal accounting simple, by @@ -246,7 +265,7 @@ that Ledger will never alter your input file. You can create and edit that file in any way you prefer, but Ledger is only for analyzing the data, not for altering it. -@node Building the Program, Getting Help, Fat-free Accounting, Introduction to Ledger +@node Building the program, Getting help, Fat-free Accounting, Introduction to Ledger @section Building the program Ledger is written in ANSI C++, and should compile on any platform. It @@ -261,7 +280,7 @@ enter these commands: $ ./configure && make install @end smallexample -@node Getting Help, , Building the Program, Introduction to Ledger +@node Getting help, , Building the program, Introduction to Ledger @section Getting help @findex help @@ -277,37 +296,36 @@ join the Ledger mailing list at You can also find help at the @code{#ledger} channel on the IRC server @code{irc.freenode.net}. -@node Ledger Tutorial, Principles of Accounting, Introduction to Ledger, Top +@node Ledger Tutorial, Principles of Accounting with Ledger, Introduction to Ledger, Top @chapter Ledger Tutorial @cindex tutorial @menu -* Start a Journal:: -* Run Some Reports:: +* Start a Journal File:: +* Run a Few Reports:: @end menu -@node Start a Journal, Run Some Reports, Ledger Tutorial, Ledger Tutorial +@node Start a Journal File, Run a Few Reports, Ledger Tutorial, Ledger Tutorial @section Start a Journal File @cindex journals -A journal is a record of your financial transactions and will be -central to using Ledger. For now we just want to get a taste of what -Ledger can do. An example journal is included with the source code -distribution, called @file{drewr3.dat} (@pxref{Example Data File}). -Copy it someplace convenient and open up a terminal window in that -directory. +A journal is a record of your financial transactions and will be central +to using Ledger. For now we just want to get a taste of what Ledger can +do. An example journal is included with the source code distribution, +called @file{drewr3.dat} (@pxref{Example Journal File}). Copy it +someplace convenient and open up a terminal window in that directory. If you would rather start with your own journal right away please @pxref{Keeping a Journal}. -@node Run Some Reports, , Start a Journal, Ledger Tutorial +@node Run a Few Reports, , Start a Journal File, Ledger Tutorial @section Run a Few Reports @menu * Balance Report:: * Register Report:: * Cleared Report:: -* Using the Windows command line:: +* Using the Windows Command Line:: @end menu Please note that as a command line program, Ledger is controlled from @@ -321,7 +339,7 @@ take that into account when entering the command line arguments given. There are too many variations between shells to give concrete examples for each. -@node Balance Report, Register Report, Run Some Reports, Run Some Reports +@node Balance Report, Register Report, Run a Few Reports, Run a Few Reports @subsection Balance Report @cindex balance report @findex balance @@ -377,7 +395,7 @@ $ ledger -f drewr3.dat balance Assets Liabilities $ -3,867.60 @end smallexample -@node Register Report, Cleared Report, Balance Report, Run Some Reports +@node Register Report, Cleared Report, Balance Report, Run a Few Reports @subsection Register Report @cindex register report @findex register @@ -428,6 +446,7 @@ Ledger will generate: @noindent To limit this to a more useful subset, simply add the accounts you are interested in seeing transactions for: + @cindex accounts, limiting by @cindex limiting by accounts @@ -444,7 +463,7 @@ $ ledger -f drewr3.dat register Groceries @end smallexample @noindent -Which matches the balance reported for the @code{Groceries} account: +Which matches the balance reported for the @samp{Groceries} account: @smallexample $ ledger -f drewr3.dat balance Groceries @@ -466,17 +485,17 @@ $ ledger -f drewr3.dat register payee "Organic" Assets:Checking $ -225.00 0 @end smallexample -@node Cleared Report, Using the Windows command line, Register Report, Run Some Reports +@node Cleared Report, Using the Windows Command Line, Register Report, Run a Few Reports @subsection Cleared Report @cindex cleared report @findex cleared A very useful report is to show what your obligations are versus what -expenditures have actually been recorded. It can take several days -for a check to clear, but you should treat it as money spent. The -@code{cleared} report shows just that (note that the cleared report -will not format correctly for accounts that contain multiple -commodities): +expenditures have actually been recorded. It can take several days for +a check to clear, but you should treat it as money spent. The +@command{cleared} report shows just that (note that the +@command{cleared} report will not format correctly for accounts that +contain multiple commodities): @smallexample $ ledger -f drewr3.dat cleared @@ -506,7 +525,7 @@ $ ledger -f drewr3.dat cleared The first column shows the outstanding balance, the second column shows the ``cleared'' balance. -@node Using the Windows command line, , Cleared Report, Run Some Reports +@node Using the Windows Command Line, , Cleared Report, Run a Few Reports @subsection Using the Windows Command Line @cindex windows cmd.exe @cindex currency symbol display on windows @@ -516,7 +535,7 @@ limitation. CMD.exe is limited to standard ASCII characters and as such cannot display any currency symbols other than dollar signs @samp{$}. -@node Principles of Accounting, Keeping a Journal, Ledger Tutorial, Top +@node Principles of Accounting with Ledger, Keeping a Journal, Ledger Tutorial, Top @chapter Principles of Accounting with Ledger @menu @@ -530,17 +549,17 @@ such cannot display any currency symbols other than dollar signs * Working with multiple funds and accounts:: @end menu -@node Accounting with Ledger, Stating where money goes, Principles of Accounting, Principles of Accounting +@node Accounting with Ledger, Stating where money goes, Principles of Accounting with Ledger, Principles of Accounting with Ledger @section Accounting with Ledger +@cindex double-entry accounting Accounting is simply tracking your money. It can range from nothing, and just waiting for automatic overdraft protection to kick in, or not, to a full blown double entry accounting system. Ledger accomplishes the latter. With ledger you can handle your personal finances or your businesses. Double-entry accounting scales. -@cindex double-entry accounting -@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting +@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting with Ledger @section Stating where money goes @cindex credits and debits @@ -594,7 +613,7 @@ place has less money now than when you started your ledger; and every positive figure means that that account or person or place has more money now than when you started your ledger. Make sense? -@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Principles of Accounting +@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Principles of Accounting with Ledger @section Assets and Liabilities @cindex assets and liabilities @cindex debts are liabilities @@ -611,8 +630,8 @@ account, such as when you get paid. Here is a typical transaction: Income:Salary @end smallexample -Money, here, comes from an Income account belonging to ``My -Employer'', and is transferred to your checking account. The money is +Money, here, comes from an Income account belonging to @samp{My +Employer}, and is transferred to your checking account. The money is now yours, which makes it an Asset. Liabilities track money owed to others. This can happen when you @@ -660,7 +679,7 @@ $ ledger -M register expenses:auto @end smallexample This assumes, of course, that you use account names like -@code{Expenses:Auto:Gas} and @code{Expenses:Auto:Repair}. +@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}. @menu * Tracking reimbursable expenses:: @@ -670,11 +689,11 @@ This assumes, of course, that you use account names like @subsection Tracking reimbursable expenses @cindex reimbursable expense tracking -Sometimes you will want to spend money on behalf of someone else, -which will eventually get repaid. Since the money is still ``yours'', -it is really an asset. And since the expenditure was for someone -else, you don't want it contaminating your Expenses reports. You will -need to keep an account for tracking reimbursements. +Sometimes you will want to spend money on behalf of someone else, which +will eventually get repaid. Since the money is still @emph{yours}, it +is really an asset. And since the expenditure was for someone else, you +don't want it contaminating your Expenses reports. You will need to +keep an account for tracking reimbursements. This is fairly easy to do in ledger. When spending the money, spend it @emph{to} your Assets:Reimbursements, using a different account for @@ -760,12 +779,12 @@ It's easier shown than said: Company XYZ:Assets:Checking $-100.00 @end smallexample -And now the reimbursements account is paid off, accounts payable is -paid off, and $100.00 has been effectively transferred from the -company's checking account to your personal checking account. The -money simply ``waited''---in both @code{Assets:Reimbursements:Company -XYZ}, and @code{Company XYZ:Accounts Payable:Your Name}---until such -time as it could be paid off. +And now the reimbursements account is paid off, accounts payable is paid +off, and $100.00 has been effectively transferred from the company's +checking account to your personal checking account. The money simply +``waited''---in both @samp{Assets:Reimbursements:Company XYZ}, and +@samp{Company XYZ:Accounts Payable:Your Name}---until such time as it +could be paid off. The value of tracking expenses from both sides like that is that you do not contaminate your personal expense report with expenses made on @@ -817,7 +836,7 @@ was spent using your MasterCard on behalf of Company XYZ, and that Company XYZ spent the money on computer software and paid it back about two weeks later. -@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Principles of Accounting +@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Principles of Accounting with Ledger @section Commodities and Currencies Ledger makes no assumptions about the commodities you use; it only @@ -876,9 +895,9 @@ P 2004/06/21 02:18:02 AU $400.00 @findex --price-db @var{FILE} @findex --market -Specify the price history to use with the @code{--price-db} option, -with the @code{-V (--market)} option to report in terms of current -market value: +Specify the price history to use with the @option{--price-db @var{FILE}} +option, with the @option{--market (-V)} option to report in terms of +current market value: @smallexample $ ledger --price-db prices.db -V balance brokerage @@ -912,11 +931,11 @@ the left value's commodity. The result of this command might be: @end smallexample @menu -* Commodity Price Histories:: +* Commodity price histories:: * Commodity equivalencies:: @end menu -@node Commodity Price Histories, Commodity equivalencies, Commodities and Currencies, Commodities and Currencies +@node Commodity price histories, Commodity equivalencies, Commodities and Currencies, Commodities and Currencies @subsection Commodity price histories Whenever a commodity is purchased using a different commodity (such as @@ -938,7 +957,7 @@ its various reports. It will always report balances in terms of the commodity total, rather than the current value of those commodities. To enable pricing reports, use one of the commodity reporting options. -@node Commodity equivalencies, , Commodity Price Histories, Commodities and Currencies +@node Commodity equivalencies, , Commodity price histories, Commodities and Currencies @subsection Commodity equivalencies Sometimes a commodity has several forms which are all equivalent. An @@ -947,7 +966,7 @@ or days, it should be possible to convert between the various forms. Doing this requires the use of commodity equivalencies. For example, you might have the following two postings, one which -transfers an hour of time into a @code{Billable} account, and another +transfers an hour of time into a @samp{Billable} account, and another which decreases the same account by ten minutes. The resulting report will indicate that fifty minutes remain: @@ -987,12 +1006,12 @@ In the above example, kilobytes are reported with two decimal places of precision and each kilobyte is equal to 1024 bytes. Equivalency chains can be as long as desired. Whenever a commodity -would report as a decimal amount (less than @code{1.00}), the next +would report as a decimal amount (less than @samp{1.00}), the next smallest commodity is used. If a commodity could be reported in terms of a higher commodity without resulting to a partial fraction, then the larger commodity is used. -@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Principles of Accounting +@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Principles of Accounting with Ledger @section Accounts and Inventories Since Ledger's accounts and commodity system is so flexible, you can @@ -1012,8 +1031,8 @@ EverQuest account: Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The amounts are negative, because you are taking @emph{from} Black's Tavern in order to add to your Inventory account. Note that you don't -have to use @code{Places:Black's Tavern} as the source account. You -could use @code{EverQuest:System} to represent the fact that you +have to use @samp{Places:Black's Tavern} as the source account. You +could use @samp{EverQuest:System} to represent the fact that you acquired them online. The only purpose for choosing one kind of source account over another is for generate more informative reports later on. The more you know, the better analysis you can perform. @@ -1030,7 +1049,7 @@ transaction would look like: Now you've turned 2 steaks into 15 gold, courtesy of your customer, Sturm Brightblade. -@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Principles of Accounting +@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Principles of Accounting with Ledger @section Understanding Equity The most confusing transaction in any ledger will be your equity @@ -1069,7 +1088,7 @@ Clear as mud? Keep thinking about it. Until you figure it out, put @code{-Equity} at the end of your balance command, to remove the confusing figure from the total. -@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Principles of Accounting +@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Principles of Accounting with Ledger @section Dealing with Petty Cash Something that stops many people from keeping a ledger at all is the @@ -1079,7 +1098,7 @@ a few large ones, as with checks. One solution is: don't bother. Move your spending to a debit card, but in general ignore cash. Once you withdraw it from the ATM, mark -it as already spent to an @code{Expenses:Cash} category: +it as already spent to an @samp{Expenses:Cash} category: @smallexample 2004/03/15 ATM @@ -1088,8 +1107,8 @@ it as already spent to an @code{Expenses:Cash} category: @end smallexample If at some point you make a large cash expense that you want to track, -just ``move'' the amount of the expense from @code{Expenses:Cash} into -the target account: +just @emph{move} the amount of the expense from @samp{Expenses:Cash} +into the target account: @smallexample 2004/03/20 Somebody @@ -1100,7 +1119,7 @@ the target account: This way, you can still track large cash expenses, while ignoring all of the smaller ones. -@node Working with multiple funds and accounts, , Dealing with Petty Cash, Principles of Accounting +@node Working with multiple funds and accounts, , Dealing with Petty Cash, Principles of Accounting with Ledger @section Working with multiple funds and accounts There are situations when the accounts you're tracking are different @@ -1128,8 +1147,8 @@ reserves resources for later: The problem with this kind of setup is that when you spend money, it comes from two or more places at once: the account and the fund. And yet, the correlation of amounts between funds and accounts is rarely -one-to-one. What if the school fund has @code{$500.00}, but -@code{$400.00} of that comes from Checking, and @code{$100.00} from +one-to-one. What if the school fund has @samp{$500.00}, but +@samp{$400.00} of that comes from Checking, and @samp{$100.00} from Savings? Traditional finance packages require that the money reside in only one @@ -1167,7 +1186,7 @@ account: When reports are generated, by default they'll appear in terms of the funds. In this case, you will likely want to mask out your -@code{Assets} account, because otherwise the balance won't make much +@samp{Assets} account, because otherwise the balance won't make much sense: @smallexample @@ -1175,7 +1194,7 @@ $ ledger bal -^Assets @end smallexample @findex --real -If the @code{--real} option is used, the report will be in terms of +If the @option{--real} option is used, the report will be in terms of the real accounts: @smallexample @@ -1197,7 +1216,7 @@ The second way of tracking funds is to use transaction codes. In this respect the codes become like virtual accounts that embrace the entire set of postings. Basically, we are associating a transaction with a fund by setting its code. Here are two transactions that deposit money -into, and spend money from, the @code{Funds:School} fund: +into, and spend money from, the @samp{Funds:School} fund: @smallexample 2004/03/25 (Funds:School) Donations @@ -1216,18 +1235,18 @@ relate to a particular fund is kept only in the code. @findex --code-as-payee @findex --by-payee How does this become a fund report? By using the -@code{--code-as-payee} option, you can generate a register report -where the payee for each posting shows the code. Alone, this is -not terribly interesting; but when combined with the -@code{--by-payee} option, you will now see account subtotals for any -postings related to a specific fund. So, to see the current -monetary balances of all funds, the command would be: +@option{--code-as-payee} option, you can generate a register report +where the payee for each posting shows the code. Alone, this is not +terribly interesting; but when combined with the @option{--by-payee +(-P)} option, you will now see account subtotals for any postings +related to a specific fund. So, to see the current monetary balances of +all funds, the command would be: @smallexample $ ledger --code-as-payee -P reg ^Assets @end smallexample -Or to see a particular funds expenses, the @code{School} fund in this +Or to see a particular funds expenses, the @samp{School} fund in this case: @smallexample @@ -1239,7 +1258,7 @@ you prefer to think of your funds: as virtual accounts, or as tags associated with particular transactions. Your own tastes will decide which is best for your situation. -@node Keeping a Journal, Transactions, Principles of Accounting, Top +@node Keeping a Journal, Transactions, Principles of Accounting with Ledger, Top @chapter Keeping a Journal The most important part of accounting is keeping a good journal. If @@ -1273,10 +1292,10 @@ display precision, etc.) based on how you used the commodity in the posting. @menu -* Most Basic Entry:: +* The Most Basic Entry:: * Starting up:: -* Structuring Your Accounts:: -* Commenting on your journal:: +* Structuring your Accounts:: +* Commenting on your Journal:: * Currency and Commodities:: * Keeping it Consistent:: * Journal Format:: @@ -1284,7 +1303,7 @@ posting. * Archiving Previous Years:: @end menu -@node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal +@node The Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal @section The Most Basic Entry Here is the Pacific Bell example from above, given as a Ledger @@ -1309,14 +1328,15 @@ amount, if it is the same as the first line: @end smallexample For this transaction, Ledger will figure out that $-23.00 must come -from @code{Assets:Checking} in order to balance the transaction. +from @samp{Assets:Checking} in order to balance the transaction. Also note the structure of the account entries. There is an implied -hierarchy established by separating with colons (@pxref{Structuring -Your Accounts}). +hierarchy established by separating with colons (@pxref{Structuring your +Accounts}). @cindex spaces in postings @cindex posting format details + @strong{The format is very flexible and it isn't necessary that you indent and space out things exactly as shown. The only requirements are that the start of the transaction (the date typically) is at the @@ -1327,7 +1347,7 @@ two spaces, or a tab, between the amount and the account. If you do not have adequate separation between the amount and the account Ledger will give an error and stop calculating.} -@node Starting up, Structuring Your Accounts, Most Basic Entry, Keeping a Journal +@node Starting up, Structuring your Accounts, The Most Basic Entry, Keeping a Journal @section Starting up @cindex initial equity @cindex beginning ledger @@ -1361,7 +1381,7 @@ There is nothing special about the name ``Opening Balances'' as the payee of the account name, anything convenient that you understand will work. -@node Structuring Your Accounts, Commenting on your journal, Starting up, Keeping a Journal +@node Structuring your Accounts, Commenting on your Journal, Starting up, Keeping a Journal @section Structuring your Accounts @cindex accounts, naming @cindex naming accounts @@ -1373,10 +1393,10 @@ system. At the highest level you have five sorts of accounts: @enumerate -@item Expenses: where money goes -@item Assets: where money sits -@item Income: where money comes from -@item Liabilities: money you owe +@item Expenses: where money goes, +@item Assets: where money sits, +@item Income: where money comes from, +@item Liabilities: money you owe, @item Equity: the real value of your property. @end enumerate @@ -1391,18 +1411,19 @@ you spend on burgers and fries, you could have the following: Expenses:Food:Hamburgers and Fries @end smallexample -@node Commenting on your journal, Currency and Commodities, Structuring Your Accounts, Keeping a Journal +@node Commenting on your Journal, Currency and Commodities, Structuring your Accounts, Keeping a Journal @section Commenting on your Journal @cindex comments, characters +@cindex block comments +@cindex comments, block Comments are generally started using a @samp{;}. However, in order to increase compatibility with other text manipulation programs and methods four additional comment characters are valid if used at the beginning of a line: @samp{#}, @samp{|}, and @samp{*} and @samp{%}. -@cindex block comments -@cindex comments, block + Block comments can be made by use @code{@!comment} ... @code{@!end -comment} +comment}. @smallexample ; This is a single line comment, @@ -1437,7 +1458,7 @@ specific transactions. The comments within the transaction must all start with @samp{;} and are preserved as part of the transaction. The @samp{:} indicates meta-data and tags (@pxref{Metadata}). -@node Currency and Commodities, Keeping it Consistent, Commenting on your journal, Keeping a Journal +@node Currency and Commodities, Keeping it Consistent, Commenting on your Journal, Keeping a Journal @section Currency and Commodities @cindex currency @cindex commodity @@ -1627,18 +1648,18 @@ Assets:Checking because its amount is null. Ledger allows you to have very detailed control over how your commodities are valued. You can fine tune the results given using the -@code{--market} or @code{--exchange @var{COMMODITY}} options. There +@option{--market} or @option{--exchange @var{COMMODITY}} options. There are now several points of interception, you can specify the valuation method: @enumerate -@item on a commodity itself -@item on a posting, via metadata (affect is largely the same as #1) -@item on an xact, which then applies to all postings in that xact -@item on any posting via an automated transaction -@item on a per-account basis -@item on a per-commodity basis -@item by changing the journal default of @code{market} +@item on a commodity itself, +@item on a posting, via metadata (affect is largely the same as #1), +@item on an xact, which then applies to all postings in that xact, +@item on any posting via an automated transaction, +@item on a per-account basis, +@item on a per-commodity basis, +@item by changing the journal default of @code{market}. @end enumerate Fixated pricing (such as @samp{@{=$20@}}) still plays a role in this @@ -1648,17 +1669,19 @@ scheme. As far as valuation goes, it's shorthand for writing A valuation function receives three arguments: @table @code + @item source A string identifying the commodity whose price is being asked for -(example: @samp{EUR}) +(example: @samp{EUR}). @item date The reference date the price should be relative. @item target A string identifying the ``target'' commodity, or the commodity the -returned price should be in. This argument is null if @code{--market} -was used instead of @code{--exchange @var{COMMODITY}}. +returned price should be in. This argument is null if @option{--market} +was used instead of @option{--exchange @var{COMMODITY}}. + @end table The valuation function should return an amount. If you've written @@ -1702,7 +1725,7 @@ account Expenses:Food5 value myfunc_five @end smallexample -The metadata field @code{Value}, if found, overrides the valuation +The metadata field @samp{Value}, if found, overrides the valuation function on a transaction-wide or per-posting basis. @smallexample @@ -1773,6 +1796,7 @@ ledger reg -V food @node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal @section Keeping it Consistent @findex --strict +@findex accounts Sometimes Ledger's flexibility can lead to difficulties. Using a freeform text editor to enter transactions makes it easy to keep the @@ -1800,7 +1824,7 @@ Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities @end smallexample If you have a large Ledger register already created use the -@code{accounts} command to get started: +@command{accounts} command to get started: @smallexample $ ledger accounts >> Accounts.dat @@ -1817,17 +1841,18 @@ supports many options, though typically the user can ignore most of them. They are summarized below. @menu -* Transaction and Comments:: +* Transactions and Comments:: * Command Directives:: @end menu -@node Transaction and Comments, Command Directives, Journal Format, Journal Format +@node Transactions and Comments, Command Directives, Journal Format, Journal Format @subsection Transactions and Comments The initial character of each line determines what the line means, and how it should be interpreted. Allowable initial characters are: @table @code + @item NUMBER A line beginning with a number denotes a transaction. It may be followed by any number of lines, each beginning with white-space, to @@ -1863,9 +1888,10 @@ the syntax @code{[ACTUAL_DATE]} or @code{[=EFFECTIVE_DATE]} or @code{[ACTUAL_DATE=EFFECTIVE_DATE]} (@pxref{Virtual postings}). @item P +@findex --download Specifies a historical price for a commodity. These are usually found -in a pricing history file (see the @code{-Q} option). The syntax -is: +in a pricing history file (see the @option{--download (-Q)} option). +The syntax is: @smallexample P DATE SYMBOL PRICE @@ -1897,21 +1923,23 @@ If the semi colon is indented and occurs inside a transaction, it is parsed as a persistent note for its preceding category. These notes or tags can be used to augment the reporting and filtering capabilities of Ledger. + @end table -@node Command Directives, , Transaction and Comments, Journal Format +@node Command Directives, , Transactions and Comments, Journal Format @subsection Command Directives @findex --strict @findex --pedantic @table @code + @item beginning of line Command directives must occur at the beginning of a line. Use of @samp{!} and @samp{@@} is deprecated. @item account Pre-declare valid account names. This only has effect if -@code{--strict} or @code{--pedantic} is used (see below). The +@option{--strict} or @option{--pedantic} is used (see below). The @code{account} directive supports several optional sub-directives, if they immediately follow the account directive and if they begin with whitespace: @@ -1964,8 +1992,8 @@ Sets the root for all accounts following the directive. Ledger supports a hierarchical tree of accounts. It may be convenient to keep two ``root accounts''. For example you may be tracking your personal finances and your business finances. In order to keep them -separate you could preface all personal accounts with @code{personal:} -and all business account with @code{business:}. You can easily split +separate you could preface all personal accounts with @samp{personal:} +and all business account with @samp{business:}. You can easily split out large groups of transaction without manually editing them using the account directive. For example: @@ -1977,8 +2005,8 @@ apply account Personal @end smallexample Would result in all postings going into -@code{Personal:Expenses:Groceries} and @code{Personal:Assets:Checking} -until and @code{end apply account} directive was found. +@samp{Personal:Expenses:Groceries} and @samp{Personal:Assets:Checking} +until and @samp{end apply account} directive was found. @item alias @c instance_t::alias_directive @@ -1992,7 +2020,6 @@ alias Checking=Assets:Credit Union:Joint Checking Account 2011/11/28 YummyPalace Dining $10.00 Checking - @end smallexample The aliases are only in effect for transactions read in after the alias @@ -2017,7 +2044,7 @@ amount and automatically calculate balance the transaction in the posting. The @code{bucket} allows you to fill in all postings and automatically generate an additional posting to the bucket account balancing the transaction. The following example set the -@code{Assets:Checking} as the bucket: +@samp{Assets:Checking} as the bucket: @smallexample bucket Assets:Checking @@ -2029,11 +2056,13 @@ bucket Assets:Checking 2011/12/01 Sale Assets:Checking:Business $ 30.00 - @end smallexample @item capture @c instance_t::account_mapping_directive +@findex print +@findex register + Directs Ledger to replace any account matching a regex with the given account. For example: @@ -2041,11 +2070,11 @@ account. For example: capture Expenses:Deductible:Medical Medical @end smallexample -Would cause any posting with @code{Medical} in its name to be replaced -with @code{Expenses:Deductible:Medical}. +Would cause any posting with @samp{Medical} in its name to be replaced +with @samp{Expenses:Deductible:Medical}. -Ledger will display the mapped payees in @code{print} and -@code{register} reports. +Ledger will display the mapped payees in @command{print} and +@command{register} reports. @item check @c instance_t::check_directive in textual.cc @@ -2061,11 +2090,13 @@ check <VALUE EXPRESSION BOOLEAN RESULT> Start a block comment, closed by @code{end comment}. @item commodity -Pre-declare commodity names. This only has effect if @code{--strict} -or @code{--pedantic} is used (see below). +Pre-declare commodity names. This only has effect if @option{--strict} +or @option{--pedantic} is used (see below). - commodity $ - commodity CAD +@smallexample +commodity $ +commodity CAD +@end smallexample The @code{commodity} directive supports several optional sub-directives, if they immediately follow the commodity directive and @@ -2116,9 +2147,9 @@ Closes block commands like @code{tag} or @code{comment}. @item fixed @c instance_t::fixed_directive in textual.cc -A fixed block is used to set fixated prices (@pxref{Fixated prices}) -for a series of transactions. It's purely a typing saver, for use -when entering many transactions with fixated prices. +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: @@ -2160,6 +2191,9 @@ Include the stated file as if it were part of the current file. @item payee @c instance_t::payee_mapping_directive in textual.cc +@findex print +@findex register + The @code{payee} directive supports one optional sub-directive, if it immediately follows the payee directive and if it begins with whitespace: @@ -2177,8 +2211,8 @@ a parsed payee, the declared payee name is substituted: ... @end smallexample -Ledger will display the mapped payees in @code{print} and -@code{register} reports. +Ledger will display the mapped payees in @command{print} and +@command{register} reports. @item apply tag @c instance_t::tag_directive in textual.cc @@ -2208,7 +2242,7 @@ end apply tag hastag @end smallexample @noindent -is the equivalent of +is the equivalent of: @smallexample 2011/01/25 Tom's Used Cars @@ -2230,13 +2264,13 @@ is the equivalent of Income:Sales @end smallexample -Note that anything following ``@code{end tag}'' is ignored. placing +Note that anything following @code{end apply tag} is ignored. placing the name of the tag that is being closed is a simple way to keep track. @item tag -Pre-declares tag names. This only has effect if @code{--strict} or -@code{--pedantic} is used (see below). +Pre-declares tag names. This only has effect if @option{--strict} or +@option{--pedantic} is used (see below). @smallexample tag Receipt @@ -2279,11 +2313,12 @@ The following single letter commands may be at the beginning of a line alone, for backwards compatibility with older Ledger versions. @table @code + @item A -See @code{bucket} +See @code{bucket}. @item Y -See @code{year} +See @code{year}. @item N SYMBOL Indicates that pricing information is to be ignored for a given @@ -2297,14 +2332,15 @@ N SYMBOL @end smallexample @item D AMOUNT +@findex xact + Specifies the default commodity to use, by specifying an amount in the -expected format. The @command{transaction} command will use this -commodity as the default when none other can be determined. This -command may be used multiple times, to set the default flags for -different commodities; whichever is seen last is used as the default -commodity. For example, to set US dollars as the default commodity, -while also setting the thousands flag and decimal flag for that -commodity, use: +expected format. The @command{xact} command will use this commodity as +the default when none other can be determined. This command may be used +multiple times, to set the default flags for different commodities; +whichever is seen last is used as the default commodity. For example, +to set US dollars as the default commodity, while also setting the +thousands flag and decimal flag for that commodity, use: @smallexample D $1,000.00 @@ -2323,20 +2359,24 @@ C 1.00 Kb = 1024 bytes These four relate to timeclock support, which permits Ledger to read timelog files. See the timeclock's documentation for more info on the syntax of its timelog files. + @end table @node Converting from other formats, Archiving Previous Years, Journal Format, Keeping a Journal @section Converting from other formats +@cindex csv importing There are numerous tools to help convert various formats to a Ledger -file. Most banks will generate a commas separated value file that can +file. Most banks will generate a comma separated values file that can easily be parsed into Ledger format using one of those tools. Some of -the more popular tools are: +the most popular tools are: @itemize -@item @code{icsv2ledger} -@item @code{csvToLedger} -@item @code{CSV2Ledger} +@item @code{ledger convert download.csv} +@item @code{hledger -f checking.csv print} +@item @uref{https://github.com/quentinsf/icsv2ledger, @code{icsv2ledger}} +@item @uref{https://github.com/tazzben/csvToLedger, @code{csvToLedger}} +@item @uref{https://launchpad.net/csv2ledger, @code{CSV2Ledger}} @end itemize @noindent @@ -2345,6 +2385,8 @@ Ledger's function. @node Archiving Previous Years, , Converting from other formats, Keeping a Journal @section Archiving Previous Years +@findex equity +@findex print After a while, your journal can get to be pretty large. While this will not slow down Ledger---it's designed to process journals very @@ -2423,7 +2465,7 @@ doing it. * Virtual posting costs:: * Commodity prices:: * Prices vs. costs:: -* Fixated prices:: +* Fixated prices and costs:: * Lot dates:: * Lot notes:: * Lot value expressions:: @@ -2510,9 +2552,9 @@ primary date with an equals sign: @end smallexample What this auxiliary date means is entirely up to you. The only use -Ledger has for it is that if you specify @code{--aux-date}, then all -reports and calculations (including pricing) will use the aux date as -if it were the primary date. +Ledger has for it is that if you specify @option{--aux-date}, then all +reports and calculations (including pricing) will use the aux date as if +it were the primary date. @node Codes, Transaction state, Auxiliary dates, Transactions @section Codes @@ -2553,9 +2595,9 @@ To mark it pending, use a !: Assets:Cash @end smallexample -What these mean is entirely up to you. The @code{--cleared} option -will limits to reports to only cleared items, while @code{--uncleared} -shows both uncleared and pending items, and @code{--pending} shows +What these mean is entirely up to you. The @option{--cleared} option +will limits to reports to only cleared items, while @option{--uncleared} +shows both uncleared and pending items, and @option{--pending} shows only pending items. I use cleared to mean that I've reconciled the transaction with my @@ -2633,6 +2675,15 @@ after the amount, or on its own line preceded by whitespace: @node Metadata, Virtual postings, Transaction notes, Transactions @section Metadata +@c TODO add cindex +@c TODO https://groups.google.com/d/msg/ledger-cli/2csLPcHJ3ak/a17jOClzLTUJ +@c > Is there a way to produce a register report that lists all the transaction +@c > that contain a certain tag, and sort them based on the value of the tag? +@c ledger reg --sort "tag('foo')" %foo +@c ledger reg --group-by "tag('Employer)" Remboursement:Employer and tag Employer +@c > Is it possible to get subtotals for each tag value? +@c ledger --group-by "tag('foo')" bal +@c TODO https://groups.google.com/d/msg/ledger-cli/K9NBhNlVnYc/TDYDAWhOA5EJ One of Ledger's more powerful features is the ability to associate typed metadata with postings and transactions (by which I mean all of @@ -2669,10 +2720,52 @@ You can gang up multiple tags by sharing colons: ; :TAG1:TAG2:TAG3: @end smallexample +@menu +* Payee metadata tag:: +@end menu + +@node Payee metadata tag, , Metadata tags, Metadata tags +@subsubsection Payee metadata tag +@cindex Payee metadata tag +@findex register +@findex payees +@findex --by-payee + +``Payee'' is a special metadata field. If set on a posting, it will be +used as the payee name for that posting. This affects the +@command{register} report, the @command{payees} report, and the +@option{--by-payee} option. + +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 below: + +@smallexample +2010-06-17 Sample + Assets:Bank $400.00 + Income:Check1 $-100.00 ; Payee: Person One + Income:Check2 $-100.00 ; Payee: Person Two + Income:Check3 $-100.00 ; Payee: Person Three + Income:Check4 $-100.00 ; Payee: Person Four +@end smallexample + +When reporting this, it appears as: + +@smallexample +10-Jun-17 Sample Assets:Bank $400.00 $400.00 + Person One Income:Check1 $-100.00 $300.00 + Person Two Income:Check2 $-100.00 $200.00 + Person Three Income:Check3 $-100.00 $100.00 + Person Four Income:Check4 $-100.00 0 +@end smallexample + +This shows that they are all in the same transaction (which is why the +date is not repeated), but they have different payees now. + @node Metadata values, Typed metadata, Metadata tags, Metadata @subsection Metadata values -To associate a value with a tag, use the syntax "Key: Value", where +To associate a value with a tag, use the syntax ``Key: Value'', where the value can be any string of characters. Whitespace is needed after the colon, and cannot appear in the Key: @@ -2726,7 +2819,7 @@ is all about! But there are some tricks up Ledger's sleeve... You can use virtual accounts to transfer amounts to an account on the sly, bypassing the balancing requirement. The trick is that these postings are not considered ``real'', and can be removed from all -reports using @code{--real}. +reports using @option{--real}. To specify a virtual account, surround the account name with parentheses: @@ -2810,7 +2903,7 @@ This sets the amount of the second posting to whatever it would need to be for the total in Assets:Cash to be $500.00 after the posting. If the resulting amount is not $-20.00 in this case, it is an error. -@node Resetting a balance, Balancing transactions, Balance assignments, Balance verification +@node Resetting a balance, Balancing transactions, Balance assignments, Balance verification @subsection Resetting a balance Say your book-keeping has gotten a bit out of date, and your Ledger @@ -2830,8 +2923,9 @@ This is the only time in ledger when more than one posting's amount may be empty---and then only because it's not true empty, it is indirectly provided by the balance assignment's value. -@node Balancing transactions, , Resetting a balance, Balance verification +@node Balancing transactions, , Resetting a balance, Balance verification @subsection Balancing transactions +@findex --empty As a consequence of all the above, consider the following transaction: @@ -2846,9 +2940,9 @@ posting must balance, ensure that its value is zero. This can only be true if Assets:Brokerage does indeed contain 10 AAPL at that point in the input file. -A balanced virtual transaction is used simply to indicate to Ledger -that this is not a ``real'' transaction. It won't appear in any -reports anyway (unless you use a register report with @code{--empty}). +A balanced virtual transaction is used simply to indicate to Ledger that +this is not a ``real'' transaction. It won't appear in any reports +anyway (unless you use a register report with @option{--empty}). @node Posting cost, Explicit posting costs, Balance verification, Transactions @section Posting cost @@ -2899,6 +2993,8 @@ from the first posting's cost, you can elide the otheramount: @node Primary and secondary commodities, , Explicit posting costs, Explicit posting costs @subsection Primary and secondary commodities +@findex --market +@findex --exchange @var{COMMODITY} It is a general convention within Ledger that the ``top'' postings in a transaction contain the target accounts, while the final posting @@ -2911,9 +3007,9 @@ Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @@ AMOUNT", the commodity used in the second amount is marked ``primary''. -The only meaning a primary commodity has is that @code{-V} flag will -never convert a primary commodity into any other commodity. @code{-X -@var{COMMODITY}} still will, however. +The only meaning a primary commodity has is that @option{--market (-V)} +flag will never convert a primary commodity into any other commodity. +@option{--exchange @var{COMMODITY} (-X)} still will, however. @node Posting cost expressions, Total posting costs, Explicit posting costs, Transactions @section Posting cost expressions @@ -2977,9 +3073,9 @@ happening in the case of an exceptional transaction, surround the When a transaction occurs that exchange one commodity for another, Ledger records that commodity price not only within its internal price -database, but also attached to the commodity itself. Usually this -fact remains invisible to the user, unless you turn on -@code{--lot-prices} to show these hidden price figures. +database, but also attached to the commodity itself. Usually this fact +remains invisible to the user, unless you turn on @option{--lot-prices} +to show these hidden price figures. For example, consider the stock sale given above: @@ -3099,7 +3195,7 @@ And in cases where the amounts do not divide into whole figure and must be rounded, the capital gains figure could be off by a cent. Use with caution. -@node Prices vs. costs, Fixated prices, Commodity prices, Transactions +@node Prices vs. costs, Fixated prices and costs, Commodity prices, Transactions @section Prices vs. costs Because lot pricing provides enough information to infer the cost, the @@ -3120,7 +3216,7 @@ example in the print report. Functionally, however, there is no difference, and neither the register nor the balance report are sensitive to this difference. -@node Fixated prices, Lot dates, Prices vs. costs, Transactions +@node Fixated prices and costs, Lot dates, Prices vs. costs, Transactions @section Fixated prices and costs If you buy a stock last year, and ask for its value today, Ledger will @@ -3153,12 +3249,12 @@ fixated prices by way of the cost: This is the same as the previous transaction, with the same caveats found in @ref{Prices vs. costs}. -@node Lot dates, Lot notes, Fixated prices, Transactions +@node Lot dates, Lot notes, Fixated prices and costs, Transactions @section Lot dates @findex --lot-dates In addition to lot prices, you can specify lot dates and reveal them -with @code{--lot-dates}. Other than that, however, they have no +with @option{--lot-dates}. Other than that, however, they have no special meaning to Ledger. They are specified after the amount in square brackets (the same way that dates are parsed in value expressions): @@ -3176,7 +3272,7 @@ expressions): @findex --lots You can also associate arbitrary notes for your own record keeping in -parentheses, and reveal them with @code{--lot-notes}. One caveat is +parentheses, and reveal them with @option{--lot-notes}. One caveat is that the note cannot begin with an @samp{@@} character, as that would indicate a virtual cost: @@ -3190,16 +3286,16 @@ indicate a virtual cost: You can any combination of lot prices, dates or notes, in any order. They are all optional. -To show all lot information in a report, use @code{--lots}. +To show all lot information in a report, use @option{--lots}. @node Lot value expressions, Automated Transactions, Lot notes, Transactions @section Lot value expressions -Normally when you ask Ledger to display the values of commodities -held, it uses a value expression called ``market'' to determine the -most recent value from its price database---even downloading prices -from the Internet, if @code{-Q} was specified and a suitable -``getquote'' script is found on your system. +Normally when you ask Ledger to display the values of commodities held, +it uses a value expression called ``market'' to determine the most +recent value from its price database---even downloading prices from the +Internet, if @option{--download (-Q)} was specified and a suitable +@file{getquote} script is found on your system. However, you can override this valuation logic by providing a commodity valuation expression in doubled parentheses. This @@ -3238,26 +3334,25 @@ a function by using a lambda expression taking three arguments: The arguments passed to these functions have the following meaning: @itemize -@item source - The source commodity string, or an amount object. If it is - a string, the return value must be an amount representing the - price of the commodity identified by that string (example: - @samp{$}). If it is an amount, return the value of that - amount as a new amount (usually calculated as commodity price - times source amount). - -@item date - The date to use for determining the value. If null, it means - no date was specified, which can mean whatever you want it to - mean. - -@item target - If not null, a string representing the desired target - commodity that the commodity price, or repriced amount, should - be valued in. Note that this string can be a comma-separated - list, and that some or all of the commodities in that list may - be suffixed with an exclamation mark, to indicate what is - being desired. + +@item source +The source commodity string, or an amount object. If it is a string, +the return value must be an amount representing the price of the +commodity identified by that string (example: @samp{$}). If it is an +amount, return the value of that amount as a new amount (usually +calculated as commodity price times source amount). + +@item date +The date to use for determining the value. If null, it means no date +was specified, which can mean whatever you want it to mean. + +@item target +If not null, a string representing the desired target commodity that the +commodity price, or repriced amount, should be valued in. Note that +this string can be a comma-separated list, and that some or all of the +commodities in that list may be suffixed with an exclamation mark, to +indicate what is being desired. + @end itemize In most cases, it is simplest to either use explicit amounts in your @@ -3480,6 +3575,7 @@ Ledger you can control every aspect of the timing of a transaction. Say you're in business. If you bill a customer, you can enter something like + @cindex effective date of invoice @smallexample @@ -3551,9 +3647,9 @@ really knows that it debited $225 this month. A periodic transaction starts with a @samp{~} followed by a period expression. Periodic transactions are used for budgeting and -forecasting only, they have no effect without the @code{--budget} -option specified. @xref{Budgeting and Forecasting} for examples and -details. +forecasting only, they have no effect without the @option{--budget} +option specified. For examples and details, @pxref{Budgeting and +Forecasting}. @node Concrete Example of Automated Transactions, , Periodic Transactions, Automated Transactions @subsection Concrete Example of Automated Transactions @@ -3658,10 +3754,10 @@ options. @menu * Controlling the Accounts and Payees:: -* Controlling formatting:: +* Controlling Formatting:: @end menu -@node Controlling the Accounts and Payees, Controlling formatting, Balance Reports, Balance Reports +@node Controlling the Accounts and Payees, Controlling Formatting, Balance Reports, Balance Reports @subsection Controlling the Accounts and Payees The balance report is the most commonly used report. The simplest @@ -3710,8 +3806,8 @@ $ ledger balance -f drewr3.dat Auto MasterCard @end smallexample @noindent -note the implicit logical and between @code{Auto} and -@code{Mastercard}. +note the implicit logical and between @samp{Auto} and +@samp{Mastercard}. If you want the entire contents of a branch of your account tree, use the highest common name in the branch: @@ -3734,11 +3830,12 @@ $ ledger balance -f drewr3.dat Bo $ 20.00 Expenses:Books @end smallexample -The first example looks for any account starting with ``Bo'', of which -there are none. The second looks for any account with ``Bo'', which is -@code{Expenses:Books}. +The first example looks for any account starting with @samp{Bo}, of +which there are none. The second looks for any account with @samp{Bo}, +which is @samp{Expenses:Books}. @cindex limit by payees +@findex --limit @var{EXPR} If you want to know exactly how much you have spent in a particular account on a particular payee, the following are equivalent: @@ -3762,7 +3859,7 @@ exclude multiple accounts with parentheses: $ ledger -s bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\) @end smallexample -@node Controlling formatting, , Controlling the Accounts and Payees, Balance Reports +@node Controlling Formatting, , Controlling the Accounts and Payees, Balance Reports @subsection Controlling Formatting These examples all use the default formatting for the balance @@ -3782,7 +3879,7 @@ $ ledger -b "last oct" -s -S T bal ^expenses From left to right the options mean: Show transactions since last October; show all sub-accounts; sort by the absolute value of the total; and report the balance for all accounts that begin with -``expenses''. +@samp{expenses}. @menu * Reporting monthly expenses:: @@ -3791,9 +3888,10 @@ total; and report the balance for all accounts that begin with @node Reporting monthly expenses, , Typical queries, Typical queries @subsection Reporting monthly expenses @findex --monthly -@findex -M @findex --display @var{EXPR} @findex --period-sort @var{VEXPR} +@findex --related +@findex --subtotal The following query makes it easy to see monthly expenses, with each month's expenses sorted by the amount: @@ -3802,8 +3900,8 @@ month's expenses sorted by the amount: $ ledger -M --period-sort "(amount)" reg ^expenses @end smallexample -Now, you might wonder where the money came from to pay for these -things. To see that report, add @code{-r}, which shows the +Now, you might wonder where the money came from to pay for these things. +To see that report, add @option{--related (-r)}, which shows the ``related account'' postings: @smallexample @@ -3813,8 +3911,8 @@ $ ledger -M --period-sort "(amount)" -r reg ^expenses But maybe this prints too much information. You might just want to see how much you're spending with your MasterCard. That kind of query requires the use of a display predicate, since the postings -calculated must match @code{^expenses}, while the postings -displayed must match @code{mastercard}. The command would be: +calculated must match @samp{^expenses}, while the postings +displayed must match @samp{mastercard}. The command would be: @smallexample $ ledger -M -r --display "account =~ /mastercard/" reg ^expenses @@ -3822,8 +3920,8 @@ $ ledger -M -r --display "account =~ /mastercard/" reg ^expenses This query says: Report monthly subtotals; report the ``related account'' postings; display only related postings whose -account matches @code{mastercard}, and base the calculation on -postings matching @code{^expenses}. +account matches @samp{mastercard}, and base the calculation on +postings matching @samp{^expenses}. This works just as well for report the overall total, too: @@ -3831,9 +3929,9 @@ This works just as well for report the overall total, too: $ ledger -s -r --display "account =~ /mastercard/" reg ^expenses @end smallexample -The @code{-s} option subtotals all postings, just as @code{-M} -subtotaled by the month. The running total in both cases is off, -however, since a display expression is being used. +The @option{--subtotal (-s)} option subtotals all postings, just as +@option{--monthly (-M)} subtotaled by the month. The running total in +both cases is off, however, since a display expression is being used. @node Advanced Reports, , Typical queries, Building Reports @section Advanced Reports @@ -3962,31 +4060,31 @@ nothing. @node Visualizing with Gnuplot, , Asset Allocation, Advanced Reports @subsection Visualizing with Gnuplot -@cindex Gnuplot script @cindex plotting @cindex Gnuplot @findex --amount-data @findex --total-data +@findex --limit @var{EXPR} +@findex --display @var{EXPR} -If you have @command{Gnuplot} installed, you can graph any of the -above register reports. The script to do this is included in the -ledger distribution, and is named @file{contrib/report}. Install -@file{report} anywhere along your @env{PATH}, and then use -@command{report} instead of @command{ledger} when doing a register -report. The only thing to keep in mind is that you must specify -@code{-j (--amount-data)} or @code{-J (--total-data)} to indicate -whether Gnuplot should plot the amount, or the running total. For -example, this command plots total monthly expenses made on your -MasterCard. +If you have ``Gnuplot'' program installed, you can graph any of the +above register reports. The script to do this is included in the ledger +distribution, and is named @file{contrib/report}. Install @file{report} +anywhere along your @env{PATH}, and then use @file{report} instead of +@file{ledger} when doing a register report. The only thing to keep in +mind is that you must specify @option{--amount-data (-j)} or +@option{--total-data (-J)} to indicate whether ``Gnuplot'' should plot +the amount, or the running total. For example, this command plots total +monthly expenses made on your MasterCard. @smallexample $ report -j -M -r --display "account =~ /mastercard/" reg ^expenses @end smallexample -The @command{report} script is a very simple Bourne shell script, that -passes a set of scripted commands to Gnuplot. Feel free to modify the -script to your liking, since you may prefer histograms to line plots, -for example. +The @file{report} script is a very simple Bourne shell script, that +passes a set of scripted commands to ``Gnuplot''. Feel free to modify +the script to your liking, since you may prefer histograms to line +plots, for example. Here are some useful plots: @@ -4006,13 +4104,13 @@ report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab @end smallexample -The last report uses both a calculation predicate (@code{-l}) and -a display predicate (@code{-d}). The calculation predicates limits -the report to postings whose amount is greater than $1 (which can only -happen if the posting amount is in dollars). The display predicate -limits the transactions @emph{displayed} to just those since last -February, even those transactions from before then will be computed as -part of the balance. +The last report uses both a calculation predicate @option{--limit +@var{EXPR} (-l)} and a display predicate @option{--display @var{EXPR} +(-d)}. The calculation predicates limits the report to postings whose +amount is greater than $1 (which can only happen if the posting amount +is in dollars). The display predicate limits the transactions +@emph{displayed} to just those since last February, even those +transactions from before then will be computed as part of the balance. @node Reporting Commands, Command-line Syntax, Building Reports, Top @chapter Reporting Commands @@ -4027,14 +4125,14 @@ part of the balance. @section Primary Financial Reports @menu -* The balance Command:: -* The equity Command:: -* The register Command:: -* The print Command:: +* The @command{balance} command:: +* The @command{equity} command:: +* The @command{register} command:: +* The @command{print} command:: @end menu -@node The balance Command, The equity Command, Primary Financial Reports, Primary Financial Reports -@subsection The @code{balance} command +@node The @command{balance} command, The @command{equity} command, Primary Financial Reports, Primary Financial Reports +@subsection The @command{balance} command @findex balance The @command{balance} command reports the current balance of all @@ -4043,17 +4141,19 @@ balance report to the matching accounts. If an account contains multiple types of commodities, each commodity's total is reported separately. -@node The equity Command, The register Command, The balance Command, Primary Financial Reports -@subsection The @code{equity} command +@node The @command{equity} command, The @command{register} command, The @command{balance} command, Primary Financial Reports +@subsection The @command{equity} command @findex equity The @command{equity} command prints out accounts balances as if they were transactions. This makes it easy to establish the starting balances for an account, such as when @ref{Archiving Previous Years}. -@node The register Command, The print Command, The equity Command, Primary Financial Reports -@subsection The @code{register} command +@node The @command{register} command, The @command{print} command, The @command{equity} command, Primary Financial Reports +@subsection The @command{register} command @findex register +@findex --amount-data +@findex --total-data The @command{register} command displays all the postings occurring in a single account, line by line. The account regex must be @@ -4067,21 +4167,22 @@ checkbook, or single-account ledger, would look like. It also shows a running balance. The final running balance of any register should always be the same as the current balance of that account. -If you have Gnuplot installed, you may plot the amount or running +If you have ``Gnuplot'' installed, you may plot the amount or running total of any register by using the script @file{report}, which is included in the Ledger distribution. The only requirement is that you -add either @code{-j} or @code{-J} to your register command, in -order to plot either the amount or total column, respectively. +add either @option{--amount-data (-j)} or @option{--total-data (-J)} to +your register command, in order to plot either the amount or total +column, respectively. -@node The print Command, , The register Command, Primary Financial Reports -@subsection The @code{print} command +@node The @command{print} command, , The @command{register} command, Primary Financial Reports +@subsection The @command{print} command @findex print The @command{print} command prints out ledger transactions in a textual format that can be parsed by Ledger. They will be properly formatted, -and output in the most economic form possible. The ``print'' command -also takes a list of optional regexes, which will cause only those -postings which match in some way to be printed. +and output in the most economic form possible. The @command{print} +command also takes a list of optional regexes, which will cause only +those postings which match in some way to be printed. The @command{print} command can be a handy way to clean up a ledger file whose formatting has gotten out of hand. @@ -4091,24 +4192,24 @@ file whose formatting has gotten out of hand. @menu * Comma Separated Values files:: -* The lisp command:: -* Emacs Org mode:: +* The @command{lisp} command:: +* Emacs @command{org} Mode:: * Org mode with Babel:: -* The pricemap Command:: -* The xml Command:: -* prices and pricedb:: +* The @command{pricemap} command:: +* The @command{xml} command:: +* @command{prices} and @command{pricedb} commands:: @end menu -@node Comma Separated Values files, The lisp command, Reports in other Formats, Reports in other Formats +@node Comma Separated Values files, The @command{lisp} command, Reports in other Formats, Reports in other Formats @subsection Comma Separated Values files @menu -* The csv command:: -* The convert command:: +* The @command{csv} command:: +* The @command{convert} command:: @end menu -@node The csv command, The convert command, Comma Separated Values files, Comma Separated Values files -@subsubsection The @code{csv} command +@node The @command{csv} command, The @command{convert} command, Comma Separated Values files, Comma Separated Values files +@subsubsection The @command{csv} command @findex csv The @command{csv} command will output print out the desired ledger @@ -4116,19 +4217,18 @@ transactions in a csv format suitable for import into other programs. You can specify the transactions to print using all the normal limiting and searching functions. -@node The convert command, , The csv command, Comma Separated Values files -@subsubsection The @code{convert} command -@cindex csv conversion -@cindex reading csv +@node The @command{convert} command, , The @command{csv} command, Comma Separated Values files +@subsubsection The @command{convert} command +@cindex csv importing @cindex comma separated variable file reading @findex convert @findex --input-date-format @var{DATE_FORMAT} -The @code{convert} command parses a comma separated value (csv) file +The @command{convert} command parses a comma separated value (csv) file and outputs Ledger transactions. Many banks offer csv file downloads. Unfortunately, the file formats, aside the from commas, are all -different. The ledger @code{convert} command tries to help as much as -it can. +different. The ledger @command{convert} command tries to help as much +as it can. Your banks csv files will have fields in different orders from other banks, so there must be a way to tell Ledger what to expect. Insert @@ -4154,9 +4254,8 @@ Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Chec Unfortunately, as it stands Ledger cannot read it, but you can. Ledger expects the first line to contain a description of the fields on each line of the file. The fields ledger can recognize are called -@option{date}, @option{posted}, @option{code}, @option{payee} or -@option{desc}, @option{amount}, @option{cost}, @option{total}, and -@option{note}. +@code{date}, @code{posted}, @code{code}, @code{payee} or @code{desc}, +@code{amount}, @code{cost}, @code{total}, and @code{note}. Delete the account description lines at the top, and replace the first line in the data above with: @@ -4171,8 +4270,8 @@ Then execute ledger like this: $ ledger convert download.csv --input-date-format "%m/%d/%Y" @end smallexample -Where the @code{--input-date-format} option tells ledger how to -interpret the dates. +Where the @option{--input-date-format @var{DATE_FORMAT}} option tells +ledger how to interpret the dates. Importing csv files is a lot of work, and but is very amenable to scripting. @@ -4188,23 +4287,24 @@ occurs in the first column of the data use: transid,date,payee,note,amount,,,code, @end smallexample -Ledger will include @code{; transid: 767718} in the first transaction +Ledger will include @samp{; transid: 767718} in the first transaction is from the file above. @findex --invert @findex --account @var{STR} @findex --rich-data -The @code{convert} command accepts three options, the most important -ones are @code{--invert} which inverts the amount field, and -@code{--account @var{STR}} which you can use to specify the account to -balance against and @code{--rich-data}. When using the rich-data +The @command{convert} command accepts three options, the most important +ones are @option{--invert} which inverts the amount field, and +@option{--account @var{STR}} which you can use to specify the account to +balance against and @option{--rich-data}. When using the rich-data switch additional metadata is stored as tags. There is, for example, -a UUID field. If an entry with the same UUID tag is already included -in the normal ledger file (specified via @code{-f} or via environment -variable @env{LEDGER_FILE}) this entry will not be printed again. +a UUID field. If an entry with the same UUID tag is already included in +the normal ledger file (specified via @option{--file @var{FILE} (-f)} or +via environment variable @env{LEDGER_FILE}) this entry will not be +printed again. -You can also use @code{convert} with @code{payee} and @code{account} +You can also use @command{convert} with @code{payee} and @code{account} directives. First, you can use the @code{payee} and @code{alias} directive to rewrite the @code{payee} field based on some rules. Then you can use the account and its @code{payee} directive to specify the @@ -4217,14 +4317,14 @@ account Aufwand:Einkauf:Lebensmittel payee ^(Aldi|Alnatura|Kaufland|REWE)$ @end smallexample -Note that it may be necessary for the output of @code{ledger convert} +Note that it may be necessary for the output of @samp{ledger convert} to be passed through @code{ledger print} a second time if you want to match on the new payee field. During the @code{ledger convert} run only the original payee name as specified in the csv data seems to be used. -@node The lisp command, Emacs Org mode, Comma Separated Values files, Reports in other Formats -@subsection The @code{lisp} command +@node The @command{lisp} command, Emacs @command{org} Mode, Comma Separated Values files, Reports in other Formats +@subsection The @command{lisp} command @findex lisp @findex emacs @@ -4238,14 +4338,14 @@ directly by Emacs Lisp. The format of the @code{sexp} is: @end smallexample @noindent -@code{emacs} can also be used as a synonym for @code{lisp} +@command{emacs} can also be used as a synonym for @command{lisp}. -@node Emacs Org mode, Org mode with Babel, The lisp command, Reports in other Formats -@subsection Emacs @code{org} Mode +@node Emacs @command{org} Mode, Org mode with Babel, The @command{lisp} command, Reports in other Formats +@subsection Emacs @command{org} Mode @findex org -The @code{org} command produces a journal file suitable for use in the -Emacs Org mode. More details on using Org mode can be found at +The @command{org} command produces a journal file suitable for use in +the Emacs Org mode. More details on using Org mode can be found at @url{http://www.orgmode.org}. Org mode has a sub-system known as Babel which allows for literate @@ -4253,31 +4353,31 @@ programming. This allows you to mix text and code within the same document and automatically execute code which may generate results which will then appear in the text. -One of the languages supported by @code{org+babel} is Ledger, so that -you can have ledger commands embedded in a text file and have the -output of ledger commands also appear in the text file. The output -can be updated whenever any new ledger entries are added. +One of the languages supported by Babel is Ledger, so that you can have +ledger commands embedded in a text file and have the output of ledger +commands also appear in the text file. The output can be updated +whenever any new ledger entries are added. For instance, the following Org mode text document snippet illustrates -a very naive but still useful of the @code{org+babel} system: +a very naive but still useful of the Babel system: @smallexample * A simple test of ledger in an org file The following are some entries and I have requested that ledger be run -to generate a balance on the accounts. I could have asked for a -register or, in fact, anything at all the ledger can do through command -line options. +to generate a balance on the accounts. I could have asked for +a register or, in fact, anything at all the ledger can do through +command line options. #+begin_src ledger :cmdline -s bal :results value 2010/01/01 * Starting balance - assets:bank:savings £1300.00 - income:starting balances + assets:bank:savings £1300.00 + income:starting balances 2010/07/22 * Got paid - assets:bank:chequing £1000.00 - income:salary + assets:bank:chequing £1000.00 + income:salary 2010/07/23 Rent - expenses:rent £500.00 - assets:bank:chequing + expenses:rent £500.00 + assets:bank:chequing #+end_src #+results: @@ -4295,20 +4395,19 @@ invoke ledger on the contents of that block and generate a ``results'' block. The results block can appear anywhere in the file but, by default, will appear immediately below the source code block. -You can combine multiple source code blocks before executing ledger -and do all kinds of other wonderful things with Babel (and org). +You can combine multiple source code blocks before executing ledger and +do all kinds of other wonderful things with Babel (and Org mode). -@node Org mode with Babel, The pricemap Command, Emacs Org mode, Reports in other Formats +@node Org mode with Babel, The @command{pricemap} command, Emacs @command{org} Mode, Reports in other Formats @subsection Org mode with Babel Using Babel, it is possible to record financial transactions conveniently in an org file and subsequently generate the financial reports required. -With a recent version of org (7.01+), Ledger support is provided. To -use it, enable Ledger support. Check the Babel documentation on Worg -for instructions on how to achieve this but I currently do this -directly as follows: +As of Org-mode 7.01, Ledger support is provided. Check the Babel +documentation on Worg for instructions on how to achieve this but +I currently do this directly as follows: @smallexample (org-babel-do-load-languages @@ -4322,26 +4421,28 @@ include Ledger entries within an org file. There are three ways (at least) in which these can be included: @enumerate + @item - place all Ledger entries within one source block and execute - this block with different arguments to generate the - appropriate reports; +place all Ledger entries within one single source block and execute this +block with different arguments to generate the appropriate reports, + @item - place Ledger entries in more than one source block and use the - noweb literary programming approach, supported by babel, to - combine these into one block elsewhere in the file for - processing by Ledger; and, +place Ledger entries in more than one source block and use the +@code{noweb} literary programming approach, supported by Babel, to +combine these into one block elsewhere in the file for processing by +Ledger, + @item - place Ledger entries in different source blocks and use - tangling to generate a Ledger file which you can subsequently - process using Ledger directly. +place Ledger entries in different source blocks and use @code{tangle} to +generate a Ledger file which you can subsequently process using Ledger +directly. @end enumerate The first two are described in more detail in this short tutorial. @menu * Embedded Ledger example with single source block:: -* Multiple Ledger source blocks with @command{noweb}:: +* Multiple Ledger source blocks with @code{noweb}:: * Income Entries:: * Expenses:: * Financial Summaries:: @@ -4350,7 +4451,7 @@ The first two are described in more detail in this short tutorial. * Summary:: @end menu -@node Embedded Ledger example with single source block, Multiple Ledger source blocks with @command{noweb}, Org mode with Babel, Org mode with Babel +@node Embedded Ledger example with single source block, Multiple Ledger source blocks with @code{noweb}, Org mode with Babel, Org mode with Babel @subsubsection Embedded Ledger example with single source block The easiest, albeit possibly less useful, way in which to use Ledger @@ -4361,36 +4462,36 @@ entries. The following is an example source block: #+name: allinone #+begin_src ledger 2010/01/01 * Starting balance - assets:bank:savings £1300.00 + assets:bank:savings £1300.00 income:starting balances 2010/07/22 * Got paid - assets:bank:chequing £1000.00 + assets:bank:chequing £1000.00 income:salary 2010/07/23 Rent - expenses:rent £500.00 + expenses:rent £500.00 assets:bank:chequing 2010/07/24 Food - expenses:food £150.00 + expenses:food £150.00 assets:bank:chequing 2010/07/31 * Interest on bank savings - assets:bank:savings £3.53 + assets:bank:savings £3.53 income:interest 2010/07/31 * Transfer savings - assets:bank:savings £250.00 + assets:bank:savings £250.00 assets:bank:chequing 2010/08/01 got paid again - assets:bank:chequing £1000.00 + assets:bank:chequing £1000.00 income:salary #+end_src @end smallexample -In this example, we have combined both expenses and income into one -set of Ledger entries. We can now generate register and balance -reports (as well as many other types of reports) using babel to invoke -Ledger with specific arguments. The arguments are passed to Ledger -using the :cmdline header argument. In the code block above, there is -no such argument so the system takes the default. For Ledger code -blocks, the default :cmdline argument is bal and the result of +In this example, we have combined both expenses and income into one set +of Ledger entries. We can now generate register and balance reports (as +well as many other types of reports) using Babel to invoke Ledger with +specific arguments. The arguments are passed to Ledger using the +@code{:cmdline} header argument. In the code block above, there is no +such argument so the system takes the default. For Ledger code blocks, +the default @code{:cmdline} argument is @code{bal} and the result of evaluating this code block (@kbd{C-c C-c}) would be: @smallexample @@ -4401,8 +4502,8 @@ evaluating this code block (@kbd{C-c C-c}) would be: @end smallexample If, instead, you wished to generate a register of all the transactions, -you would change the #+begin_src line for the code block to include the -required command line option: +you would change the @code{#+begin_src} line for the code block to +include the required command line option: @smallexample #+begin_src ledger :cmdline reg @@ -4412,15 +4513,15 @@ Evaluating the code block again would generate a different report. Having to change the actual directive on the code block and re-evaluate makes it difficult to have more than one view of your transactions and -financial state. Eventually, babel will support passing arguments to +financial state. Eventually, Babel will support passing arguments to @code{#+call} evaluations of code blocks but this support is missing currently. Instead, we can use the concepts of literary programming, as -implemented by the noweb features of babel, to help us. +implemented by the @code{noweb} features of Babel, to help us. -@node Multiple Ledger source blocks with @command{noweb}, Income Entries, Embedded Ledger example with single source block, Org mode with Babel -@subsubsection Multiple Ledger source blocks with @command{noweb} +@node Multiple Ledger source blocks with @code{noweb}, Income Entries, Embedded Ledger example with single source block, Org mode with Babel +@subsubsection Multiple Ledger source blocks with @code{noweb} -The @command{noweb} feature of babel allows us to expand references to +The @code{noweb} feature of Babel allows us to expand references to other code blocks within a code block. For Ledger, this can be used to group transactions according to type, say, and then bring various sets of transactions together to generate reports. @@ -4428,32 +4529,32 @@ of transactions together to generate reports. Using the same transactions used above, we could consider splitting these into expenses and income, as follows: -@node Income Entries, Expenses, Multiple Ledger source blocks with @command{noweb}, Org mode with Babel +@node Income Entries, Expenses, Multiple Ledger source blocks with @code{noweb}, Org mode with Babel @subsubsection Income Entries The first set of entries relates to income, either monthly pay or interest, all typically going into one of my bank accounts. Here, I have placed several entries, but we could have had each entry in a separate -src block. Note that all code blocks you wish to refer to later must -have the :noweb yes babel header argument specified. +@code{src} block. Note that all code blocks you wish to refer to later +must have the @code{:noweb yes} header argument specified. @smallexample #+name: income #+begin_src ledger :noweb yes 2010/01/01 * Starting balance - assets:bank:savings £1300.00 + assets:bank:savings £1300.00 income:starting balances 2010/07/22 * Got paid - assets:bank:chequing £1000.00 + assets:bank:chequing £1000.00 income:salary 2010/07/31 * Interest on bank savings - assets:bank:savings £3.53 + assets:bank:savings £3.53 income:interest 2010/07/31 * Transfer savings - assets:bank:savings £250.00 + assets:bank:savings £250.00 assets:bank:chequing 2010/08/01 got paid again - assets:bank:chequing £1000.00 + assets:bank:chequing £1000.00 income:salary #+end_src @end smallexample @@ -4462,17 +4563,17 @@ have the :noweb yes babel header argument specified. @subsubsection Expenses The following entries relate to personal expenses, such as rent and -food. Again, these have all been placed in a single src block but could -have been done individually. +food. Again, these have all been placed in a single @code{src} block but +could have been done individually. @smallexample #+name: expenses #+begin_src ledger :noweb yes 2010/07/23 Rent - expenses:rent £500.00 + expenses:rent £500.00 assets:bank:chequing 2010/07/24 Food - expenses:food £150.00 + expenses:food £150.00 assets:bank:chequing #+end_src @end smallexample @@ -4481,20 +4582,21 @@ have been done individually. @subsubsection Financial Summaries Given the ledger entries defined above in the income and expenses code -blocks, we can now refer to these using the noweb expansion -directives, @code{<<name>>}. We can now define different code blocks -to generate specific reports for those transactions. Below are two -examples, one to generate a balance report and one to generate -a register report of all transactions. +blocks, we can now refer to these using the noweb expansion directives, +@code{<<name>>}. We can now define different code blocks to generate +specific reports for those transactions. Below are two examples, one to +generate a balance report and one to generate a register report of all +transactions. @node An overall balance summary, Generating a monthly register, Financial Summaries, Org mode with Babel @subsubsection An overall balance summary +@findex --subtotal The overall balance of your account and expenditure with a breakdown -according to category is specified by passing the :cmdline bal -argument to Ledger. This code block can now be evaluated (@kbd{C-c -C-c}) and the results generated by incorporating the transactions -referred to by the @code{<<income>>} and @code{<<expenses>>} lines. +according to category is specified by passing the @code{:cmdline bal} +argument to Ledger. This code block can now be evaluated (@kbd{C-c C-c}) +and the results generated by incorporating the transactions referred to +by the @code{<<income>>} and @code{<<expenses>>} lines. @smallexample #+name: balance @@ -4510,9 +4612,9 @@ referred to by the @code{<<income>>} and @code{<<expenses>>} lines. @end smallexample If you want a more detailed breakdown of where your money is and where -it has been spent, you can specify the @code{-s} flag -(i.e. @code{:cmdline -s bal}) to tell Ledger to include sub-accounts -in the report. +it has been spent, you can specify the @option{--subtotal (-s)} flag +(i.e. @code{:cmdline -s bal}) to tell Ledger to include sub-accounts in +the report. @smallexample #+begin_src ledger :cmdline -s bal :noweb yes @@ -4535,12 +4637,14 @@ in the report. @node Generating a monthly register, Summary, An overall balance summary, Org mode with Babel @subsubsection Generating a monthly register +@findex register +@findex --monthly -You can also generate a monthly register (the reg command) by -executing the following src block. This presents a summary of -transactions for each monthly period (the @code{-M} argument) with -a running total in the final column (which should be 0 at the end if -all the entries are correct). +You can also generate a monthly register (the @command{reg} command) by +executing the following @code{src} block. This presents a summary of +transactions for each monthly period (the @option{--monthly (-M)} +argument) with a running total in the final column (which should be 0 at +the end if all the entries are correct). @smallexample #+name: monthlyregister @@ -4551,15 +4655,15 @@ all the entries are correct). #+results: monthlyregister :2010/01/01 - 2010/01/31 assets:bank:savings £1300.00 £1300.00 -: in:starting balances £-1300.00 0 +: in:starting balances £-1300.00 0 :2010/07/01 - 2010/07/31 assets:bank:chequing £100.00 £100.00 : assets:bank:savings £253.53 £353.53 : expenses:food £150.00 £503.53 : expenses:rent £500.00 £1003.53 : income:interest £-3.53 £1000.00 -: income:salary £-1000.00 0 +: income:salary £-1000.00 0 :2010/08/01 - 2010/08/01 assets:bank:chequing £1000.00 £1000.00 -: income:salary £-1000.00 0 +: income:salary £-1000.00 0 @end smallexample We could also generate a monthly report on our assets showing how these @@ -4588,11 +4692,11 @@ file and manipulated using Babel. However, only simple Ledger features have been illustrated; please refer to the Ledger documentation for examples of more complex operations with a ledger. -@node The pricemap Command, The xml Command, Org mode with Babel, Reports in other Formats -@subsection The @code{pricemap} command +@node The @command{pricemap} command, The @command{xml} command, Org mode with Babel, Reports in other Formats +@subsection The @command{pricemap} command @findex pricemap -If you have the @code{graphviz} graph visualization package installed, +If you have the @file{graphviz} graph visualization package installed, ledger can generate a graph of the relationship between your various commodities. The output file is in the ``dot'' format. @@ -4600,8 +4704,8 @@ This is probably not very interesting, unless you have many different commodities valued in terms of each other. For example, multiple currencies and multiples investments valued in those currencies. -@node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats -@subsection The @code{xml} command +@node The @command{xml} command, @command{prices} and @command{pricedb} commands, The @command{pricemap} command, Reports in other Formats +@subsection The @command{xml} command @findex xml By default, Ledger uses a human-readable data format, and displays its @@ -4647,7 +4751,7 @@ both contain whatever text the user wishes. After the initial transaction data, there must follow a set of postings marked with @code{en:postings}. Typically these postings will all balance each other, but if not they will be automatically balanced into -an account named @code{<Unknown>}. +an account named @samp{Unknown}. Within the @code{en:postings} tag is a series of one or more @code{posting}'s, which have the following form: @@ -4677,10 +4781,10 @@ Lastly follows the amount of the posting, indicated by there are four different kinds, each with its own format: @enumerate -@item Boolean -@item integer -@item amount -@item balance +@item Boolean, +@item integer, +@item amount, +@item balance. @end enumerate The format of a Boolean value is @code{true} or @code{false} @@ -4702,15 +4806,20 @@ quantity. The commodity can have a set of flags that indicate how to display it. The meaning of the flags (all of which are optional) are: @table @code + @item P The commodity is prefixed to the value. + @item S The commodity is separated from the value by a space. + @item T Thousands markers are used to display the amount. + @item E The format of the amount is European, with period used as a thousands marker, and comma used as the decimal point. + @end table The actual quantity for an amount is an integer of arbitrary size. @@ -4751,15 +4860,16 @@ That is the extent of the XML data format used by Ledger. It will output such data if the @command{xml} command is used, and can read the same data. -@node prices and pricedb, , The xml Command, Reports in other Formats -@subsection @code{prices} and @code{pricedb} commands +@node @command{prices} and @command{pricedb} commands, , The @command{xml} command, Reports in other Formats +@subsection @command{prices} and @command{pricedb} commands @findex prices @findex pricedb +@findex --average The @command{prices} command displays the price history for matching -commodities. The @code{-A} flag is useful with this report, to -display the running average price, or @code{-D} to show each price's -deviation from that average. +commodities. The @option{--average (-A)} option is useful with this +report, to display the running average price, or @option{--deviation +(-D)} to show each price's deviation from that average. There is also a @command{pricedb} command which outputs the same information as @command{prices}, but does in a format that can be @@ -4771,31 +4881,30 @@ pricedb database files. @findex --count @menu -* accounts:: -* payees:: -* commodities:: -* tags:: -* entry and xact:: -* stats:: -* select:: +* @command{accounts}:: +* @command{payees}:: +* @command{commodities}:: +* @command{tags}:: +* @command{xact}:: +* @command{stats}:: +* @command{select}:: @end menu -@node accounts, payees, Reports about your Journals, Reports about your Journals -@subsection @code{accounts} +@node @command{accounts}, @command{payees}, Reports about your Journals, Reports about your Journals +@subsection @command{accounts} @findex accounts The @command{accounts} reports all of the accounts in the journal. -Following the command with a regular expression will limit the output -to accounts matching the regex. The output is sorted by name. Using -the @code{--count} option will tell you how many entries use each -account. +Following the command with a regular expression will limit the output to +accounts matching the regex. The output is sorted by name. Using the +@option{--count} option will tell you how many entries use each account. -@node payees, commodities, accounts, Reports about your Journals -@subsection @code{payees} +@node @command{payees}, @command{commodities}, @command{accounts}, Reports about your Journals +@subsection @command{payees} @findex payees The @command{payees} reports all of the unique payees in the journal. -Using the @code{--count} option will tell you how many entries use +Using the @option{--count} option will tell you how many entries use each payee. To filter the payees displayed you must use the prefix: @smallexample @@ -4806,34 +4915,33 @@ Oudtshoorn Municipality Vaca Veronica @end smallexample -@node commodities, tags, payees, Reports about your Journals +@node @command{commodities}, @command{tags}, @command{payees}, Reports about your Journals @subsection @command{commodities} @findex commodities -Report all commodities present in the journals under consideration. -The output is sorted by name. Using the @code{--count} option will -tell you how many entries use each commodity. +Report all commodities present in the journals under consideration. The +output is sorted by name. Using the @option{--count} option will tell +you how many entries use each commodity. -@node tags, entry and xact, commodities, Reports about your Journals +@node @command{tags}, @command{xact}, @command{commodities}, Reports about your Journals @subsection @command{tags} @findex tags @findex --values The @command{tags} reports all of the tags in the journal. The output -is sorted by name. Using the @code{--count} option will tell you how -many entries use each tag. Using the @code{--values} option will +is sorted by name. Using the @option{--count} option will tell you how +many entries use each tag. Using the @option{--values} option will report the values used by each tag. -@node entry and xact, stats, tags, Reports about your Journals -@subsection @command{draft}, @command{entry} and @command{xact} +@node @command{xact}, @command{stats}, @command{tags}, Reports about your Journals +@subsection @command{xact} @findex draft @findex entry @findex xact -The @code{draft}, @code{entry} and @command{xact} commands simplify -the creation of new transactions. It works on the principle that 80% -of all postings are variants of earlier postings. Here's how it -works: +The @command{xact} command simplify the creation of new transactions. +It works on the principle that 80% of all postings are variants of +earlier postings. Here's how it works: Say you currently have this posting in your ledger file: @@ -4844,12 +4952,12 @@ Say you currently have this posting in your ledger file: Liabilities:MasterCard $-15.00 @end smallexample -Now it's @code{2004/4/9}, and you've just eating at @code{Viva -Italiano} again. The exact amounts are different, but the overall -form is the same. With the @command{xact} command you can type: +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva Italiano} +again. The exact amounts are different, but the overall form is the +same. With the @command{xact} command you can type: @smallexample -$ ledger entry 2004/4/9 viva food 11 tips 2.50 +$ ledger xact 2004/4/9 viva food 11 tips 2.50 @end smallexample This produces the following output: @@ -4862,8 +4970,8 @@ This produces the following output: @end smallexample It works by finding a past posting matching the regular expression -@code{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier posting. If Ledger does not succeed in +@samp{viva}, and assuming that any accounts or amounts specified will be +similar to that earlier posting. If Ledger does not succeed in generating a new transaction, an error is printed and the exit code is set to @samp{1}. @@ -4871,26 +4979,27 @@ Here are a few more examples of the @command{xact} command, assuming the above journal transaction: @smallexample -$ ledger entry 4/9 viva 11.50 -$ ledger entry 4/9 viva 11.50 checking # (from `checking') -$ ledger entry 4/9 viva food 11.50 tips 8 +$ ledger xact 4/9 viva 11.50 +$ ledger xact 4/9 viva 11.50 checking # (from `checking') +$ ledger xact 4/9 viva food 11.50 tips 8 $ ledger xact 4/9 viva food 11.50 tips 8 cash $ ledger xact 4/9 viva food $11.50 tips $8 cash $ ledger xact 4/9 viva dining "DM 11.50" @end smallexample -@command{xact} is identical to @command{entry} and is provide for -backwards compatibility with Ledger 2.X. +@command{draft} and @command{entry} are both synonyms of +@command{xact}. @command{entry} is provided for backwards compatibility +with Ledger 2.X. -@node stats, select, entry and xact, Reports about your Journals -@subsection @code{stats} +@node @command{stats}, @command{select}, @command{xact}, Reports about your Journals +@subsection @command{stats} @findex stats @findex stat FIX THIS ENTRY @c FIXME thdox -@node select, , stats, Reports about your Journals -@subsection @code{select} +@node @command{select}, , @command{stats}, Reports about your Journals +@subsection @command{select} @findex select FIX THIS ENTRY @c FIXME thdox @@ -4901,7 +5010,7 @@ FIX THIS ENTRY @c FIXME thdox @menu * Basic Usage:: * Command Line Quick Reference:: -* Detailed Options Description:: +* Detailed Option Description:: * Period Expressions:: @end menu @@ -4913,7 +5022,7 @@ survey this to get an overview before diving in to the @ref{Ledger Tutorial} and more detailed examples that follow. Ledger has a very simple command-line interface, named---enticingly -enough---@command{ledger}. It supports a few reporting commands, and +enough---@file{ledger}. It supports a few reporting commands, and a large number of options for refining the output from those commands. The basic syntax of any ledger command is: @@ -4924,8 +5033,8 @@ $ ledger [OPTIONS...] COMMAND [ARGS...] After the command word there may appear any number of arguments. For most commands, these arguments are regular expressions that cause the output to relate only to postings matching those regular expressions. -For the @command{transaction} command, the arguments have a special -meaning, described below. +For the @command{xact} command, the arguments have a special meaning, +described below. The regular expressions arguments always match the account name that a posting refers to. To match on the payee of the transaction @@ -4945,286 +5054,370 @@ or $ ledger bal rent food movies @@freddie @end smallexample -There are many, many command options available with the -@command{ledger} command, and it takes a while to master them. -However, none of them are required to use the basic reporting -commands. +There are many, many command options available with the @file{ledger} +program, and it takes a while to master them. However, none of them are +required to use the basic reporting commands. -@node Command Line Quick Reference, Detailed Options Description, Basic Usage, Command-line Syntax +@node Command Line Quick Reference, Detailed Option Description, Basic Usage, Command-line Syntax @section Command Line Quick Reference @menu -* Reporting Commands Quick Reference:: -* Basic Options Quick Reference:: -* Report Filtering Quick Reference:: +* Basic Reporting Commands:: +* Basic Options:: +* Report Filtering:: * Error Checking and Calculation Options:: -* Output Customization Quick Reference:: +* Output Customization:: * Grouping Options:: -* Commodity Reporting Quick Reference:: +* Commodity Reporting:: @end menu -@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference -@subsection Reporting Commands +@node Basic Reporting Commands, Basic Options, Command Line Quick Reference, Command Line Quick Reference +@subsection Basic Reporting Commands @ftable @code + @item balance @itemx bal -Show account balances +Show account balances. + @item register @itemx reg -Show all transactions with running total +Show all transactions with running total. + @item csv -Show transactions in csv format, for exporting to other programs +@cindex csv exporting +Show transactions in csv format, for exporting to other programs. + @item print -Print transaction in a ledger readable format +Print transaction in a ledger readable format. + @item xml -Produce XML output of the register command +Produce XML output of the register command. + @item lisp @itemx emacs -Produce Emacs lisp output +Produce Emacs lisp output. + @item equity -Print account balances as transactions +Print account balances as transactions. + @item prices -Print price history for matching commodities +Print price history for matching commodities. + @item pricedb -Print price history for matching commodities in ledger readable format +Print price history for matching commodities in ledger readable format. + @item xact -Generate transactions based on previous postings +Generate transactions based on previous postings. + @end ftable -@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference +@node Basic Options, Report Filtering, Basic Reporting Commands, Command Line Quick Reference @subsection Basic Options @ftable @code + @item --help @itemx -h -Print summary of all options +Print summary of all options. @item --version @itemx -v -Print version of ledger executable +Print version of ledger executable. @item --file @var{FILE} @itemx -f @var{FILE} -Read @file{FILE} as a ledger file +Read @file{FILE} as a ledger file. @item --output @var{FILE} @itemx -o @var{FILE} -Redirect output to @file{FILE} +Redirect output to @file{FILE}. @item --init-file @var{FILE} @itemx -i @var{FILE} -Specify options file +Specify options file. @item --account @var{STR} @itemx -a @var{STR} -Specify default account @var{STR} for QIF file postings +Specify default account @var{STR} for QIF file postings. + @end ftable -@node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference +@node Report Filtering, Error Checking and Calculation Options, Basic Options, Command Line Quick Reference @subsection Report Filtering @ftable @code + @item --current @itemx -c -Display transaction on or before the current date +Display transaction on or before the current date. + @item --begin @var{DATE} @itemx -b @var{DATE} -Begin reports on or after @var{DATE} +Begin reports on or after @var{DATE}. + @item --end @var{DATE} @itemx -e @var{DATE} -Limit end date of transactions for report +Limit end date of transactions for report. + @item --period @var{PERIOD_EXPRESSION} @itemx -p @var{PERIOD_EXPRESSION} -Set report period to @var{PERIOD_EXPRESSION} +Set report period to @var{PERIOD_EXPRESSION}. + @item --period-sort @var{VEXPR} -Sort postings within each period +Sort postings within each period. + @item --cleared @itemx -C -Display only cleared postings +Display only cleared postings. + @item --dc -Display register or balance in debit/credit format +Display register or balance in debit/credit format. + @item --uncleared @itemx -U -Display only uncleared postings +Display only uncleared postings. + @item --real @itemx -R -Display only real postings +Display only real postings. + @item --actual @itemx -L -Display only actual postings, not automated +Display only actual postings, not automated. + @item --related @itemx -r -Display related postings +Display related postings. + @item --budget -Display how close your postings meet your budget +Display how close your postings meet your budget. + @item --add-budget -Show un-budgeted postings +Show un-budgeted postings. + @item --unbudgeted -Show only un-budgeted postings -@item --forecast -Project balances into the future +Show only un-budgeted postings. + +@item --forecast @var{VEXPR} +Project balances into the future. + @item --limit @var{EXPR} @itemx -l @var{EXPR} -Limit postings in calculations +Limit postings in calculations. + @item --amount @var{EXPR} @itemx -t @var{EXPR} -Change value expression reported in @command{register} report +Change value expression reported in @command{register} report. + @item --total @var{VEXPR} @itemx -T @var{VEXPR} Change the value expression used for ``totals'' column in -@command{register} and @command{balance} reports +@command{register} and @command{balance} reports. + @end ftable -@node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference +@node Error Checking and Calculation Options, Output Customization, Report Filtering, Command Line Quick Reference @subsection Error Checking and Calculation Options @ftable @code + @item --strict -Accounts, tags or commodities not previously declared will cause warnings +Accounts, tags or commodities not previously declared will cause +warnings. + @item --pedantic -Accounts, tags or commodities not previously declared will cause errors +Accounts, tags or commodities not previously declared will cause errors. + @item --check-payees -Enable strict and pedantic checking for payees as well as accounts, commodities and tags +Enable strict and pedantic checking for payees as well as accounts, +commodities and tags. + @item --immediate -Instruct ledger to evaluate calculations immediately rather than lazily +Instruct ledger to evaluate calculations immediately rather than lazily. + @end ftable -@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference +@node Output Customization, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference @subsection Output Customization @ftable @code + @item --collapse @itemx -n -Collapse transactions with multiple postings +Collapse transactions with multiple postings. + @item --subtotal @itemx -s -Report register as a single subtotal +Report register as a single subtotal. + @item --by-payee @itemx -P -Report subtotals by payee +Report subtotals by payee. + @item --empty @itemx -E -Include empty accounts in report +Include empty accounts in report. + @item --weekly @itemx -W -Report posting totals by week +Report posting totals by week. + @item --yearly @itemx -Y -Report posting totals by year +Report posting totals by year. + @item --dow -Report Posting totals by day of week +Report Posting totals by day of week. + @item --sort @var{VEXPR} @itemx -S @var{VEXPR} -Sort a report using @var{VEXPR} +Sort a report using @var{VEXPR}. + @item --wide @itemx -w -Assume 132 columns instead of 80 +Assume 132 columns instead of 80. + @item --head @var{INT} -Report the first @var{INT} postings +Report the first @var{INT} postings. + @item --tail @var{INT} -Report the last @var{INT} postings +Report the last @var{INT} postings. + @item --pager @var{FILE} -Direct output to @var{FILE} pager program +Direct output to @var{FILE} pager program. + @item --average @itemx -A -Report average posting value +Report average posting value. + @item --deviation @itemx -D -Report each posting deviation from the average +Report each posting deviation from the average. + @item --percent @itemx -% -Show subtotals in the balance report as percentages +Show subtotals in the balance report as percentages. @c @item --totals -@c Include running total in the @code{xml} report +@c Include running total in the @command{xml} report + @item --pivot @var{TAG} -Produce a pivot table of the @var{TAG} type specified +Produce a pivot table of the @var{TAG} type specified. + @item --amount-data @itemx -j -Show only date and value column to format the output for plots +Show only date and value column to format the output for plots. + @item --plot-amount-format @var{FORMAT_STRING} -Specify the format for the plot output +Specify the format for the plot output. + @item --total-data @itemx -J -Show only dates and totals to format the output for plots +Show only dates and totals to format the output for plots. + @item --plot-total-format @var{FORMAT_STRING} -Specify the format for the plot output +Specify the format for the plot output. + @item --display @var{EXPR} @itemx -d @var{EXPR} -Display only posting that meet the criterias in the @var{EXPR} +Display only posting that meet the criterias in the @var{EXPR}. + @item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} -Change the basic date format used in reports +Change the basic date format used in reports. + @item --format @var{FORMAT_STRING} @itemx --balance-format @var{FORMAT_STRING} @itemx --register-format @var{FORMAT_STRING} @itemx --prices-format @var{FORMAT_STRING} @itemx -F @var{FORMAT_STRING} -Set reporting format +Set reporting format. + @item --wide @itemx -w -Wide +Wide. + @item --anon -Print the ledger register with anonymized accounts and payees, useful for filing bug reports +Print the ledger register with anonymized accounts and payees, useful +for filing bug reports. + @end ftable -@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference +@node Grouping Options, Commodity Reporting, Output Customization, Command Line Quick Reference @subsection Grouping Options @ftable @code + @item --by-payee @itemx -P -Group postings by common payee names +Group postings by common payee names. + @item --daily @itemx -D -Group postings by day +Group postings by day. + @item --weekly @itemx -W -Group postings by week +Group postings by week. + @item --monthly @itemx -M -Group postings by month +Group postings by month. + @item --quarterly -Group postings by quarter +Group postings by quarter. + @item --yearly @itemx -Y -Group postings by year +Group postings by year. + @item --dow -Group by day of weeks +Group by day of weeks. + @item --subtotal @itemx -s -Group posting together, similar to balance report +Group posting together, similar to balance report. + @end ftable -@node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference +@node Commodity Reporting, , Grouping Options, Command Line Quick Reference @subsection Commodity Reporting @ftable @code + @item --price-db @var{FILE} Use @file{FILE} for retrieving stored commodity prices. + @item --price-exp @var{INT} -@itemx -L @var{INT} +@itemx -Z @var{INT} Set expected freshness of prices in @var{INT} minutes. + @item --download @itemx -Q Download quotes using named @file{getquote}. + @item --getquote @var{FILE} Sets path to a user defined script to download commodity prices. + @item --quantity @itemx -O Report commodity totals without conversion. + @item --basis @itemx -B Report cost basis. + @item --market @itemx -V Report last known market value. + @item --gain @itemx -G Report net gain loss for commodities that have a price history. + @end ftable -@node Detailed Options Description, Period Expressions, Command Line Quick Reference, Command-line Syntax +@node Detailed Option Description, Period Expressions, Command Line Quick Reference, Command-line Syntax @section Detailed Option Description @menu @@ -5232,13 +5425,13 @@ Report net gain loss for commodities that have a price history. * Session Options:: * Report Options:: * Basic options:: -* Report Filtering:: -* Output Customization:: -* Commodity Reporting:: -* Environment Variables:: +* Report filtering:: +* Output customization:: +* Commodity reporting:: +* Environment variables:: @end menu -@node Global Options, Session Options, Detailed Options Description, Detailed Options Description +@node Global Options, Session Options, Detailed Option Description, Detailed Option Description @subsection Global Options Options for Ledger report affect three separate scopes of operation: @@ -5249,6 +5442,7 @@ instance of Ledger running in the background and running multiple sessions with multiple reports per session. @ftable @code + @item --args-only Ignore all environment and init-file settings and use only command-line arguments to control Ledger. Useful for debugs @@ -5263,7 +5457,7 @@ FIX THIS ENTRY @c FIXME thdox Display the info page for ledger. @item --init-file @var{FILE} -Specify the location of the init file. The default is @file{~/.ledgerrc} +Specify the location of the init file. The default is @file{~/.ledgerrc}. @item --options Display the options in effect for this Ledger invocation, along with @@ -5323,9 +5517,10 @@ FIX THIS ENTRY @c FIXME thdox @item --version FIX THIS ENTRY @c FIXME thdox + @end ftable -@node Session Options, Report Options, Global Options, Detailed Options Description +@node Session Options, Report Options, Global Options, Detailed Option Description @subsection Session Options Options for Ledger report affect three separate scopes of operation: @@ -5336,6 +5531,7 @@ instance of Ledger running in the background and running multiple sessions with multiple reports per session. @ftable @code + @item --cache @var{FIXME} FIX THIS ENTRY @c FIXME thdox @@ -5352,7 +5548,7 @@ decimal separator, vice a period. @item --download @itemx -Q Direct Ledger to download prices using the script defined in -@code{--getquote @var{FILE}}. +@option{--getquote @var{FILE}}. @item --explicit FIX THIS ENTRY @c FIXME thdox @@ -5418,32 +5614,33 @@ Specify the location of the price entry data file. @itemx -Z @var{INT} @itemx --leeway @var{INT} Set the expected freshness of price quotes, in @var{INT} minutes. That -is, if the last known quote for any commodity is older than this -value, and if @code{--download} is being used, then the Internet will -be consulted again for a newer price. Otherwise, the old price is -still considered to be fresh enough. +is, if the last known quote for any commodity is older than this value, +and if @option{--download} is being used, then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. @item --strict -Ledger normally silently accepts any account or commodity in -a posting, even if you have misspelled a common used one. The option -@code{--strict} changes that behavior. While running @code{--strict}, -Ledger interprets all cleared transactions as correct, and if it finds -a new account or commodity (same as a misspelled commodity or account) -it will issue a warning giving you the file and line number of the -problem. +Ledger normally silently accepts any account or commodity in a posting, +even if you have misspelled a common used one. The option +@option{--strict} changes that behavior. While running +@option{--strict}, Ledger interprets all cleared transactions as +correct, and if it finds a new account or commodity (same as +a misspelled commodity or account) it will issue a warning giving you +the file and line number of the problem. @item --time-colon -The --time-colon option will display the value for a seconds based -commodity as real hours and minutes. +The @option{--time-colon} option will display the value for a seconds +based commodity as real hours and minutes. For example 8100 seconds by default will be displayed as 2.25 whereas -with the --time-colon option they will be displayed as 2:15. +with the @option{--time-colon} option they will be displayed as 2:15. @item --value-expr @var{FIXME} FIX THIS ENTRY @c FIXME thdox + @end ftable -@node Report Options, Basic options, Session Options, Detailed Options Description +@node Report Options, Basic options, Session Options, Detailed Option Description @subsection Report Options Options for Ledger report affect three separate scopes of operation: @@ -5454,6 +5651,7 @@ instance of Ledger running in the background and running multiple sessions with multiple reports per session. @ftable @code + @item --abbrev-len @var{INT} Set the minimum length an account can be abbreviated to if it doesn't fit inside the @code{account-width}. If @var{INT} is zero, then the @@ -5464,7 +5662,7 @@ desired width. @item --account @var{STR} Prepend @var{STR} to all accounts reported. That is, the option -@code{--account Personal} would tack @samp{Personal:} to the beginning +@samp{--account Personal} would track @samp{Personal:} to the beginning of every account reported in a balance report or register report. @item --account-width @var{INT} @@ -5482,8 +5680,8 @@ Show only un-budgeted postings. @item --amount @var{EXPR} @itemx -t @var{EXPR} Apply the given value expression to the posting amount (@pxref{Value -Expressions}). Using @code{--amount} you can apply an arbitrary -transformation to the postings. +Expressions}). Using @option{--amount @var{EXPR}} you can apply an +arbitrary transformation to the postings. @item --amount-data @itemx -j @@ -5510,7 +5708,7 @@ Print average values over the number of transactions instead of running totals. @item --balance-format @var{FORMAT_STRING} -Specify the format to use for the @code{balance} report (@pxref{Format +Specify the format to use for the @command{balance} report (@pxref{Format Strings}). The default is: @smallexample @@ -5527,7 +5725,7 @@ FIX THIS ENTRY @c ASK JOHN @item --basis @itemx -B @itemx --cost -Report the cost basis on all posting +Report the cost basis on all posting. @item --begin @var{DATE} Specify the start @var{DATE} of all calculations. Transactions before @@ -5543,7 +5741,7 @@ $ ledger reg Expenses --begin Dec --bold-if "amount > 100" @noindent list all transactions since the beginning of December and bold any -posting greater than $100 +posting greater than $100. @item --budget Only display budgeted items. In a register report this @@ -5551,7 +5749,7 @@ displays transaction in the budget, in a balance report this displays accounts in the budget (@pxref{Budgeting and Forecasting}). @item --budget-format @var{FORMAT_STRING} -Specify the format to use for the @code{budget} report (@pxref{Format +Specify the format to use for the @command{budget} report (@pxref{Format Strings}). The default is: @smallexample @@ -5568,12 +5766,12 @@ Group the register report by payee. @item --cleared @itemx -C -Consider only transaction that have been cleared for -display and calculation. +Consider only transaction that have been cleared for display and +calculation. @item --cleared-format @var{FORMAT_STRING} FIX THIS ENTRY @c FIXME thdox: to keep? -Specify the format to use for the @code{cleared} report (@pxref{Format +Specify the format to use for the @command{cleared} report (@pxref{Format Strings}). The default is: @smallexample @@ -5591,11 +5789,10 @@ Strings}). The default is: @item --collapse @itemx -n By default ledger prints all account in an account tree. With -@code{--collapse} it print only the top level account specified. +@option{--collapse} it print only the top level account specified. @item --collapse-if-zero -Collapse the account display only if it has -a zero balance. +Collapse the account display only if it has a zero balance. @item --color @itemx --ansi @@ -5605,11 +5802,11 @@ Use color is the tty supports it. Specify the width of the @command{register} report in characters. @item --count -Direct ledger to report the number of items when -appended to the commodities, accounts or payees command. +Direct ledger to report the number of items when appended to the +commodities, accounts or payees command. @item --csv-format @var{FORMAT_STRING} -Specify the format to use for the @code{csv} report (@pxref{Format +Specify the format to use for the @command{csv} report (@pxref{Format Strings}). The default is: @smallexample @@ -5624,11 +5821,11 @@ Strings}). The default is: @end smallexample @item --current -Shorthand for @code{--limit "date <= today"} +Shorthand for @samp{--limit "date <= today"}. @item --daily @itemx -D -Shorthand for @code{--period "daily"} +Shorthand for @samp{--period "daily"}. @item --date @var{EXPR} Transform the date of the transaction using @var{EXPR}. @@ -5647,7 +5844,7 @@ FIX THIS ENTRY @c ASK JOHN @item --dc Display register or balance in debit/credit format If you use -@code{--dc} with either the register (reg) or balance (bal) commands, +@option{--dc} with either the register (reg) or balance (bal) commands, you will now get extra columns. The register goes from this: @smallexample @@ -5682,7 +5879,7 @@ Where the first column is debits, the second is credits, and the third is the running total. Only the running total may contain negative values. -For the balance report without @code{--dc}: +For the balance report without @option{--dc}: @smallexample $70 Assets:Cash @@ -5693,7 +5890,7 @@ For the balance report without @code{--dc}: @end smallexample @noindent -And with @code{--dc} it becomes this: +And with @option{--dc} it becomes this: @smallexample $105 $35 $70 Assets:Cash @@ -5704,15 +5901,15 @@ And with @code{--dc} it becomes this: @end smallexample @item --depth @var{INT} -Limit the depth of the account tree. In a balance report, for -example, a @code{--depth 2} statement will print balances only for -account with two levels, i.e. @code{Expenses:Entertainment} but not -@code{Expenses:entertainemnt:Dining}. This is a display predicate, -which means it only affects display, not the total calculations. +Limit the depth of the account tree. In a balance report, for example, +a @samp{--depth 2} statement will print balances only for account with +two levels, i.e. @samp{Expenses:Entertainment} but not +@samp{Expenses:entertainemnt:Dining}. This is a display predicate, which +means it only affects display, not the total calculations. @item --deviation -Report each posting’s deviation from the average. It is only -meaningful in the register and prices reports. +Report each posting’s deviation from the average. It is only meaningful +in the register and prices reports. @item --display @var{EXPR} Display lines that satisfy the expression given. @@ -5745,9 +5942,9 @@ Specify the end @var{DATE} for transaction to be considered in the report. @item --equity -Related to the @code{equity} command (@pxref{The -equity Command}). Gives current account balances in the form of a -register report. +Related to the @command{equity} command (@pxref{The @command{equity} +command}). Gives current account balances in the form of a register +report. @item --exact FIX THIS ENTRY @c ASK JOHN @@ -5796,8 +5993,8 @@ or @code{commodity}. The @code{tags()} function is also useful here. @item --group-title-format @var{FORMAT_STRING} Set the format for the headers that separate reports section of -a grouped report. Only has effect with a @code{--group-by} register -report. +a grouped report. Only has effect with a @option{--group-by @var{EXPR}} +register report. @smallexample $ ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n" @@ -5814,7 +6011,8 @@ $ ledger reg Expenses --group-by "payee" --group-title-format "----------------- @item --head @var{INT} @itemx --first @var{INT} -Print the first @var{INT} entries. Opposite of @code{--tail}. +Print the first @var{INT} entries. Opposite of @option{--tail +@var{INT}}. @item --historical @itemx -H @@ -5873,30 +6071,30 @@ In the register report, prepend the transaction with the value of the given @var{TAG}. @item --meta-width @var{INT} -Specify the width of the Meta column used for the @code{--meta} -options. +Specify the width of the Meta column used for the @option{--meta +@var{TAG}} options. @item --monthly @itemx -M -Synonym for @code{--period "monthly"} +Synonym for @samp{--period "monthly"}. @item --no-color -suppress any color TTY output. +Suppress any color TTY output. @item --no-rounding -Don't output <Rounding> postings. Note that this will cause the -running total to often not add up! It's main use is for @code{-j} and -@code{-J} reports. +Don't output @samp{<Rounding>} postings. Note that this will cause the +running total to often not add up! It's main use is for +@option{--amount-data (-j)} and @option{--total-data (-J)} reports. @item --no-titles -Suppress the output of group titles +Suppress the output of group titles. @item --no-total Suppress printing the final total line in a balance report. @item --now @var{DATE} Define the current date in case to you to do calculate in the past or -future using @code{--current} +future using @option{--current}. @item --only @var{FIXME} This is a postings predicate that applies after certain transforms have @@ -5918,7 +6116,7 @@ Set the number of columns dedicated to the payee in the register report. @item --pending -Use only postings that are marked pending +Use only postings that are marked pending. @item --percent @itemx -% @@ -5933,11 +6131,11 @@ For a balance report only those transactions will be accounted in the final balances. @item --pivot @var{TAG} -Produce a balance pivot report ``around'' the given @var{TAG}. For +Produce a balance pivot report @emph{around} the given @var{TAG}. For example, if you have multiple cars and track each fuel purchase in -@code{Expenses:Auto:Fuel} and tag each fuel purchase with a tag -identifying which car the purchase was for @code{; Car: Prius}, then -the command: +@samp{Expenses:Auto:Fuel} and tag each fuel purchase with a tag +identifying which car the purchase was for @samp{; Car: Prius}, then the +command: @smallexample $ ledger bal Fuel --pivot "Car" --period "this year" @@ -5962,7 +6160,7 @@ Define the output format for a total data plot. @xref{Visualizing with Gnuplot}. @item --prepend-format @var{FORMAT_STRING} -Prepend @var{STR} to every line of the output +Prepend @var{STR} to every line of the output. @item --prepend-width @var{INT} Reserve @var{INT} spaces at the beginning of each line of the output. @@ -5986,7 +6184,7 @@ Show primary dates for all calculations (@pxref{Effective Dates}). FIX THIS ENTRY @item --quarterly -Synonym for @code{--period "quarterly"}. +Synonym for @samp{--period "quarterly"}. @item --raw In the print report, show transactions using the exact same syntax as @@ -6004,11 +6202,11 @@ FIX THIS ENTRY @c FIXME thdox @item --related In a register report show the related account. This is the other -``side'' of the transaction. +@emph{side} of the transaction. @item --related-all -Show all postings in a transaction, similar to @code{--related} but -show both ``sides'' of each transaction. +Show all postings in a transaction, similar to @option{--related} but +show both @emph{sides} of each transaction. @item --revalued FIX THIS ENTRY @@ -6040,7 +6238,7 @@ Sort the posting within transactions using the given value expression. @item --start-of-week @var{INT} Tell ledger to use a particular day of the week to start its ``weekly'' -summary. @code{--start-of-week=1} specifies Monday as the start of the +summary. @samp{--start-of-week=1} specifies Monday as the start of the week. @item --subtotal @@ -6101,26 +6299,27 @@ FIX THIS ENTRY @c FIXME thdox @item --weekly @itemx -W -Synonym for @code{--period "weekly"} +Synonym for @samp{--period "weekly"}. @item --wide -Let the register report use 132 columns. Identical to @code{--columns -"132"} +Let the register report use 132 columns. Identical to @samp{--columns +"132"}. @item --yearly @itemx -Y -Synonym for @code{--period "yearly"} +Synonym for @samp{--period "yearly"}. @end ftable -@node Basic options, Report Filtering, Report Options, Detailed Options Description +@node Basic options, Report filtering, Report Options, Detailed Option Description @subsection Basic options These are the most basic command options. Most likely, the user will want to set them using environment variables (see @ref{Environment -Variables}), instead of using actual command-line options: +variables}), instead of using actual command-line options: @ftable @code + @item --help @itemx -h Print a summary of all the options, and what they are used for. This @@ -6166,15 +6365,17 @@ precedence over settings in the init file. @itemx -a @var{STR} Specify the default account which QIF file postings are assumed to relate to. + @end ftable -@node Report Filtering, Output Customization, Basic options, Detailed Options Description +@node Report filtering, Output customization, Basic options, Detailed Option Description @subsection Report filtering These options change which postings affect the outcome of a report, in ways other than just using regular expressions: @ftable @code + @item --current @itemx -c Display only transactions occurring on or before the current date. @@ -6185,7 +6386,7 @@ Constrain the report to transactions on or after @var{DATE}. Only transactions after that date will be calculated, which means that the running total in the balance report will always start at zero with the first matching transaction. (Note: This is different from using -@code{--display} to constrain what is displayed). +@option{--display @var{EXPR}} to constrain what is displayed). @item --end @var{DATE} @itemx -e @var{DATE} @@ -6198,7 +6399,7 @@ Set the reporting period to @var{STR}. This will subtotal all matching transactions within each period separately, making it easy to see weekly, monthly, quarterly, etc., posting totals. A period string can even specify the beginning and end of the report range, using simple -terms like ``last June'' or ``next month''. For more using period +terms like @samp{last June} or @samp{next month}. For more using period expressions, see @ref{Period Expressions}. @item --period-sort @var{VEXPR} @@ -6264,10 +6465,10 @@ posting that matched: @item --budget Useful for displaying how close your postings meet your budget. -@code{--add-budget} also shows un-budgeted postings, while -@code{--unbudgeted} shows only those. @code{--forecast} is a related -option that projects your budget into the future, showing how it will -affect future balances. @xref{Budgeting and Forecasting}. +@option{--add-budget} also shows un-budgeted postings, while +@option{--unbudgeted} shows only those. @option{--forecast @var{VEXPR}} +is a related option that projects your budget into the future, showing +how it will affect future balances. @xref{Budgeting and Forecasting}. @item --limit @var{EXPR} @itemx -l @var{EXPR} @@ -6284,6 +6485,7 @@ totals in the @command{balance} report, and the values printed in the @itemx -T @var{VEXPR} Set the value expression used for the ``totals'' column in the @command{register} and @command{balance} reports. + @end ftable @c @node Search Terms, Output Customization, Report Filtering, Detailed Options Description @@ -6330,13 +6532,14 @@ Set the value expression used for the ``totals'' column in the @c ledger reg food not dining expr 'payee =~ /chang/' @c @end smallexample -@node Output Customization, Commodity Reporting, Report Filtering, Detailed Options Description -@subsection Output Customization +@node Output customization, Commodity reporting, Report filtering, Detailed Option Description +@subsection Output customization These options affect only the output, but not which postings are used to create it: @ftable @code + @item --collapse @itemx -n Cause transactions in a @command{register} report with multiple @@ -6359,15 +6562,16 @@ Include even empty accounts in the @command{balance} report. @itemx -W Report posting totals by the week. The week begins on whichever day of the week begins the month containing that posting. To set a specific -begin date, use a period string, such as @code{weekly from DATE}. +begin date, use a period string, such as @samp{weekly from DATE}. @item --monthly @itemx -M -Report posting totals by month; +Report posting totals by month. @item --yearly @itemx -Y Report posting totals by year. For more complex period, using the +@c TODO end this sentence @item --period @var{PERIOD_EXPRESSION} Option described above. @@ -6379,10 +6583,10 @@ to see if weekend spending is more than on weekdays. @item --sort @var{VEXPR} @itemx -S @var{VEXPR} Sort a report by comparing the values determined using the value -expression @var{VEXPR}. For example, using @code{-S -UT} in the -balance report will sort account balances from greatest to least, using -the absolute value of the total. For more on how to use value -expressions, see @ref{Value Expressions}. +expression @var{VEXPR}. For example, using @samp{-S -UT} in the balance +report will sort account balances from greatest to least, using the +absolute value of the total. For more on how to use value expressions, +see @ref{Value Expressions}. @item --pivot @var{TAG} Produce a pivot table around the @var{TAG} provided. This requires @@ -6395,8 +6599,8 @@ instead of 80. @item --head @var{INT} Cause only the first @var{INT} transactions to be printed. This is -different from using the command-line utility @command{head}, which -would limit to the first @var{INT} postings. @code{--tail} outputs +different from using the command-line utility @file{head}, which would +limit to the first @var{INT} postings. @option{--tail @var{INT}} outputs only the last @var{INT} transactions. Both options may be used simultaneously. If a negative amount is given, it will invert the meaning of the flag (instead of the first five transactions being @@ -6413,15 +6617,15 @@ Report the average posting value. @item --deviation @itemx -D -Report each posting's deviation from the average. It is only -meaningful in the @command{register} and @command{prices} reports. +Report each posting's deviation from the average. It is only meaningful +in the @command{register} and @command{prices} reports. @item --percent @itemx -% -Show account subtotals in the @command{balance} report as percentages -of the parent account. +Show account subtotals in the @command{balance} report as percentages of +the parent account. -@c @code{--totals} include running total information in the +@c @option{--totals} include running total information in the @c @command{xml} report. @item --amount-data @@ -6458,15 +6662,16 @@ $ ledger -p "last month" reg checking @end smallexample Which is more useful depends on what you're looking to know: the total -amount for the reporting range (@code{-p}), or simply a display -restricted to the reporting range (using @code{-d}). +amount for the reporting range (using @option{--period +@var{PERIOD_EXPRESSION} (-p)}), or simply a display restricted to the +reporting range (using @option{--display @var{EXPR} (-d)}). @item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} Change the basic date format used by reports. The default uses a date -like @code{2004/08/01}, which represents the default date format of +like @samp{2004/08/01}, which represents the default date format of @code{%Y/%m/%d}. To change the way dates are printed in general, the -easiest way is to put @code{--date-format @var{DATE_FORMAT}} in the +easiest way is to put @option{--date-format @var{DATE_FORMAT}} in the Ledger initialization file @file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). @@ -6477,8 +6682,8 @@ Set the reporting format for whatever report ledger is about to make. each report type: @item --balance-format @var{FORMAT_STRING} -Define the output format for the @code{balance} report. The default -(defined in @code{report.h} is: +Define the output format for the @command{balance} report. The default +(defined in @file{report.h} is: @smallexample "%(ansify_if( @@ -6510,8 +6715,8 @@ Define the format for the cleared report. The default is: @end smallexample @item --register-format @var{FORMAT_STRING} -Define the output format for the @code{register} report. The default -(defined in @code{report.h} is: +Define the output format for the @command{register} report. The default +(defined in @file{report.h} is: @smallexample "%(ansify_if( @@ -6548,7 +6753,7 @@ Define the output format for the @code{register} report. The default @end smallexample @item --csv-format @var{FORMAT_STRING} -Set the format for @code{csv} reports. The default is: +Set the format for @command{csv} reports. The default is: @smallexample "%(quoted(date)), @@ -6562,23 +6767,23 @@ Set the format for @code{csv} reports. The default is: @end smallexample @item --plot-amount-format @var{FORMAT_STRING} -Set the format for amount plots, using the @code{-j} option. The -default is: +Set the format for amount plots, using the @option{--amount-data (-j)} +option. The default is: @smallexample "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n" @end smallexample @item --plot-total-format @var{FORMAT_STRING} -Set the format for total plots, using the @code{-J} option. The -default is: +Set the format for total plots, using the @option{--total-data (-J)} +option. The default is: @smallexample "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n" @end smallexample @item --pricedb-format @var{FORMAT_STRING} -Set the format expected for the historical price file. The default is +Set the format expected for the historical price file. The default is: @smallexample "P %(datetime) %(display_account) %(scrub(display_amount))\n" @@ -6591,14 +6796,16 @@ Set the format for the @command{prices} report. The default is: "%(date) %-8(display_account) %(justify(scrub(display_amount), 12, 2 + 9 + 8 + 12, true, color))\n" @end smallexample + @end ftable -@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description -@subsection Commodity Reporting +@node Commodity reporting, Environment variables, Output customization, Detailed Option Description +@subsection Commodity reporting These options affect how commodity values are displayed: @ftable @code + @item --price-db @var{FILE} Set the file that is used for recording downloaded commodity prices. It is always read on startup, to determine historical prices. Other @@ -6618,37 +6825,40 @@ updating the price-db file. The best way is to have your price download script maintain this file. The format of the file can be changed by telling ledger to use the -@code{--pricedb-format @var{FORMAT_STRING}} you define. +@option{--pricedb-format @var{FORMAT_STRING}} you define. @item --price-exp @var{INT} -@itemx -L @var{INT} +@itemx -Z @var{INT} Set the expected freshness of price quotes, in @var{INT} minutes. That -is, if the last known quote for any commodity is older than this -value, and if @code{--download} is being used, then the Internet will -be consulted again for a newer price. Otherwise, the old price is -still considered to be fresh enough. +is, if the last known quote for any commodity is older than this value, +and if @option{--download} is being used, then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. @item --download @itemx -Q -Cause quotes to be automagically downloaded, as needed, by running a -script named @command{getquote} and expecting that script to return a -value understood by ledger. A sample implementation of a -@command{getquote} script, implemented in Perl, is provided in the +Cause quotes to be automagically downloaded, as needed, by running +a script named @file{getquote} and expecting that script to return +a value understood by ledger. A sample implementation of +a @file{getquote} script, implemented in Perl, is provided in the distribution. Downloaded quote price are then appended to the price database, usually specified using the environment variable @env{LEDGER_PRICE_DB}. + @end ftable There are several different ways that ledger can report the totals it displays. The most flexible way to adjust them is by using value -expressions, and the @code{-t} and @code{-T} options. However, -there are also several ``default'' reports, which will satisfy most -users basic reporting needs: +expressions, and the @option{--amount @var{EXPR} (-t)} and +@option{--total @var{VEXPR} (-T)} options. However, there are also +several ``default'' reports, which will satisfy most users basic +reporting needs: @ftable @code + @item --quantity @itemx -O -Report commodity totals (this is the default) +Report commodity totals (this is the default). @item --basis @itemx -B @@ -6662,6 +6872,7 @@ Use the last known value for commodities to calculate final values. @itemx -G Report the net gain/loss for all commodities in the report that have a price history. + @end ftable Often you will be more interested in the value of your entire holdings, @@ -6673,16 +6884,18 @@ the accounts involved, the commodities, the nature of the transactions, etc. @findex --now @var{DATE} +@findex --market +@findex --exchange @var{COMMODITY} -When you specify @code{-V}, or @code{-X @var{COMMODITY}}, you are -requesting that some or all of the commodities be valuated as of today -(or whatever @code{--now @var{DATE}} is set to). But what does such -a valuation mean? This meaning is governed by the presence of -a @code{VALUE} meta-data property, whose content is an expression used -to compute that value. +When you specify @option{--market (-V)}, or @option{--exchange +@var{COMMODITY} (-X)}, you are requesting that some or all of the +commodities be valuated as of today (or whatever @option{--now +@var{DATE}} is set to). But what does such a valuation mean? This +meaning is governed by the presence of a @var{VALUE} meta-data property, +whose content is an expression used to compute that value. -If no VALUE property is specified, each posting is assumed to have a -default, as if you'd specified a global, automated transaction as +If no @var{VALUE} property is specified, each posting is assumed to have +a default, as if you'd specified a global, automated transaction as follows: @smallexample @@ -6690,21 +6903,22 @@ follows: ; VALUE:: market(amount, date, exchange) @end smallexample -This definition emulates the present day behavior of @code{-V} and -@code{-X @var{COMMODITY}} (in the case of @code{-X}, the requested -commodity is passed via the string @samp{exchange} above). +This definition emulates the present day behavior of @option{--market +(-V)} and @option{--exchange @var{COMMODITY} (-X)} (in the case of +@samp{-X}, the requested commodity is passed via the string +@samp{exchange} above). @cindex Euro conversion One thing many people have wanted to do is to fixate the valuation of old European currencies in terms of the Euro after a certain date: @smallexample - = expr commodity == "DM" += expr commodity == "DM" ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR @end smallexample -This says: If @code{--now @var{DATE}} is some old date, use market -prices as they were at that time; but if @code{--now @var{DATE}} is +This says: If @option{--now @var{DATE}} is some old date, use market +prices as they were at that time; but if @option{--now @var{DATE}} is past June 2008, use a fixed price for converting Deutsch Mark to Euro. Or how about never re-valuating commodities used in Expenses, since @@ -6717,7 +6931,7 @@ they cannot have a different future value: This says the future valuation is the same as the valuation at the time of posting. post.date equals the posting's date, while just 'date' is -the value of @code{--now @var{DATE}} (defaults to today). +the value of @option{--now @var{DATE}} (defaults to today). Or how about valuating miles based on a reimbursement rate during a specific time period: @@ -6766,44 +6980,56 @@ valuated in another currency. For example: @cindex FIFO/LIFO @cindex LIFO/FIFO @findex --lots +@findex --lot-prices +@findex --exchange @var{COMMODITY} +@findex --historical +@findex --basis +@findex --price + Ledger presently has no way of handling such things as FIFO and LIFO. If you specify an unadorned commodity name, like AAPL, it will balance -against itself. If @code{--lots} are not being displayed, then it will -appear to balance against any lot of AAPL. +against itself. If @option{--lots} are not being displayed, then it +will appear to balance against any lot of AAPL. @cindex adorned commodity @findex --lot-prices -If you specify an adorned commodity, like AAPL @{$10.00@}, it will -also balance against itself, and against any AAPL if @code{--lots} is -not specified. But if you do specify @code{--lot-prices}, for -example, then it will balance against that specific price for AAPL. +If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +balance against itself, and against any AAPL if @option{--lots} is not +specified. But if you do specify @option{--lot-prices}, for example, +then it will balance against that specific price for AAPL. + +Normally when you use @option{--exchange @var{COMMODITY} (-X)} to +request that amounts be reported in a specific commodity, Ledger uses +these values: -Normally when you use @code{-X @var{COMMODITY}} to request that -amounts be reported in a specific commodity, Ledger uses these values: @itemize @item Register Report -For the register report, use the value of that commodity on the date -of the posting being reported, with a <Revalued> posting added at the -end of today's value is different from the value of the last posting. +For the register report, use the value of that commodity on the date of +the posting being reported, with a @samp{<Revalued>} posting added at +the end of today's value is different from the value of the last +posting. @item Balance Report For the balance report, use the value of that commodity as of today. + @end itemize -You can now specify @code{-H} to ask that all valuations for any -amount be done relative to the date that amount was encountered. +You can now specify @option{--historical (-H)} to ask that all +valuations for any amount be done relative to the date that amount was +encountered. -You can also now use @code{-X @var{COMMODITY}} (and @code{-H}) in -conjunction with @code{-B} and @code{-I}, to see valuation reports of -just your basis costs or lot prices. +You can also now use @option{--exchange @var{COMMODITY} (-X)} (and +@option{--historical (-H)}) in conjunction with @option{--basis (-B)} +and @option{--price (-I)}, to see valuation reports of just your basis +costs or lot prices. -@node Environment Variables, , Commodity Reporting, Detailed Options Description +@node Environment variables, , Commodity reporting, Detailed Option Description @subsection Environment variables Every option to ledger may be set using an environment variable. If -an option has a long name such @code{--this-option}, setting the +an option has a long name such @option{--this-option}, setting the environment variable @env{LEDGER_THIS_OPTION} will have the same effect as specifying that option on the command-line. Options on the command-line always take precedence over environment variable @@ -6816,8 +7042,9 @@ option settings in the file @file{~/.ledgerrc}, for example: --pager /bin/cat @end smallexample -@node Period Expressions, , Detailed Options Description, Command-line Syntax +@node Period Expressions, , Detailed Option Description, Command-line Syntax @section Period Expressions +@c TODO use @var below A period expression indicates a span of time, or a reporting interval, or both. The full syntax is: @@ -6879,7 +7106,7 @@ last week The beginning and ending can be given at the same time, if it spans a single period. In that case, just use @var{SPEC} by itself. In that -case, the period @code{oct}, for example, will cover all the days in +case, the period @samp{oct}, for example, will cover all the days in October. The possible forms are: @smallexample @@ -6916,6 +7143,7 @@ weekly last august @findex --budget @findex --add-budget @findex --unbudgeted +@findex --monthly Keeping a budget allows you to pay closer attention to your income and expenses, by reporting how far your actual financial activity is from @@ -6954,9 +7182,9 @@ $ ledger -p "this year" --monthly --average --subtotal balance ^expenses The reported totals are the current year's average for each account. -Once these period transactions are defined, creating a budget report -is as easy as adding @code{--budget} to the command-line. For -example, a typical monthly expense report would be: +Once these period transactions are defined, creating a budget report is +as easy as adding @option{--budget} to the command-line. For example, +a typical monthly expense report would be: @smallexample $ ledger --monthly register ^expenses @@ -6968,10 +7196,10 @@ To see the same report balanced against your budget, use: $ ledger --budget --monthly register ^expenses @end smallexample -A budget report includes only those accounts that appear in the -budget. To see all expenses balanced against the budget, use -@code{--add-budget}. You can even see only the un-budgeted expenses -using @code{--unbudgeted}: +A budget report includes only those accounts that appear in the budget. +To see all expenses balanced against the budget, use +@option{--add-budget}. You can even see only the un-budgeted expenses +using @option{--unbudgeted}: @smallexample $ ledger --unbudgeted --monthly register ^expenses @@ -6981,7 +7209,7 @@ You can also use these flags with the @command{balance} command. @node Forecasting, , Budgeting, Budgeting and Forecasting @section Forecasting -@findex --forecast +@findex --forecast @var{VEXPR} Sometimes it's useful to know what your finances will look like in the future, such as determining when an account will reach zero. Ledger @@ -7005,6 +7233,7 @@ $ ledger --forecast "d<[2010]" bal ^assets ^liabilities @node Time Keeping, Value Expressions, Budgeting and Forecasting, Top @chapter Time Keeping +@findex --day-break Ledger directly supports ``timelog'' entries, which have this form: @@ -7013,13 +7242,13 @@ i 2013/03/28 22:13:00 ACCOUNT[ PAYEE] o 2013/03/29 03:39:00 @end smallexample -This records a check-in to the given ACCOUNT, and a check-out. You -can be checked-in to multiple accounts at a time, if you wish, and -they can span multiple days (use @code{--day-break} to break them up -in the report). The number of seconds between is accumulated as time -to that ACCOUNT. If the checkout uses a capital @samp{O}, the -transaction is marked ``cleared''. You can use an optional PAYEE for -whatever meaning you like. +This records a check-in to the given ACCOUNT, and a check-out. You can +be checked-in to multiple accounts at a time, if you wish, and they can +span multiple days (use @option{--day-break} to break them up in the +report). The number of seconds between is accumulated as time to that +ACCOUNT. If the checkout uses a capital @samp{O}, the transaction is +marked ``cleared''. You can use an optional PAYEE for whatever meaning +you like. Now, there are a few ways to generate this information. You can use the @file{timeclock.el} package, which is part of Emacs. Or you can @@ -7034,20 +7263,28 @@ transactions are. @node Value Expressions, Format Strings, Time Keeping, Top @chapter Value Expressions +@findex --limit @var{EXPR} +@findex --display @var{EXPR} Ledger uses value expressions to make calculations for many different purposes: @enumerate + @item -The values displayed in reports +The values displayed in reports. + @item For predicates (where truth is anything non-zero), to determine which -postings are calculated (@code{-l}) or displayed (@code{-d}). +postings are calculated (option @option{--limit @var{EXPR} (-l)}) or +displayed (option @option{--display @var{EXPR} (-d)}). + @item For sorting criteria, to yield the sort key. + @item In the matching criteria used by automated postings. + @end enumerate Value expressions support most simple math and logic operators, in @@ -7088,11 +7325,13 @@ $ ledger -b "this month" register checking * Variables:: * Functions:: * Operators:: -* Complex Expressions:: +* Complex expressions:: @end menu @node Variables, Functions, Value Expressions, Value Expressions @section Variables +@findex --amount @var{EXPR} +@findex --total @var{VEXPR} Below are the one letter variables available in any value expression. For the register and print commands, these variables relate to @@ -7102,20 +7341,24 @@ accounts, often with a subtle difference in meaning. The use of each variable for both is specified. @table @code + @item t -This maps to whatever the user specified with @code{-t}. In a -register report, @code{-t} changes the value column; in a balance -report, it has no meaning by default. If @code{-t} was not -specified, the current report style's value expression is used. +This maps to whatever the user specified with @option{--amount +@var{EXPR} (-t)}. In a register report, @option{--amount @var{EXPR} +(-t)} changes the value column; in a balance report, it has no meaning +by default. If @option{--amount @var{EXPR} (-t)} was not specified, the +current report style's value expression is used. @item T -This maps to whatever the user specified with @code{-T}. In a -register report, @code{-T} changes the totals column; in a balance -report, this is the value given for each account. If @code{-T} was -not specified, the current report style's value expression is used. +This maps to whatever the user specified with @option{--total +@var{VEXPR} (-T)}. In a register report, @option{--total @var{VEXPR} +(-T)} changes the totals column; in a balance report, this is the value +given for each account. If @option{--total @var{VEXPR} (-T)} was not +specified, the current report style's value expression is used. @item m This is always the present moment/date. + @end table @menu @@ -7127,6 +7370,7 @@ This is always the present moment/date. @subsection Posting/account details @table @code + @item d A posting's date, as the number of seconds past the epoch. This is always ``today'' for an account. @@ -7162,12 +7406,14 @@ account. @item Z @samp{1} if a posting is not automated, @samp{0} otherwise. + @end table @node Calculated totals, , Posting/account details, Variables @subsection Calculated totals @table @code + @item O The total of all postings seen so far, or the total of an account and all its children. @@ -7188,6 +7434,7 @@ all its children. The total net gain (market value minus cost basis), for a series of postings, or an account and its children. It is the same as @samp{V-B}. + @end table @node Functions, Operators, Variables, Value Expressions @@ -7196,6 +7443,7 @@ postings, or an account and its children. It is the same as The available one letter functions are: @table @code + @item - Negates the argument. @@ -7213,9 +7461,10 @@ The arithmetic mean of the argument; @samp{Ax} is the same as The present market value of the argument. The syntax @samp{P(x,d)} is supported, which yields the market value at time @samp{d}. If no date is given, then the current moment is used. + @end table -@node Operators, Complex Expressions, Functions, Value Expressions +@node Operators, Complex expressions, Functions, Value Expressions @section Operators The binary and ternary operators, in order of precedence, are: @@ -7262,12 +7511,13 @@ The binary and ternary operators, in order of precedence, are: @code{CALL} @code{MATCH} -@node Complex Expressions, , Operators, Value Expressions +@node Complex expressions, , Operators, Value Expressions @section Complex expressions More complicated expressions are possible using: @table @code + @item NUM A plain integer represents a commodity-less amount. @@ -7306,14 +7556,15 @@ precedence order of operators. @item [DATE] Useful specifying a date in plain terms. For example, you could say -@code{[2004/06/01]}. +@samp{[2004/06/01]}. + @end table @menu -* Misc:: +* Miscellaneous:: @end menu -@node Misc, , Complex Expressions, Complex Expressions +@node Miscellaneous, , Complex expressions, Complex expressions @subsection Miscellaneous @table @code @@ -7323,7 +7574,8 @@ Useful specifying a date in plain terms. For example, you could say @item ceiling Return the next integer toward +infinity @item code -Return the transaction code, the string between the parenthesis after the date. +Return the transaction code, the string between the parenthesis after +the date. @item commodity @item date @item display_amount --> t @@ -7375,17 +7627,16 @@ Return value rounded to n digits. Does not affect formatting. @chapter Format Strings @menu -* Basics:: +* Format String Basics:: * Format String Structure:: * Format Expressions:: -* --balance-format:: -* Formatting codes:: +* Balance format:: +* Formatting Functions and Codes:: @end menu -@node Basics, Format String Structure, Format Strings, Format Strings +@node Format String Basics, Format String Structure, Format Strings, Format Strings @section Format String Basics @findex --format @var{FORMAT_STRING} -@findex -F @var{FORMAT_STRING} @findex --balance-format @var{FORMAT_STRING} @findex --budget-format @var{FORMAT_STRING} @findex --cleared-format @var{FORMAT_STRING} @@ -7396,11 +7647,11 @@ Return value rounded to n digits. Does not affect formatting. @findex --prices-format @var{FORMAT_STRING} @findex --register-format @var{FORMAT_STRING} -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the @code{-F -(--format)} option. Within that string, constructs are allowed which -make it possible to display the various parts of an account or posting -in custom ways. +Format strings may be used to change the output format of reports. They +are specified by passing a formatting string to the @option{--format +@var{FORMAT_STRING} (-F)} option. Within that string, constructs are +allowed which make it possible to display the various parts of an +account or posting in custom ways. There are several additional flags that allow you to define formats for specific reports. These are useful to define in your configuration @@ -7408,18 +7659,18 @@ file and will allow you to run ledger reports from the command line without having to enter a new format for each command. @itemize -@item @code{--balance-format} -@item @code{--budget-format} -@item @code{--cleared-format} -@item @code{--csv-format} -@item @code{--plot-amount-format} -@item @code{--plot-total-format} -@item @code{--pricedb-format} -@item @code{--prices-format} -@item @code{--register-format} +@item @option{--balance-format @var{FORMAT_STRING}} +@item @option{--budget-format @var{FORMAT_STRING}} +@item @option{--cleared-format @var{FORMAT_STRING}} +@item @option{--csv-format @var{FORMAT_STRING}} +@item @option{--plot-amount-format @var{FORMAT_STRING}} +@item @option{--plot-total-format @var{FORMAT_STRING}} +@item @option{--pricedb-format @var{FORMAT_STRING}} +@item @option{--prices-format @var{FORMAT_STRING}} +@item @option{--register-format @var{FORMAT_STRING}} @end itemize -@node Format String Structure, Format Expressions, Basics, Format Strings +@node Format String Structure, Format Expressions, Format String Basics, Format Strings @section Format String Structure Within a format string, a substitution is specified using a percent @@ -7437,47 +7688,54 @@ a maximum width is given, the substituted text will never be wider than this, and will be truncated to fit. Here are some examples: @table @code + @item %-20P A transaction's payee, left justified and padded to 20 characters wide. + @item %20P The same, right justified, at least 20 chars wide. + @item %.20P The same, no more than 20 chars wide. + @end table The expression following the format constraints can be a single letter, or an expression enclosed in parentheses or brackets. -@node Format Expressions, --balance-format, Format String Structure, Format Strings +@node Format Expressions, Balance format, Format String Structure, Format Strings @section Format Expressions +@findex --amount @var{EXPR} +@findex --total @var{VEXPR} The allowable expressions are: @table @code + @item % Inserts a percent sign. @item t -Inserts the results of the value expression specified by @code{-t}. -If @code{-t} was not specified, the current report style's value -expression is used. +Inserts the results of the value expression specified by +@option{--amount @var{EXPR} (-t)}. If @option{--amount @var{EXPR} (-t)} +was not specified, the current report style's value expression is used. @item T -Inserts the results of the value expression specified by @code{-T}. -If @code{-T} was not specified, the current report style's value -expression is used. +Inserts the results of the value expression specified by @option{--total +@var{VEXPR} (-T)}. If @option{--total @var{VEXPR} (-T)} was not +specified, the current report style's value expression is used. @item (EXPR) Inserts the amount resulting from the value expression given in parentheses. To insert five times the total value of an account, for -example, one could say @code{%12(5*O)}. Note: It's important to put the +example, one could say @samp{%12(5*O)}. Note: It's important to put the five first in that expression, so that the commodity doesn't get stripped from the total. @item [DATEFMT] Inserts the result of formatting a posting's date with a date format string, exactly like those supported by @code{strftime}. For -example: @code{%[%Y/%m/%d %H:%M:%S]}. +example: @samp{%[%Y/%m/%d %H:%M:%S]}. @item S Insert the pathname of the file from which the transaction's data was @@ -7497,10 +7755,10 @@ file. @item e Inserts the ending line of that transaction within the file. -@c @item D By default, this is the same as @code{%[%Y/%m%/d]}. The -@c date format used can be changed at any time with the @code{-y} -@c flag, however. Using @code{%D} gives the user more control over -@c the way dates are output. +@c @item D By default, this is the same as @code{%[%Y/%m%/d]}. The date +@c format used can be changed at any time with the @option{--date-format +@c @var{DATE_FORMAT} (-y)} flag, however. Using @code{%D} gives the +@c user more control over the way dates are output. @item d Returns the date according to the default format. If the transaction @@ -7550,16 +7808,17 @@ The @samp{%/} construct is special. It separates a format string between what is printed for the first posting of a transaction, and what is printed for all subsequent postings. If not used, the same format string is used for all postings. + @end table -@node --balance-format, Formatting codes, Format Expressions, Format Strings -@section --balance-format +@node Balance format, Formatting Functions and Codes, Format Expressions, Format Strings +@section Balance format @findex --balance-format @var{FORMAT_STRING} @findex --format @var{FORMAT_STRING} -As an example of how flexible the @code{--format @var{FORMAT_STRING}} -strings can be, the default balance format looks like this (the -various functions are described later): +As an example of how flexible the @option{--format @var{FORMAT_STRING}} +strings can be, the default balance format looks like this (the various +functions are described later): @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" @@ -7569,20 +7828,20 @@ various functions are described later): "--------------------\n" @end smallexample -@node Formatting codes, , --balance-format, Format Strings +@node Formatting Functions and Codes, , Balance format, Format Strings @section Formatting Functions and Codes @menu * Field Widths:: * Colors:: * Quantities and Calculations:: -* Dates:: +* Date Functions:: * Date and Time Format Codes:: * Text Formatting:: * Data File Parsing Information:: @end menu -@node Field Widths, Colors, Formatting codes, Formatting codes +@node Field Widths, Colors, Formatting Functions and Codes, Formatting Functions and Codes @subsection Field Widths The following codes return the width allocated for the specific fields. @@ -7597,7 +7856,7 @@ options: @item @code{total_width} @end itemize -@node Colors, Quantities and Calculations, Field Widths, Formatting codes +@node Colors, Quantities and Calculations, Field Widths, Formatting Functions and Codes @subsection Colors The character based formatting ledger can do is limited to the ANSI @@ -7610,7 +7869,7 @@ terminal character colors and font highlights in a normal TTY session. @item @code{blue} @tab @code{black} @end multitable -@node Quantities and Calculations, Dates, Colors, Formatting codes +@node Quantities and Calculations, Date Functions, Colors, Formatting Functions and Codes @subsection Quantities and Calculations @table @code @@ -7637,35 +7896,43 @@ terminal character colors and font highlights in a normal TTY session. @item unrounded @end table -@node Dates, Date and Time Format Codes, Quantities and Calculations, Formatting codes +@node Date Functions, Date and Time Format Codes, Quantities and Calculations, Formatting Functions and Codes @subsection Date Functions @findex --now @var{DATE} The following functions allow you to manipulate and format dates. @table @code + @item date -Return the date of the current transaction +Return the date of the current transaction. + @item format_date(date, "FORMAT_STRING") Format the date using the given format string. + @item now -Return the current date and time. If the @code{--now @var{DATE}} +Return the current date and time. If the @option{--now @var{DATE}} option is defined it will return that value. + @item today -Return the current date. If the @code{--now @var{DATE}} option is +Return the current date. If the @option{--now @var{DATE}} option is defined it will return that value. + @item to_datetime -Convert a string to a date-time value +Convert a string to a date-time value. + @item to_date -Convert a string to date value +Convert a string to date value. + @item value_date + @end table @menu * Date and Time Format Codes:: @end menu -@node Date and Time Format Codes, Text Formatting, Dates, Formatting codes +@node Date and Time Format Codes, Text Formatting, Date Functions, Formatting Functions and Codes @subsection Date and Time Format Codes Date and time format are specified as strings of single letter codes @@ -7686,21 +7953,23 @@ Dates are formed from a combination of day, month and year codes, in whatever order you prefer: @table @code + @item %Y -Four digit year +Four digit year. @item %y -Two digit year +Two digit year. @item %m -Two digit month +Two digit month. @item %d -Two digit date +Two digit date. + @end table @noindent -So @code{"%Y%m%d"} yields @code{20111214} which provides a date that +So @code{"%Y%m%d"} yields @samp{20111214} which provides a date that is simple to sort on. @node Weekdays, Month, Days, Date and Time Format Codes @@ -7710,31 +7979,41 @@ You can have additional weekday information in your date with @samp{%A} as @table @code + @item %m-%d-%Y %A -yields @code{02-10-2010 Wednesday} +yields @samp{02-10-2010 Wednesday}. @item %A %m-%d-%Y -yields @code{Wednesday 02-10-2010} +yields @samp{Wednesday 02-10-2010}. + @end table @noindent These are options you can select for weekday @table @code + @item %a -weekday, abbreviated Wed +weekday, abbreviated Wed. + @item %A -weekday, full Wednesday +weekday, full Wednesday. + @item %d -day of the month (dd), zero padded 10 +day of the month (dd), zero padded 10. + @item %e -day of the month (dd) 10 +day of the month (dd) 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 +day of week starting with Monday (1), i.e. @code{mtwtfss} 3. + @item %w -day of week starting with Sunday (0), i.e. @code{smtwtfs} 3 +day of week starting with Sunday (0), i.e. @code{smtwtfs} 3. + @end table @node Month, Miscellaneous Date Codes, Weekdays, Date and Time Format Codes @@ -7744,26 +8023,30 @@ You can have additional month information in your date with @samp{%B} as @table @code + @item %m-%d-%Y %B -yields @code{02-10-2010 February} +yields @samp{02-10-2010 February}. @item %B %m-%d-%Y -yields @code{February 02-10-2010} +yields @samp{February 02-10-2010}. + @end table @noindent These are options you can select for month @table @code + @item %m -@samp{mm} month as two digits +@samp{mm} month as two digits. @item %b Locale’s abbreviated month, for example @samp{02} might be abbreviated -as @samp{Feb} +as @samp{Feb}. @item %B -Locale’s full month, variable length February +Locale’s full month, variable length February. + @end table @node Miscellaneous Date Codes, , Month, Date and Time Format Codes @@ -7772,34 +8055,37 @@ Locale’s full month, variable length February Additional date format parameters which can be used: @table @code + @item %U -week number Sunday as first day of week 01–53 +week number Sunday as first day of week, ranging 01–53. + @item %W -week number Monday as first day of week 01–53 +week number Monday as first day of week, ranging 01–53. + @item %V -week of the year 01–53 +week of the year, ranging 01–53. + @item %C -@code{cc} century 00–99 +century, ranging 00–99. + @item %D -yields @code{mm/dd/yy 02/10/10} +yields @code{%m/%d/%y} as in @samp{02/10/10}. + @item %x -locale’s date representation @code{02/10/2010} for the U.S. +locale’s date representation, as @samp{02/10/2010} for the U.S. + @item %F -yields @code{%Y-%m-%d 2010-02-10} -@end table +yields @code{%Y-%m-%d} as in @samp{2010-02-10}. -@menu -* Text Formatting:: -* Data File Parsing Information:: -* Misc:: -@end menu +@end table -@node Text Formatting, Data File Parsing Information, Date and Time Format Codes, Formatting codes +@node Text Formatting, Data File Parsing Information, Date and Time Format Codes, Formatting Functions and Codes @subsection Text Formatting The following format functions allow you limited formatting of text: @table @code + @item ansify_if(value, color) Surrounds the string representing value with ANSI codes to give it @code{color} on an TTY display. Has no effect if directed to a file. @@ -7818,14 +8104,15 @@ justified and padded to the full width of the field. If Replaces line feeds in @code{STR} with @samp{\n}. @item quoted(STR) -Return @code{STR} surrounded by double quotes, @code{"STR"}. +Return @code{STR} surrounded by double quotes, @samp{"STR"}. @item strip(value) Values can have numerous annotations, such as effective dates and lot prices. @code{strip} removes these annotations. + @end table -@node Data File Parsing Information, , Text Formatting, Formatting codes +@node Data File Parsing Information, , Text Formatting, Formatting Functions and Codes @subsection Data File Parsing Information The following format strings provide locational metadata @@ -7833,20 +8120,26 @@ regarding the coordinates of entries in the source data file(s) that generated the posting. @table @code + @item filename -name of ledger data file from whence posting came, abbreviated @samp{S} +name of ledger data file from whence posting came, abbreviated @samp{S}. + @item beg_pos character position in @code{filename} where entry for posting begins, -abbreviated @samp{B} +abbreviated @samp{B}. + @item end_pos character position in @code{filename} where entry for posting ends, -abbreviated @samp{E} +abbreviated @samp{E}. + @item beg_line line number in @code{filename} where entry for posting begins, -abbreviated @samp{b} +abbreviated @samp{b}. + @item end_line line number in @code{filename} where posting's entry for posting ends, -abbreviated @samp{e} +abbreviated @samp{e}. + @end table @node Extending with Python, Ledger for Developers, Format Strings, Top @@ -7894,9 +8187,9 @@ for xact in ledger.read_journal("sample.dat").xacts: @node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python @section Raw vs. Cooked -Ledger data exists in one of two forms: raw and cooked. Raw objects -are what you get from a traversal like the above, and represent -exactly what was seen in the data file. Consider this journal: +Ledger data exists in one of two forms: raw and cooked. Raw objects are +what you get from a traversal like the above, and represent exactly what +was seen in the data file. Consider this journal: @smallexample = true @@ -7936,10 +8229,10 @@ for post in ledger.read_journal("sample.dat").query("food"): print "Transferring %s to/from %s" % (post.amount, post.account) @end smallexample -The reason why queries iterate over postings instead of transactions -is that queries often return only a ``slice'' of the transactions they +The reason why queries iterate over postings instead of transactions is +that queries often return only a ``slice'' of the transactions they apply to. You can always get at a matching posting's transaction by -looking at its ``xact'' member: +looking at its @code{xact} member: @smallexample last_xact = None @@ -7952,20 +8245,19 @@ for post in ledger.read_journal("sample.dat").query(""): @end smallexample This query ends up reporting every cooked posting in the Journal, but -does it transaction-wise. It relies on the fact that an unsorted -report returns postings in the exact order they were parsed from the -journal file. +does it transaction-wise. It relies on the fact that an unsorted report +returns postings in the exact order they were parsed from the journal +file. @node Queries, Embedded Python, Raw vs. Cooked, Extending with Python @section Queries -The Journal.query() method accepts every argument you can specify on -the command-line, including --options. +The Journal.query() method accepts every argument you can specify on the +command-line, including @option{--options}. -Since a query ``cooks'' the journal it applies to, only one query may -be active for that journal at a given time. Once the query object is -gone (after the for loop), then the data reverts back to its raw -state. +Since a query ``cooks'' the journal it applies to, only one query may be +active for that journal at a given time. Once the query object is gone +(after the for loop), then the data reverts back to its raw state. @node Embedded Python, Amounts, Queries, Extending with Python @section Embedded Python @@ -7988,8 +8280,8 @@ tag PATH Assets:Cash @end smallexample -Any Python functions you define this way become immediately available -as valexpr functions. +Any Python functions you define this way become immediately available as +valexpr functions. @node Amounts, , Embedded Python, Extending with Python @section Amounts @@ -8012,12 +8304,12 @@ print total @menu * Internal Design:: -* Journal File Format:: +* Journal File Format for Developers:: * Developer Commands:: * Ledger Development Environment:: @end menu -@node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers +@node Internal Design, Journal File Format for Developers, Ledger for Developers, Ledger for Developers @section Internal Design Ledger is developed as a tiered set of functionality, where lower tiers @@ -8029,90 +8321,91 @@ modularity. Those tiers are: @itemize + @item Utility code -There's lots of general utility in Ledger for doing time parsing, -using Boost.Regex, error handling, etc. It's all done in a way that -can be reused in other projects as needed. +There's lots of general utility in Ledger for doing time parsing, using +Boost.Regex, error handling, etc. It's all done in a way that can be +reused in other projects as needed. @item Commoditized Amounts (amount_t, commodity_t and friends) -An numerical abstraction combining multi-precision rational numbers -(via GMP) with commodities. These structures can be manipulated like -regular numbers in either C++ or Python (as Amount objects). +An numerical abstraction combining multi-precision rational numbers (via +GMP) with commodities. These structures can be manipulated like regular +numbers in either C++ or Python (as Amount objects). @item Commodity Pool -Commodities are all owned by a commodity pool, so that future parsing -of amounts can link to the same commodity and established a consistent +Commodities are all owned by a commodity pool, so that future parsing of +amounts can link to the same commodity and established a consistent price history and record of formatting details. @item Balances -Adds the concept of multiple amounts with varying commodities. -Supports simple arithmetic, and multiplication and division with -non-commoditized values. +Adds the concept of multiple amounts with varying commodities. Supports +simple arithmetic, and multiplication and division with non-commoditized +values. @item Price history -Amounts have prices, and these are kept in a data graph which the -amount code itself is only dimly aware of (there's three points of -access so an amount can query its revalued price on a given date). +Amounts have prices, and these are kept in a data graph which the amount +code itself is only dimly aware of (there's three points of access so an +amount can query its revalued price on a given date). @item Values Often the higher layers in Ledger don't care if something is an amount -or a balance, they just want to add stuff to it or print it. For -this, I created a type-erasure class, value_t/Value, into which many -things can be stuffed and then operated on. They can contain amounts, -balances, dates, strings, etc. If you try to apply an operation -between two values that makes no sense (like dividing an amount by -a balance), an error occurs at runtime, rather than at compile-time -(as would happen if you actually tried to divide an @code{amount_t} by +or a balance, they just want to add stuff to it or print it. For this, +I created a type-erasure class, value_t/Value, into which many things +can be stuffed and then operated on. They can contain amounts, +balances, dates, strings, etc. If you try to apply an operation between +two values that makes no sense (like dividing an amount by a balance), +an error occurs at runtime, rather than at compile-time (as would happen +if you actually tried to divide an @code{amount_t} by a @code{balance_t}). This is the core data type for the value expression language. @item Value expressions -The next layer up adds functions and operators around the Value -concept. This lets you apply transformations and tests to Values at -runtime without having to bake it into C++. The set of functions -available is defined by each object type in Ledger (posts, accounts, -transactions, etc.), though the core engine knows nothing about these. -At its base, it only knows how to apply operators to values, and how -to pass them to and receive them from functions. +The next layer up adds functions and operators around the Value concept. +This lets you apply transformations and tests to Values at runtime +without having to bake it into C++. The set of functions available is +defined by each object type in Ledger (posts, accounts, transactions, +etc.), though the core engine knows nothing about these. At its base, +it only knows how to apply operators to values, and how to pass them to +and receive them from functions. @item Query expressions Expressions can be onerous to type at the command-line, so there's a shorthand for reporting called ``query expressions''. These add no functionality of their own, but are purely translated from the input -string (cash) down to the corresponding value expression -@code{(account =~ /cash/)}. This is a convenience layer. +string (cash) down to the corresponding value expression @samp{(account +=~ /cash/)}. This is a convenience layer. @item Format strings Format strings let you interpolate value expressions into string, with the requirement that any interpolated value have a string -representation. Really all this does is calculate the value -expression in the current report context, call the resulting value's -@code{to_string()} method, and stuffs the result into the output -string. It also provides printf-like behavior, such as min/max width, -right/left justification, etc. +representation. Really all this does is calculate the value expression +in the current report context, call the resulting value's +@code{to_string()} method, and stuffs the result into the output string. +It also provides printf-like behavior, such as min/max width, right/left +justification, etc. @item Journal items -Next is a base type shared by anything that can appear in a journal: -an item_t. It contains details common to all such parsed entities, -like what file and line it was found on, etc. +Next is a base type shared by anything that can appear in a journal: an +item_t. It contains details common to all such parsed entities, like +what file and line it was found on, etc. @item Journal posts -The most numerous object found in a Journal, postings are a type of -item that contain an account, an amount, a cost, and metadata. There -are some other complications, like the account can be marked virtual, -the amount could be an expression, etc. +The most numerous object found in a Journal, postings are a type of item +that contain an account, an amount, a cost, and metadata. There are +some other complications, like the account can be marked virtual, the +amount could be an expression, etc. @item Journal transactions @@ -8124,8 +8417,8 @@ transaction is queried to see if it can provide it. @item Journal accounts Postings are also shared by accounts, though the actual memory is -managed by the transaction. Each account knows all the postings -within it, but contains relatively little information of its own. +managed by the transaction. Each account knows all the postings within +it, but contains relatively little information of its own. @item The Journal object @@ -8136,35 +8429,34 @@ querying ad reporting on your data. @item Textual journal parser There is a textual parser, wholly contained in textual.cc, which knows -how to parse text into journal objects, which then get ``finalized'' -and added to the journal. Finalization is the step that enforces the +how to parse text into journal objects, which then get ``finalized'' and +added to the journal. Finalization is the step that enforces the double-entry guarantee. @item Iterators -Every journal object is ``iterable'', and these iterators are defined -in iterators.h and iterators.cc. This iteration logic is kept out of -the basic journal objects themselves for the sake of modularity. +Every journal object is ``iterable'', and these iterators are defined in +iterators.h and iterators.cc. This iteration logic is kept out of the +basic journal objects themselves for the sake of modularity. @item Comparators -Another abstraction isolated to its own layer, this class -encapsulating the comparison of journal objects, based on whatever -value expression the user passed to @code{--sort}. +Another abstraction isolated to its own layer, this class encapsulating +the comparison of journal objects, based on whatever value expression +the user passed to @option{--sort @var{VEXPR}}. @item Temporaries -Many reports bring pseudo-journal objects into existence, like -postings which report totals in a @code{<Total>} account. These -objects are created and managed by a temporaries_t object, which gets -used in many places by the reporting filters. +Many reports bring pseudo-journal objects into existence, like postings +which report totals in a @samp{Total} account. These objects are +created and managed by a temporaries_t object, which gets used in many +places by the reporting filters. @item Option handling -There is an option handling subsystem used by many of the layers -further down. It makes it relatively easy for me to add new options, -and to have those option settings immediately accessible to value -expressions. +There is an option handling subsystem used by many of the layers further +down. It makes it relatively easy for me to add new options, and to +have those option settings immediately accessible to value expressions. @item Session objects @@ -8176,10 +8468,10 @@ a separate session. They are all owned by the global scope. @item Report objects Every time you create report output, a report object is created to -determine what you want to see. In the Ledger REPL, a new report -object is created every time a command is executed. In CLI mode, only -one report object ever comes into being, as Ledger immediately exits -after displaying the results. +determine what you want to see. In the Ledger REPL, a new report object +is created every time a command is executed. In CLI mode, only one +report object ever comes into being, as Ledger immediately exits after +displaying the results. @item Reporting filters @@ -8187,27 +8479,26 @@ The way Ledger generates data is this: it asks the session for the current journal, and then creates an iterator applied to that journal. The kind of iterator depends on the type of report. -This iterator is then walked, and every object yielded from the -iterator is passed to an ``item handler'', whose type is directly -related to the type of the iterator. +This iterator is then walked, and every object yielded from the iterator +is passed to an ``item handler'', whose type is directly related to the +type of the iterator. -There are many, many item handlers, which can be chained together. -Each one receives an item (post, account, xact, etc.), performs some -action on it, and then passes it down to the next handler in the -chain. There are filters which compute the running totals; that queue -and sort all the input items before playing them back out in a new -order; that filter out items which fail to match a predicate, etc. -Almost every reporting feature in Ledger is related to one or more -filters. Looking at @code{filters.h}, I see over 25 of them defined -currently. +There are many, many item handlers, which can be chained together. Each +one receives an item (post, account, xact, etc.), performs some action +on it, and then passes it down to the next handler in the chain. There +are filters which compute the running totals; that queue and sort all +the input items before playing them back out in a new order; that filter +out items which fail to match a predicate, etc. Almost every reporting +feature in Ledger is related to one or more filters. Looking at +@file{filters.h}, I see over 25 of them defined currently. @item The filter chain -How filters get wired up, and in what order, is a complex process -based on all the various options specified by the user. This is the -job of the chain logic, found entirely in @code{chain.cc}. It took -a really long time to get this logic exactly write, which is why -I haven't exposed this layer to the Python bridge yet. +How filters get wired up, and in what order, is a complex process based +on all the various options specified by the user. This is the job of +the chain logic, found entirely in @file{chain.cc}. It took a really +long time to get this logic exactly right, which is why I haven't +exposed this layer to the Python bridge yet. @item Output modules @@ -8215,16 +8506,16 @@ Although filters are great and all, in the end you want to see stuff. This is the job of special ``leaf'' filters call output modules. They are implemented just like a regular filter, but they don't have a ``next'' filter to pass the time on down to. Instead, they are the -end of the line and must do something with the item that results in -the user seeing something on their screen or in a file. +end of the line and must do something with the item that results in the +user seeing something on their screen or in a file. @item Select queries Select queries know a lot about everything, even though they implement their logic by implementing the user's query in terms of all the other -features thus presented. Select queries have no functionality of -their own, they are simple a shorthand to provide access to much of -Ledger's functionality via a cleaner, more consistent syntax. +features thus presented. Select queries have no functionality of their +own, they are simple a shorthand to provide access to much of Ledger's +functionality via a cleaner, more consistent syntax. @item The Global Scope @@ -8236,8 +8527,9 @@ Application object. @item The Main Driver This creates the global scope object, performs error reporting, and -handles command-line options which must precede even the creation of -the global scope, such as @code{--debug}. +handles command-line options which must precede even the creation of the +global scope, such as @option{--debug @var{CODE}}. + @end itemize And that's Ledger in a nutshell. All the rest are details, such as @@ -8245,13 +8537,13 @@ which value expressions each journal item exposes, how many filters currently exist, which options the report and session scopes define, etc. -@node Journal File Format, Developer Commands, Internal Design, Ledger for Developers +@node Journal File Format for Developers, Developer Commands, Internal Design, Ledger for Developers @section Journal File Format for Developers This chapter offers a complete description of the journal data format, -suitable for implementers in other languages to follow. For users, -the chapter on keeping a journal is less extensive, but more typical -of common usage (@pxref{Keeping a Journal}). +suitable for implementers in other languages to follow. For users, the +chapter on keeping a journal is less extensive, but more typical of +common usage (@pxref{Keeping a Journal}). Data is collected in the form of @dfn{transactions} which occur in one or more @dfn{journal files}. Each transaction, in turn, is made up of @@ -8265,23 +8557,23 @@ journal files: Income:Another:Account @end smallexample -In this example, there is a transaction date, a payee, or description -of the transaction, and two postings. The postings show movement of -one hundred dollars from an account within the Income hierarchy, to -the specified expense account. The name and meaning of these accounts -in arbitrary, with no preferences implied, although you will find it -useful to follow standard accounting practice (@pxref{Principles of -Accounting}). +In this example, there is a transaction date, a payee, or description of +the transaction, and two postings. The postings show movement of one +hundred dollars from an account within the Income hierarchy, to the +specified expense account. The name and meaning of these accounts in +arbitrary, with no preferences implied, although you will find it useful +to follow standard accounting practice (@pxref{Principles of Accounting +with Ledger}). -Since an amount is missing from the second posting, it is assumed to -be the inverse of the first. This guarantees the cardinal rule of +Since an amount is missing from the second posting, it is assumed to be +the inverse of the first. This guarantees the cardinal rule of double-entry accounting: the sum of every transaction must balance to zero, or it is in error. Whenever Ledger encounters a @dfn{null posting} in a transaction, it uses it to balance the remainder. -It is also typical, though not enforced, to think of the first -posting as the destination, and the final as the source. Thus, the -amount of the first posting is typically positive. Consider: +It is also typical, though not enforced, to think of the first posting +as the destination, and the final as the source. Thus, the amount of +the first posting is typically positive. Consider: @smallexample 2010/05/31 An income transaction @@ -8300,15 +8592,15 @@ amount of the first posting is typically positive. Consider: * Primary commodities:: @end menu -@node Comments and meta-data, Specifying Amounts, Journal File Format, Journal File Format +@node Comments and meta-data, Specifying Amounts, Journal File Format for Developers, Journal File Format for Developers @subsection Comments and meta-data Comments are generally started using a @samp{;}. However, in order to -increase compatibility with other text manipulation programs and -methods three additional comment characters are valid if used at the -beginning of a line: @samp{#}, @samp{|}, and @samp{*}. +increase compatibility with other text manipulation programs and methods +three additional comment characters are valid if used at the beginning +of a line: @samp{#}, @samp{|}, and @samp{*}. -@node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format +@node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format for Developers @subsection Specifying Amounts @cindex amounts @@ -8338,20 +8630,20 @@ In the simplest form, bare decimal numbers are accepted: @end smallexample @cindex uncommoditized amounts -Such amounts may only use an optional period for a decimal point. -These are referred to as @dfn{integer amounts} or @dfn{uncommoditized -amounts}. In most ways they are similar to @dfn{commoditized -amounts}, but for one significant difference: They always display in -reports with @dfn{full precision}. More on this in a moment. For -now, a word must be said about how Ledger stores numbers. +Such amounts may only use an optional period for a decimal point. These +are referred to as @dfn{integer amounts} or @dfn{uncommoditized +amounts}. In most ways they are similar to @dfn{commoditized amounts}, +but for one significant difference: They always display in reports with +@dfn{full precision}. More on this in a moment. For now, a word must +be said about how Ledger stores numbers. Every number parsed by Ledger is stored internally as an infinite-precision rational value. Floating-point math is never used, as it cannot be trusted to maintain precision of values. So, in the -case of @code{1000.00} above, the internal value is @code{100000/100}. +case of @samp{1000.00} above, the internal value is @samp{100000/100}. While rational numbers are great at not losing precision, the question -arises: How should they be displayed? A number like @code{100000/100} +arises: How should they be displayed? A number like @samp{100000/100} is no problem, since it represents a clean decimal fraction. But what about when the number @samp{1/1} is divided by three? How should one print @samp{1/3}, an infinitely repeating decimal? @@ -8411,9 +8703,9 @@ part is the commodity. Another feature of commoditized amounts is that they are reported back in the same form as parsed. If you specify dollar amounts using -@code{$100}, they will print the same; likewise with @code{100 $} or -@code{$100.000}. You may even use decimal commas, such as -@code{$100,00}, or thousand-marks, as in @code{$10,000.00}. +@samp{$100}, they will print the same; likewise with @samp{100 $} or +@samp{$100.000}. You may even use decimal commas, such as +@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}. These display characteristics become associated with the commodity, with the result being that all amounts of the same commodity are @@ -8430,7 +8722,7 @@ commodity will be displayed. An example of this is found in cost expressions, covered next. -@node Posting costs, Primary commodities, Specifying Amounts, Journal File Format +@node Posting costs, Primary commodities, Specifying Amounts, Journal File Format for Developers @subsection Posting costs You have seen how to specify either a commoditized or an integer @@ -8478,11 +8770,13 @@ postings are involved: Assets:Checking @end smallexample -Here the implied cost is @code{$57.00}, which is entered into the null +Here the implied cost is @samp{$57.00}, which is entered into the null posting automatically so that the transaction balances. -@node Primary commodities, , Posting costs, Journal File Format +@node Primary commodities, , Posting costs, Journal File Format for Developers @subsection Primary commodities +@findex --market +@findex --basis In every transaction involving more than one commodity, there is always one which is the @dfn{primary commodity}. This commodity @@ -8506,32 +8800,33 @@ on the placement of the commodity in the transaction: @end smallexample The only case where knowledge of primary versus secondary comes into -play is in reports that use the @code{-V} or @code{-B} options. -With these, only primary commodities are shown. +play is in reports that use the @option{--market (-V)} or +@option{--basis (-B)} options. With these, only primary commodities are +shown. If a transaction uses only one commodity, this commodity is also considered a primary. In fact, when Ledger goes about ensures that all transactions balance to zero, it only ever asks this of primary commodities. -@node Developer Commands, Ledger Development Environment, Journal File Format, Ledger for Developers +@node Developer Commands, Ledger Development Environment, Journal File Format for Developers, Ledger for Developers @section Developer Commands @menu -* echo:: -* reload:: -* source:: +* @command{echo}:: +* @command{reload}:: +* @command{source}:: * Debug Options:: -* Pre-commands:: +* Pre-Commands:: @end menu -@node echo, reload, Developer Commands, Developer Commands +@node @command{echo}, @command{reload}, Developer Commands, Developer Commands @subsection @command{echo} @findex echo This command simply echoes its argument back to the output. -@node reload, source, echo, Developer Commands +@node @command{reload}, @command{source}, @command{echo}, Developer Commands @subsection @command{reload} @findex reload @@ -8539,22 +8834,23 @@ Forces ledger to reload any journal files. This function exists to support external programs controlling a running ledger process and does nothing for a command line user. -@node source, Debug Options, reload, Developer Commands +@node @command{source}, Debug Options, @command{reload}, Developer Commands @subsection @command{source} @findex source -The @code{source} command take a journal file as an argument and parses -it checking for errors, no other reports are generated, and no other -arguments are necessary. Ledger will return success if no errors are -found. +The @command{source} command take a journal file as an argument and +parses it checking for errors, no other reports are generated, and no +other arguments are necessary. Ledger will return success if no errors +are found. -@node Debug Options, Pre-commands, source, Developer Commands +@node Debug Options, Pre-Commands, @command{source}, Developer Commands @subsection Debug Options These options are primarily for Ledger developers, but may be of some use to a user trying something new. @ftable @code + @item --args-only Ignore init files and environment variables for the ledger run. @@ -8613,7 +8909,7 @@ Print detailed information on the execution of Ledger. @item --verify Enable additional assertions during run-time. This causes a significant -slowdown. When combined with @code{--debug} ledger will produce +slowdown. When combined with @option{--debug @var{CODE}} ledger will produce memory trace information. @item --verify-memory @@ -8621,9 +8917,10 @@ FIX THIS ENTRY @c FIXME thdox @item --version Print version information and exit. + @end ftable -@node Pre-commands, , Debug Options, Developer Commands +@node Pre-Commands, , Debug Options, Developer Commands @subsection Pre-Commands @cindex pre-commands @@ -8632,9 +8929,10 @@ will work. The difference between a pre-command and a regular command is that pre-commands ignore the journal data file completely, nor is the user's init file read. -@ftable @code +@ftable @command + @item eval @var{VEXPR} -Evaluate the given value expression against the model transaction +Evaluate the given value expression against the model transaction. @item format @var{FORMAT_STRING} Print details of how ledger uses the given formatting description and @@ -8642,7 +8940,7 @@ apply it against a model transaction. @item generate Randomly generates syntactically valid Ledger data from a seed. Used -by the GenerateTests harness for development testing +by the GenerateTests harness for development testing. @item parse @var{VEXPR} @itemx expr @var{VEXPR} @@ -8716,27 +9014,28 @@ true FIX THIS ENTRY @c FIXME thdox @item template -Shows the insertion template that a @code{draft} or @code{xact} -sub-command generates. This is a debugging command. +Shows the insertion template that @command{xact} sub-command generates. +This is a debugging command. + @end ftable @node Ledger Development Environment, , Developer Commands, Ledger for Developers @section Ledger Development Environment @menu -* acprep build configuration tool:: +* @file{acprep} build configuration tool:: * Testing Framework:: @end menu -@node acprep build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment -@subsection @code{acprep} build configuration tool +@node @file{acprep} build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment +@subsection @file{acprep} build configuration tool -@node Testing Framework, , acprep build configuration tool, Ledger Development Environment +@node Testing Framework, , @file{acprep} build configuration tool, Ledger Development Environment @subsection Testing Framework Ledger source ships with a fairly complete set of tests to verify that all is well, and no old errors have been resurfaced. Tests are run -individually with @code{ctest}. All tests can be run using @code{make +individually with @file{ctest}. All tests can be run using @code{make check} or @code{ninja check} depending on which build tool you prefer. Once built, the ledger executable resides under the @file{build} @@ -8765,21 +9064,27 @@ where the regex matches the name of the test you want to build. There are nearly 300 tests stored under the @file{test} subdirectory in main source distribution. They are broken into two broad categories, baseline and regression. To run the @file{5FBF2ED8} test, -for example, issue @code{ctest -V -R "5FB"}. +for example, issue @samp{ctest -V -R "5FB"}. @node Writing Tests, , Running Tests, Testing Framework @subsubsection Writing Tests -@node Major Changes from version 2.6, Example Data File, Ledger for Developers, Top +@node Major Changes from version 2.6, Example Journal File, Ledger for Developers, Top @chapter Major Changes from version 2.6 @itemize -@item OFX support has been removed from Ledger 3.0 -@item single character value expressions are deprecated and should be changed to the new value expressions available in 3.0 + +@item +OFX support has been removed from Ledger 3.0 + +@item +Single character value expressions are deprecated and should be changed +to the new value expressions available in 3.0 + @end itemize -@node Example Data File, Miscellaneous Notes, Major Changes from version 2.6, Top -@appendix Example Journal File: drewr.dat +@node Example Journal File, Miscellaneous Notes, Major Changes from version 2.6, Top +@appendix Example Journal File The following journal file is included with the source distribution of ledger. It is called @file{drewr.dat} and exhibits many ledger @@ -8851,7 +9156,7 @@ features, include automatic and virtual transactions, Income:Sales @end smallexample -@node Miscellaneous Notes, Concept Index, Example Data File, Top +@node Miscellaneous Notes, Concepts Index, Example Journal File, Top @appendix Miscellaneous Notes Various notes from the discussion list that I haven't incorporated in @@ -8894,12 +9199,12 @@ $ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 (Liabilities:Tithe Owed) -1.0 @end smallexample -@node Concept Index, Command Index, Miscellaneous Notes, Top +@node Concepts Index, Commands & Options Index, Miscellaneous Notes, Top @unnumbered Concepts Index @printindex cp -@node Command Index, , Concept Index, Top +@node Commands & Options Index, , Concepts Index, Top @unnumbered Commands & Options Index @printindex fn |