Merge commit 'bc08eed3cb1bdb4f67d1b77273f3254d0cf13be2'

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