;dev: doc: update CLI usage texts

hledger/Hledger/Cli/Commands/Close.txt

@@ -1,96 +1,192 @@
 close, equity
-Prints a "closing balances" transaction and an "opening balances"
+Prints a sample "closing" transaction bringing specified account
-transaction that bring account balances to and from zero, respectively.
+balances to zero, and an inverse "opening" transaction restoring the
-These can be added to your journal file(s), eg to bring asset/liability
+same account balances.
-balances forward into a new journal file, or to close out
+
-revenues/expenses to retained earnings at the end of a period.
+If like most people you split your journal files by time, eg by year: at
+the end of the year you can use this command to "close out" your asset
+and liability (and perhaps equity) balances in the old file, and
+reinitialise them in the new file. This helps ensure that report
+balances remain correct whether you are including old files or not.
+(Because all closing/opening transactions except the very first will
+cancel out - see example below.)
+
+Some people also use this command to close out revenue and expense
+balances at the end of an accounting period. This properly records the
+period's profit/loss as "retained earnings" (part of equity), and allows
+the accounting equation (A-L=E) to balance, which you could then check
+by the bse report's zero total.
 
 _FLAGS
 
-You can print just one of these transactions by using the --close or
+You can print just the closing transaction by using the --close flag, or
---open flag. You can customise their descriptions with the --close-desc
+just the opening transaction with the --open flag.
-and --open-desc options.
 
-One amountless posting to "equity:opening/closing balances" is added to
+Their descriptions are closing balances and opening balances by default;
-balance the transactions, by default. You can customise this account
+you can customise these with the --close-desc and --open-desc options.
-name with --close-acct and --open-acct; if you specify only one of
-these, it will be used for both.
 
-With --x/--explicit, the equity posting's amount will be shown. And if
+Just one balancing equity posting is used by default, with the amount
-it involves multiple commodities, a posting for each commodity will be
+left implicit. The default account name is
-shown, as with the print command.
+equity:opening/closing balances. You can customise the account name(s)
+with --close-acct and --open-acct. (If you specify only one of these, it
+will be used for both.)
 
-With --interleaved, the equity postings are shown next to the postings
+With --x/--explicit, the equity posting's amount will be shown
-they balance, which makes troubleshooting easier.
+explicitly, and if it involves multiple commodities, there will be a
+separate equity posting for each commodity (as in the print command).
 
-By default, transaction prices in the journal are ignored when
+With --interleaved, each equity posting is shown next to the posting it
-generating the closing/opening transactions. With --show-costs, this
+balances (good for troubleshooting).
-cost information is preserved (balance -B reports will be unchanged
-after the transition). Separate postings are generated for each cost in
-each commodity. Note this can generate very large journal entries, if
-you have many foreign currency or investment transactions.
 
-close usage
+close and prices
 
-If you split your journal files by time (eg yearly), you will typically
+Transaction prices are ignored (and discarded) by closing/opening
-run this command at the end of the year, and save the closing
+transactions, by default. With --show-costs, they are preserved; there
-transaction as last entry of the old file, and the opening transaction
+will be a separate equity posting for each cost in each commodity. This
-as the first entry of the new file. This makes the files self contained,
+means balance -B reports will look the same after the transition. Note
-so that correct balances are reported no matter which of them are
+if you have many foreign currency or investment transactions, this will
-loaded. Ie, if you load just one file, the balances are initialised
+generate very large journal entries.
-correctly; or if you load several files, the redundant closing/opening
-transactions cancel each other out. (They will show up in print or
-register reports; you can exclude them with a query like
-not:desc:'(opening|closing) balances'.)
 
-If you're running a business, you might also use this command to "close
+close date
-the books" at the end of an accounting period, transferring income
-statement account balances to retained earnings. (You may want to change
-the equity account name to something like "equity:retained earnings".)
 
-By default, the closing transaction is dated yesterday, the balances are
+The default closing date is yesterday, or the journal's end date,
-calculated as of end of yesterday, and the opening transaction is dated
+whichever is later.
-today. To close on some other date, use: hledger close -e OPENINGDATE.
-Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also
-use -p or date:PERIOD (any starting date is ignored).
 
-Both transactions will include balance assertions for the
+Unless you are running close on exactly the first day of the new period,
-closed/reopened accounts. You probably shouldn't use status or realness
+you'll want to override the closing date. This is done by specifying a
-filters (like -C or -R or status:) with this command, or the generated
+report period, where "last day of the report period" will be the closing
-balance assertions will depend on these flags. Likewise, if you run this
+date. The opening date is always the following day. So to close on
-command with --auto, the balance assertions will probably always require
+2020-12-31 and open on 2021-01-01, any of these work
---auto.
 
-Examples:
+-   -p 2020
+-   date:2020
+-   -e 2021-01-01 (remember -e specifies an exclusive end date)
+-   -e 2021
 
-Carrying asset/liability balances into a new file for 2019:
+Example: close asset/liability accounts for file transition
 
