;doc: update manuals

hledger-ui/hledger-ui.1

@@ -113,9 +113,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
 \f[CR]\-\-alias=OLD=NEW\f[R]
 rename accounts named OLD to NEW
 .TP
-\f[CR]\-\-anon\f[R]
-anonymize accounts and payees
-.TP
 \f[CR]\-\-pivot FIELDNAME\f[R]
 use some other field or tag for the account name
 .TP

hledger-ui/hledger-ui.info

@@ -148,9 +148,6 @@ File: hledger-ui.info,  Node: General input options,  Next: General reporting op
 '--alias=OLD=NEW'
 
      rename accounts named OLD to NEW
-'--anon'
-
-     anonymize accounts and payees
 '--pivot FIELDNAME'
 
      use some other field or tag for the account name
@@ -680,40 +677,40 @@ Node: General help options2951
 Ref: #general-help-options3100
 Node: General input options3382
 Ref: #general-input-options3567
-Node: General reporting options4269
-Ref: #general-reporting-options4433
-Node: MOUSE7823
-Ref: #mouse7918
-Node: KEYS8155
-Ref: #keys8248
-Node: SCREENS12903
-Ref: #screens13001
-Node: Menu13581
-Ref: #menu13674
-Node: Cash accounts13869
-Ref: #cash-accounts14011
-Node: Balance sheet accounts14195
-Ref: #balance-sheet-accounts14376
-Node: Income statement accounts14496
-Ref: #income-statement-accounts14682
-Node: All accounts14846
-Ref: #all-accounts14992
-Node: Register15174
-Ref: #register15298
-Node: Transaction17582
-Ref: #transaction17705
-Node: Error19122
-Ref: #error19216
-Node: TIPS19460
-Ref: #tips19559
-Node: Watch mode19601
-Ref: #watch-mode19708
-Node: Debug output21167
-Ref: #debug-output21278
-Node: ENVIRONMENT21490
-Ref: #environment21600
-Node: BUGS21791
-Ref: #bugs21874
+Node: General reporting options4224
+Ref: #general-reporting-options4388
+Node: MOUSE7778
+Ref: #mouse7873
+Node: KEYS8110
+Ref: #keys8203
+Node: SCREENS12858
+Ref: #screens12956
+Node: Menu13536
+Ref: #menu13629
+Node: Cash accounts13824
+Ref: #cash-accounts13966
+Node: Balance sheet accounts14150
+Ref: #balance-sheet-accounts14331
+Node: Income statement accounts14451
+Ref: #income-statement-accounts14637
+Node: All accounts14801
+Ref: #all-accounts14947
+Node: Register15129
+Ref: #register15253
+Node: Transaction17537
+Ref: #transaction17660
+Node: Error19077
+Ref: #error19171
+Node: TIPS19415
+Ref: #tips19514
+Node: Watch mode19556
+Ref: #watch-mode19663
+Node: Debug output21122
+Ref: #debug-output21233
+Node: ENVIRONMENT21445
+Ref: #environment21555
+Node: BUGS21746
+Ref: #bugs21829
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -102,8 +102,6 @@ OPTIONS
        --alias=OLD=NEW
               rename accounts named OLD to NEW
 
-       --anon anonymize accounts and payees
-
        --pivot FIELDNAME
               use some other field or tag for the account name
 

hledger-web/hledger-web.1

@@ -160,9 +160,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
 \f[CR]\-\-alias=OLD=NEW\f[R]
 rename accounts named OLD to NEW
 .TP
-\f[CR]\-\-anon\f[R]
-anonymize accounts and payees
-.TP
 \f[CR]\-\-pivot FIELDNAME\f[R]
 use some other field or tag for the account name
 .TP

hledger-web/hledger-web.info

@@ -189,9 +189,6 @@ File: hledger-web.info,  Node: General input options,  Next: General reporting o
 '--alias=OLD=NEW'
 
      rename accounts named OLD to NEW
-'--anon'
-
-     anonymize accounts and payees
 '--pivot FIELDNAME'
 
      use some other field or tag for the account name
@@ -638,24 +635,24 @@ Node: General help options5257
 Ref: #general-help-options5407
 Node: General input options5689
 Ref: #general-input-options5875
