doc: note an issue with balance assertions & multiple -f options

[ci skip]
2017-01-14 17:49:26 -08:00 · 2017-01-14 17:49:26 -08:00 · d657374ac4
commit d657374ac4
parent d3883bad1f
8 changed files with 563 additions and 499 deletions
--- a/hledger-lib/doc/hledger_journal.5
+++ b/hledger-lib/doc/hledger_journal.5
@ -368,6 +368,7 @@ might break and require updating.
 This order dependence does bring an advantage: precise control over the
 order of postings and assertions within a day, so you can assert
 intra\-day balances.
+.SS Assertions and included files
 .PP
 With included files, things are a little more complicated.
 Including preserves the ordering of postings and assertions.
@ -375,6 +376,11 @@ If you have multiple postings to an account on the same day, split
 across different files, and you also want to assert the account\[aq]s
 balance on the same day, you\[aq]ll have to put the assertion in the
 right file.
+.SS Assertions and multiple \-f options
+.PP
+Balance assertions don\[aq]t work well across files specified with
+multiple \-f options.
+Use include or concatenate the files instead.
 .SS Assertions and commodities
 .PP
 The asserted balance must be a simple single\-commodity amount, and in
--- a/hledger-lib/doc/hledger_journal.5.info
+++ b/hledger-lib/doc/hledger_journal.5.info
@ -361,12 +361,14 @@ for reading Ledger files.
 * Menu:

 * Assertions and ordering::
+* Assertions and included files::
+* Assertions and multiple -f options::
 * Assertions and commodities::
 * Assertions and subaccounts::
 * Assertions and virtual postings::


-File: hledger_journal.5.info,  Node: Assertions and ordering,  Next: Assertions and commodities,  Up: Balance Assertions
+File: hledger_journal.5.info,  Node: Assertions and ordering,  Next: Assertions and included files,  Up: Balance Assertions

 1.6.1 Assertions and ordering
 -----------------------------
@ -384,6 +386,12 @@ updating. This order dependence does bring an advantage: precise control
 over the order of postings and assertions within a day, so you can
 assert intra-day balances.

+
+File: hledger_journal.5.info,  Node: Assertions and included files,  Next: Assertions and multiple -f options,  Prev: Assertions and ordering,  Up: Balance Assertions
+
+1.6.2 Assertions and included files
+-----------------------------------
+
 With included files, things are a little more complicated. Including
 preserves the ordering of postings and assertions. If you have multiple
 postings to an account on the same day, split across different files,
@ -391,9 +399,18 @@ and you also want to assert the account's balance on the same day,
 you'll have to put the assertion in the right file.


-File: hledger_journal.5.info,  Node: Assertions and commodities,  Next: Assertions and subaccounts,  Prev: Assertions and ordering,  Up: Balance Assertions
+File: hledger_journal.5.info,  Node: Assertions and multiple -f options,  Next: Assertions and commodities,  Prev: Assertions and included files,  Up: Balance Assertions

-1.6.2 Assertions and commodities
+1.6.3 Assertions and multiple -f options
+----------------------------------------
+
+Balance assertions don't work well across files specified with multiple
+-f options. Use include or concatenate the files instead.
+
+
+File: hledger_journal.5.info,  Node: Assertions and commodities,  Next: Assertions and subaccounts,  Prev: Assertions and multiple -f options,  Up: Balance Assertions
+
+1.6.4 Assertions and commodities
 --------------------------------

 The asserted balance must be a simple single-commodity amount, and in
@ -411,7 +428,7 @@ for this kind of total balance assertion if there's demand.)

 File: hledger_journal.5.info,  Node: Assertions and subaccounts,  Next: Assertions and virtual postings,  Prev: Assertions and commodities,  Up: Balance Assertions

-1.6.3 Assertions and subaccounts
+1.6.5 Assertions and subaccounts
 --------------------------------

 Balance assertions do not count the balance from subaccounts; they check
@ -436,7 +453,7 @@ $ hledger bal checking --flat

 File: hledger_journal.5.info,  Node: Assertions and virtual postings,  Prev: Assertions and subaccounts,  Up: Balance Assertions

-1.6.4 Assertions and virtual postings
+1.6.6 Assertions and virtual postings
 -------------------------------------

 Balance assertions are checked against all postings, both real and
@ -984,53 +1001,57 @@ Node: Virtual Postings10420
 Ref: #virtual-postings10581
 Node: Balance Assertions11801
 Ref: #balance-assertions11978
