;doc: update command help

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -61,7 +61,8 @@ ensure perfect alignment, at the cost of more time and memory, use the
 --align-all flag.
 
 This command also supports the output destination and output format
-options. The output formats supported are txt, csv, tsv, and json.
+options. The output formats supported are txt, csv, tsv (Added in 1.32),
+and json.
 
 aregister and posting dates
 

hledger/Hledger/Cli/Commands/Balance.txt

@@ -66,9 +66,9 @@ balance can show..
 -   commodities displayed on the same line or multiple lines (--layout)
 
 This command supports the output destination and output format options,
-with output formats txt, csv, tsv, json, and (multi-period reports
+with output formats txt, csv, tsv (Added in 1.32), json, and
-only:) html. In txt output in a colour-supporting terminal, negative
+(multi-period reports only:) html. In txt output in a colour-supporting
-amounts are shown in red.
+terminal, negative amounts are shown in red.
 
 The --related/-r flag shows the balance of the other postings in the
 transactions of the postings which would normally be shown.

hledger/Hledger/Cli/Commands/Balancesheet.txt

@@ -41,4 +41,5 @@ 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 json.
+options The output formats supported are txt, csv, tsv (Added in 1.32),
+html, and json.

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -47,4 +47,5 @@ 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 json.
+options The output formats supported are txt, csv, tsv (Added in 1.32),
+html, and json.

hledger/Hledger/Cli/Commands/Close.txt

@@ -2,125 +2,150 @@ close
 
 (equity)
 
-A transaction-generating command which generates several kinds of
+close generates several kinds of "closing" and/or "opening"
-"closing" and/or "opening" transactions useful in certain situations. It
+transactions, useful in certain situations, including migrating balances
-prints one or two transactions to stdout, but does not write them to the
+to a new journal file, retaining earnings into equity, consolidating
-journal file; you can append or copy them there when you are happy with
+balances, or viewing lots. Like print, it prints valid journal entries.
-the output.
+You can append or copy these to your journal file(s) when you are happy
+with how they look.
 
 _FLAGS
 
