Merge branch 'master' into v2.7a

1 files changed, 115 insertions, 1 deletions

diff --git a/NEWS b/NEWS
index ac56c581..cd95ed87 100644
--- a/NEWS
+++ b/NEWS
@@ -2,7 +2,121 @@
 
 * 2.6.1
 
-- This version has no new features, it's all bug fixes.
+- Added the concept of "balance setting transactions":
+
+  # Setting an account's balance
+
+  You can now manually set an account's balance to whatever you want, at
+  any time.  Here's how it might look at the beginning of your Ledger
+  file:
+
+    2008/07/27 Starting fresh
+        Assets:Checking      = $1,000.00
+        Equity:Opening Balances
+
+  If Assets:Checking is empty, this is no different from omitting the
+  "=".  However, if Assets:Checking did have a prior balance, the amount
+  of the transaction will be auto-calculated so that the final balance
+  of Assets:Checking is now $1,000.00.
+
+  Let me give an example of this.  Say you have this:
+
+    2008/07/27 Starting fresh
+        Assets:Checking          $750.00
+        Equity:Opening Balances
+  
+    2008/07/27 Starting fresh
+        Assets:Checking      = $1,000.00
+        Equity:Adjustments
+
+  These two entries are exactly equivalent to these two:
+
+    2008/07/27 Starting fresh
+        Assets:Checking          $750.00
+        Equity:Opening Balances
+  
+    2008/07/27 Starting fresh
+        Assets:Checking          $250.00
+        Equity:Adjustments
+
+  The use of the "=" sign here is that it sets the transaction's amount
+  to whatever is required to satisfy the assignment.  This is the
+  behavior if the transaction's amount is left empty.
+
+  # Multiple commodities
+
+  As far as commodities go, the = sign only works if the account
+  balance's commodity matches the commodity of the amount after the
+  equals sign.  However, if the account has multiple commodities, only
+  the matching commodity is affected.  Here's what I mean:
+
+    2008/07/24 Opening Balance
+        Assets:Checking        = $250.00            ; we force set it
+        Equity:Opening Balances
+  
+    2008/07/24 Opening Balance
+        Assets:Checking      = EC 250.00          ; we force set it again
+        Equity:Opening Balances
+
+  This is an error, because $250.00 cannot be auto-balanced to match EC
+  250.00.  However:
+
+    2008/07/24 Opening Balance
+        Assets:Checking        = $250.00          ; we force set it again
+        Assets:Checking        EC 100.00          ; and add some EC's
+        Equity:Opening Balances
+  
+    2008/07/24 Opening Balance
+        Assets:Checking      = EC 250.00          ; we force set the EC's
+        Equity:Opening Balances
+
+  This is *not* an error, because the latter auto-balancing transaction
+  only affects the EC 100.00 part of the account's balance; the $250.00
+  part is left alone.
+
+  # Checking statement balances
+
+  When you reconcile a statement, there are typically one or more
+  transactions which result in a known balance.  Here's how you specify
+  that in your Ledger data:
+
+    2008/07/24 Opening Balance
+        Assets:Checking        = $100.00
+        Equity:Opening Balances
+  
+    2008/07/30 We spend money, with a known balance afterward
+        Expenses:Food             $20.00
+        Assets:Checking         = $80.00
+  
+    2008/07/30 Again we spend money, but this time with all the info
+        Expenses:Food             $20.00
+        Assets:Checking          $-20.00 = $60.00
+  
+    2008/07/30 This entry yield an 'unbalanced' error
+        Expenses:Food             $20.00
+        Assets:Checking          $-20.00 = $30.00
+
+  The last entry in this set fails to balance with an unbalanced
+  remainder of $-10.00.  Either the entry must be corrected, or you can
+  have Ledger deal with the remainder automatically:
+
+  2008/07/30 The fixed entry
+      Expenses:Food              $20.00
+      Assets:Checking           $-20.00 = $30.00
+      Equity:Adjustments
+
+  # Conclusion
+
+  This simple feature has all the utility of @check, plus auto-balancing
+  to match known target balances, plus the ability to guarantee that an
+  account which uses only one commodity does contain only that
+  commodity.
+
+  This feature slows down textual parsing slightly, does not affect
+  speed when loading from the binary cache.
+
+- The rest of the changes in the version is all bug fixes (around 45 of
+  them).
 
 * 2.6.0.90