-Node: General reporting options6577
-Ref: #general-reporting-options6742
-Node: PERMISSIONS10132
-Ref: #permissions10271
-Node: EDITING UPLOADING DOWNLOADING11483
-Ref: #editing-uploading-downloading11664
-Node: RELOADING12498
-Ref: #reloading12632
-Node: JSON API13065
-Ref: #json-api13180
-Node: DEBUG OUTPUT18668
-Ref: #debug-output18793
-Node: Debug output18820
-Ref: #debug-output-118921
-Node: ENVIRONMENT19338
-Ref: #environment19457
-Node: BUGS19574
-Ref: #bugs19658
+Node: General reporting options6532
+Ref: #general-reporting-options6697
+Node: PERMISSIONS10087
+Ref: #permissions10226
+Node: EDITING UPLOADING DOWNLOADING11438
+Ref: #editing-uploading-downloading11619
+Node: RELOADING12453
+Ref: #reloading12587
+Node: JSON API13020
+Ref: #json-api13135
+Node: DEBUG OUTPUT18623
+Ref: #debug-output18748
+Node: Debug output18775
+Ref: #debug-output-118876
+Node: ENVIRONMENT19293
+Ref: #environment19412
+Node: BUGS19529
+Ref: #bugs19613
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -142,8 +142,6 @@ OPTIONS
        --alias=OLD=NEW
               rename accounts named OLD to NEW
 
-       --anon anonymize accounts and payees
-
        --pivot FIELDNAME
               use some other field or tag for the account name
 

hledger/hledger.1

@@ -343,9 +343,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
 \f[CR]\-\-alias=OLD=NEW\f[R]
 rename accounts named OLD to NEW
 .TP
-\f[CR]\-\-anon\f[R]
-anonymize accounts and payees
-.TP
 \f[CR]\-\-pivot FIELDNAME\f[R]
 use some other field or tag for the account name
 .TP
@@ -992,6 +989,11 @@ $ hledger print \-c \[aq]$1.000,0\[aq]
 This option can repeated to set the display style for multiple
 commodities/currencies.
 Its argument is as described in the commodity directive.
+.PP
+hledger will occasionally make some additional adjustments to number
+formatting, eg adding a trailing decimal mark to disambiguate numbers
+with digit group marks; for details, see Amount formatting,
+parseability.
 .SS Colour
 In terminal output, some commands can produce colour when the terminal
 supports it:
@@ -1667,6 +1669,11 @@ reports.
 When rounding, hledger uses banker\[aq]s rounding (it rounds to the
 nearest even digit).
 So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq].
+.SS Number format
+hledger will occasionally make some additional adjustments to number
+formatting, eg adding a trailing decimal mark to disambiguate numbers
+with digit group marks; for details, see Amount formatting,
+parseability.
 .PP
 .SS Costs
 After a posting amount, you can note its cost (when buying) or selling
@@ -2018,8 +2025,11 @@ by a full colon, in a transaction or posting or account directive\[aq]s
 comment.
 (This is an exception to the usual rule that things in comments are
 ignored.)
-Eg, here four different tags are recorded: one on the checking account,
-two on the transaction, and one on the expenses posting:
+You can write multiple tags separated by comma, and/or you can add more
+comment lines and write more tags there.
+.PP
+Here five different tags are recorded: one on the checking account, two
+on the transaction, and two on the expenses posting:
 .IP
 .EX
 account assets:checking         ; accounttag:
@@ -2027,18 +2037,58 @@ account assets:checking         ; accounttag:
 2017/1/16 bought groceries      ; transactiontag\-1:
     ; transactiontag\-2:
     assets:checking        $\-1
-    expenses:food           $1  ; postingtag:
+    expenses:food           $1  ; postingtag:, another\-posting\-tag:
 .EE
 .PP
-Postings also inherit tags from their transaction and their account.
-And transactions also acquire tags from their postings (and
-postings\[aq] accounts).
-So in the example above, the expenses posting effectively has all four
-tags (by inheriting from account and transaction), and the transaction
-also has all four tags (by acquiring from the expenses posting).
-.PP
 You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or
 match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query.
