;doc: update CLI usage texts

hledger/Hledger/Cli/Commands/Accounts.txt

@@ -1,4 +1,5 @@
 accounts
+
 Show account names.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Activity.txt

@@ -1,4 +1,5 @@
 activity
+
 Show an ascii barchart of posting counts per interval.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Add.txt

@@ -1,4 +1,5 @@
 add
+
 Prompt for transactions and add them to the journal. Any arguments will
 be used as default inputs for the first N prompts.
 

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -1,4 +1,6 @@
-aregister, areg
+aregister
+
+(areg)
 
 Show the transactions and running historical balance of a single
 account, with each transaction displayed as one line.

hledger/Hledger/Cli/Commands/Balance.txt

@@ -1,4 +1,7 @@
-balance, bal
+balance
+
+(bal)
+
 Show accounts and their balances.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Balancesheet.txt

@@ -1,4 +1,7 @@
-balancesheet, bs
+balancesheet
+
+(bs)
+
 This command displays a balance sheet, showing historical ending
 balances of asset and liability accounts. (To see equity as well, use
 the balancesheetequity command.) Amounts are shown with normal positive

hledger/Hledger/Cli/Commands/Balancesheetequity.txt

@@ -1,4 +1,7 @@
-balancesheetequity, bse
+balancesheetequity
+
+(bse)
+
 This command displays a balance sheet, showing historical ending
 balances of asset, liability and equity accounts. Amounts are shown with
 normal positive sign, as in conventional financial statements.

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -1,4 +1,7 @@
-cashflow, cf
+cashflow
+
+(cf)
+
 This command displays a cashflow statement, showing the inflows and
 outflows affecting "cash" (ie, liquid, easily convertible) assets.
 Amounts are shown with normal positive sign, as in conventional

hledger/Hledger/Cli/Commands/Check.txt

@@ -1,4 +1,5 @@
 check
+
 Check for various kinds of errors in your data.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Close.txt

@@ -1,203 +1,166 @@
-close, equity
+close
-Prints a sample "closing" transaction bringing specified account
-balances to zero, and an inverse "opening" transaction restoring the
-same account balances.
 
-If like most people you split your journal files by time, eg by year: at
+close [--retain | --migrate | --open] [QUERY]
-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
+By default: prints a transaction that zeroes out ("closes") all
-balances at the end of an accounting period. This properly records the
+accounts, transferring their balances to an equity account. Query
-period's profit/loss as "retained earnings" (part of equity), and allows
+arguments can be added to override the accounts selection. Three other
-the accounting equation (A-L=E) to balance, which you could then check
+modes are supported:
-by the bse report's zero total.
+
+--retain: prints a transaction closing revenue and expense balances.
+This is traditionally done by businesses at the end of each accounting
+period; it is less necessary in personal and computer-based accounting,
+but it can help balance the accounting equation A=L+E.
+
+--migrate: prints a transaction to close asset, liability and most
+equity balances, and another transaction to re-open them. This can be
+useful when starting a new file (for performance or data protection).
+Adding the closing transaction to the old file allows old and new files
+to be combined.
+
+--open: as above, but prints just the opening transaction. This can be
+useful for starting a new file, leaving the old file unchanged. Similar
+to Ledger's equity command.
 
 _FLAGS
 
-You can print just the closing transaction by using the --close flag, or
+You can change the equity account name with --close-acct ACCT. It
-just the opening transaction with the --open flag.
+defaults to equity:retained earnings with --retain, or
+equity:opening/closing balances otherwise.
 
-Their descriptions are closing balances and opening balances by default;
+You can change the transaction description(s) with --close-desc 'DESC'
-you can customise these with the --close-desc and --open-desc options.
+and --open-desc 'DESC'. It defaults to retain earnings with --retain, or
+closing balances and opening balances otherwise.
 
-Just one balancing equity posting is used by default, with the amount
+Just one posting to the equity account will be used by default, with an
-left implicit. The default account name is
+implicit amount.
-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 --x/--explicit, the equity posting's amount will be shown
+With --x/--explicit the amount will be shown explicitly, and if it
-explicitly, and if it involves multiple commodities, there will be a
+involves multiple commodities, a separate posting will be generated for
-separate equity posting for each commodity (as in the print command).
+each commodity.
 
-With --interleaved, each equity posting is shown next to the posting it
+With --interleaved, each equity posting is shown next to the
-balances (good for troubleshooting).
+corresponding source/destination posting.
+
+The default closing date is yesterday or the journal's end date,
+whichever is later. You can change this by specifying a report end date;
+the last day of the report period will be the closing date. Eg -e 2022
+means "close on 2022-12-31".
+
+The default closing date is yesterday, or the journal's end date,
+whichever is later. You can change this by specifying a report end date;
+(The report start date does not matter.) The last day of the report
+period will be the closing date; eg -e 2022 means "close on 2022-12-31".
+The opening date is always the day after the closing date.
 
 close and costs
 
