;update CLI usage texts

hledger/Hledger/Cli/Commands/Balance.txt

@@ -29,10 +29,31 @@ html, and json.
 
 The balance command can produce several styles of report:
 
-Classic balance report
+Single-period flat balance report
 
-This is the original balance report, as found in Ledger. It usually
+This is the default for hledger's balance command: a flat list of all
-looks like this:
+(or with a query, matched) accounts, showing full account names.
+Accounts are sorted by declaration order if any, and then by account
+name. Accounts which have zero balance are not shown unless -E/--empty
+is used. The reported balances' total is shown as the last line, unless
+disabled by -N/--no-total.
+
+$ hledger bal
+                  $1  assets:bank:saving
+                 $-2  assets:cash
+                  $1  expenses:food
+                  $1  expenses:supplies
+                 $-1  income:gifts
+                 $-1  income:salary
+                  $1  liabilities:debts
+--------------------
+                   0  
+
+Single-period tree-mode balance report
+
+With the -t/--tree flag, accounts are displayed hierarchically, showing
+subaccounts as short names indented below their parent. (This is the
+default style in Ledger and in older hledger versions.)
 
 $ hledger balance
                  $-1  assets
@@ -48,33 +69,26 @@ $ hledger balance
 --------------------
                    0
 
-By default, accounts are displayed hierarchically, with subaccounts
+For more compact output, "boring" accounts containing a single
-indented below their parent, with accounts at each level of the tree
+interesting subaccount and no balance of their own (assets:bank and
-sorted by declaration order if declared, then by account name.
+liabilities here) are elided into the following line, unless --no-elide
+is used. And accounts which have zero balance and no non-zero
+subaccounts are omitted, unless -E/--empty is used.
 
-"Boring" accounts, which contain a single interesting subaccount and no
+Account balances in tree mode are "inclusive" - they include the
-balance of their own, are elided into the following line for more
+balances of any subaccounts. Eg, the assets $-1 balance here includes
-compact output. (Eg above, the "liabilities" account.) Use --no-elide to
+the $1 from assets:bank:saving and the $-2 from assets:cash. (And it
-prevent this.
+would include balance posted to the assets account itself, if there was
+any). Note this causes some repetition, and the final total (0) is the
+sum of the top-level balances, not of all the balances shown.
 
-Account balances are "inclusive" - they include the balances of any
+Each group of sibling accounts is sorted separately, by declaration
-subaccounts.
+order and then by account name.
 
-Accounts which have zero balance (and no non-zero subaccounts) are
+Customising single-period balance reports
-omitted. Use -E/--empty to show them.
 
-A final total is displayed by default; use -N/--no-total to suppress it,
+You can customise the layout of single-period balance reports with
-eg:
+--format FMT, which sets the format of each line. Eg:
-
-$ hledger balance -p 2008/6 expenses --no-total
-                  $2  expenses
-                  $1    food
-                  $1    supplies
-
-Customising the classic balance report
-
-You can customise the layout of classic balance reports with
---format FMT:
 
 $ hledger balance --format "%20(account) %12(total)"
               assets          $-1
@@ -129,28 +143,12 @@ Some example formats:
 -   %20(total)  %2(depth_spacer)%-(account) - the default format for the
     single-column balance report
 
-Colour support
+Depth limiting
 
-In terminal output, when colour is enabled, the balance command shows
+With a depth:N query, or --depth N option, or just -N, balance reports
-negative amounts in red.
+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
-Flat mode
+shows the top-level accounts:
-
-To see a flat list instead of the default hierarchical display, use
---flat. In this mode, accounts (unless depth-clipped) show their full
-names and "exclusive" balance, excluding any subaccount balances. In
-this mode, you can also use --drop N to omit the first few account name
-components.
-
-$ hledger balance -p 2008/6 expenses -N --flat --drop 1
-                  $1  food
-                  $1  supplies
-
-Depth limited balance reports
-
-With --depth N or depth:N or just -N, balance reports show accounts only
-to the specified numeric depth. This is very useful to summarise a
-complex set of accounts and get an overview.
 
 $ hledger balance -N -1
                  $-1  assets
@@ -158,8 +156,30 @@ $ hledger balance -N -1
                  $-2  income
                   $1  liabilities
 
-Flat-mode balance reports, which normally show exclusive balances, show
+Accounts at the depth limit will include the balances of any hidden
-inclusive balances at the depth limit.
+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
 
@@ -189,47 +209,37 @@ 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.
 
-Sorting by amount
+Multi-period balance report
 
-With -S/--sort-amount, accounts with the largest (most positive)
+Multi-period balance reports are a very useful hledger feature,
-balances are shown first. For example, hledger bal expenses -MAS shows
+activated if you provide one of the reporting interval flags, such as
-your biggest averaged monthly expenses first.
+-M/--monthly. They are similar to single-period balance reports, but
+they show the report as a table, with columns representing one or more
+successive time periods. This is the usually the preferred style of
+balance report in hledger (even for a single period).
 
-Revenues and liability balances are typically negative, however, so -S
+Multi-period balance reports come in several types, showing different
-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.
-
-Multicolumn balance report
-
-Multicolumn or tabular balance reports are a very useful hledger
-feature, and usually the preferred style. They share many of the above
-features, but they show the report as a table, with columns representing
-time periods. This mode is activated by providing a reporting interval.
-
-There are three types of multicolumn balance report, showing different
 information:
 