+.SS Tag inheritance
+Postings also inherit tags from their transaction and their account.
+And transactions also acquire tags from their postings (and
+postings\[aq] accounts).
+So in the example above, the expenses posting effectively has all five
+tags (by inheriting from the account and transaction), and the
+transaction also has all five tags (by acquiring from the expenses
+posting).
+.SS Tag names
+Tag names are currently not very clearly specified; any sequence of
+non\-whitespace characters followed by a colon may work.
+.PP
+The following tag names are generated by hledger or have special
+significance to hledger, so you may want to avoid using them yourself:
+.IP \[bu] 2
+\f[CR]balances\f[R] \-\- a balance assertions transaction generated by
+close
+.IP \[bu] 2
+\f[CR]retain\f[R] \-\- a retain earnings transaction generated by close
+.IP \[bu] 2
+\f[CR]start\f[R] \-\- a opening balances, closing balances or balance
+assignment transaction generated by close
+.IP \[bu] 2
+\f[CR]generated\-transaction\f[R] \-\- a transaction generated by
+\-\-forecast
+.IP \[bu] 2
+\f[CR]generated\-posting\f[R] \-\- a posting generated by \-\-auto
+.IP \[bu] 2
+\f[CR]modified\f[R] \-\- a transaction which has had postings added by
+\-\-auto
+.IP \[bu] 2
+\f[CR]type\f[R] \-\- declares an account\[aq]s type in an account
+declaration
+.IP \[bu] 2
+\f[CR]t\f[R] \-\- stores the (user defined, single letter) type of a 15m
+unit of time parsed from timedot format
+.PP
+Some additional tag names with an underscore prefix are used internally
+and not displayed in reports (but can be matched by queries):
+.IP \[bu] 2
+\f[CR]_generated\-transaction\f[R]
+.IP \[bu] 2
+\f[CR]_generated\-posting\f[R]
+.IP \[bu] 2
+\f[CR]_modified\f[R]
+.IP \[bu] 2
+\f[CR]_conversion\-matched\f[R]
 .SS Tag values
 Tags can have a value, which is any text after the colon up until a
 comma or end of line (with surrounding whitespace removed).
@@ -4206,12 +4256,14 @@ By default they are OR\[aq]d (any one of them can match)
 When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be
 AND\[aq]ed with the previous matcher (both of them must match)
 .IP \[bu] 2
-When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the
-matcher is negated (it may not match).
+\f[I]Added in 1.32\f[R] When a matcher is preceded by an exclamation
+mark (\f[CR]!\f[R]), the matcher is negated (it may not match).
 .PP
 Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and
 \f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher).
 .SS Match groups
+\f[I]Added in 1.32\f[R]
+.PP
 Matchers can define match groups: parenthesised portions of the regular
 expression which are available for reference in field assignments.
 Groups are enclosed in regular parentheses (\f[CR](\f[R] and
@@ -5195,7 +5247,7 @@ one or more dots (period characters), each representing 0.25.
 These are the dots in \[dq]timedot\[dq].
 Spaces are ignored and can be used for grouping/alignment.
 .IP \[bu] 2
-one or more letters.
+\f[I]Added in 1.32\f[R] one or more letters.
 These are like dots but they also generate a tag \f[CR]t:\f[R] (short
 for \[dq]type\[dq]) with the letter as its value, and a separate posting
 for each of the values.
@@ -7876,7 +7928,7 @@ memory, use the \f[CR]\-\-align\-all\f[R] flag.
 This command also supports the output destination and output format
 options.
 The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
-\f[CR]tsv\f[R], and \f[CR]json\f[R].
+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
 .SS aregister and posting dates
 aregister always shows one line (and date and amount) per transaction.
 But sometimes transactions have postings with different dates.
@@ -7981,8 +8033,9 @@ commodities displayed on the same line or multiple lines
 (\f[CR]\-\-layout\f[R])
 .PP
 This command supports the output destination and output format options,
-with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R],
-\f[CR]json\f[R], and (multi\-period reports only:) \f[CR]html\f[R].
+with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R]
+(\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports
+only:) \f[CR]html\f[R].
 In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
 amounts are shown in red.
 .PP