-Costs are ignored (and discarded) by closing/opening transactions, by
+With --show-costs, any amount costs are shown, with separate postings
-default. With --show-costs, they are preserved; there will be a separate
+for each cost. (This currently the best way to view investment assets,
-equity posting for each cost in each commodity. This means balance -B
+showing lots and cost bases.) If you have many currency conversion or
-reports will look the same after the transition. Note if you have many
+investment transactions, it can generate very large journal entries.
-foreign currency or investment transactions, this will generate very
-large journal entries.
-
-close date
-
-The default closing date is yesterday, or the journal's end date,
-whichever is later.
-
-Unless you are running close on exactly the first day of the new period,
-you'll want to override the closing date. This is done by specifying a
-report end date, where "last day of the report period" will be the
-closing date. The opening date is always the following day. So to close
-on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these
-will work:
-
-  -----------------------------------------------------------------------
-  end date        explanation
-  argument        
-  --------------- -------------------------------------------------------
-  -e 2021-01-01   end dates are exclusive
-
-  -e 2021         equivalent, per smart dates
-
-  -p 2020         equivalent, the period's begin date is ignored
-
-  date:2020       equivalent query
-  -----------------------------------------------------------------------
-
-Example: close asset/liability accounts for file transition
-
-Carrying asset/liability balances from 2020.journal into a new file for
-2021:
-
-$ 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
-
-Or:
-
-$ hledger close -f 2020.journal -p 2020 assets liabilities --open  >> 2021.journal  # add 2021's first transaction
-$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal  # add 2020's last transaction
-
-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  ; clopen:2020
-...
-
-; 2020.journal
-2020-01-01 opening balances  ; clopen:2020
-...
-2020-12-31 closing balances  ; clopen:2021
-...
-
-; 2021.journal
-2021-01-01 opening balances  ; clopen: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:clopen
-    # all years checking register, hiding non-essential opening/closing txns
-
-$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020
-    # 2020 year end balances, suppressing 2020 closing txn
 
 close and balance assertions
 
-The closing and opening transactions will include balance assertions,
+Balance assertions will be generated, verifying that the accounts have
-verifying that the accounts have first been reset to zero and then
+been reset to zero (and then restored to their previous balances, if
-restored to their previous balance. These provide valuable error
+there is an opening transaction).
-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
+These provide useful error checking, but you can ignore them temporarily
-status:) with close, or the generated balance assertions will depend on
+with -I, or remove them if you prefer.
-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
+You probably should avoid filtering transactions by status or realness
-the balance assertions, because the money is temporarily "invisible"
+(-C, -R, status:), or generating postings (--auto), with this command,
-while in transit:
+since the balance assertions would depend on these.
 
-2020/12/30 a purchase made in december, cleared in the next year
+Note custom posting dates spanning the file boundary will disrupt the
+balance assertions:
+
+2023-12-30 a purchase made in december, cleared in january
     expenses:food          5
-    assets:bank:checking  -5  ; date: 2021/1/2
+    assets:bank:checking  -5  ; date: 2023-01-02
 
-To fix the assertions, you can add a temporary account to track such
+To solve that you can transfer the money to and from a temporary
-in-transit money (splitting the multi-day transaction into two
+account, in effect splitting the multi-day transaction into two
-single-day transactions):
+single-day transactions:
 
-; in 2020.journal:
+; in 2022.journal:
-2020/12/30 a purchase made in december, cleared in the next year
+2022-12-30 a purchase made in december, cleared in january
     expenses:food          5
-    liabilities:pending
+    equity:pending        -5
 
-; in 2021.journal:
+; in 2023.journal:
-2021/1/2 clearance of last year's pending transactions
+2023-01-02 last year's transaction cleared
-    liabilities:pending    5 = 0
+    equity:pending         5 = 0
-    assets:bank:checking
+    assets:bank:checking  -5
 
-Example: close revenue/expense accounts to retained earnings
+Example: retain earnings
 
-For this, use --close to suppress the opening transaction, as it's not
+Record 2022's revenues/expenses as retained earnings on 2022-12-31,
-needed. Also you'll want to change the equity account name to your
+appending the generated transaction to the journal:
-equivalent of "equity:retained earnings".
 
-Closing 2021's first quarter revenues/expenses:
+$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
 
-$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \
+Now 2022's income statement will show only zeroes. To see it again,
-    --close-acct='equity:retained earnings' >> 2021.journal
+exclude the retain transaction. Eg:
 
-The same, using the default journal and current year:
+$ hledger -f 2022.journal is not:desc:'retain earnings'
 
-$ hledger close --close revenues expenses -p Q1 \
+Example: migrate balances to a new file
-    --close-acct='equity:retained earnings' >> $LEDGER_FILE
 
-Now, the first quarter's balance sheet should show a zero (unless you
+Close assets/liabilities/equity on 2022-12-31 and re-open them on
-are using @/@@ notation without equity postings):
+2023-01-01:
 
-$ hledger bse -p Q1
+$ hledger close --migrate -f 2022.journal -p 2022
+# copy/paste the closing transaction to the end of 2022.journal
+# copy/paste the opening transaction to the start of 2023.journal
 
