diff options
Diffstat (limited to 'doc/ledger3.texi')
| -rw-r--r-- | doc/ledger3.texi | 300 |
1 files changed, 227 insertions, 73 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 2b962180..4ab8f4fd 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -20,9 +20,83 @@ @c Restructuring manual ideas @c http://beyondgrep.com/documentation/ack-2.04-man.html +@c How to make documented ledger examples validate automatically. +@c +@c The test/DocTests.py script will be run along the with the other +@c tests when using ctest or acprep check. +@c The script parses the texinfo file and looks for three kinds of +@c specially marked @smallexamples, then it will run the ledger +@c command from the exmaple, and compare the results with the output +@c from the documentation. +@c +@c To specially mark a @smallexample append @c command:UUID, where +@c UUID is the first 7 digits from the commands sha1sum, e.g.: +@c +@c @smallexample @c command:CDE330A +@c $ ledger -f sample.dat reg expenses +@c @end smallexample +@c +@c Then DocTests.py will look for corresponding documented output, +@c which may appear anywhere in the file, and is marked with +@c @smallexample @c output:UUID where UUID is the UUID from the +@c corresponding ledger command example, e.g.: +@c +@c @smallexample @c output:CDE330A +@c 04-May-27 Book Store Expenses:Books $20.00 $20.00 +@c Expenses:Cards $40.00 $60.00 +@c Expenses:Docs $30.00 $90.0 +@c @end smallexample +@c +@c Now where does this data in sample.dat come from? +@c DocTests.py is a bit smart about ledger's file argument, since +@c it will check if the given filename exists in the test/input/ +@c directory. +@c +@c Sometimes the journal data for an example is specified within +@c the documentation itself, in that case the journal example data +@c needs to be specially marked as well using @smallexample @c input:UUID, +@c again with the UUID being the UUID of the corresponding ledger example +@c command. If multiple inputs with the same UUID are found they will be +@c concatenated together and given as one set of data to the example command. +@c +@c @smallexample @c input:35CB2A3 +@c 2014/02/09 The Italian Place +@c Expenses:Food:Dining $ 36.84 +@c Assets:Cash +@c @end smallexample +@c +@c @smallexample @c command:35CB2A3 +@c $ ledger -f inline.dat accounts +@c @end smallexample +@c +@c @smallexample @c output:35CB2A3 +@c Assets:Cash +@c Expenses:Food:Dining +@c @end smallexample +@c +@c To use different example commands with the same input from the documentation +@c add with_input:UUID to the example command, where UUID is the UUID of the input, +@c e.g.: +@c +@c @smallexample @c command:94FD2B6,with_input:35CB2A3 +@c $ ledger -f inline.dat bal expenses +@c @end smallexample +@c +@c @smallexample @c output:94FD2B6 +@c $ 36.84 Expenses:Food:Dining +@c @end smallexample +@c +@c Additionally DocTests.py will pass --init-file /dev/null to ledger to +@c ignore any default arguments to ledger the user running the tests +@c has configured. +@c +@c To manually run the tests in this file run: +@c $ ./test/DocTests.py -vv --ledger ./ledger --file ./test/ledger3.texi + + @copying -Copyright @copyright{} 2003–2013, John Wiegley. All rights reserved. +Copyright @copyright{} 2003–2014, 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 @@ -245,7 +319,7 @@ And just for the sake of example---as a starting point for those who want to dive in head-first---here are the journal transactions from above, formatted as the Ledger program wishes to see them: -@smallexample +@smallexample @c input:48DDF26 2004/09/29 Pacific Bell Expenses:Pacific Bell $23.00 Assets:Checking @@ -254,12 +328,37 @@ above, formatted as the Ledger program wishes to see them: The account balances and registers in this file, if saved as @file{ledger.dat}, could be reported using: -@smallexample +@smallexample @c command:48DDF26 $ ledger -f ledger.dat balance +@end smallexample + +@smallexample @c output:48DDF26 + $-23.00 Assets:Checking + $23.00 Expenses:Pacific Bell +-------------------- + 0 +@end smallexample + +Or + +@smallexample @c command:8C7295F,with_input:48DDF26 $ ledger -f ledger.dat register checking +@end smallexample + +@smallexample @c output:8C7295F +04-Sep-29 Pacific Bell Assets:Checking $-23.00 $-23.00 +@end smallexample + +And even: + +@smallexample @c command:BB32EF2,with_input:48DDF26 $ ledger -f ledger.dat register Bell @end smallexample +@smallexample @c output:BB32EF2 +04-Sep-29 Pacific Bell Expenses:Pacific Bell $23.00 $23.00 +@end smallexample + An important difference between Ledger and other finance packages is 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 @@ -346,13 +445,13 @@ for each. To find the balances of all of your accounts, run this command: -@smallexample +@smallexample @c command:1071890 $ ledger -f drewr3.dat balance @end smallexample Ledger will generate: -@smallexample +@smallexample @c output:1071890 $ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business @@ -381,8 +480,11 @@ pare this down to show only the accounts you want. A more useful report is to show only your Assets and Liabilities: -@smallexample +@smallexample @c command:5BF4D8E $ ledger -f drewr3.dat balance Assets Liabilities +@end smallexample + +@smallexample @c output:5BF4D8E $ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business @@ -402,16 +504,16 @@ $ ledger -f drewr3.dat balance Assets Liabilities To show all transactions and a running total: -@smallexample +@smallexample @c command:66E3A2C $ ledger -f drewr3.dat register @end smallexample @noindent Ledger will generate: -@smallexample +@smallexample @c output:66E3A2C 10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00 - Equity:Opening Balances $ -1,000.00 0 + Equit:Opening Balances $ -1,000.00 0 10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 @@ -450,8 +552,11 @@ interested in seeing transactions for: @cindex accounts, limiting by @cindex limiting by accounts -@smallexample +@smallexample @c command:96B0EB3 $ ledger -f drewr3.dat register Groceries +@end smallexample + +@smallexample @c output:96B0EB3 10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 @@ -465,8 +570,11 @@ $ ledger -f drewr3.dat register Groceries @noindent Which matches the balance reported for the @samp{Groceries} account: -@smallexample +@smallexample @c command:AECD64E $ ledger -f drewr3.dat balance Groceries +@end smallexample + +@smallexample @c output:AECD64E $ 334.00 Expenses:Food:Groceries @end smallexample @@ -474,8 +582,11 @@ $ ledger -f drewr3.dat balance Groceries If you would like to find transaction to only a certain payee use @samp{payee} or @samp{@@}: -@smallexample +@smallexample @c command:C6BC57E $ ledger -f drewr3.dat register payee "Organic" +@end smallexample + +@smallexample @c output:C6BC57E 10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 @@ -497,8 +608,11 @@ a check to clear, but you should treat it as money spent. The @command{cleared} report will not format correctly for accounts that contain multiple commodities): -@smallexample +@smallexample @c command:B86F6A6 $ ledger -f drewr3.dat cleared +@end smallexample + +@smallexample @c output:B86F6A6 $ -3,804.00 $ 775.00 Assets $ 1,396.00 $ 775.00 10-Dec-20 Checking $ 30.00 0 Business @@ -517,8 +631,8 @@ $ ledger -f drewr3.dat cleared $ -20.00 0 MasterCard $ 200.00 0 Mortgage:Principal $ -243.60 0 Tithe ----------------- ---------------- --------- - $ -243.60 0 +---------------- ---------------- --------- + $ -243.60 0 @end smallexample @noindent @@ -624,7 +738,7 @@ owe. ``Liabilities'' is just a more inclusive name for Debts. An Asset is typically increased by transferring money from an Income account, such as when you get paid. Here is a typical transaction: -@smallexample +@smallexample @c input:6B43DD4 2004/09/29 My Employer Assets:Checking $500.00 Income:Salary @@ -639,7 +753,7 @@ borrow money to buy something, or if you owe someone money. Here is an example of increasing a MasterCard liability by spending money with it: -@smallexample +@smallexample @c input:6B43DD4 2004/09/30 Restaurant Expenses:Dining $25.00 Liabilities:MasterCard @@ -653,10 +767,17 @@ offsets the value of your assets. The combined total of your Assets and Liabilities is your net worth. So to see your current net worth, use this command: -@smallexample +@smallexample @c command:6B43DD4 $ ledger balance ^assets ^liabilities @end smallexample +@smallexample @c output:6B43DD4 + $500.00 Assets:Checking + $-25.00 Liabilities:MasterCard +-------------------- + $475.00 +@end smallexample + In a similar vein, your Income accounts show up negative, because they transfer money @emph{from} an account in order to increase your assets. Your Expenses show up positive because that is where the @@ -665,10 +786,17 @@ flow. A positive cash flow means you are spending more than you make, since income is always a negative figure. To see your current cash flow, use this command: -@smallexample +@smallexample @c command:DB128F3,with_input:6B43DD4 $ ledger balance ^income ^expenses @end smallexample +@smallexample @c output:DB128F3 + $25.00 Expenses:Dining + $-500.00 Income:Salary +-------------------- + $-475.00 +@end smallexample + Another common question to ask of your expenses is: How much do I spend each month on X? Ledger provides a simple way of displaying monthly totals for any account. Here is an example that summarizes @@ -1488,7 +1616,7 @@ entry. For example, the following entries reflect transaction made for a business trip to Europe from the US: -@smallexample +@smallexample @c input:82150D9 2011/09/23 Cash in Munich Assets:Cash E50.00 Assets:Checking $-66.00 @@ -1504,8 +1632,11 @@ spent on Dinner in Munich. Running a ledger balance report shows: -@smallexample +@smallexample @c command:82150D9 $ ledger -f example.dat bal +@end smallexample + +@smallexample @c output:82150D9 $-66.00 E15.00 Assets E15.00 Cash @@ -1741,7 +1872,7 @@ function on a transaction-wide or per-posting basis. Lastly, you can specify the valuation function/value for any specific amount using the @samp{(( ))} commodity annotation. -@smallexample +@smallexample @c input:814A366 2012-03-02 KFC Expenses:Food2 $1 ((2 EUR)) Assets:Cash2 @@ -1777,20 +1908,24 @@ amount using the @samp{(( ))} commodity annotation. Assets:Cash9 @end smallexample -@smallexample -ledger reg -V food +@smallexample @c command:814A366 +$ ledger reg -V food +@end smallexample + +@smallexample @c output:814A366 12-Mar-02 KFC Expenses:Food2 2 EUR 2 EUR -12-Mar-03 KFC <Adjustment> -1 EUR 1 EUR - Expenses:Food3 3 EUR 4 EUR -12-Mar-04 KFC <Adjustment> -2 EUR 2 EUR - Expenses:Food4 4 EUR 6 EUR -12-Mar-05 KFC <Adjustment> -3 EUR 3 EUR - Expenses:Food5 5 EUR 8 EUR -12-Mar-06 KFC <Adjustment> -4 EUR 4 EUR - Expenses:Food6 6 EUR 10 EUR -12-Mar-07 KFC Expenses:Food7 7 EUR 17 EUR -12-Mar-08 XACT Expenses:Food8 8 EUR 25 EUR -12-Mar-09 POST (Expenses:Food9) 9 EUR 34 EUR +12-Mar-03 KFC Expenses:Food3 3 EUR 5 EUR +12-Mar-04 KFC Expenses:Food4 4 EUR 9 EUR +12-Mar-05 KFC Expenses:Food5 $1 $1 + 9 EUR +12-Mar-06 KFC Expenses:Food6 $1 $2 + 9 EUR +12-Mar-07 KFC Expenses:Food7 1 CAD $2 + 1 CAD + 9 EUR +12-Mar-08 XACT Expenses:Food8 $1 $3 + 1 CAD + 9 EUR @end smallexample @node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal @@ -2979,7 +3114,7 @@ after the amount or amount expression: @end smallexample When you do this, since Ledger can now figure out the balancing amount -from the first posting's cost, you can elide the otheramount: +from the first posting's cost, you can elide the other amount: @smallexample 2012-03-10 My Broker @@ -3626,7 +3761,7 @@ the money to be evenly distributed over the next six months so that your monthly budgets gradually take a hit for the vegetables you'll pick up from the co-op, even though you've already paid for them. -@smallexample +@smallexample @c input:6453542 2008/10/16 * (2090) Bountiful Blessings Farm Expenses:Food:Groceries $ 37.50 ; [=2008/10/01] Expenses:Food:Groceries $ 37.50 ; [=2008/11/01] @@ -3644,15 +3779,17 @@ really knows that it debited $225 this month. And using @option{--effective} option, initial date will be overridden by effective dates. -@smallexample +@smallexample @c command:6453542 $ ledger --effective register Groceries +@end smallexample -08-Oct-01 Bountiful Blessi.. Expe:Food:Groceries $ 37.50 $ 37.50 -08-Nov-01 Bountiful Blessi.. Expe:Food:Groceries $ 37.50 $ 75.00 -08-Dec-01 Bountiful Blessi.. Expe:Food:Groceries $ 37.50 $ 112.50 -09-Jan-01 Bountiful Blessi.. Expe:Food:Groceries $ 37.50 $ 150.00 -09-Feb-01 Bountiful Blessi.. Expe:Food:Groceries $ 37.50 $ 187.50 -09-Mar-01 Bountiful Blessi.. Expe:Food:Groceries $ 37.50 $ 225.00 +@smallexample @c output:6453542 +08-Oct-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 37.50 +08-Nov-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 75.00 +08-Dec-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 112.50 +09-Jan-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 150.00 +09-Feb-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 187.50 +09-Mar-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 225.00 @end smallexample @node Periodic Transactions, Concrete Example of Automated Transactions, Effective Dates, Automated Transactions @@ -3777,14 +3914,14 @@ options. The balance report is the most commonly used report. The simplest invocation is: -@smallexample +@smallexample @c command:1D00D56 $ ledger balance -f drewr3.dat @end smallexample @noindent which will print the balances of every account in your journal. -@smallexample +@smallexample @c output:1D00D56 $ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business @@ -3811,8 +3948,11 @@ Most times this is more than you want. Limiting the results to specific accounts is as easy as entering the names of the accounts after the command. -@smallexample +@smallexample @c command:06B2AD4 $ ledger balance -f drewr3.dat Auto MasterCard +@end smallexample + +@smallexample @c output:06B2AD4 $ 5,500.00 Expenses:Auto $ -20.00 Liabilities:MasterCard -------------------- @@ -3820,14 +3960,17 @@ $ ledger balance -f drewr3.dat Auto MasterCard @end smallexample @noindent -note the implicit logical and between @samp{Auto} and +note the implicit logical or 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: -@smallexample +@smallexample @c command:B0468E1 $ ledger balance -f drewr3.dat Income +@end smallexample + +@smallexample @c output:B0468E1 $ -2,030.00 Income $ -2,000.00 Salary $ -30.00 Sales @@ -3838,15 +3981,25 @@ $ ledger balance -f drewr3.dat Income You can use general regular expressions in nearly anyplace Ledger needs a string: -@smallexample +@smallexample @c command:EAE389F $ ledger balance -f drewr3.dat ^Bo +@end smallexample +@smallexample @c output:EAE389F +@end smallexample + +This first example looks for any account starting with @samp{Bo}, of +which there are none. + +@smallexample @c command:E2AF6AD $ ledger balance -f drewr3.dat Bo +@end smallexample + +@smallexample @c output:E2AF6AD $ 20.00 Expenses:Books @end smallexample -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}. +This second example looks for any account with @samp{Bo}, which is +@samp{Expenses:Books}. @cindex limit by payees @findex --limit @var{EXPR} @@ -4964,7 +5117,7 @@ earlier postings. Here's how it works: Say you currently have this posting in your ledger file: -@smallexample +@smallexample @c input:03ACB97 2004/03/15 * Viva Italiano Expenses:Food $12.45 Expenses:Tips $2.55 @@ -4975,17 +5128,17 @@ 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 +@smallexample @c command:03ACB97 $ ledger xact 2004/4/9 viva food 11 tips 2.50 @end smallexample This produces the following output: -@smallexample +@smallexample @c output:03ACB97 2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard @end smallexample It works by finding a past posting matching the regular expression @@ -5339,7 +5492,7 @@ 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 criteria in the @var{EXPR}. @item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} @@ -5596,22 +5749,23 @@ Format Codes}). @item --master-account @var{STR} Prepend all account names with the argument. -@smallexample -$ ledger -f test/input/drewr3.dat bal --master-account HUMBUG +@smallexample @c command:A76BB56 +$ ledger -f drewr3.dat bal --no-total --master-account HUMBUG +@end smallexample + +@smallexample @c output:A76BB56 0 HUMBUG $ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business $ -5,200.00 Savings - $ 20.00 Books $ -1,000.00 Equity:Opening Balances - $ 6,634.00 Expenses - $ 11,000.00 Auto + $ 6,654.00 Expenses + $ 5,500.00 Auto $ 20.00 Books $ 300.00 Escrow $ 334.00 Food:Groceries $ 500.00 Interest:Mortgage - $ -5,520.00 Assets:Checking $ -2,030.00 Income $ -2,000.00 Salary $ -30.00 Sales @@ -6462,7 +6616,7 @@ In the balance report, it shows all the accounts affected by transactions having a related posting. For example, if a file had this transaction: -@smallexample +@smallexample @c input:94C5675 2004/03/20 Safeway Expenses:Food $65.00 Expenses:Cash $20.00 @@ -6471,16 +6625,16 @@ this transaction: And the register command was: -@smallexample -$ ledger -r register food +@smallexample @c command:94C5675 +$ ledger -f example.dat -r register food @end smallexample The following would be output, showing the postings related to the posting that matched: -@smallexample -2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 +@smallexample @c output:94C5675 +04-Mar-20 Safeway Expenses:Cash $20.00 $20.00 + Assets:Checking $-85.00 $-65.00 @end smallexample @item --budget @@ -9071,7 +9225,7 @@ test subdirectory for the build. For example, @node Running Tests, Writing Tests, Testing Framework, Testing Framework @subsubsection Running Tests -The complete test sweet can be run from the build directory using the +The complete test suite can be run from the build directory using the check option for the build tool you use. For example, @code{make check}. The entire test suit lasts around a minute for the optimized built and many times longer for the debug version. While developing |