Merge pull request #392 from thdox/doc-validation

Changes mainly about validation of @smallexample

doc/ledger3.texi

@@ -1396,7 +1396,7 @@ $ ledger --real --no-total bal
 If more asset accounts are needed as the source of a posting, just
 list them as you would normally, for example:
 
-@smallexample
+@smallexample @c input:validate
 2004/03/25 Payment for books (paid from Checking)
     Expenses:Books                    $100.00
     Assets:Checking                   $-50.00
@@ -1612,7 +1612,7 @@ Beneath these top level accounts you can have any level of detail you
 desire.  For example, if you want to keep specific track of how much
 you spend on burgers and fries, you could have the following:
 
-@smallexample
+@smallexample @c input:validate
 Expenses:Food:Hamburgers and Fries
 @end smallexample
 
@@ -1898,14 +1898,14 @@ your function in Python, you can return something like
 that value is always used, regardless of the commodity, the date, or
 the desired target commodity.  For example,
 
-@smallexample
+@smallexample @c input:validate
 define myfunc_seven(s, d, t) = 7 EUR
 @end smallexample
 
 In order to specify a fixed price, but still valuate that price into
 the target commodity, use something like this:
 
-@smallexample
+@smallexample @c input:validate
 define myfunc_five(s, d, t) = market(5 EUR, d, t)
 @end smallexample
 
@@ -1913,14 +1913,14 @@ The @code{value} directive sets the valuation used for all commodities
 used in the rest of the data stream.  This is the fallback, if nothing
 more specific is found.
 
-@smallexample
+@smallexample @c input:validate
 value myfunc_seven
 @end smallexample
 
 You can set a specific valuation function on a per-commodity basis.
 Instead of defining a function, you can also pass a lambda.
 
-@smallexample
+@smallexample @c input:validate
 commodity $
     value s, d, t -> 6 EUR
 @end smallexample
@@ -1928,7 +1928,7 @@ commodity $
 Each account can also provide a default valuation function for any
 commodities transferred to that account.
 
-@smallexample
+@smallexample @c input:validate
 account Expenses:Food5
     value myfunc_five
 @end smallexample
@@ -1936,7 +1936,7 @@ account Expenses:Food5
 The metadata field @samp{Value}, if found, overrides the valuation
 function on a transaction-wide or per-posting basis.
 
-@smallexample
+@smallexample @c input:validate
 = @@XACT and Food
     ; Value:: 8 EUR
     (Equity)                     $1
@@ -2019,10 +2019,9 @@ In order to combat inconsistency you can define allowable accounts and
 payees.  For simplicity, create a separate text file and define accounts
 and payees like
 
-@smallexample
+@smallexample @c input:validate
 account Expenses
 account Expenses:Utilities
-...
 @end smallexample
 
 Using the @option{--strict} option will cause Ledger to complain if any
@@ -2038,7 +2037,7 @@ Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities
 If you have a large Ledger register already created use the
 @command{accounts} command to get started:
 
-@smallexample
+@smallexample @c command:validate
 $ ledger accounts >> Accounts.dat
 @end smallexample
 
@@ -2457,15 +2456,14 @@ payee KFC
 The @code{alias} sub-directive provides a regex which, if it matches
 a parsed payee, the declared payee name is substituted:
 
-@smallexample
+@smallexample @c input:validate
 2012-02-27 KENTUCKY FRIED CHICKEN  ; will be read as being 'KFC'
-...
 @end smallexample
 
 The @code{uuid} sub-directive specifies that a transaction with exactly
 the uuid given should have the declared payee name substituted:
 
-@smallexample
+@smallexample @c input:validate
 2014-05-13 UNHELPFUL PAYEE  ; will be read as being 'KFC'
     ; UUID: 2a2e21d434356f886c84371eebac6e44f1337fda
 @end smallexample
@@ -2593,7 +2591,7 @@ with a home currency, such as the dollar @samp{$}.  It is recommended
 that these pricing options be set in the price database file, which
 defaults to @file{~/.pricedb}.  The syntax for this command is:
 
-@smallexample
+@smallexample @c input:validate
 N SYMBOL
 @end smallexample
 
