;update CLI usage texts

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -1,35 +1,52 @@
 aregister, areg
-Show transactions affecting a particular account, and the account's
+
-running balance.
+Show the transactions and running historical balance in an account, with
+each line item representing one transaction.
 
 _FLAGS
 
-aregister shows the transactions affecting a particular account (and its
+aregister shows the transactions affecting a particular account and its
-subaccounts), from the point of view of that account. Each line shows:
+subaccounts, with each line item representing a whole transaction - as
+in bank statements, hledger-ui, hledger-web and other accounting apps.
 
--   the transaction's (or posting's, see below) date
+Note this is unlike the register command, which shows individual
--   the names of the other account(s) involved
+postings and does not always show a single account or a historical
--   the net change to this account's balance
+balance.
--   the account's historical running balance (including balance from
-    transactions before the report start date).
 
-With aregister, each line represents a whole transaction - as in
+A reminder, "historical" balances include any balance from transactions
-hledger-ui, hledger-web, and your bank statement. By contrast, the
+before the report start date, so (if opening balances are recorded
-register command shows individual postings, across all accounts. You
+correctly) aregister will show the real-world balances of an account, as
-might prefer aregister for reconciling with real-world asset/liability
+you would see in a bank statement.
-accounts, and register for reviewing detailed revenues/expenses.
 
-An account must be specified as the first argument, which should be the
+As a quick rule of thumb, use aregister for reconciling real-world
-full account name or an account pattern (regular expression). aregister
+asset/liability accounts and register for reviewing detailed
-will show transactions in this account (the first one matched) and any
+revenues/expenses.
-of its subaccounts.
+
+aregister shows the register for just one account (and its subaccounts).
+This account must be specified as the first argument. 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.)
 
 Any additional arguments form a query which will filter the transactions
 shown.
 
+Each aregister line item shows:
+
+-   the transaction's date (or the relevant posting's date if different,
+    see below)
+-   the names of all the other account(s) involved in this transaction
+    (probably abbreviated)
+-   the total change to this account's balance from this transaction
+-   the account's historical running balance after this transaction.
+
 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.
 

hledger/Hledger/Cli/Commands/Balance.txt

@@ -85,130 +85,6 @@ sum of the top-level balances, not of all the balances shown.
 Each group of sibling accounts is sorted separately, by declaration
 order and then by account name.
 
-Customising single-period balance reports
-
-You can customise the layout of single-period balance reports with
---format FMT, which sets the format of each line. Eg:
-
-$ hledger balance --format "%20(account) %12(total)"
-              assets          $-1
-         bank:saving           $1
-                cash          $-2
-            expenses           $2
-                food           $1
-            supplies           $1
-              income          $-2
-               gifts          $-1
-              salary          $-1
-   liabilities:debts           $1
----------------------------------
-                                0
-
-The FMT format string (plus a newline) specifies the formatting applied
-to each account/balance pair. It may contain any suitable text, with
-data fields interpolated like so:
-
-%[MIN][.MAX](FIELDNAME)
-
--   MIN pads with spaces to at least this width (optional)
-
--   MAX truncates at this width (optional)
-
--   FIELDNAME must be enclosed in parentheses, and can be one of:
-
-    -   depth_spacer - a number of spaces equal to the account's depth,
-        or if MIN is specified, MIN * depth spaces.
-    -   account - the account's name
-    -   total - the account's balance/posted total, right justified
-
-Also, FMT can begin with an optional prefix to control how
-multi-commodity amounts are rendered:
-
--   %_ - render on multiple lines, bottom-aligned (the default)
--   %^ - render on multiple lines, top-aligned
--   %, - render on one line, comma-separated
-
-There are some quirks. Eg in one-line mode, %(depth_spacer) has no
-effect, instead %(account) has indentation built in. Experimentation may
-be needed to get pleasing results.
-
-Some example formats:
-
--   %(total) - the account's total
--   %-20.20(account) - the account's name, left justified, padded to 20
-    characters and clipped at 20 characters
--   %,%-50(account)  %25(total) - account name padded to 50 characters,
-    total padded to 20 characters, with multiple commodities rendered on
-    one line
--   %20(total)  %2(depth_spacer)%-(account) - the default format for the
-    single-column balance report
-
-Depth limiting
-
-With a depth:N query, or --depth N option, or just -N, balance reports
-will show accounts only to the specified depth. This is very useful to
-hide low-level accounts and get an overview. Eg, limiting to depth 1
-shows the top-level accounts:
-
-$ hledger balance -N -1
-                 $-1  assets
-                  $2  expenses
-                 $-2  income
-                  $1  liabilities
-
-Accounts at the depth limit will include the balances of any hidden
-subaccounts (even in flat mode, which normally shows exclusive
-balances).
-
-You can also drop account name components from the start of account
-names, using --drop N. This can be useful to hide unwanted top-level
-detail.
-
-Colour support
-
-In terminal output, when colour is enabled, the balance command shows
-negative amounts in red.
-
-Sorting by amount
-
-With -S/--sort-amount, accounts with the largest (most positive)
-balances are shown first. For example, hledger bal expenses -MAS shows
-your biggest averaged monthly expenses first.
-
-Revenues and liability balances are typically negative, however, so -S
-shows these in reverse order. To work around this, you can add --invert
-to flip the signs. Or, use one of the sign-flipping reports like
-balancesheet or incomestatement, which also support -S. Eg:
-hledger is -MAS.
-
-Percentages
-
-With -% or --percent, balance reports show each account's value
-expressed as a percentage of the column's total. This is useful to get
-an overview of the relative sizes of account balances. For example to
-obtain an overview of expenses:
-
-$ hledger balance expenses -%
-             100.0 %  expenses
-              50.0 %    food
-              50.0 %    supplies
---------------------
-             100.0 %
-
-Note that --tree does not have an effect on -%. The percentages are
-always relative to the total sum of each column, they are never relative
-to the parent account.
-
-Since the percentages are relative to the columns sum, it is usually not
-useful to calculate percentages if the signs of the amounts are mixed.
-Although the results are technically correct, they are most likely
-useless. Especially in a balance report that sums up to zero (eg
-hledger balance -B) all percentage values will be zero.
-
-This flag does not work if the report contains any mixed commodity
-accounts. If there are mixed commodity accounts in the report be sure to
-use -V or -B to coerce the report into using a single commodity.
-
 Multi-period balance report
 
 Multi-period balance reports are a very useful hledger feature,
