;doc: update embedded manuals

2025-06-13 09:11:44 -10:00 · 2025-06-13 09:11:44 -10:00 · 53120e86bc
commit 53120e86bc
parent a823a719f2
3 changed files with 195 additions and 119 deletions
--- a/hledger/hledger.1
+++ b/hledger/hledger.1
@ -8929,6 +8929,27 @@ Provide answers for the first four prompts:
 .RE
 .PP
 There is a detailed tutorial at https://hledger.org/add.html.
+.SS add and balance assertions
+Since hledger 1.43, whenever you enter a posting amount, \f[CR]add\f[R]
+will re\-check all balance assertions in the journal, and if any of them
+fail, it will report the problem and ask for the amount again.
+.PP
+You can also add a new balance assertion, following the amount as in
+journal format.
+.PP
+The new transaction\[aq]s date, and the new posting\[aq]s posting date
+if any (entered in a comment following the amount), will influence
+assertion checking.
+.PP
+You can use \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable
+this assertion checking.
+.SS add and balance assignments
+You can\[aq]t add new postings which are dated earlier than a balance
+assignment, currently.
+It\[aq]s because balance assignments are performed once, before
+\f[CR]add\f[R]; by the time \f[CR]add\f[R] runs, all amounts in the
+journal are explicit, and assignments have become assertions.
+(#2406).
 .SS import
 Import new transactions from one or more data files to the main journal.
 .IP
--- a/hledger/hledger.info
+++ b/hledger/hledger.info
@ -8528,10 +8528,12 @@ File: hledger.info,  Node: Data entry commands,  Next: Basic report commands,  P
 * Menu:

 * add::
+* add and balance assertions::
+* add and balance assignments::
 * import::


-File: hledger.info,  Node: add,  Next: import,  Up: Data entry commands
+File: hledger.info,  Node: add,  Next: add and balance assertions,  Up: Data entry commands

 26.1 add
 ========
@ -8596,9 +8598,40 @@ or press control-d or control-c to exit.
   There is a detailed tutorial at https://hledger.org/add.html.


-File: hledger.info,  Node: import,  Prev: add,  Up: Data entry commands
+File: hledger.info,  Node: add and balance assertions,  Next: add and balance assignments,  Prev: add,  Up: Data entry commands

-26.2 import
+26.2 add and balance assertions
+===============================
+
+Since hledger 1.43, whenever you enter a posting amount, 'add' will
+re-check all balance assertions in the journal, and if any of them fail,
+it will report the problem and ask for the amount again.
+
+   You can also add a new balance assertion, following the amount as in
+journal format.
+
+   The new transaction's date, and the new posting's posting date if any
+(entered in a comment following the amount), will influence assertion
+checking.
+
+   You can use '-I'/'--ignore-assertions' to disable this assertion
+checking.
+
+
+File: hledger.info,  Node: add and balance assignments,  Next: import,  Prev: add and balance assertions,  Up: Data entry commands
+
+26.3 add and balance assignments
+================================
+
+You can't add new postings which are dated earlier than a balance
+assignment, currently.  It's because balance assignments are performed
+once, before 'add'; by the time 'add' runs, all amounts in the journal
+are explicit, and assignments have become assertions.  (#2406).
+
+
+File: hledger.info,  Node: import,  Prev: add and balance assignments,  Up: Data entry commands
+
+26.4 import
 ===========

 Import new transactions from one or more data files to the main journal.
@ -8636,7 +8669,7 @@ $ hledger import *.csv

 File: hledger.info,  Node: Import preview,  Next: Overlap detection,  Up: import

-26.2.1 Import preview
+26.4.1 Import preview
 ---------------------

 It's useful to preview the import by running first with '--dry-run', to
@ -8665,7 +8698,7 @@ $ hledger import bank.csv

 File: hledger.info,  Node: Overlap detection,  Next: First import,  Prev: Import preview,  Up: import

-26.2.2 Overlap detection
+26.4.2 Overlap detection
 ------------------------

 Reading CSV files is built in to hledger, and not specific to 'import';
@ -8731,7 +8764,7 @@ works:

 File: hledger.info,  Node: First import,  Next: Importing balance assignments,  Prev: Overlap detection,  Up: import

-26.2.3 First import
+26.4.3 First import
 -------------------

 The first time you import from a file, when no corresponding .latest
@ -8764,7 +8797,7 @@ newer records.

 File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: First import,  Up: import

-26.2.4 Importing balance assignments
+26.4.4 Importing balance assignments
 ------------------------------------

 Journal entries added by import will have all posting amounts made
@ -8790,7 +8823,7 @@ that and send a pull request.)

 File: hledger.info,  Node: Import and commodity styles,  Next: Import special cases,  Prev: Importing balance assignments,  Up: import

-26.2.5 Import and commodity styles
+26.4.5 Import and commodity styles
 ----------------------------------

 Amounts in entries added by import will be formatted according to the
@ -8802,7 +8835,7 @@ directives or inferred from the journal's amounts.

 File: hledger.info,  Node: Import special cases,  Prev: Import and commodity styles,  Up: import

-26.2.6 Import special cases
+26.4.6 Import special cases
 ---------------------------

 If you have a download whose file name varies, you could rename it to a
@ -13078,116 +13111,118 @@ Node: Examples 2309050
 Node: ui310074
 Node: web310211
 Node: Data entry commands310339
-Node: add310537
-Node: import312992
-Node: Import preview314026
-Node: Overlap detection314974
-Node: First import317860
-Node: Importing balance assignments319055
-Node: Import and commodity styles320110
-Node: Import special cases320548
-Node: Basic report commands321883
-Node: accounts322184
-Node: codes325117
-Node: commodities326139
-Node: descriptions326383
-Node: files326850
-Node: notes327147
-Node: payees327659
-Node: prices328443
-Node: stats329335
-Node: tags331076
-Node: Standard report commands332383
-Node: print332688
-Node: print explicitness335499
-Node: print amount style336419
-Node: print parseability337657
-Node: print other features338576
-Node: print output format339537
-Node: aregister342822
-Node: aregister and posting dates347375
-Node: register348276
-Node: Custom register output355517
-Node: balancesheet356702
-Node: balancesheetequity361667
-Node: cashflow367002
-Node: incomestatement371815
-Node: Advanced report commands376664
-Node: balance376872
-Node: balance features382293
-Node: Simple balance report384396
-Node: Balance report line format386206
-Node: Filtered balance report388566
-Node: List or tree mode389085
-Node: Depth limiting390598
-Node: Dropping top-level accounts391365
-Node: Showing declared accounts391875
-Node: Sorting by amount392605
-Node: Percentages393459
-Node: Multi-period balance report394166
-Node: Balance change end balance396918
-Node: Balance report modes398555
-Node: Calculation mode399234
-Node: Accumulation mode399938
-Node: Valuation mode401039
-Node: Combining balance report modes402383
-Node: Budget report404413
-Node: Using the budget report406713
-Node: Budget date surprises408989
-Node: Selecting budget goals410353
-Node: Budgeting vs forecasting411301
-Node: Balance report layout412978
-Node: Wide layout414183
-Node: Tall layout416588
-Node: Bare layout417894
-Node: Tidy layout419958
-Node: Balance report output421502
-Node: Some useful balance reports422276
-Node: roi423536
-Node: Spaces and special characters in --inv and --pnl425783
-Node: Semantics of --inv and --pnl426509
-Node: IRR and TWR explained428596
-Node: Chart commands432007
-Node: activity432188
-Node: Data generation commands432685
-Node: close432891
-Node: close --clopen435454
-Node: close --close437628
-Node: close --open438152
-Node: close --assert438402
-Node: close --assign438729
-Node: close --retain439408
-Node: close customisation440265
-Node: close and balance assertions441909
-Node: close examples443431
-Node: Retain earnings443668
-Node: Migrate balances to a new file444171
-Node: More detailed close examples445533
-Node: rewrite445755
-Node: Re-write rules in a file448327
-Node: Diff output format449637
-Node: rewrite vs print --auto450910
-Node: Maintenance commands451624
-Node: check451843
-Node: Basic checks452925
-Node: Strict checks453946
-Node: Other checks454883
-Node: Custom checks456635
-Node: diff457090
-Node: setup458298
-Node: test461165
-Node: PART 5 COMMON TASKS462068
-Node: Getting help462301
-Node: Constructing command lines463210
-Node: Starting a journal file464048
-Node: Setting LEDGER_FILE465432
-Node: Setting opening balances466690
-Node: Recording transactions470012
-Node: Reconciling470737
-Node: Reporting473126
-Node: Migrating to a new file477240
-Node: BUGS477689
-Node: Troubleshooting478657
+Node: add310600
+Node: add and balance assertions313075
+Node: add and balance assignments313792
+Node: import314266
+Node: Import preview315324
+Node: Overlap detection316272
+Node: First import319158
+Node: Importing balance assignments320353
+Node: Import and commodity styles321408
+Node: Import special cases321846
+Node: Basic report commands323181
+Node: accounts323482
+Node: codes326415
+Node: commodities327437
+Node: descriptions327681
+Node: files328148
+Node: notes328445
+Node: payees328957
+Node: prices329741
+Node: stats330633
+Node: tags332374
+Node: Standard report commands333681
+Node: print333986
+Node: print explicitness336797
+Node: print amount style337717
+Node: print parseability338955
+Node: print other features339874
+Node: print output format340835
+Node: aregister344120
+Node: aregister and posting dates348673
+Node: register349574
+Node: Custom register output356815
+Node: balancesheet358000
+Node: balancesheetequity362965
+Node: cashflow368300
+Node: incomestatement373113
+Node: Advanced report commands377962
+Node: balance378170
+Node: balance features383591
+Node: Simple balance report385694
+Node: Balance report line format387504
+Node: Filtered balance report389864
+Node: List or tree mode390383
+Node: Depth limiting391896
+Node: Dropping top-level accounts392663
+Node: Showing declared accounts393173
+Node: Sorting by amount393903
+Node: Percentages394757
+Node: Multi-period balance report395464
+Node: Balance change end balance398216
+Node: Balance report modes399853
+Node: Calculation mode400532
+Node: Accumulation mode401236
+Node: Valuation mode402337
+Node: Combining balance report modes403681
+Node: Budget report405711
+Node: Using the budget report408011
+Node: Budget date surprises410287
+Node: Selecting budget goals411651
+Node: Budgeting vs forecasting412599
+Node: Balance report layout414276
+Node: Wide layout415481
+Node: Tall layout417886
+Node: Bare layout419192
+Node: Tidy layout421256
+Node: Balance report output422800
+Node: Some useful balance reports423574
+Node: roi424834
+Node: Spaces and special characters in --inv and --pnl427081
+Node: Semantics of --inv and --pnl427807
+Node: IRR and TWR explained429894
+Node: Chart commands433305
+Node: activity433486
+Node: Data generation commands433983
+Node: close434189
+Node: close --clopen436752
+Node: close --close438926
+Node: close --open439450
+Node: close --assert439700
+Node: close --assign440027
+Node: close --retain440706
+Node: close customisation441563
+Node: close and balance assertions443207
+Node: close examples444729
+Node: Retain earnings444966
+Node: Migrate balances to a new file445469
+Node: More detailed close examples446831
+Node: rewrite447053
+Node: Re-write rules in a file449625
+Node: Diff output format450935
+Node: rewrite vs print --auto452208
+Node: Maintenance commands452922
+Node: check453141
+Node: Basic checks454223
+Node: Strict checks455244
+Node: Other checks456181
+Node: Custom checks457933
+Node: diff458388
+Node: setup459596
+Node: test462463
+Node: PART 5 COMMON TASKS463366
+Node: Getting help463599
+Node: Constructing command lines464508
+Node: Starting a journal file465346
+Node: Setting LEDGER_FILE466730
+Node: Setting opening balances467988
+Node: Recording transactions471310
+Node: Reconciling472035
+Node: Reporting474424
+Node: Migrating to a new file478538
+Node: BUGS478987
+Node: Troubleshooting479955

 End Tag Table

--- a/hledger/hledger.txt
+++ b/hledger/hledger.txt
@ -6911,6 +6911,26 @@ Data entry commands

       There is a detailed tutorial at https://hledger.org/add.html.

+   add and balance assertions
+       Since hledger 1.43, whenever you  enter  a  posting  amount,  add  will
+       re-check  all  balance  assertions  in  the journal, and if any of them
+       fail, it will report the problem and ask for the amount again.
+
+       You can also add a new balance assertion, following the  amount  as  in
+       journal format.
+
+       The  new  transaction's date, and the new posting's posting date if any
+       (entered in a comment following the amount), will  influence  assertion
+       checking.
+
+       You can use -I/--ignore-assertions to disable this assertion checking.
+
+   add and balance assignments
+       You  can't  add new postings which are dated earlier than a balance as-
+       signment, currently.  It's because balance  assignments  are  performed
+       once,  before add; by the time add runs, all amounts in the journal are
+       explicit, and assignments have become assertions.  (#2406).
+
   import
       Import new transactions from one or more data files to the  main  jour-
       nal.