@@ -3015,7 +3013,7 @@ 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 @c input:validate
+@smallexample @c input:9B43E57
 2010-06-17 Sample
     Assets:Bank        $400.00
     Income:Check1     $-100.00  ; Payee: Person One
@@ -3024,14 +3022,20 @@ below:
     Income:Check4     $-100.00  ; Payee: Person Four
 @end smallexample
 
-When reporting this, it appears as:
+When reporting with
 
-@smallexample
+@smallexample @c command:9B43E57
-10-Jun-17 Sample             Assets:Bank             $400.00     $400.00
+$ ledger reg
-          Person One         Income:Check1          $-100.00     $300.00
+@end smallexample
-          Person Two         Income:Check2          $-100.00     $200.00
+
-          Person Three       Income:Check3          $-100.00     $100.00
+it appears as:
-          Person Four        Income:Check4          $-100.00           0
+
+@smallexample @c output:9B43E57
+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
@@ -3585,13 +3589,13 @@ If you use the functional form, you can either specify a function
 name, or a lambda expression.  Here's a function that yields the price
 as $10 in whatever commodity is being requested:
 
-@smallexample
+@smallexample @c input:validate
 define ten_dollars(s, date, t) = market($10, date, t)
 @end smallexample
 
 I can now use that in a lot value expression as follows:
 
-@smallexample
+@smallexample @c input:validate
 2012-04-10 My Broker
     Assets:Brokerage:Cash       $375.00
     Assets:Brokerage            -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00
@@ -4203,8 +4207,7 @@ you want, or interface Ledger with other programs.
 A query such as the following shows all expenses since last
 October, sorted by total:
 
-@c TODO: does not validate with @c command:validate, because "last oct" is split at the space
+@smallexample @c command:validate
-@smallexample
 $ ledger -b "last oct" -S T bal ^expenses
 @end smallexample
 
@@ -4296,11 +4299,11 @@ invested in equities, and partially invested in bonds and cash.  Below
 is the asset allocation for each of the instruments listed above:
 
 @multitable @columnfractions .2 .2 .3 .3
-@item @tab Domestic @tab Global @tab
+@item        @tab Domestic @tab Global @tab
-@item Symbol @tab Equity @tab Equity @tab bonds/cash
+@item Symbol @tab Equity   @tab Equity @tab bonds/cash
-@item VIFSX @tab 100% @tab @tab
+@item VIFSX  @tab 100%     @tab        @tab
-@item VTHRX @tab 24.0% @tab 56.3% @tab 19.7%
+@item VTHRX  @tab 24.0%    @tab 56.3%  @tab 19.7%
-@item VSGBX @tab @tab @tab 100%
+@item VSGBX  @tab          @tab        @tab 100%
 @end multitable
 
 These numbers are available from the prospectus of any publicly
@@ -4309,7 +4312,7 @@ and a single bond issue is 100% bonds.
 
 We track purchases of specific investments using the symbol of that
 investment as its commodity.  How do we tell Ledger that a share of
-VTHRX is 24% Global equity etc.?  Enter automatic transactions and
+VTHRX is 24% Domestic equity?  Enter automatic transactions and
 virtual accounts.
 
 At the top of our ledger we enter automatic transactions that describe
@@ -4320,12 +4323,9 @@ actual balances.
 For the three instruments listed above, those automatic transactions
 would look like:
 
-@smallexample @c input:validate
+@smallexample @c input:582C8C2
-;
-; automatic calculations for asset allocation tracking
-;
 = expr ( commodity == 'VIFSX' )
-    (Allocation:Equities:Domestic)                 1.000
+    (Allocation:Equities:Domestic)             1.000
 
 = expr ( commodity == 'VTHRX' )
     (Allocation:Equities:Global)               0.240
@@ -4334,6 +4334,18 @@ would look like:
 
 = expr ( commodity == 'VBMFX')
     (Allocation:Bonds/Cash)                    1.000