@@ -325,13 +201,137 @@ When the report is still too wide, a good workaround is to pipe it into
 less -RS (-R for colour, -S to chop long lines). Eg:
 hledger bal -D --color=yes | less -RS.
 
+Depth limiting
+
+With a depth:N query, or --depth N option, or just -N, balance reports
+will show accounts only to the specified depth. This is very useful to
+hide low-level accounts and get an overview. Eg, limiting to depth 1
+shows the top-level accounts:
+
+$ hledger balance -N -1
+                 $-1  assets
+                  $2  expenses
+                 $-2  income
+                  $1  liabilities
+
+Accounts at the depth limit will include the balances of any hidden
+subaccounts (even in flat mode, which normally shows exclusive
+balances).
+
+You can also drop account name components from the start of account
+names, using --drop N. This can be useful to hide unwanted top-level
+detail.
+
+Colour support
+
+In terminal output, when colour is enabled, the balance command shows
+negative amounts in red.
+
+Sorting by amount
+
+With -S/--sort-amount, accounts with the largest (most positive)
+balances are shown first. For example, hledger bal expenses -MAS shows
+your biggest averaged monthly expenses first.
+
+Revenues and liability balances are typically negative, however, so -S
+shows these in reverse order. To work around this, you can add --invert
+to flip the signs. Or, use one of the sign-flipping reports like
+balancesheet or incomestatement, which also support -S. Eg:
+hledger is -MAS.
+
+Percentages
+
+With -% or --percent, balance reports show each account's value
+expressed as a percentage of the column's total. This is useful to get
+an overview of the relative sizes of account balances. For example to
+obtain an overview of expenses:
+
+$ hledger balance expenses -%
+             100.0 %  expenses
+              50.0 %    food
+              50.0 %    supplies
+--------------------
+             100.0 %
+
+Note that --tree does not have an effect on -%. The percentages are
+always relative to the total sum of each column, they are never relative
+to the parent account.
+
+Since the percentages are relative to the columns sum, it is usually not
+useful to calculate percentages if the signs of the amounts are mixed.
+Although the results are technically correct, they are most likely
+useless. Especially in a balance report that sums up to zero (eg
+hledger balance -B) all percentage values will be zero.
+
+This flag does not work if the report contains any mixed commodity
+accounts. If there are mixed commodity accounts in the report be sure to
+use -V or -B to coerce the report into using a single commodity.
+
+Customising single-period balance reports
+
+You can customise the layout of single-period balance reports with
+--format FMT, which sets the format of each line. Eg:
+
+$ hledger balance --format "%20(account) %12(total)"
+              assets          $-1
+         bank:saving           $1
+                cash          $-2
+            expenses           $2
+                food           $1
+            supplies           $1
+              income          $-2
+               gifts          $-1
+              salary          $-1
+   liabilities:debts           $1
+---------------------------------
+                                0
+
+The FMT format string (plus a newline) specifies the formatting applied
+to each account/balance pair. It may contain any suitable text, with
+data fields interpolated like so:
+
+%[MIN][.MAX](FIELDNAME)
+
+-   MIN pads with spaces to at least this width (optional)
+
+-   MAX truncates at this width (optional)
+
+-   FIELDNAME must be enclosed in parentheses, and can be one of:
+
+    -   depth_spacer - a number of spaces equal to the account's depth,
+        or if MIN is specified, MIN * depth spaces.
+    -   account - the account's name
+    -   total - the account's balance/posted total, right justified
+
+Also, FMT can begin with an optional prefix to control how
+multi-commodity amounts are rendered:
+
+-   %_ - render on multiple lines, bottom-aligned (the default)
+-   %^ - render on multiple lines, top-aligned
+-   %, - render on one line, comma-separated
+
+There are some quirks. Eg in one-line mode, %(depth_spacer) has no
+effect, instead %(account) has indentation built in. Experimentation may
+be needed to get pleasing results.
+
+Some example formats:
+
+-   %(total) - the account's total
+-   %-20.20(account) - the account's name, left justified, padded to 20
+    characters and clipped at 20 characters
+-   %,%-50(account)  %25(total) - account name padded to 50 characters,
+    total padded to 20 characters, with multiple commodities rendered on
+    one line
+-   %20(total)  %2(depth_spacer)%-(account) - the default format for the
+    single-column balance report
+
 Budget report
 