-This command is most often used when migrating balances to a new journal
+close currently has six modes, selected by a single mode flag:
-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 (or no mode flag) it prints a "closing balances"
+close --migrate
-    transaction that zeroes out all the asset, liability, and equity
-    account balances, by default (this requires inferred or declared
-    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
+This is the most common mode. It prints a "closing balances" transaction
-    that restores the same account balances, starting from zero. This
+that zeroes out all asset and liability balances (by default), and an
-    mode is similar to Ledger's equity command.
+opposite "opening balances" transaction that restores them again. The
+balancing account will be equity:opening/closing balances (or another
+specified by --close-acct or --open-acct).
 
-3.  With --migrate, it prints both the closing and opening transactions
+This is useful when migrating balances to a new journal file at the
-    above. This is a common way to migrate balances to a new file at
+start of a new year. Essentially, you run
-    year end; run hledger close --migrate -e NEWYEAR (-e influences the
+hledger close --migrate=NEWYEAR -e NEWYEAR and then copy the closing
-    transaction date) and add the closing transaction at the end of the
+transaction to the end of the old file and the opening transaction to
-    old file, and the opening transaction at the start of the new file.
+the start of the new file. The opening transaction sets correct starting
-    Doing this means you can include past year files in your reports at
+balances in the new file when it is used alone, and the closing
-    any time without disturbing asset/liability/equity balances, because
+transaction keeps balances correct when you use both old and new files
-    the closing balances transaction cancels out the following opening
+together, by cancelling out the following opening transaction and
-    balances transaction. You will sometimes need to exclude these
+preventing buildup of duplicated opening balances. Think of the
-    transactions from reports, eg to see an end of year balance sheet; a
+closing/opening pair as "moving the balances into the next file".
-    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 --assert it prints a "closing balances" transaction that just
+You can close a different set of accounts by providing a query. Eg if
-    asserts the current balances, without changing them. This can be
+you want to include equity, you can add assets liabilities equity or
-    useful as documention and to guard against errors and changes.
+type:ALE arguments. (The balancing account is always excluded.) Revenues
+and expenses usually are not migrated to a new file directly; see
+--retain below.
 
-5.  With --assign it prints an "opening balances" transaction that
+The generated transactions will have a start: tag, with its value set to
-    restores the account balances using balance assignments. Balance
+--migrate's NEW argument if any, for easier matching or exclusion. When
-    assignments work regardless of any previous balance, so a preceding
+NEW is not specified, it will be inferred if possible by incrementing a
-    closing balances transaction is not needed. This is an alternative
+number (eg a year number) within the default journal's main file name.
-    to --close and --open: at year end,
+The other modes behave similarly.
-    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
+close --close
-    transfers revenue and expense balances to equity:retained earnings.
+
-    This is a traditional end-of-period bookkeeping operation also
+This prints just the closing balances transaction of --migrate. It is
-    called "closing the books"; in personal accounting you probably will
+the default behaviour if you specify no mode flag. Using the
-    not need this but it could be useful if you want to see the
+customisation options below, you can move balances from any set of
-    accounting equation (A=L+E) balanced.
+accounts to a different account.
+
+close --open
+
+This prints just the opening balances transaction of --migrate. It is
+similar to Ledger's equity command.
+
+close --assert
+
+This prints a "closing balances" transaction (with balances: tag), that
+just declares balance assertions for the current balances without
+changing them. It could be useful as documention and to guard against
+changes.
+
+close --assign
+
+This 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.
+
+However, omitting the closing balances transaction would unbalance
+equity. This is relatively harmless for personal reports, but it
+disturbs the accounting equation, removing a source of error detection.
+So --migrate is generally the best way to set to set balances in new
+files, for now.
+
+close --retain
+
+This is like --close with different defaults: it prints a "retain
+earnings" transaction (with retain: tag), that transfers revenue and
+expense balances to equity:retained earnings.
+
+This is a different kind of closing, called "retaining earnings" or
+"closing the books"; it is traditionally performed by businesses at the
+end of each accounting period, to consolidate revenues and expenses into
+the main equity balance. ("Revenues" and "expenses" are actually equity
+by another name, kept separate temporarily for reporting purposes.)
+
+In personal accounting you generally don't need to do this, unless you
+want the balancesheetequity report to show a zero total, demonstrating
+that the accounting equation (A-L=E) is satisfied.
+
+close customisation
 
 In all modes, the following things can be overridden:
 
--   the transaction descriptions can be changed with --close-desc=DESC
+-   the accounts to be closed/opened, with account query arguments
-    and --open-desc=DESC
+-   the balancing account, with --close-acct=ACCT and/or
--   the account to transfer to and from can be changed with
+    --open-acct=ACCT
-    --close-acct=ACCT and --open-acct=ACCT
+-   the transaction descriptions, with --close-desc=DESC and
--   the accounts to be closed/opened can be changed with ACCTQUERY
+    --open-desc=DESC
-    (account query arguments).
+-   the transaction's tag value, with a --MODE=NEW option argument
--   the closing/opening dates can be changed with -e DATE (a report end
+-   the closing/opening dates, with -e OPENDATE
-    date)
 
-By default just one destination/source posting will be used, with its
+By default, the closing date is yesterday, or the journal's end date,
-amount left implicit. With --x/--explicit, the amount will be shown
+whichever is later; and the opening date is always one day after the
-explicitly, and if it involves multiple commodities, a separate posting
+closing date. You can change these by specifying a report end date; the
-will be generated for each of them (similar to print -x).
+closing date will be the last day of the report period. Eg -e 2024 means
+"close on 2023-12-31, open on 2024-01-01".
 
-With --show-costs, any amount costs are shown, with separate postings
+With --x/--explicit, the balancing amount will be shown explicitly, and
-for each cost. This is currently the best way to view investment lots.
+if it involves multiple commodities, a separate posting will be
-If you have many currency conversion or investment transactions, it can
+generated for each of them (similar to print -x).
-generate very large journal entries.
 
 With --interleaved, each individual transfer is shown with source and
-destination postings next to each other. This could be useful for
+destination postings next to each other (perhaps useful for
-troubleshooting.
+troubleshooting).
 
-The default closing date is yesterday, or the journal's end date,
+With --show-costs, balances' costs are also shown, with different costs
-whichever is later. You can change this by specifying a report end date
+kept separate. This may generate very large journal entries, if you have
-with -e. The last day of the report period will be the closing date, eg
+many currency conversions or investment transactions. close --show-costs
--e 2024 means "close on 2023-12-31". The opening date is always the day
+is currently the best way to view investment lots with hledger. (To move
-after the closing date.
+or dispose of lots, see the more capable hledger-move script.)
 
 close and balance assertions
 
-Balance assertions will be generated, verifying that the accounts have
+close adds balance assertions verifying that the accounts have been
-been reset to zero (and then restored to their previous balances, if
+reset to zero in a closing transaction or restored to their previous
-there is an opening transaction).
+balances in an opening transaction. These provide useful error checking,
+but you can ignore them temporarily with -I, or remove them if you
+prefer.
 
-These provide useful error checking, but you can ignore them temporarily
+When running close you should probably avoid using -C, -R, status:
-with -I, or remove them if you prefer.
+(filtering by status or realness) or --auto (generating postings), since
+the generated balance assertions would then require these.
 
-You probably should avoid filtering transactions by status or realness
+Transactions with multiple dates (eg posting dates) spanning the file
-(-C, -R, status:), or generating postings (--auto), with this command,
+boundary also can disrupt the balance assertions:
-since the balance assertions would depend on these.
-
-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: 2023-01-02
 
-To solve that you can transfer the money to and from a temporary
+To solve this you can transfer the money to and from a temporary
-account, in effect splitting the multi-day transaction into two
+account, splitting the multi-day transaction into two single-day
-single-day transactions:
+transactions:
 
 ; in 2022.journal:
 2022-12-30 a purchase made in december, cleared in january
@@ -132,76 +157,44 @@ single-day transactions:
     equity:pending         5 = 0
     assets:bank:checking  -5
 
-Example: retain earnings
+close examples
+
+Retain earnings
 
 Record 2022's revenues/expenses as retained earnings on 2022-12-31,
 appending the generated transaction to the journal:
 
 $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
 
-Note 2022's income statement will now show only zeroes, because revenues
+After this, to see 2022's revenues and expenses you must exclude the
-and expenses have been moved entirely to equity. To see them again, you
+retain earnings transaction:
-could exclude the retain transaction:
 
 $ hledger -f 2022.journal is not:desc:'retain earnings'
 
-Example: migrate balances to a new file
+Migrate balances to a new file
 
-Close assets/liabilities/equity on 2022-12-31 and re-open them on
+Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
-2023-01-01:
 
 $ 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
 
-Now 2022's balance sheet will show only zeroes, indicating a balanced
+After this, to see 2022's end-of-year balances you must exclude the
-accounting equation. (Unless you are using @/@@ notation - in that case,
+closing balances transaction:
-try adding --infer-equity.) To see the end-of-year balances again, you
-could exclude the closing transaction:
 
 $ hledger -f 2022.journal bs not:desc:'closing balances'
 
-Example: excluding closing/opening transactions
+For more flexibility, it helps to tag closing and opening transactions
+with eg start:NEWYEAR, then you can ensure correct balances by excluding
+all opening/closing transactions except the first, like so:
 
-When combining many files for multi-year reports, the closing/opening
+$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'
-transactions cause some noise in transaction-oriented reports like print
+$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:start=2021 or not tag:start'
-and register. You can exclude them as shown above, but not:desc:... is
+$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:start=2022 or not tag:start'
-not ideal as it depends on consistent descriptions; also you will want
+$ hledger bs -Y -f 2021.j                     expr:'tag:start=2021 or not tag:start'
-to avoid excluding the very first opening transaction, which could be
+$ hledger bs -Y -f 2022.j                     expr:'tag:start=2022 or not tag:start'
-awkward. Here is one alternative, using tags:
+$ hledger bs -Y -f 2023.j                     # unclosed file, no query needed
 
-Add clopen: tags to all opening/closing balances transactions except the
+More detailed close examples
-first, like this:
 
-; 2021.journal
+See examples/multi-year.
-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/Incomestatement.txt

@@ -43,4 +43,5 @@ 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 json.
+options The output formats supported are txt, csv, tsv (Added in 1.32),
+html, and json.

hledger/Hledger/Cli/Commands/Print.txt

@@ -55,8 +55,9 @@ their symbol placement, decimal mark, and digit group marks will be made
 consistent. By default, decimal digits are shown as they are written in
 the journal.
 
-With the --round option, print will try increasingly hard to display
+With the --round (Added in 1.32) option, print will try increasingly
-decimal digits according to the commodity display styles:
+hard to display decimal digits according to the commodity display
+styles:
 
 -   --round=none show amounts with original precisions (default)
 -   --round=soft add/remove decimal zeros in amounts (except costs)
@@ -105,8 +106,8 @@ shown and the program exit code will be non-zero.
 print output format
 
 This command also supports the output destination and output format
-options The output formats supported are txt, beancount, csv, tsv, json
+options The output formats supported are txt, beancount (Added in 1.32),
-and sql.
+csv, tsv (Added in 1.32), json and sql.
 
 The beancount format tries to produce Beancount-compatible output, as
 follows:

hledger/Hledger/Cli/Commands/Register.txt

@@ -125,4 +125,5 @@ $ 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 json.
+options The output formats supported are txt, csv, tsv (Added in 1.32),
+and json.