@@ -9041,7 +9094,8 @@ sign flipped.
 .PP
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
-\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
+\f[CR]json\f[R].
 .SS balancesheetequity
 (bse)
 .PP
@@ -9149,7 +9203,8 @@ but with smarter account detection.
 .PP
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
-\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
+\f[CR]json\f[R].
 .SS check
 Check for various kinds of errors in your data.
 .PP
@@ -9245,133 +9300,150 @@ against the real\-world balance.)
 .SS close
 (equity)
 .PP
-A transaction\-generating command which generates several kinds of
-\[dq]closing\[dq] and/or \[dq]opening\[dq] transactions useful in
-certain situations.
-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.
+\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or
+\[dq]opening\[dq] transactions, useful in certain situations, including
+migrating balances to a new journal file, retaining earnings into
+equity, consolidating balances, or viewing lots.
+Like \f[CR]print\f[R], it prints valid journal entries.
+You can append or copy these to your journal file(s) when you are happy
+with how they look.
 .PP
-This command is most often used when migrating balances to a new journal
-file, at the start of a new financial year.
-It can also be used to \[dq]retain earnings\[dq] (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:
-.IP "1." 3
-With \f[CR]\-\-close\f[R] (or no mode flag) it prints a \[dq]closing
-balances\[dq] 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 \[dq]opening/closing
-balances\[dq] equity account.
-.IP "2." 3
-With \f[CR]\-\-open\f[R], it prints an opposite \[dq]opening
-balances\[dq] transaction that restores the same account balances,
-starting from zero.
-This mode is similar to Ledger\[aq]s equity command.
-.IP "3." 3
-With \f[CR]\-\-migrate\f[R], 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
-\f[CR]hledger close \-\-migrate \-e NEWYEAR\f[R] (\-e influences the
-transaction date) and add the closing transaction at the end of the old
-file, and the opening transaction at the start of the new file.
-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 \f[CR]not:opening/closing\f[R]
-query argument should do.
-You should probably also use this query when \f[CR]close\f[R]\-ing, to
-exclude the \[dq]opening/closing balances\[dq] account which might
-otherwise cause problems.
-Or you can just migrate assets and liabilities:
-\f[CR]hledger close type:AL\f[R].
-Most people don\[aq]t need to migrate equity.
-And revenues and expenses usually should not be migrated.
-.IP "4." 3
-With \f[CR]\-\-assert\f[R] it prints a \[dq]closing balances\[dq]
-transaction that just asserts the current balances, without changing
-them.
-This can be useful as documention and to guard against errors and
-changes.
-.IP "5." 3
-With \f[CR]\-\-assign\f[R] it prints an \[dq]opening balances\[dq]
-transaction that restores the account balances using balance
-assignments.
+\f[CR]close\f[R] currently has six modes, selected by a single mode
+flag:
+.SS close \-\-migrate
+This is the most common mode.
+It prints a \[dq]closing balances\[dq] transaction that zeroes out all
+asset and liability balances (by default), and an opposite \[dq]opening
+balances\[dq] transaction that restores them again.
+The balancing account will be \f[CR]equity:opening/closing balances\f[R]
+(or another specified by \f[CR]\-\-close\-acct\f[R] or
+\f[CR]\-\-open\-acct\f[R]).
+.PP
+This is useful when migrating balances to a new journal file at the
+start of a new year.
+Essentially, you run
+\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] and then copy
+the closing transaction to the end of the old file and the opening
+transaction to the start of the new file.
+The opening transaction sets correct starting balances in the new file
+when it is used alone, and the closing transaction keeps balances
+correct when you use both old and new files together, by cancelling out
+the following opening transaction and preventing buildup of duplicated
+opening balances.
+Think of the closing/opening pair as \[dq]moving the balances into the
+next file\[dq].
+.PP
+You can close a different set of accounts by providing a query.
+Eg if you want to include equity, you can add
+\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.
+(The balancing account is always excluded.)
+Revenues and expenses usually are not migrated to a new file directly;
+see \f[CR]\-\-retain\f[R] below.
+.PP
+The generated transactions will have a \f[CR]start:\f[R] tag, with its
+value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if
+any, for easier matching or exclusion.
+When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by
+incrementing a number (eg a year number) within the default
+journal\[aq]s main file name.
+The other modes behave similarly.
+.SS close \-\-close
+This prints just the closing balances transaction of
+\f[CR]\-\-migrate\f[R].
+It is the default behaviour if you specify no mode flag.
+Using the customisation options below, you can move balances from any
+set of accounts to a different account.
+.SS close \-\-open
+This prints just the opening balances transaction of
+\f[CR]\-\-migrate\f[R].
+It is similar to Ledger\[aq]s equity command.
+.SS close \-\-assert
+This prints a \[dq]closing balances\[dq] transaction (with
+\f[CR]balances:\f[R] tag), that just declares balance assertions for the
+current balances without changing them.
+It could be useful as documention and to guard against changes.
+.SS close \-\-assign
+This prints an \[dq]opening balances\[dq] 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 \f[CR]\-\-close\f[R] and \f[CR]\-\-open\f[R]:
-at year end, \f[CR]hledger close \-\-assert \-e NEWYEAR\f[R] in the old
-file (optional, but useful for error checking), and
-\f[CR]hledger close \-\-assign \-e NEWYEAR\f[R] in the new file.
-This might be more convenient, eg if you are often doing cleanups or
-fixes which would break closing/opening transactions.
-.IP "6." 3
-With \f[CR]\-\-retain\f[R], it prints a \[dq]retain earnings\[dq]
-transaction that transfers revenue and expense balances to
-\f[CR]equity:retained earnings\f[R].
-This is a traditional end\-of\-period bookkeeping operation also called
-\[dq]closing the books\[dq]; 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.
 .PP
