;doc: update command docs

hledger/Hledger/Cli/Commands/Add.txt

@@ -62,24 +62,22 @@ There is a detailed tutorial at https://hledger.org/add.html.
 
 add and balance assertions
 
-Since hledger 1.43, whenever you enter a posting amount, add will
+Since hledger 1.43, you can add a balance assertion by writing
-re-check all balance assertions in the journal, and if any of them fail,
+AMOUNT = BALANCE when asked for an amount. Eg 100 = 500.
-it will report the problem and ask for the amount again.
 
-You can also add a new balance assertion, following the amount as in
+Also, each time you enter a new amount, hledger re-checks all balance
-journal format.
+assertions in the journal and rejects the new amount if it would make
-
+any of them fail. You can run add with -I/--ignore-assertions to disable
-The new transaction's date, and the new posting's posting date if any
+balance assertion checking.
-(entered in a comment following the amount), will influence assertion
-checking.
-
-You can use -I/--ignore-assertions to disable assertion checking
-temporarily.
 
 add and balance assignments
 
-Balance assignments are not recalculated during a hledger add session.
+Since hledger 1.51, you can add a balance assignment by writing
-When add runs, it sees the journal with all balance assignments already
+= BALANCE (or ==, =* etc) when asked for an amount. The missing amount
-processed and converted to assertions. So if you add a new posting which
+will be calculated automatically.
-is dated earlier than a balance assignment, it will break the assertion
+
-and be rejected. You can make it work by using hledger add -I.
+add normally won't let you add a new posting which is dated earlier than
+an existing balance assignment. (Because when add runs, existing balance
+assignments have already been calculated and converted to amounts and
+balance assertions.) You can allow it by disabling balance assertion
+checking with -I.

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -33,9 +33,10 @@ this behaviour using the --cumulative option.
 
 This is a more "real world", bank-like view than the register command
 (which shows individual postings, possibly from multiple accounts, not
-necessarily in historical mode). As a quick rule of thumb: - use
+necessarily in historical mode). As a quick rule of thumb:
-aregister for reviewing and reconciling real-world asset/liability
+
-accounts - use register for reviewing detailed revenues/expenses.
+- aregister is best when reconciling real-world asset/liability accounts
+- register is best when reviewing individual revenues/expenses.
 
 Note this command's non-standard, and required, first argument; it
 specifies the account whose register will be shown. You can write the

hledger/Hledger/Cli/Commands/Check.txt

@@ -18,9 +18,9 @@ hledger check ordereddates payees  # run basic checks and two others
 If you are an Emacs user, you can also configure flycheck-hledger to run
 these checks, providing instant feedback as you edit the journal.
 
-Here are the checks currently available. Generally, they are performed
+Here are the checks currently available. They are generally checked in
-in the order they are shown here (and only the first failure is
+the order they are shown here, and only the first failure will be
-reported).
+reported.
 
 Basic checks
 
@@ -33,30 +33,30 @@ commands:
 
 - autobalanced - all transactions are balanced, after automatically
   inferring missing amounts and conversion rates and then converting
-  amounts to cost. This ensures that each transaction's entry is well
+  amounts to cost. This ensures that each transaction's journal entry is
-  formed.
+  well formed.
 
 - assertions - all balance assertions in the journal are passing.
-  Balance assertions are a strong defense against errors; they help
+  Balance assertions are a strong defense against errors, catching many
-  catch many problems. If this check gets in your way, you can disable
+  problems. This check is on by default, but if it gets in your way, you
-  it with -I/--ignore-assertions. Or you can add that to your config
+  can disable it temporarily with -I/--ignore-assertions, or as a
-  file to disable it by default (and then use -s/--strict or
+  default by adding that flag to your config file. (Then use -s/--strict
-  hledger check assertions to enable it).
+  or hledger check assertions when you want to enable it).
 
 Strict checks
 
-These additional checks are performed by all commands when the
+When the -s/--strict flag is used (AKA strict mode), all commands will
--s/--strict flag is used (strict mode). They provide extra
+perform the following additional checks (and assertions, above). These
-error-catching power to keep your data clean and correct. Strict mode
+provide extra error-catching power to help you keep your data clean and
-also always enables the assertions check.
+correct:
 
