;doc: update command docs

hledger/Hledger/Cli/Commands/Accounts.txt

@@ -1,34 +1,29 @@
 accounts
 
-List account names.
+List the account names used or declared in the journal.
 
 Flags:
-  -u --used                 show only accounts used by transactions
+  -u --used                 list accounts used
-  -d --declared             show only accounts declared by account directive
+  -d --declared             list accounts declared
-     --unused               show only accounts declared but not used
+     --undeclared           list accounts used but not declared
-     --undeclared           show only accounts used but not declared
+     --unused               list accounts declared but not used
+     --find                 list the first account matched by the first
+                            argument (a case-insensitive infix regexp)
      --types                also show account types when known
      --positions            also show where accounts were declared
      --directives           show as account directives, for use in journals
-     --find                 find the first account matched by the first
-                            argument (a case-insensitive infix regexp or
-                            account name)
   -l --flat                 list/tree mode: show accounts as a flat list
                             (default)
   -t --tree                 list/tree mode: show accounts as a tree
      --drop=N               flat mode: omit N leading account name parts
 
-This command lists account names. By default it shows all known
+This command lists account names - all of them by default. or just the
-accounts, either used in transactions or declared with account
+ones which have been used in transactions, or declared with account
-directives.
+directives, or used but not declared, or declared but not used, or just
+the first account name matched by a pattern.
 
-With query arguments, only matched account names and account names
+You can add query arguments to select a subset of transactions or
-referenced by matched postings are shown.
+accounts.
-
-Or it can show just the used accounts (--used/-u), the declared accounts
-(--declared/-d), the accounts declared but not used (--unused), the
-accounts used but not declared (--undeclared), or the first account
-matched by an account name pattern, if any (--find).
 
 It shows a flat list by default. With --tree, it uses indentation to
 show the account hierarchy. In flat mode you can add --drop N to omit
@@ -42,10 +37,10 @@ With --positions, it also shows the file and line number of each
 account's declaration, if any, and the account's overall declaration
 order; these may be useful when troubleshooting account display order.
 
-With --directives, it adds the account keyword, showing valid account
+With --directives, it shows valid account directives which could be
-directives which can be pasted into a journal file. This is useful
+pasted into a journal file. This is useful together with --undeclared
-together with --undeclared when updating your account declarations to
+when updating your account declarations to satisfy
-satisfy hledger check accounts.
+hledger check accounts.
 
 The --find flag can be used to look up a single account name, in the
 same way that the aregister command does. It returns the

hledger/Hledger/Cli/Commands/Add.txt

@@ -57,3 +57,27 @@ Examples:
   hledger add today 'best buy' expenses:supplies '$20'
 
 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
+re-check all balance assertions in the journal, and if any of them fail,
+it will report the problem and ask for the amount again.
+
+You can also add a new balance assertion, following the amount as in
+journal format.
+
+The new transaction's date, and the new posting's posting date if any
+(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.
+When add runs, it sees the journal with all balance assignments already
+processed and converted to assertions. So if you add a new posting which
+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.

hledger/Hledger/Cli/Commands/Commodities.txt

@@ -1,6 +1,16 @@
 commodities
 
-List all commodity/currency symbols used or declared in the journal.
+List the commodity symbols used or declared in the journal.
 
 Flags:
-no command-specific flags
+     --used                 list commodities used
+     --declared             list commodities declared
+     --undeclared           list commodities used but not declared
+     --unused               list commodities declared but not used
+
+This command lists commodity symbols/names - all of them by default, or
+just the ones which have been used in transactions or P directives, or
+declared with commodity directives, or used but not declared, or
+declared but not used.
+
+You can add cur: query arguments to further limit the commodities.

hledger/Hledger/Cli/Commands/Descriptions.txt

@@ -1,6 +1,6 @@
 descriptions
 
-List the unique descriptions that appear in transactions.
+List the unique descriptions used in transactions.
 
 Flags:
 no command-specific flags

hledger/Hledger/Cli/Commands/Payees.txt

@@ -1,20 +1,23 @@
 payees
 
-List the unique payee/payer names that appear in transactions.
+List the payee/payer names used or declared in the journal.
 
 Flags:
-     --declared             show payees declared with payee directives
+     --used                 list payees used
-     --used                 show payees referenced by transactions
+     --declared             list payees declared
+     --undeclared           list payees used but not declared
+     --unused               list payees declared but not used
 
-This command lists unique payee/payer names which have been declared
+This command lists unique payee/payer names - all of them by default, or
-with payee directives (--declared), used in transaction descriptions
+just the ones which have been used in transaction descriptions, or
-(--used), or both (the default).
+declared with payee directives, or used but not declared, or declared
+but not used.
 
-The payee/payer is the part of the transaction description before a |
+The payee/payer name is the part of the transaction description before a
-character (or if there is no |, the whole description).
+| character (or if there is no |, the whole description).
 
-You can add query arguments to select a subset of transactions. This
+You can add query arguments to select a subset of transactions or
-implies --used.
+payees.
 
 Example:
 

hledger/Hledger/Cli/Commands/Print.txt

@@ -24,7 +24,7 @@ Flags:
      --base-url=URLPREFIX   in html output, generate links to hledger-web,
                             with this prefix. (Usually the base url shown by
                             hledger-web; can also be relative.)
-     --location             add file/line number tags to print output
+     --location             add tags showing file paths and line numbers
   -O --output-format=FMT    select the output format. Supported formats:
                             txt, beancount, csv, tsv, html, fods, json, sql.
   -o --output-file=FILE     write output to FILE. A file extension matching

hledger/Hledger/Cli/Commands/Tags.txt

@@ -1,30 +1,34 @@
 tags
 
-List the tags used in the journal, or their values.
+List the tag names used or declared in the journal, or their values.
 
 Flags:
+     --used                 list tags used
+     --declared             list tags declared
+     --undeclared           list tags used but not declared
+     --unused               list tags declared but not used
      --values               list tag values instead of tag names
-     --parsed               show tags/values in the order they were parsed,
+     --parsed               show them in the order they were parsed (mostly),
                             including duplicates
 
-This command lists the tag names used in the journal, whether on
+This command lists tag names - all of them by default, or just the ones
-transactions, postings, or account declarations.
+which have been used on transactions/postings/accounts, or declared with
+tag directives, or used but not declared, or declared but not used.
 
-With a TAGREGEX argument, only tag names matching this regular
+You can add one TAGREGEX argument, to show only tags whose name is
-expression (case insensitive, infix matched) are shown.
+matched by this case-insensitive, infix-matching regular expression.
 
-With QUERY arguments, only transactions and accounts matching this query
+After that, you can add query arguments to filter the transactions,
-are considered. If the query involves transaction fields (date:, desc:,
+postings, or accounts providing tags.
-amt:, ...), the search is restricted to the matched transactions and
-their accounts.
 
-With the --values flag, the tags' unique non-empty values are listed
+With --values, the tags' unique non-empty values are listed instead.
-instead. With -E/--empty, blank/empty values are also shown.
+
+With -E/--empty, blank/empty values are also shown.
 
 With --parsed, tags or values are shown in the order they were parsed,
 with duplicates included. (Except, tags from account declarations are
 always shown first.)
 
-Tip: remember, accounts also acquire tags from their parents, postings
+Remember that accounts also acquire tags from their parents; postings
-also acquire tags from their account and transaction, transactions also
+also acquire tags from their account and transaction; and transactions
-acquire tags from their postings.
+also acquire tags from their postings.