-1.  By default: each column shows the sum of postings in that period, ie
+1.  A balance change report: by default, each column shows the sum of
-    the account's change of balance in that period. This is useful eg
+    postings in that period, ie the account's change of balance in that
-    for a monthly income statement:
+    period. This is useful eg for a monthly income statement:
 
-    $ hledger balance --quarterly income expenses -E
+$ hledger balance --quarterly income expenses -E
-    Balance changes in 2008:
+Balance changes in 2008:
 
-                       ||  2008q1  2008q2  2008q3  2008q4 
+                   ||  2008q1  2008q2  2008q3  2008q4 
-    ===================++=================================
+===================++=================================
-     expenses:food     ||       0      $1       0       0 
+ expenses:food     ||       0      $1       0       0 
-     expenses:supplies ||       0      $1       0       0 
+ expenses:supplies ||       0      $1       0       0 
-     income:gifts      ||       0     $-1       0       0 
+ income:gifts      ||       0     $-1       0       0 
-     income:salary     ||     $-1       0       0       0 
+ income:salary     ||     $-1       0       0       0 
-    -------------------++---------------------------------
+-------------------++---------------------------------
-                       ||     $-1      $1       0       0 
+                   ||     $-1      $1       0       0 
 
-2.  With --cumulative: each column shows the ending balance for that
+2.  A cumulative end balance report: with --cumulative, each column
-    period, accumulating the changes across periods, starting from 0 at
+    shows the end balance for that period, accumulating the changes
-    the report start date:
+    across periods, starting from 0 at the report start date:
 
     $ hledger balance --quarterly income expenses -E --cumulative
     Ending balances (cumulative) in 2008:
@@ -243,11 +253,12 @@ information:
     -------------------++-------------------------------------------------
                        ||         $-1           0           0           0 
 
-3.  With --historical/-H: each column shows the actual historical ending
+3.  A historical end balance report: with --historical/-H, each column
-    balance for that period, accumulating the changes across periods,
+    shows the actual historical end balance for that period,
-    starting from the actual balance at the report start date. This is
+    accumulating the changes across periods, and including the balance
-    useful eg for a multi-period balance sheet, and when you are showing
+    from any postings before the report start date. This is useful eg
-    only the data after a certain start date:
+    for a multi-period balance sheet, and when you want to see balances
+    only after a certain date:
 
     $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
     Ending balances (historical) in 2008/04/01-2008/12/31:
@@ -264,9 +275,6 @@ information:
 Note that --cumulative or --historical/-H disable --row-total/-T, since
 summing end balances generally does not make sense.
 
-Multicolumn balance reports display accounts in flat mode by default; to
-see the hierarchy, use --tree.
-
 With a reporting interval (like --quarterly above), the report start/end
 dates will be adjusted if necessary so that they encompass the displayed
 report periods. This is so that the first and last periods will be

hledger/Hledger/Cli/Commands/Check.txt

@@ -1,16 +1,19 @@
 check
-Check for various kinds of errors in your data. experimental
+Check for various kinds of errors in your data.
 
 _FLAGS
 
 hledger provides a number of built-in error checks to help prevent
 problems in your data. Some of these are run automatically; or, you can
 use this check command to run them on demand, with no output and a zero
-exit code if all is well. Some examples:
+exit code if all is well. Specify their names (or a prefix) as
+argument(s).
+
+Some examples:
 
 hledger check      # basic checks
 hledger check -s   # basic + strict checks
-hledger check ordereddates uniqueleafnames  # basic + specified checks
+hledger check ordereddates payees  # basic + two other checks
 
 Here are the checks currently available:
 
@@ -32,7 +35,7 @@ commands, including check:
 Strict checks
 
 These additional checks are run when the -s/--strict (strict mode) flag
-is used. They can also be run by specifying their names as arguments to
+is used. Or, they can be run by giving their names as arguments to
 check:
 
 -   accounts - all account names used by transactions have been declared
@@ -41,8 +44,9 @@ check:
 
 Other checks
 
-These checks can be run only by specifying their names as arguments to
+These checks can be run only by giving their names as arguments to
-check:
+check. They are more specialised and not desirable for everyone,
+therefore optional:
 
 -   ordereddates - transactions are ordered by date (similar to the old
     check-dates command)
@@ -50,12 +54,11 @@ check:
 -   payees - all payees used by transactions have been declared
 
 -   uniqueleafnames - all account leaf names are unique (similar to the
-    old check-dupes command)
+    old check-dupes command).
 
-Add-on checks
+Custom checks
 
-These checks are not yet integrated with check, but are available as
+A few more checks are are available as separate add-on commands, in
-add-on commands in
 https://github.com/simonmichael/hledger/tree/master/bin:
 
 -   hledger-check-tagfiles - all tag values containing / (a forward
@@ -64,5 +67,5 @@ https://github.com/simonmichael/hledger/tree/master/bin:
 -   hledger-check-fancyassertions - more complex balance assertions are
     passing
 
-You could make your own similar scripts to perform custom checks;
+You could make similar scripts to perform your own custom checks. See:
-Cookbook -> Scripting may be helpful.
+Cookbook -> Scripting.