;doc: update CLI usage texts

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -1,36 +1,39 @@
 aregister, areg
 
-Show the transactions and running historical balance in an account, with
-each line item representing one transaction.
+Show the transactions and running historical balance of a single
+account, with each transaction displayed as one line.
 
 _FLAGS
 
-aregister shows the transactions affecting a particular account and its
-subaccounts, with each line item representing a whole transaction - as
-in bank statements, hledger-ui, hledger-web and other accounting apps.
+aregister shows the overall transactions affecting a particular account
+(and any subaccounts). Each report line represents one transaction in
+this account. Transactions before the report start date are always
+included in the running balance (--historical mode is always on).
 
-Note this is unlike the register command, which shows individual
-postings and does not always show a single account or a historical
-balance.
+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
+aregister for reviewing and reconciling real-world asset/liability
+accounts - use register for reviewing detailed revenues/expenses.
 
-A reminder, "historical" balances include any balance from transactions
-before the report start date, so (if opening balances are recorded
-correctly) aregister will show the real-world balances of an account, as
-you would see in a bank statement.
-
-As a quick rule of thumb, use aregister for reconciling real-world
-asset/liability accounts and register for reviewing detailed
-revenues/expenses.
-
-aregister shows the register for just one account (and its subaccounts).
-This account must be specified as the first argument. You can write
+aregister requires one argument: the account to report on. You can write
 either the full account name, or a case-insensitive regular expression
 which will select the alphabetically first matched account. (Eg if you
 have assets:aaa:checking and assets:bbb:checking accounts,
 hledger areg checking would select assets:aaa:checking.)
 
+Transactions involving subaccounts of this account will also be shown.
+aregister ignores depth limits, so its final total will always match a
+balance report with similar arguments.
+
 Any additional arguments form a query which will filter the transactions
-shown.
+shown. Note some queries will disturb the running balance, causing it to
+be different from the account's real-world running balance.
+
+An example: this shows the transactions and historical running balance
+during july, in the first account whose name contains "checking":
+
+$ hledger areg checking date:jul
 
 Each aregister line item shows:
 
@@ -44,11 +47,8 @@ Each aregister line item shows:
 Transactions making a net change of zero are not shown by default; add
 the -E/--empty flag to show them.
 
-aregister ignores a depth limit, so its final total will always match a
-balance report with similar arguments.
-
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, and json.
+options. The output formats supported are txt, csv, and json.
 
 aregister and custom posting dates
 
@@ -61,15 +61,3 @@ the one shown by register -H with the same arguments.
 To filter strictly by transaction date instead, add the --txn-dates
 flag. If you use this flag and some of your postings have custom dates,
 it's probably best to assume the running balance is wrong.
-
-Examples:
-
-Show all transactions and historical running balance in the first
-account whose name contains "checking":
-
-$ hledger areg checking
-
-Show transactions and historical running balance in all asset accounts
-during july:
-
-$ hledger areg assets date:jul