-With --budget, extra columns are displayed showing budget goals for each
+There is also a special balance report mode for showing budget
-account and period, if any. Budget goals are defined by periodic
+performance. The --budget flag activates extra columns showing the
-transactions. This is very useful for comparing planned and actual
+budget goals for each account and period, if any. For this report,
-income, expenses, time usage, etc. --budget is most often combined with
+budget goals are defined by periodic transactions. This is very useful
-a report interval.
+for comparing planned and actual income, expenses, time usage, etc.
 
 For example, you can take average monthly expenses in the common expense
 categories to construct a minimal monthly budget:

hledger/Hledger/Cli/Commands/Payees.txt

@@ -3,11 +3,15 @@ List the unique payee/payer names that appear in transactions.
 
 _FLAGS
 
-This command lists the unique payee/payer names that appear in
+This command lists unique payee/payer names which have been declared
-transactions, in alphabetic order. You can add a query to select a
+with payee directives (--declared), used in transaction descriptions
-subset of transactions. The payee/payer is the part of the transaction
+(--used), or both (the default).
-description before a | character (or if there is no |, the whole
+
-description).
+The payee/payer is the part of the transaction description before a |
+character (or if there is no |, the whole description).
+
+You can add query arguments to select a subset of transactions. This
+implies --used.
 
 Example:
 

hledger/Hledger/Cli/Commands/Print.txt

@@ -5,9 +5,21 @@ _FLAGS
 
 The print command displays full journal entries (transactions) from the
 journal file, sorted by date (or with --date2, by secondary date).
+
+Amounts are shown mostly normalised to commodity display style, eg the
+placement of commodity symbols will be consistent. All of their decimal
+places are shown, as in the original journal entry (with one alteration:
+in some cases trailing zeroes are added.)
+
 Amounts are shown right-aligned within each transaction (but not across
-all transactions). Directives and inter-transaction comments are not
+all transactions).
-shown. Eg:
+
+Directives and inter-transaction comments are not shown, currently. This
+means the print command is somewhat lossy, and if you are using it to
+reformat your journal you should take care to also copy over the
+directives and file-level comments.
+
+Eg:
 
 $ hledger print
 2008/01/01 income
@@ -41,8 +53,6 @@ $ hledger print assets:cash | hledger -f- -I reg expenses:food
 
 There are some situations where print's output can become unparseable:
 
--   Rounding amounts according to commodity display styles can cause
-    transactions to appear unbalanced.
 -   Valuation affects posting amounts but not balance assertion or
     balance assignment amounts, potentially causing those to fail.
 -   Auto postings can generate postings with too many missing amounts.