+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 \f[CR]\-\-migrate\f[R] is generally the best way to set to set
+balances in new files, for now.
+.SS close \-\-retain
+This is like \f[CR]\-\-close\f[R] with different defaults: it prints a
+\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),
+that transfers revenue and expense balances to
+\f[CR]equity:retained earnings\f[R].
+.PP
+This is a different kind of closing, called \[dq]retaining earnings\[dq]
+or \[dq]closing the books\[dq]; it is traditionally performed by
+businesses at the end of each accounting period, to consolidate revenues
+and expenses into the main equity balance.
+(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by
+another name, kept separate temporarily for reporting purposes.)
+.PP
+In personal accounting you generally don\[aq]t need to do this, unless
+you want the \f[CR]balancesheetequity\f[R] report to show a zero total,
+demonstrating that the accounting equation (A\-L=E) is satisfied.
+.SS close customisation
 In all modes, the following things can be overridden:
 .IP \[bu] 2
-the transaction descriptions can be changed with
-\f[CR]\-\-close\-desc=DESC\f[R] and \f[CR]\-\-open\-desc=DESC\f[R]
+the accounts to be closed/opened, with account query arguments
 .IP \[bu] 2
-the account to transfer to and from can be changed with
-\f[CR]\-\-close\-acct=ACCT\f[R] and \f[CR]\-\-open\-acct=ACCT\f[R]
+the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or
+\f[CR]\-\-open\-acct=ACCT\f[R]
 .IP \[bu] 2
-the accounts to be closed/opened can be changed with
-\f[CR]ACCTQUERY\f[R] (account query arguments).
+the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and
+\f[CR]\-\-open\-desc=DESC\f[R]
 .IP \[bu] 2
-the closing/opening dates can be changed with \f[CR]\-e DATE\f[R] (a
-report end date)
+the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option
+argument
+.IP \[bu] 2
+the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]
 .PP
-By default just one destination/source posting will be used, with its
-amount left implicit.
-With \f[CR]\-\-x/\-\-explicit\f[R], the amount will be shown explicitly,
-and if it involves multiple commodities, a separate posting will be
-generated for each of them (similar to \f[CR]print \-x\f[R]).
+By default, the closing date is yesterday, or the journal\[aq]s end
+date, whichever is later; and the opening date is always one day after
+the closing date.
+You can change these by specifying a report end date; the closing date
+will be the last day of the report period.
+Eg \f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31, open on
+2024\-01\-01\[dq].
 .PP