-$ hledger close -f 2018.journal -e 2019 assets liabilities --open
+Carrying asset/liability balances from 2020.journal into a new file for
-    # (copy/paste the output to the start of your 2019 journal file)
+2021:
-$ hledger close -f 2018.journal -e 2019 assets liabilities --close
-    # (copy/paste the output to the end of your 2018 journal file)
 
-Now:
+$ hledger close -f 2020.journal -p 2020 assets liabilities
+# copy/paste the closing transaction to the end of 2020.journal
+# copy/paste the opening transaction to the start of 2021.journal
 
-$ hledger bs -f 2019.journal                   # one file - balances are correct
+Or:
-$ hledger bs -f 2018.journal -f 2019.journal   # two files - balances still correct
-$ hledger bs -f 2018.journal not:desc:closing  # to see year-end balances, must exclude closing txn
 
-Transactions spanning the closing date can complicate matters, breaking
+$ hledger close -f 2020.journal -p 2020 assets liabilities --open  >> 2021.journal  # add 2021's first transaction
-balance assertions:
+$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal  # add 2020's last transaction
 
-2018/12/30 a purchase made in 2018, clearing the following year
+Now,
+
+$ hledger bs -f 2021.journal                   # just new file - balances correct
+$ hledger bs -f 2020.journal -f 2021.journal   # old and new files - balances correct
+$ hledger bs -f 2020.journal                   # just old files - balances are zero ?
+                                               # (exclude final closing txn, see below)
+
+Hiding opening/closing transactions
+
+Although the closing/opening transactions cancel out, they will be
+visible in reports like print and register, creating some visual
+clutter. You can exclude them all with a query, like:
+
+$ hledger print not:desc:'opening|closing'             # less typing
+$ hledger print not:'equity:opening/closing balances'  # more precise
+
+But when reporting on multiple files, this can get a bit tricky; you may
+need to keep the earliest opening balances, for a historical register
+report; or you may need to suppress a closing transaction, to see
+year-end balances. If you find yourself needing more precise queries,
+here's one solution: add more easily-matched tags to opening/closing
+transactions, like this:
+
+; 2019.journal
+2019-01-01 opening balances  ; earliest opening txn, no tag here
+...
+2019-12-31 closing balances  ; close:2019
+...
+
+; 2020.journal
+2020-01-01 opening balances  ; open:2020
+...
+2020-12-31 closing balances  ; close:2020
+...
+
+; 2021.journal
+2021-01-01 opening balances  ; open:2021
+...
+
+Now with
+
+; all.journal
+include 2019.journal
+include 2020.journal
+include 2021.journal
+
+you could do eg:
+
+$ hledger -f all.journal reg -H checking not:tag:'open|close'
+    # all years checking register, hiding non-essential opening/closing txns
+
+$ hledger -f all.journal bs -p 2020 not:tag:close=2020
+    # 2020 year end balances, suppressing 2020 closing txn
+
+$ hledger -f 2020.journal bs not:tag:close
+    # 2020 year end balances, easier case
+
+close and balance assertions
+
+The closing and opening transactions will include balance assertions,
+verifying that the accounts have first been reset to zero and then
+restored to their previous balance. These provide valuable error
+checking, alerting you when things get out of line, but you can ignore
+them temporarily with -I or just remove them if you prefer.
+
+You probably shouldn't use status or realness filters (like -C or -R or
+status:) with close, or the generated balance assertions will depend on
+these flags. Likewise, if you run this command with --auto, the balance
+assertions would probably always require --auto.
+
+Multi-day transactions (where some postings have a different date) break
+the balance assertions, because the money is temporarily "invisible"
+while in transit:
+
+2020/12/30 a purchase made in december, cleared in the next year
     expenses:food          5
-    assets:bank:checking  -5  ; [2019/1/2]
+    assets:bank:checking  -5  ; date: 2021/1/2
 
-Here's one way to resolve that:
+To fix the assertions, you can add a temporary account to track such
+in-transit money (splitting the multi-day transaction into two
+single-day transactions):
 
-; in 2018.journal:
+; in 2020.journal:
-2018/12/30 a purchase made in 2018, clearing the following year
+2020/12/30 a purchase made in december, cleared in the next year
     expenses:food          5
     liabilities:pending
 
-; in 2019.journal:
+; in 2021.journal:
-2019/1/2 clearance of last year's pending transactions
+2021/1/2 clearance of last year's pending transactions
     liabilities:pending    5 = 0
-    assets:checking
+    assets:bank:checking
+
+Example: close revenue/expense accounts to retained earnings
+
+Here, the opening transaction is supressed with --close, as it's
+probably not needed. Also you'll want to use a different equity account
+name:
+
+$ hledger close -f 2021.journal -p 2021Q1 --close --close-acct='equity:retained earnings' revenues expenses >> 2021.journal
+    # close 2021 first quarter revenues/expenses
+
+Or, operating on the default journal:
+
+$ hledger close -p Q1 --close --close-acct='equity:retained earnings' revenues expenses >> $LEDGER_FILE
+    # close current year's first quarter revenues/expenses
+
+Now, eg:
+
+$ hledger bse -p Q1
+    # Q1 full balance sheet, total should be zero
+
+$ hledger is -p Q1 not:'retained earnings'
+    # Q1 income statement, must suppress the closing txn