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

[ci skip]

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

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,16 +386,31 @@ 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.
 
-   With included files, things are a little more complicated. Including
+
+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,
 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
+Node: Assertions and ordering12873
-Ref: #assertions-and-ordering12985
+Ref: #assertions-and-ordering13061
-Node: Assertions and commodities14016
+Node: Assertions and included files13758
-Ref: #assertions-and-commodities14242
+Ref: #assertions-and-included-files14001
-Node: Assertions and subaccounts14934
+Node: Assertions and multiple -f options14332
-Ref: #assertions-and-subaccounts15168
+Ref: #assertions-and-multiple--f-options14588
-Node: Assertions and virtual postings15690
+Node: Assertions and commodities14719
-Ref: #assertions-and-virtual-postings15899
+Ref: #assertions-and-commodities14956
-Node: Balance Assignments16040
+Node: Assertions and subaccounts15648
-Ref: #balance-assignments16209
+Ref: #assertions-and-subaccounts15882
-Node: Prices17327
+Node: Assertions and virtual postings16404
-Ref: #prices17460
+Ref: #assertions-and-virtual-postings16613
-Node: Transaction prices17511
+Node: Balance Assignments16754
-Ref: #transaction-prices17656
+Ref: #balance-assignments16923
-Node: Market prices19236
+Node: Prices18041
-Ref: #market-prices19371
+Ref: #prices18174
-Node: Comments20371
+Node: Transaction prices18225
-Ref: #comments20493
+Ref: #transaction-prices18370
-Node: Tags21605
+Node: Market prices19950
-Ref: #tags21725
+Ref: #market-prices20085
-Node: Directives22648
+Node: Comments21085
-Ref: #directives22763
+Ref: #comments21207
-Node: Account aliases22956
+Node: Tags22319
-Ref: #account-aliases23102
+Ref: #tags22439
-Node: Basic aliases23704
+Node: Directives23362
-Ref: #basic-aliases23849
+Ref: #directives23477
-Node: Regex aliases24537
+Node: Account aliases23670
-Ref: #regex-aliases24707
+Ref: #account-aliases23816
-Node: Multiple aliases25477
+Node: Basic aliases24418
-Ref: #multiple-aliases25651
+Ref: #basic-aliases24563
-Node: end aliases26147
+Node: Regex aliases25251
-Ref: #end-aliases26289
+Ref: #regex-aliases25421
-Node: account directive26391
+Node: Multiple aliases26191
-Ref: #account-directive26573
+Ref: #multiple-aliases26365
-Node: apply account directive26869
+Node: end aliases26861
-Ref: #apply-account-directive27067
+Ref: #end-aliases27003
-Node: Multi-line comments27727
+Node: account directive27105
-Ref: #multi-line-comments27919
+Ref: #account-directive27287
-Node: commodity directive28046
+Node: apply account directive27583
-Ref: #commodity-directive28232
+Ref: #apply-account-directive27781
-Node: Default commodity29105
+Node: Multi-line comments28441
-Ref: #default-commodity29280
+Ref: #multi-line-comments28633
-Node: Default year29816
+Node: commodity directive28760
-Ref: #default-year29983
+Ref: #commodity-directive28946
-Node: Including other files30406
+Node: Default commodity29819
-Ref: #including-other-files30565
+Ref: #default-commodity29994
-Node: EDITOR SUPPORT30961
+Node: Default year30530
-Ref: #editor-support31081
+Ref: #default-year30697
+Node: Including other files31120
+Ref: #including-other-files31279
+Node: EDITOR SUPPORT31675
+Ref: #editor-support31795
 
 End Tag Table

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
 

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

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.
+There are some limitations with this:
-If you need that, use the include directive instead.)
+.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

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

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.
+       big journal.  There are some limitations with this:
-       If you need that, use the include directive instead.)
+
+       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

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, 
+There are some limitations with this:
-use the [include directive](#including-other-files) instead.)
+
+- 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