+
+2015-01-01 Buy VIFSX
+    Assets:Broker                                100 VIFSX
+    Assets:Cash                              $-10000
+
+2015-01-01 Buy VTHRX
+    Assets:Broker                                 10 VTHRX
+    Assets:Cash                              $-10000
+
+2015-01-01 Buy VBMFX
+    Assets:Broker                                  1 VBMFX
+    Assets:Cash                              $-10000
 @end smallexample
 
 How do these work? First the @samp{=} sign at the beginning of the
@@ -4352,23 +4364,21 @@ the various asset classes how do we get a report that tells us our
 current allocation?  Using the balance command and some tricky
 formatting!
 
-@c TODO: does not @c command:validate due to multiple lines
+@smallexample @c command:582C8C2
-@smallexample
 ledger bal Allocation --current --format "\
         %-17((depth_spacer)+(partial_account))\
         %10(percent(market(display_total), market(parent.total)))\
         %16(market(display_total))\n%/"
 @end smallexample
 
-@noindent
 Which yields:
 
-@smallexample
+@smallexample @c result:582C8C2
-Allocation          100.00%      $100000.00
+        Allocation                  100.00%                  $30000
-  Bonds/Cash         38.94%       $38940.00
+          Bonds/Cash                 39.90%                  $11970
-  Equities           61.06%       $61060.00
+          Equities                   60.10%                  $18030
-    Domestic         95.31%       $58196.29
+            Domestic                 86.69%                  $15630
-    Global            4.69%        $2863.71
+            Global                   13.31%                   $2400
 @end smallexample
 
 Let's look at the Ledger invocation a bit closer.  The command above is
@@ -5249,8 +5259,10 @@ journal.  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
+@smallexample @c command:validate
 $ ledger payees @@Nic
+@end smallexample
+@smallexample
 Nicolas
 Nicolas BOILABUS
 Oudtshoorn Municipality
@@ -6380,8 +6392,10 @@ Set the format for the headers that separates the report sections of
 a grouped report.  Only has an effect with a @option{--group-by
 @var{EXPR}} register report.
 
-@smallexample
+@smallexample @c command:validate
 $ ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n"
+@end smallexample
+@smallexample
 ------------------------ 7-Eleven             ---------------------
 2011/08/13 7-Eleven              Expenses:Auto:Misc          $ 5.80       $ 5.80
 
@@ -6528,8 +6542,10 @@ example, if you have multiple cars and track each fuel purchase in
 identifying which car the purchase was for @samp{; Car: Prius}, then the
 command:
 
-@smallexample
+@smallexample @c command:validate
 $ ledger bal Fuel --pivot "Car" --period "this year"
+@end smallexample
+@smallexample
            $ 3491.26  Car
            $ 1084.22    M3:Expenses:Auto:Fuel
             $ 149.65    MG V11:Expenses:Auto:Fuel
@@ -6752,7 +6768,7 @@ settings.  To specify options in the init file, use the same syntax as
 on the command-line, but put each option on its own line.  Here is an
 example init file:
 
-@smallexample
+@smallexample @c input:validate
 --price-db ~/finance/.pricedb
 --wide
 ; ~/.ledgerrc ends here
@@ -7055,8 +7071,7 @@ register report, for example, but they will not be displayed.  This is
 useful for seeing last month's checking postings, against a running
 balance which includes all posting values:
 
-@c TODO: does not @c command:validate due to space in "last month"
+@smallexample @c command:validate
-@smallexample
 $ ledger -d "d>=[last month]" reg checking
 @end smallexample
 
@@ -7064,8 +7079,7 @@ The output from this command is very different from the following,
 whose running total includes only postings from the last month
 onward:
 
-@c TODO: does not @c command:validate due to space in "last month"
+@smallexample @c command:validate
-@smallexample
 $ ledger -p "last month" reg checking
 @end smallexample
 
@@ -7221,7 +7235,7 @@ settings can be placed in this file manually, to prevent downloading
 quotes for a specific commodity, for example.  This is done by adding a
 line like the following:
 
-@smallexample
+@smallexample @c input:validate
 ; Don't download quotes for the dollar, or timelog values
 N $
 N h
@@ -7459,7 +7473,7 @@ command-line always take precedence over environment variable settings, however.
 Note that you may also permanently specify option values by placing
 option settings in the file @file{~/.ledgerrc} one option per line, for example:
 