-And we must suppress the closing transaction to see the first quarter's
+Now 2022's balance sheet will show only zeroes, indicating a balanced
-income statement (using the description; not:'retained earnings' won't
+accounting equation. (Unless you are using @/@@ notation - in that case,
-work here):
+try adding --infer-equity.) To see it again, exclude the closing
+transaction. Eg:
 
-$ hledger is -p Q1 not:desc:'closing balances'
+$ hledger -f 2022.journal bs not:desc:'closing balances'
+
+Example: excluding closing/opening transactions
+
+When combining many files for multi-year reports, the closing/opening
+transactions cause some noise in reports like print and register. You
+can exclude them as shown above, but not:desc:... could be fragile, and
+also you will need to avoid excluding the very first opening
+transaction, which can be awkward. Here is a way to do it, using tags:
+add clopen: tags to all opening/closing balances transactions except the
+first, like this:
+
+; 2021.journal
+2021-06-01 first opening balances
+...
+2021-12-31 closing balances  ; clopen:2022
+...
+
+; 2022.journal
+2022-01-01 opening balances  ; clopen:2022
+...
+2022-12-31 closing balances  ; clopen:2023
+...
+
+; 2023.journal
+2023-01-01 opening balances  ; clopen:2023
+...
+
+Now, assuming a combined journal like:
+
+; all.journal
+include 2021.journal
+include 2022.journal
+include 2023.journal
+
+The clopen: tag can exclude all but the first opening transaction. To
+show a clean multi-year checking register:
+
+$ hledger -f all.journal areg checking not:tag:clopen
+
+And the year values allow more precision. To show 2022's year-end
+balance sheet:
+
+$ hledger -f all.journal bs -e2023 not:tag:clopen=2023

hledger/Hledger/Cli/Commands/Codes.txt

@@ -1,4 +1,5 @@
 codes
+
 List the codes seen in transactions, in the order parsed.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Commodities.txt

@@ -1,4 +1,5 @@
 commodities
+
 List all commodity/currency symbols used or declared in the journal.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Descriptions.txt

@@ -1,4 +1,5 @@
 descriptions
+
 List the unique descriptions that appear in transactions.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Diff.txt

@@ -1,4 +1,5 @@
 diff
+
 Compares a particular account's transactions in two input files. It
 shows any transactions to this account which are in one file but not in
 the other.

hledger/Hledger/Cli/Commands/Files.txt

@@ -1,4 +1,5 @@
 files
+
 List all files included in the journal. With a REGEX argument, only file
 names matching the regular expression (case sensitive) are shown.
 

hledger/Hledger/Cli/Commands/Help.txt

@@ -1,4 +1,5 @@
 help
+
 Show the hledger user manual in the terminal, with info, man, or a
 pager. With a TOPIC argument, open it at that topic if possible. TOPIC
 can be any heading in the manual, or a heading prefix, case insensitive.

hledger/Hledger/Cli/Commands/Import.txt

@@ -1,4 +1,5 @@
 import
+
 Read new transactions added to each FILE since last run, and add them to
 the journal. Or with --dry-run, just print the transactions that would
 be added. Or with --catchup, just mark all of the FILEs' transactions as

hledger/Hledger/Cli/Commands/Incomestatement.txt

@@ -1,4 +1,7 @@
-incomestatement, is
+incomestatement
+
+(is)
+
 This command displays an income statement, showing revenues and expenses
 during one or more periods. Amounts are shown with normal positive sign,
 as in conventional financial statements.

hledger/Hledger/Cli/Commands/Notes.txt

@@ -1,4 +1,5 @@
 notes
+
 List the unique notes that appear in transactions.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Payees.txt

@@ -1,4 +1,5 @@
 payees
+
 List the unique payee/payer names that appear in transactions.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Prices.txt

@@ -1,4 +1,5 @@
 prices
+
 Print market price directives from the journal. With
 --infer-market-prices, generate additional market prices from costs.
 With --infer-reverse-prices, also generate market prices by inverting

hledger/Hledger/Cli/Commands/Print.txt

@@ -1,4 +1,5 @@
 print
+
 Show transaction journal entries, sorted by date.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Register.txt

@@ -1,4 +1,7 @@
-register, reg
+register
+
+(reg)
+
 Show postings and their running total.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Rewrite.txt

@@ -1,4 +1,5 @@
 rewrite
+
 Print all transactions, rewriting the postings of matched transactions.
 For now the only rewrite available is adding new postings, like print
 --auto.

hledger/Hledger/Cli/Commands/Roi.txt

@@ -1,4 +1,5 @@
 roi
+
 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on
 your investments.
 

hledger/Hledger/Cli/Commands/Stats.txt

@@ -1,4 +1,5 @@
 stats
+
 Show journal and performance statistics.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Tags.txt

@@ -1,4 +1,5 @@
 tags
+
 List the tags used in the journal, or their values.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Test.txt

@@ -1,4 +1,5 @@
 test
+
 Run built-in unit tests.
 
 _FLAGS