-Node: Assertions and ordering12800
-Ref: #assertions-and-ordering12985
-Node: Assertions and commodities14016
-Ref: #assertions-and-commodities14242
-Node: Assertions and subaccounts14934
-Ref: #assertions-and-subaccounts15168
-Node: Assertions and virtual postings15690
-Ref: #assertions-and-virtual-postings15899
-Node: Balance Assignments16040
-Ref: #balance-assignments16209
-Node: Prices17327
-Ref: #prices17460
-Node: Transaction prices17511
-Ref: #transaction-prices17656
-Node: Market prices19236
-Ref: #market-prices19371
-Node: Comments20371
-Ref: #comments20493
-Node: Tags21605
-Ref: #tags21725
-Node: Directives22648
-Ref: #directives22763
-Node: Account aliases22956
-Ref: #account-aliases23102
-Node: Basic aliases23704
-Ref: #basic-aliases23849
-Node: Regex aliases24537
-Ref: #regex-aliases24707
-Node: Multiple aliases25477
-Ref: #multiple-aliases25651
-Node: end aliases26147
-Ref: #end-aliases26289
-Node: account directive26391
-Ref: #account-directive26573
-Node: apply account directive26869
-Ref: #apply-account-directive27067
-Node: Multi-line comments27727
-Ref: #multi-line-comments27919
-Node: commodity directive28046
-Ref: #commodity-directive28232
-Node: Default commodity29105
-Ref: #default-commodity29280
-Node: Default year29816
-Ref: #default-year29983
-Node: Including other files30406
-Ref: #including-other-files30565
-Node: EDITOR SUPPORT30961
-Ref: #editor-support31081
+Node: Assertions and ordering12873
+Ref: #assertions-and-ordering13061
+Node: Assertions and included files13758
+Ref: #assertions-and-included-files14001
+Node: Assertions and multiple -f options14332
+Ref: #assertions-and-multiple--f-options14588
+Node: Assertions and commodities14719
+Ref: #assertions-and-commodities14956
+Node: Assertions and subaccounts15648
+Ref: #assertions-and-subaccounts15882
+Node: Assertions and virtual postings16404
+Ref: #assertions-and-virtual-postings16613
+Node: Balance Assignments16754
+Ref: #balance-assignments16923
+Node: Prices18041
+Ref: #prices18174
+Node: Transaction prices18225
+Ref: #transaction-prices18370
+Node: Market prices19950
+Ref: #market-prices20085
+Node: Comments21085
+Ref: #comments21207
+Node: Tags22319
+Ref: #tags22439
+Node: Directives23362
+Ref: #directives23477
+Node: Account aliases23670
+Ref: #account-aliases23816
+Node: Basic aliases24418
+Ref: #basic-aliases24563
+Node: Regex aliases25251
+Ref: #regex-aliases25421
+Node: Multiple aliases26191
+Ref: #multiple-aliases26365
+Node: end aliases26861
+Ref: #end-aliases27003
+Node: account directive27105
+Ref: #account-directive27287
+Node: apply account directive27583
+Ref: #apply-account-directive27781
+Node: Multi-line comments28441
+Ref: #multi-line-comments28633
+Node: commodity directive28760
+Ref: #commodity-directive28946
+Node: Default commodity29819
+Ref: #default-commodity29994
+Node: Default year30530
+Ref: #default-year30697
+Node: Including other files31120
+Ref: #including-other-files31279
+Node: EDITOR SUPPORT31675
+Ref: #editor-support31795

 End Tag Table
--- a/hledger-lib/doc/hledger_journal.5.m4.md
+++ b/hledger-lib/doc/hledger_journal.5.m4.md
@ -290,6 +290,8 @@ updating. This order dependence does bring an advantage: precise
 control over the order of postings and assertions within a day, so you
 can assert intra-day balances.