-With \f[CR]\-\-show\-costs\f[R], any amount costs are shown, with
-separate postings for each cost.
-This is currently the best way to view investment lots.
-If you have many currency conversion or investment transactions, it can
-generate very large journal entries.
+With \f[CR]\-\-x/\-\-explicit\f[R], the balancing amount will be shown
+explicitly, and if it involves multiple commodities, a separate posting
+will be generated for each of them (similar to \f[CR]print \-x\f[R]).
 .PP
 With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with
-source and destination postings next to each other.
-This could be useful for troubleshooting.
+source and destination postings next to each other (perhaps useful for
+troubleshooting).
 .PP
-The default closing date is yesterday, or the journal\[aq]s end date,
-whichever is later.
-You can change this by specifying a report end date with \f[CR]\-e\f[R].
-The last day of the report period will be the closing date, eg
-\f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31\[dq].
-The opening date is always the day after the closing date.
+With \f[CR]\-\-show\-costs\f[R], balances\[aq] costs are also shown,
+with different costs kept separate.
+This may generate very large journal entries, if you have many currency
+conversions or investment transactions.
+\f[CR]close \-\-show\-costs\f[R] is currently the best way to view
+investment lots with hledger.
+(To move or dispose of lots, see the more capable
+\f[CR]hledger\-move\f[R] script.)
 .SS close and balance assertions
-Balance assertions will be generated, verifying that the accounts have
-been reset to zero (and then restored to their previous balances, if
-there is an opening transaction).
-.PP
+\f[CR]close\f[R] adds balance assertions verifying that the accounts
+have been reset to zero in a closing transaction or restored to their
+previous balances in an opening transaction.
 These provide useful error checking, but you can ignore them temporarily
 with \f[CR]\-I\f[R], or remove them if you prefer.
 .PP
-You probably should avoid filtering transactions by status or realness
-(\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R]), or generating
-postings (\f[CR]\-\-auto\f[R]), with this command, since the balance
-assertions would depend on these.
+When running \f[CR]close\f[R] you should probably avoid using
+\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status
+or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the
+generated balance assertions would then require these.
 .PP
-Note custom posting dates spanning the file boundary will disrupt the
-balance assertions:
+Transactions with multiple dates (eg posting dates) spanning the file
+boundary also can disrupt the balance assertions:
 .IP
 .EX
 2023\-12\-30 a purchase made in december, cleared in january
@@ -9379,9 +9451,9 @@ balance assertions:
     assets:bank:checking  \-5  ; date: 2023\-01\-02
 .EE
 .PP
-To solve that you can transfer the money to and from a temporary
-account, in effect splitting the multi\-day transaction into two
-single\-day transactions:
+To solve this you can transfer the money to and from a temporary
+account, splitting the multi\-day transaction into two single\-day
+transactions:
 .IP
 .EX
 ; in 2022.journal:
@@ -9394,7 +9466,8 @@ single\-day transactions:
     equity:pending         5 = 0
     assets:bank:checking  \-5
 .EE
-.SS Example: retain earnings
+.SS close examples
+.SS Retain earnings
 Record 2022\[aq]s revenues/expenses as retained earnings on
 2022\-12\-31, appending the generated transaction to the journal:
 .IP
@@ -9402,15 +9475,14 @@ Record 2022\[aq]s revenues/expenses as retained earnings on
 $ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal
 .EE
 .PP
-Note 2022\[aq]s income statement will now show only zeroes, because
-revenues and expenses have been moved entirely to equity.
-To see them again, you could exclude the retain transaction:
+After this, to see 2022\[aq]s revenues and expenses you must exclude the
+retain earnings transaction:
 .IP
 .EX
 $ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]
 .EE
-.SS Example: migrate balances to a new file
-Close assets/liabilities/equity on 2022\-12\-31 and re\-open them on
+.SS Migrate balances to a new file
+Close assets/liabilities on 2022\-12\-31 and re\-open them on
 2023\-01\-01:
 .IP
 .EX
@@ -9419,74 +9491,27 @@ $ hledger close \-\-migrate \-f 2022.journal \-p 2022
 # copy/paste the opening transaction to the start of 2023.journal
 .EE
 .PP
