equity: improve help, note limitations, ignore --date2

Try to make this less confusing.

hledger/Hledger/Cli/Commands/Equity.hs

@@ -18,40 +18,45 @@ equitymode = hledgerCommandMode
 Print a "closing balances" transaction that brings all accounts (or with
 query arguments, just the matched accounts) to a zero balance, followed by an
 opposite "opening balances" transaction that restores the balances from zero.
-Such transactions can be useful, eg, for bringing account balances across
-file boundaries.
 
 FLAGS
 
-The opening balances transaction is useful to carry over
+The opening transaction is useful to carry over asset/liability balances 
-asset/liability balances if you choose to start a new journal file,
+if you choose to start a new journal file, eg yearly. The closing transaction
-eg at the beginning of the year.
+can be a useful complement, allowing you to optionally include old files 
+(for more history) without disturbing the asset/liability balances 
+(since the closing/opening pairs cancel out).
 
-The closing balances transaction is useful to zero out balances in
+This command may also be useful for closing out expense/income accounts 
-the old file, which gives you the option of reporting on both files
+for a period (ie "closing the books" in accounting).
-at once while still seeing correct balances.
 
-Balances are calculated, and the opening transaction is dated, as of
+The closing transaction asserts a zero balance for each closed account.
-the report end date, which you should specify with -e or date: (and
-the closing transaction is dated one day earlier). If a report end
-date is not specified, it defaults to today.
 
-Example:
+By default, the closing transaction is dated yesterday, with balances 
-```shell
+calculated as of end of yesterday, and the opening transaction is dated today.
-$ hledger equity -f 2015.journal -e 2016/1/1 assets liabilities >>2015.journal
+To close on some other date, use: `hledger close -e OPENINGDATE ...`
-# move the opening balances transaction to 2016.journal
+
-$ hledger -f 2015.journal bal assets liabilities not:desc:closing # shows correct 2015 balances
+For example, carrying asset/liability balances into a new file for 2018:
-$ hledger -f 2016.journal bal assets liabilities                  # shows correct 2016 balances
-$ hledger -f 2015.journal -f 2016.journal bal assets liabilities  # still shows correct 2016 balances
 ```
-Open question: how to handle txns spanning a file boundary ? Eg:
+$ hledger equity -f 2017.journal -e 2018/1/1 ^assets ^liab >>2017.journal
-```journal
+# cut & paste the opening transaction from 2017.journal to a new 2018.journal
-2015/12/30 * food
+# now:
-    expenses:food:dining   $10
+$ hledger bs -f 2018.journal                   # correct balances
-    assets:bank:checking  -$10  ; date:2016/1/4
+$ hledger bs -f 2018.journal -f 2017.journal   # still correct
+$ hledger bs -f 2017.journal not:desc:closing  # must exclude closing txn 
+```
+
+Possible issues/complications/todos:
+- -p or date: should work as well as -e, but can be buggy
+- a begin date should have no effect. Closed balances should be historical.
+- transactions on the opening date should be excluded from closed balances 
+- balance assertions can fail due to filtering by status or realness
+- transactions spanning a file boundary, eg:
+```
+2017/12/31
+    expenses:food          1
+    assets:bank:checking  -1  ; date:2018/1/1
 ```
-This command might or might not have some connection to the concept of
-"closing the books" in accounting.
   |]
   []
   [generalflagsgroup1]
@@ -60,8 +65,12 @@ This command might or might not have some connection to the concept of
 
 equity CliOpts{reportopts_=ropts} j = do
   today <- getCurrentDay
-  let ropts_ = ropts{accountlistmode_=ALFlat}
+  let 
+      -- TODO: this query is sometimes wrong 
+      ropts_ = ropts{accountlistmode_=ALFlat}
       q = queryFromOpts today ropts_
+      openingdate = fromMaybe today $ queryEndDate False q
+      closingdate = addDays (-1) openingdate
       (acctbals,_) = balanceReport ropts_ q j
       balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmountSquashPricesForDisplay b) acctbals
       ps = [posting{paccount=a
@@ -72,7 +81,6 @@ equity CliOpts{reportopts_=ropts} j = do
            ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb
            ]
            ++ [posting{paccount="equity:opening balances", pamount=balancingamt}]
-      enddate = fromMaybe today $ queryEndDate (date2_ ropts_) q
       nps = [posting{paccount=a
                     ,pamount=mixed [negate b]
                     ,pbalanceassertion=Just (b{aquantity=0}, nullsourcepos)
@@ -81,5 +89,5 @@ equity CliOpts{reportopts_=ropts} j = do
             ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb
             ]
            ++ [posting{paccount="equity:closing balances", pamount=negate balancingamt}]
-  putStr $ showTransaction (nulltransaction{tdate=addDays (-1) enddate, tdescription="closing balances", tpostings=nps})
+  putStr $ showTransaction (nulltransaction{tdate=closingdate, tdescription="closing balances", tpostings=nps})
-  putStr $ showTransaction (nulltransaction{tdate=enddate, tdescription="opening balances", tpostings=ps})
+  putStr $ showTransaction (nulltransaction{tdate=openingdate, tdescription="opening balances", tpostings=ps})