+### Assertions and included files
+
 With [included files](#including-other-files), things are a little
 more complicated. Including preserves the ordering of postings and
 assertions. If you have multiple postings to an account on the same
@ -297,6 +299,11 @@ day, split across different files, and you also want to assert the
 account's balance on the same day, you'll have to put the assertion
 in the right file.

+### Assertions and multiple -f options
+
+Balance assertions don't work well across files specified
+with multiple -f options. Use include or [concatenate the files](/hledger.html#input-files)
+instead.

 ### Assertions and commodities

--- a/hledger-lib/doc/hledger_journal.5.txt
+++ b/hledger-lib/doc/hledger_journal.5.txt
@ -287,12 +287,17 @@ FILE FORMAT
       trol over the order of postings and assertions within a day, so you can
       assert intra-day balances.

+   Assertions and included files
       With  included  files, things are a little more complicated.  Including
       preserves the ordering of postings and assertions.  If you have  multi-
       ple  postings  to  an  account  on the same day, split across different
       files, and you also want to assert the account's balance  on  the  same
       day, you'll have to put the assertion in the right file.

+   Assertions and multiple -f options
+       Balance assertions don't work well across files specified with multiple
+       -f options.  Use include or concatenate the files instead.
+
   Assertions and commodities
       The asserted balance must be a simple single-commodity amount,  and  in
       fact  the  assertion  checks  only  this commodity's balance within the
--- a/hledger/doc/hledger.1
+++ b/hledger/doc/hledger.1
@ -490,8 +490,14 @@ $\ echo\ \[aq]i\ 2009/13/1\ 08:00:00\[aq]\ |\ hledger\ print\ \-ftimeclock:\-
 .PP
 You can also specify multiple \f[C]\-f\f[] options, to read multiple
 files as one big journal.
-(Directives in one file will not affect the other files.
-If you need that, use the include directive instead.)
+There are some limitations with this:
+.IP \[bu] 2
+directives in one file will not affect the other files
+.IP \[bu] 2
+balance assertions will not see any account balances from previous files
+.PP
+If you need those, either use the include directive, or concatenate the
+files, eg: \f[C]cat\ a.journal\ b.journal\ |\ hledger\ \-f\-\ CMD\f[].
 .SS Depth limiting
 .PP
 With the \f[C]\-\-depth\ N\f[] option, commands like account, balance
--- a/hledger/doc/hledger.1.info
+++ b/hledger/doc/hledger.1.info
@ -369,8 +369,15 @@ $ hledger -f csv:/some/csv-file.dat stats
 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-

   You can also specify multiple `-f' options, to read multiple files
-as one big journal. (Directives in one file will not affect the other
-files. If you need that, use the include directive instead.)
+as one big journal. There are some limitations with this:
+
+   * directives in one file will not affect the other files
+
+   * balance assertions will not see any account balances from previous
+     files
+
+   If you need those, either use the include directive, or concatenate
+the files, eg: `cat a.journal b.journal | hledger -f- CMD'.


 File: hledger.1.info,  Node: Depth limiting,  Next: Smart dates,  Prev: Input files,  Up: OPTIONS
@ -2283,93 +2290,93 @@ Node: Reporting options7611
 Ref: #reporting-options7764
 Node: Input files9587
 Ref: #input-files9727
-Node: Depth limiting11564
-Ref: #depth-limiting11704
-Node: Smart dates11905
-Ref: #smart-dates12051
-Node: Report start & end date13048
-Ref: #report-start-end-date13220
-Node: Report intervals14296
-Ref: #report-intervals14461
-Node: Period expressions14860
-Ref: #period-expressions15025
-Node: Regular expressions17360
-Ref: #regular-expressions17502
-Node: QUERIES18985
-Ref: #queries19089
-Node: COMMANDS22728
-Ref: #commands22842
-Node: accounts23515
-Ref: #accounts23615
-Node: activity24597
-Ref: #activity24709
-Node: add25068
-Ref: #add25169
-Node: balance27832
-Ref: #balance27945
-Node: Flat mode30958
-Ref: #flat-mode31085
-Node: Depth limited balance reports31504
-Ref: #depth-limited-balance-reports31707
-Node: Multicolumn balance reports32128
-Ref: #multicolumn-balance-reports32330
-Node: Market value36979
-Ref: #market-value37143
-Node: Custom balance output38444
-Ref: #custom-balance-output38617
-Node: Output destination40721
-Ref: #output-destination40886
-Node: CSV output41156
-Ref: #csv-output41275
-Node: balancesheet41672
-Ref: #balancesheet41800
-Node: cashflow42452
-Ref: #cashflow42569
-Node: help43259
-Ref: #help43371
-Node: incomestatement44208
-Ref: #incomestatement44338
-Node: info45065
-Ref: #info45172
-Node: man45534
-Ref: #man45631
-Node: print46034
-Ref: #print46139
-Node: register49888
-Ref: #register50001
-Node: Custom register output54493
-Ref: #custom-register-output54624
-Node: stats55921
-Ref: #stats56027
-Node: test56907
-Ref: #test56994
-Node: ADD-ON COMMANDS57361
-Ref: #add-on-commands57497
-Node: api58785
-Ref: #api58877
-Node: autosync58911
-Ref: #autosync59026
-Node: diff61341
-Ref: #diff61451
-Node: equity62115
-Ref: #equity62229
-Node: interest63557
-Ref: #interest63674
-Node: irr66758
-Ref: #irr66871
-Node: print-unique69246
-Ref: #print-unique69376
-Node: rewrite69634
-Ref: #rewrite69753
-Node: ui70282
-Ref: #ui70382
-Node: web70423
-Ref: #web70511
-Node: TROUBLESHOOTING70544
-Ref: #troubleshooting70663
-Node: Run-time problems70717
-Ref: #run-time-problems70860
-Node: Known limitations72804
-Ref: #known-limitations72947
+Node: Depth limiting11768
+Ref: #depth-limiting11908
+Node: Smart dates12109
+Ref: #smart-dates12255
+Node: Report start & end date13252
+Ref: #report-start-end-date13424
+Node: Report intervals14500
+Ref: #report-intervals14665
+Node: Period expressions15064
+Ref: #period-expressions15229
+Node: Regular expressions17564
+Ref: #regular-expressions17706
+Node: QUERIES19189
+Ref: #queries19293
+Node: COMMANDS22932
+Ref: #commands23046
+Node: accounts23719
+Ref: #accounts23819
+Node: activity24801
+Ref: #activity24913
+Node: add25272
+Ref: #add25373
+Node: balance28036
+Ref: #balance28149
+Node: Flat mode31162
+Ref: #flat-mode31289
+Node: Depth limited balance reports31708
+Ref: #depth-limited-balance-reports31911
+Node: Multicolumn balance reports32332
+Ref: #multicolumn-balance-reports32534
+Node: Market value37183
+Ref: #market-value37347
+Node: Custom balance output38648
+Ref: #custom-balance-output38821
+Node: Output destination40925
+Ref: #output-destination41090
+Node: CSV output41360
+Ref: #csv-output41479
+Node: balancesheet41876
+Ref: #balancesheet42004
+Node: cashflow42656
+Ref: #cashflow42773
+Node: help43463
+Ref: #help43575
+Node: incomestatement44412
+Ref: #incomestatement44542
+Node: info45269
+Ref: #info45376
+Node: man45738
+Ref: #man45835
+Node: print46238
+Ref: #print46343
+Node: register50092
+Ref: #register50205
+Node: Custom register output54697
+Ref: #custom-register-output54828
+Node: stats56125
+Ref: #stats56231
+Node: test57111
+Ref: #test57198
+Node: ADD-ON COMMANDS57565
+Ref: #add-on-commands57701
+Node: api58989
+Ref: #api59081
+Node: autosync59115
+Ref: #autosync59230
+Node: diff61545
+Ref: #diff61655
+Node: equity62319
+Ref: #equity62433
+Node: interest63761
+Ref: #interest63878
+Node: irr66962
+Ref: #irr67075
+Node: print-unique69450
+Ref: #print-unique69580
+Node: rewrite69838
+Ref: #rewrite69957
+Node: ui70486
+Ref: #ui70586
+Node: web70627
+Ref: #web70715
+Node: TROUBLESHOOTING70748
+Ref: #troubleshooting70867
+Node: Run-time problems70921
+Ref: #run-time-problems71064
+Node: Known limitations73008
+Ref: #known-limitations73151

 End Tag Table
--- a/hledger/doc/hledger.1.txt
+++ b/hledger/doc/hledger.1.txt
@ -317,8 +317,15 @@ OPTIONS
              $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-

       You can also specify multiple -f options, to read multiple files as one
-       big journal.  (Directives in one file will not affect the other  files.
-       If you need that, use the include directive instead.)
+       big journal.  There are some limitations with this:
+
+       o directives in one file will not affect the other files
+
+       o balance assertions will not see any account  balances  from  previous
+         files
+
+       If you need those, either use the include directive, or concatenate the
+       files, eg: cat a.journal b.journal | hledger -f- CMD.

   Depth limiting
       With the --depth N option, commands like account, balance and  register
--- a/hledger/doc/options.m4.md
+++ b/hledger/doc/options.m4.md
@ -113,8 +113,13 @@ $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
 ```

 You can also specify multiple `-f` options, to read multiple files as one big journal.
-(Directives in one file will not affect the other files. If you need that, 
-use the [include directive](#including-other-files) instead.)
+There are some limitations with this:
+
+- directives in one file will not affect the other files
+- [balance assertions](/journal.html#balance-assertions) will not see any account balances from previous files
+
+If you need those, either use the [include directive](/journal.html#including-other-files),
+or concatenate the files, eg: `cat a.journal b.journal | hledger -f- CMD`.

 ## Depth limiting