-Now 2022\[aq]s balance sheet will show only zeroes, indicating a
-balanced accounting equation.
-(Unless you are using \[at]/\[at]\[at] notation \- in that case, try
-adding \-\-infer\-equity.)
-To see the end\-of\-year balances again, you could exclude the closing
-transaction:
+After this, to see 2022\[aq]s end\-of\-year balances you must exclude
+the closing balances transaction:
 .IP
 .EX
 $ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]
 .EE
-.SS Example: excluding closing/opening transactions
-When combining many files for multi\-year reports, the closing/opening
-transactions cause some noise in transaction\-oriented reports like
-\f[CR]print\f[R] and \f[CR]register\f[R].
-You can exclude them as shown above, but \f[CR]not:desc:...\f[R] is not
-ideal as it depends on consistent descriptions; also you will want to
-avoid excluding the very first opening transaction, which could be
-awkward.
-Here is one alternative, using tags:
 .PP
-Add \f[CR]clopen:\f[R] tags to all opening/closing balances transactions
-except the first, like this:
+For more flexibility, it helps to tag closing and opening transactions
+with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances
+by excluding all opening/closing transactions except the first, like so:
 .IP
 .EX
-; 2021.journal
-2021\-06\-01 first opening balances
-\&...
-2021\-12\-31 closing balances  ; clopen:2022
-\&...
-.EE
-.IP
-.EX
-; 2022.journal
-2022\-01\-01 opening balances  ; clopen:2022
-\&...
-2022\-12\-31 closing balances  ; clopen:2023
-\&...
-.EE
-.IP
-.EX
-; 2023.journal
-2023\-01\-01 opening balances  ; clopen:2023
-\&...
-.EE
-.PP
-Now, assuming a combined journal like:
-.IP
-.EX
-; all.journal
-include 2021.journal
-include 2022.journal
-include 2023.journal
-.EE
-.PP
-The \f[CR]clopen:\f[R] tag can exclude all but the first opening
-transaction.
-To show a clean multi\-year checking register:
-.IP
-.EX
-$ hledger \-f all.journal areg checking not:tag:clopen
-.EE
-.PP
-And the year values allow more precision.
-To show 2022\[aq]s year\-end balance sheet:
-.IP
-.EX
-$ hledger \-f all.journal bs \-e2023 not:tag:clopen=2023
+$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
+$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:start=2021 or not tag:start\[aq]
+$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:start=2022 or not tag:start\[aq]
+$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:start=2021 or not tag:start\[aq]
+$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:start=2022 or not tag:start\[aq]
+$ hledger bs \-Y \-f 2023.j                     # unclosed file, no query needed
 .EE
+.SS More detailed close examples
+See examples/multi\-year.
 .SS codes
 List the codes seen in transactions, in the order parsed.
 .PP
@@ -9816,7 +9841,8 @@ sign flipped.
 .PP
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
-\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
+\f[CR]json\f[R].
 .SS notes
 List the unique notes that appear in transactions.
 .PP
@@ -9928,9 +9954,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.
 .PP
-With the \f[CR]\-\-round\f[R] option, \f[CR]print\f[R] will try
-increasingly hard to display decimal digits according to the commodity
-display styles:
+With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option,
+\f[CR]print\f[R] will try increasingly hard to display decimal digits
+according to the commodity display styles:
 .IP \[bu] 2
 \f[CR]\-\-round=none\f[R] show amounts with original precisions
 (default)
@@ -9988,8 +10014,9 @@ the program exit code will be non\-zero.
 .SS print output format
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R],
-\f[CR]beancount\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R], \f[CR]json\f[R]
-and \f[CR]sql\f[R].
+\f[CR]beancount\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]csv\f[R],
+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R] and
+\f[CR]sql\f[R].
 .PP
 The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible
 output, as follows:
@@ -10211,7 +10238,7 @@ $ hledger reg \-w $COLUMNS,40      # use terminal width, & description width 40
 .PP
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
-\f[CR]tsv\f[R], and \f[CR]json\f[R].
+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
 .SS rewrite
 Print all transactions, rewriting the postings of matched transactions.
 For now the only rewrite available is adding new postings, like print