-@smallexample
+@smallexample @c input:validate
 --pager /bin/cat
 @end smallexample
 
@@ -7597,7 +7611,7 @@ These two periodic transactions give the usual monthly expenses, as well
 as one typical yearly expense.  For help on finding out what your
 average monthly expenses are for any category, use a command like:
 
-@smallexample
+@smallexample @c command:validate
 $ ledger -p "this year" --monthly --average balance ^expenses
 @end smallexample
 
@@ -7730,7 +7744,7 @@ constrain which transactions are printed.  For example, the following
 command shows only transactions from the beginning of the current month,
 while still calculating the running balance based on all transactions:
 
-@smallexample
+@smallexample @c command:validate
 $ ledger -d "d>[this month]" register checking
 @end smallexample
 
@@ -7739,7 +7753,7 @@ running total in terms of all transactions in the register.  The
 following, simpler command is similar, but totals only the displayed
 postings:
 
-@smallexample
+@smallexample @c command:validate
 $ ledger -b "this month" register checking
 @end smallexample
 
@@ -7945,7 +7959,7 @@ field.  This searches only a posting's field, not the transaction's note
 or comment field.  For example, @code{ledger reg "expr" "comment =~
 /landline/"} will match:
 
-@smallexample
+@smallexample @c input:validate
 2014/1/29  Phone bill
     Assets:Checking                           $50.00
     Expenses:Phone                           $-50.00  ; landline bill
@@ -7953,7 +7967,7 @@ or comment field.  For example, @code{ledger reg "expr" "comment =~
 
 but will not match:
 
-@smallexample
+@smallexample @c input:validate
 2014/1/29  Phone bill  ; landline bill
     ; landline bill
     Assets:Checking                           $50.00
@@ -7969,19 +7983,19 @@ This searches all comments in the transaction, including comments on
 individual postings.  Thus, @samp{ledger reg "expr" "note =~ /landline/"}
 will match both all the three examples below:
 
-@smallexample
+@smallexample @c input:validate
 2014/1/29  Phone bill
     Assets:Checking                           $50.00
     Expenses:Phone                           $-50.00  ; landline bill
 @end smallexample
 
-@smallexample
+@smallexample @c input:validate
 2014/1/29  Phone bill  ; landline bill
     Assets:Checking                           $50.00
     Expenses:Phone                           $-50.00
 @end smallexample
 
-@smallexample
+@smallexample @c input:validate
 2014/1/29  Phone bill
     ; landline bill
     Assets:Checking                           $50.00
@@ -8130,7 +8144,7 @@ for format string details.
 $ ledger -f expr.dat --format "%(format_date(date, '%A, %B %d. %Y'))\n" reg assets
 @end smallexample
 @smallexample @c output:9605B13
-Friday, January 16.  2015
+Friday, January 16. 2015
 @end smallexample
 @end defun
 
@@ -9757,8 +9771,10 @@ and apply it against a model transaction.
 @item period @var{PERIOD_EXPRESSION}
 Evaluate the given period and report how Ledger interprets it:
 
-@smallexample
+@smallexample @c command:51F6A2C
-$ ledger period "this year"
+$ ledger period "this year"  --now 2011-01-01
+@end smallexample
+@smallexample @c result:51F6A2C
 --- Period expression tokens ---
 TOK_THIS: this
 TOK_YEAR: year
@@ -9781,8 +9797,10 @@ END_REACHED: <EOF>
 Evaluate the given arguments and report how Ledger interprets it against
 the following model transaction:
 
-@smallexample
+@smallexample @c command:validate
 $ ledger query "/Book/"
+@end smallexample
+@smallexample
 --- Input arguments ---
 ("/Book/")
 
@@ -9910,7 +9928,7 @@ The test scripts take the remainder of the @code{test} line and use
 it as command-line arguments for ledger, the text enclosed in @code{test}
 and @code{end test} is expected output, for example:
 
-@smallexample
+@smallexample @c input:validate
 ; This is the journal data
 year 2014
 12/24 (C0d3) Santa Claus