;doc:close: improvements

hledger/Hledger/Cli/Commands/Close.md

@@ -4,50 +4,57 @@
 
 A transaction-generating command which generates several kinds of "closing"
 and/or "opening" transactions useful in certain situations.
-It prints one or two transactions to stdout, but does not write them to the journal automatically.
+It prints one or two transactions to stdout, but does not write them to the journal file;
+you can append or copy them there when you are happy with the output.
 
 *(experimental)*
 
 _FLAGS
 
+<!-- related:  -->
+
 This command is most often used when migrating balances to a new
 journal file, at the start of a new financial year. There are a few
-ways to do that, we're not sure which is best, and this command has
-other uses as well; so it currently has six modes, selected by a mode
-flag. Use only one of these flags at a time:
+ways to do that, we're not sure which is best, and this command is
+also a sort of general "balance mover"; so it currently has six modes,
+selected by a mode flag. Use only one of these flags at a time:
 
 1. With `--close` (or no mode flag) it prints a "closing balances" transaction
-that zeroes out all the ALE (asset, liability, equity) accounts, by default
-(this requires inferred or declared [account types](hledger.md#account-types));
-or, the accounts matched by ACCTQUERY arguments you provide.
-The balances are transferred to an equity account.
+that zeroes out all the asset, liability, and equity account balances, by default
+(this requires inferred or declared [account types](hledger.md#account-types)).
+Or, it will zero out the accounts matched by any ACCTQUERY arguments you provide.
+All of the balances are transferred to a special "opening/closing balances" equity account.
 
 2. With `--open`, it prints an opposite "opening balances" transaction that
 "unzeros" the same accounts, restoring their balances from zero.
 (This mode is similar to Ledger's equity command.)
 
-3. With `--migrate`, it prints both the `--close` and the `--open` transactions.
+3. With `--migrate`, it prints both the closing and opening transactions above.
 This is a common way to migrate balances to a new file at year end;
-run `hledger close --migrate` (or `hledger close --close` and `hleddger close --open`)
-and add the closing transaction at the end of the old file,
+run `hledger close --migrate -e NEWYEAR` and add the closing transaction at the end of the old file,
 and the opening transaction at the start of the new file.
-This allows you to use the new file by itself, or together with previous file(s),
-and still get correct balances either way, 
-because the matching closing/opening transactions will cancel each other out.
-(You will need to exclude them sometimes, eg to see an end of year balance sheet;
-`not:opening/closing` often works.)
+Doing this means you can include past year files in your reports at any time
+without disturbing asset/liability/equity balances,
+because the closing balances transaction cancels out the following opening balances transaction.
+You will sometimes need to exclude these transactions from reports, eg to see an end of year balance sheet;
+a `not:opening/closing` query argument should do.
+You should probably also use this query when `close`-ing, to exclude the "opening/closing balances" account
+which might otherwise [cause problems](https://www.reddit.com/r/plaintextaccounting/comments/18zxlbn/hledger_year_closing/).
+Or you can just migrate assets and liabilities: `hledger close type:AL`.
+Most people don't need to migrate equity.
+And revenues and expenses usually should not be migrated.
 
 4. With `--assert` it prints a "closing balances" transaction that
 just asserts the current balances, without changing them.
+This can be useful as documention and to guard against errors and changes.
 
 5. With `--assign` it prints an "opening balances" transaction that
-restores the account balances by using balance assignments,
-which always succeed and do need to be preceded by a closing transaction.
-This is an alternative to `--close` and `--open`: at year end
-you can `--assert` in the old file and `--assign` in the new file;
-(or skip the `--assert` and just do the `--assign`).
-This sacrifices some error checking, but could be convenient if you are
-often doing cleanups or fixes which break your closing/opening transactions.
+restores the account balances using [balance assignments](#balance-assignments).
+Balance assignments work regardless of any previous balance, so a preceding closing balances transaction is not needed.
+This is an alternative to `--close` and `--open`: at year end,
+`hledger close --assert -e NEWYEAR` in the old file (optional, but useful for error checking),
+and `hledger close --assign -e NEWYEAR` in the new file.
+This might be more convenient, eg if you are often doing cleanups or fixes which would break closing/opening transactions.
 
 6. With `--retain`, it prints a "retain earnings" transaction that transfers
 RX (revenue and expense) balances to `equity:retained earnings`.
@@ -55,10 +62,10 @@ This is a traditional end-of-period bookkeeping operation also called "closing t
 in personal accounting you probably will not need this but it could be useful
 if you want to see the accounting equation (A=L+E) balanced.
 
-In all modes, the defaults can be overridden:
+In all modes, the following things can be overridden:
 
 - the transaction descriptions can be changed with `--close-desc=DESC` and `--open-desc=DESC`
-- the account to transfer to/from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT`
+- the account to transfer to and from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT`
 - the accounts to be closed/opened can be changed with `ACCTQUERY` (account query arguments).
 - the closing/opening dates can be changed with `-e DATE` (a report end date)