-- balanced - like autobalanced, but all conversions between commodities
+- balanced - like autobalanced, but implicit conversions between
-  must use explicit cost notation or equity postings. This prevents
+  commodities are not allowed; all conversion transactions must use cost
-  wrong conversions caused by typos.
+  notation or equity postings. This prevents wrong conversions caused by
+  typos.
 
 - commodities - all commodity symbols used must be declared. This guards
-  against mistyping or omitting commodity symbols. Declaring commodities
+  against mistyping or omitting commodity symbols.
-  also sets their precision for display and transaction balancing.
 
 - accounts - all account names used must be declared. This prevents the
   use of mis-spelled or outdated account names.
@@ -84,10 +84,9 @@ command:
   encourage adding balance assertions for your active asset/liability
   accounts, which in turn should encourage you to reconcile regularly
   with those real world balances - another strong defense against
-  errors. hledger close --assert can help generate assertion entries.
+  errors. (hledger close --assert >>$LEDGER_FILE is a convenient way to
-  Over time the older assertions become somewhat redundant, and you can
+  add new balance assertions. Later these become quite redundant, and
-  remove them if you like (they don't affect performance much, but they
+  you might choose to remove them to reduce clutter.)
-  add some noise to the journal).
 
 - uniqueleafnames - no two accounts may have the same last account name
   part (eg the checking in assets:bank:checking). This ensures each
@@ -99,8 +98,8 @@ Custom checks
 You can build your own custom checks with add-on command scripts. See
 also Cookbook > Scripting. Here are some examples from hledger/bin/:
 
-- hledger-check-tagfiles - all tag values containing / (a forward slash)
+- hledger-check-tagfiles - all tag values containing / exist as file
-  exist as file paths
+  paths
 
 - hledger-check-fancyassertions - more complex balance assertions are
   passing

hledger/Hledger/Cli/Commands/Close.txt

@@ -36,9 +36,17 @@ Flags:
                             all  - also round cost amounts to precision
                                    (can unbalance transactions)
 
-close has six modes, selected by choosing one of the mode flags (--close
+close has six modes, selected by choosing one of the mode flags:
-is the default). They all do much the same operation, but with different
+--clopen, --close (default), --open, --assert, --assign, or --retain.
-defaults, useful in different situations.
+They are all doing the same kind of operation, but with different
+defaults for different situations.
+
+The journal entries generated by close will have a clopen: tag, which is
+helpful when you want to exclude them from reports. If the main journal
+file name contains a number, the tag's value will be that base file name
+with the number incremented. Eg if the journal file is 2025.journal, the
+tag will be clopen:2026. Or you can set the tag value by providing an
+argument to the mode flag. Eg --close=foo or --clopen=2025-main.
 
 close --clopen
 
@@ -77,11 +85,6 @@ RX accounts (Revenue, Expense).
 Assertions will be added indicating and checking the new balances of the
 closed/opened accounts.
 
-The generated transactions will have a clopen: tag. If the main
-journal's base file name contains a number (eg a year number), the tag's
-value will be that base file name with the number incremented. Or you
-can choose the tag value yourself, by using --clopen=TAGVAL.
-
 close --close
 
 This prints just the closing balances transaction of --clopen. It is the
@@ -137,11 +140,12 @@ close customisation
 In all modes, the following things can be overridden:
 
 - the accounts to be closed/opened, with account query arguments
+- the closing/opening dates, with -e OPENDATE
 - the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
 - the transaction descriptions, with --close-desc=DESC and
   --open-desc=DESC
-- the transaction's tag value, with a --MODE=NEW option argument
+- the transactions' clopen tag value, with a TAGVAL argument for the
-- the closing/opening dates, with -e OPENDATE
+  mode flag (see above).
 
 By default, the closing date is yesterday, or the journal's end date,
 whichever is later; and the opening date is always one day after the

hledger/Hledger/Cli/Commands/Print.txt

@@ -121,6 +121,9 @@ unparseable:
 - Auto postings can generate too many amountless postings.
 - --infer-costs or --infer-equity can generate too-complex redundant
   costs.
+- Because print always shows transactions in date order, balance
+  assertions involving non-date-ordered transactions (and same-day
+  postings) could be disrupted.
 
 print, other features