;doc: update command help

hledger/Hledger/Cli/Commands/Add.txt

@@ -63,5 +63,8 @@ Saved.
 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
 Date [2015/05/22]: <CTRL-D> $
 
-On Microsoft Windows, the add command makes sure that no part of the
+If you enter a number with no commodity symbol, and you have declared a
-file path ends with a period, as that would cause problems (#1056).
+default commodity with a D directive, you might expect add to add this
+symbol for you. It does not do this; we assume that if you are using a D
+directive you prefer not to see the commodity symbol repeated on amounts
+in the journal.

hledger/Hledger/Cli/Commands/Balance.txt

@@ -332,7 +332,7 @@ Notes:
 -   Accounts (rows) containing all zeroes are not shown, unless
     -E/--empty is used.
 -   Amounts with many commodities are shown in abbreviated form, unless
-    --no-elide is used. (experimental)
+    --no-elide is used.
 -   Average and/or total columns can be added with the -A/--average and
     -T/--row-total flags.
 -   The --transpose flag can be used to exchange rows and columns.

hledger/Hledger/Cli/Commands/Balancesheet.txt

@@ -41,5 +41,4 @@ It is similar to hledger balance -H assets liabilities, but with smarter
 account detection, and liabilities displayed with their sign flipped.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, tsv, html, and
+options The output formats supported are txt, csv, tsv, html, and json.
-(experimental) json.

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -47,5 +47,4 @@ hledger balance assets not:fixed not:investment not:receivable, but with
 smarter account detection.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, tsv, html, and
+options The output formats supported are txt, csv, tsv, html, and json.
-(experimental) json.

hledger/Hledger/Cli/Commands/Close.txt

@@ -2,50 +2,76 @@ close
 
 (equity)
 
-Generate transactions which transfer account balances to and/or from
+A transaction-generating command which generates several kinds of
-another account (typically equity). This can be useful for migrating
+"closing" and/or "opening" transactions useful in certain situations. It
-balances to a new journal file, or for merging earnings into equity at
+prints one or two transactions to stdout, but does not write them to the
-end of accounting period.
+journal file; you can append or copy them there when you are happy with
-
+the output.
-By default, it prints a transaction that zeroes out ALE accounts (asset,
-liability, equity accounts; this requires account types to be
-configured); or if ACCTQUERY is provided, the accounts matched by that.
-
-(experimental)
 
 _FLAGS
 
-This command has four main modes, corresponding to the most common use
+This command is most often used when migrating balances to a new journal
-cases:
+file, at the start of a new financial year. It can also be used to
+"retain earnings" (transfer revenues and expenses to equity), or as a
+sort of generic mover of balances from any group of accounts to some
+other account. So it currently has six modes, selected by a mode flag.
+Use only one of these flags at a time:
 
-1.  With --close (default), it prints a "closing balances" transaction
+1.  With --close (or no mode flag) it prints a "closing balances"
-    that zeroes out ALE (asset, liability, equity) accounts by default
+    transaction that zeroes out all the asset, liability, and equity
-    (this requires account types to be inferred or declared); or, the
+    account balances, by default (this requires inferred or declared
-    accounts matched by the provided ACCTQUERY arguments.
+    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 restores those balances from zero. This is similar to Ledger's
+    that restores the same account balances, starting from zero. This
-    equity command.
+    mode is similar to Ledger's equity command.
 
-3.  With --migrate, it prints both the closing and opening transactions.
+3.  With --migrate, it prints both the closing and opening transactions
-    This is the preferred way to migrate balances to a new file: run
+    above. This is a common way to migrate balances to a new file at
-    hledger close --migrate, add the closing transaction at the end of
+    year end; run hledger close --migrate -e NEWYEAR (-e influences the
-    the old file, and add the opening transaction at the start of the
+    transaction date) and add the closing transaction at the end of the
-    new file. The matching closing/opening transactions cancel each
+    old file, and the opening transaction at the start of the new file.
-    other out, preserving correct balances during multi-file reporting.
+    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. 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 --retain, it prints a "retain earnings" transaction that
+4.  With --assert it prints a "closing balances" transaction that just
-    transfers RX (revenue and expense) balances to
+    asserts the current balances, without changing them. This can be
-    equity:retained earnings. Businesses traditionally do this at the
+    useful as documention and to guard against errors and changes.
-    end of each accounting period; it is less necessary with
-    computer-based accounting, but it could still be useful if you want
-    to see the accounting equation (A=L+E) satisfied.
 
-In all modes, the defaults can be overridden:
+5.  With --assign it prints an "opening balances" transaction that
+    restores the account balances using 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 revenue and expense balances to equity:retained earnings.
+    This is a traditional end-of-period bookkeeping operation also
+    called "closing the books"; 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 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
+-   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).

hledger/Hledger/Cli/Commands/Incomestatement.txt

@@ -43,5 +43,4 @@ smarter account detection, and revenues/income displayed with their sign
 flipped.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, tsv, html, and
+options The output formats supported are txt, csv, tsv, html, and json.
-(experimental) json.

hledger/Hledger/Cli/Commands/Print.txt

@@ -108,8 +108,8 @@ This command also supports the output destination and output format
 options The output formats supported are txt, beancount, csv, tsv, json
 and sql.
 
-Experimental: The beancount format tries to produce Beancount-compatible
+The beancount format tries to produce Beancount-compatible output, as
-output, as follows:
+follows:
 
 -   Transaction and postings with unmarked status are converted to
     cleared (*) status.

hledger/Hledger/Cli/Commands/Register.txt

@@ -125,5 +125,4 @@ $ hledger reg -w 100,40           # set overall width 100, description width 40
 $ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, tsv, and
+options The output formats supported are txt, csv, tsv, and json.
-(experimental) json.