;doc: update CLI usage texts

hledger/Hledger/Cli/Commands/Add.txt

@@ -24,8 +24,8 @@ Features:
 -   You can also set the initial defaults with command line arguments.
 -   Readline-style edit keys can be used during data entry.
 -   The tab key will auto-complete whenever possible - accounts,
-    descriptions, dates (yesterday, today, tomorrow). If the input area
+    payees/descriptions, dates (yesterday, today, tomorrow). If the
-    is empty, it will insert the default value.
+    input area is empty, it will insert the default value.
 -   If the journal defines a default commodity, it will be added to any
     bare numbers entered.
 -   A parenthesised transaction code may be entered following a date.

hledger/Hledger/Cli/Commands/Balance.txt

@@ -387,29 +387,21 @@ balances:
 Balance report types
 
 The balance command is quite flexible; here is the full detail on how to
-control what it reports. There are three important option groups:
+control what it reports. If the following seems complicated, don't
+worry - this is for advanced reporting, and it does typically take some
+time and experimentation to get clear on all these report modes.
+
+There are three important option groups:
 
 hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
 
-The first two are the most important:
-
--   calculation type selects the basic calculation to perform for each
-    table cell
--   accumulation type says which postings should be included in each
-    cell's calculation
-
-Typically one or both of these are selected by default, so you don't
-need to write them explicitly. Then
-
--   a valuation type can be added if you want to convert the basic
-    report to value or cost
-
 Calculation type
 
 The basic calculation to perform for each table cell. It is one of:
 
 -   --sum : sum the posting amounts (default)
--   --budget : like --sum but also show a goal amount
+-   --budget : sum the amounts, but also show the budget goal amount
+    (for each account/period)
 -   --valuechange : show the change in period-end historical balance
     values (caused by deposits, withdrawals, and/or market price
     fluctuations)
@@ -418,36 +410,49 @@ The basic calculation to perform for each table cell. It is one of:
 
 Accumulation type
 
-Which postings should be included in each cell's calculation. It is one
+How amounts should accumulate across report periods. Another way to say
-of:
+it: which time period's postings should contribute to each cell's
+calculation. It is one of:
 
--   --change : postings from column start to column end, ie within the
+-   --change : calculate with postings from column start to column end,
-    cell's period. Typically used to see revenues/expenses. (default for
+    ie "just this column". Typically used to see revenues/expenses.
-    balance, incomestatement)
+    (default for balance, incomestatement)
 
--   --cumulative : postings from report start to column end, eg to show
+-   --cumulative : calculate with postings from report start to column
-    changes accumulated since the report's start date. Rarely used.
+    end, ie "previous columns plus this column". Typically used to show
+    changes accumulated since the report's start date. Not often used.
 
--   --historical/-H : postings from journal start to column end, ie all
+-   --historical/-H : calculate with postings from journal start to
-    postings from account creation to the end of the cell's period.
+    column end, ie "all postings from before report start date until
-    Typically used to see historical end balances of
+    this column's end". Typically used to see historical end balances of
     assets/liabilities/equity. (default for balancesheet,
     balancesheetequity, cashflow)
 
 Valuation type
 
-Which kind of valuation, valuation date(s) and optionally a target
+Which kind of value or cost conversion should be applied, if any, before
-valuation commodity to use. It is one of:
+displaying the report. It is one of:
 
--   no valuation, show amounts in their original commodities (default)
+-   no valuation type : don't convert to cost or value (default)
--   --value=cost[,COMM] : no valuation, show amounts converted to cost
+-   --value=cost[,COMM] : convert amounts to cost (then optionally to
--   --value=then[,COMM] : show value at transaction dates
+    some other commodity)
--   --value=end[,COMM] : show value at period end date(s) (default with
+-   --value=then[,COMM] : convert amounts to market value on transaction
-    --valuechange, --gain)
+    dates
--   --value=now[,COMM] : show value at today's date
+-   --value=end[,COMM] : convert amounts to market value on period end
--   --value=YYYY-MM-DD[,COMM] : show value at another date
+    date(s)
+    (default with --valuechange, --gain)
+-   --value=now[,COMM] : convert amounts to market value on today's date
+-   --value=YYYY-MM-DD[,COMM] : convert amounts to market value on
+    another date
 
-or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
+or one of the equivalent simpler flags:
+
+-   -B/--cost : like --value=cost (though, note --cost and --value are
+    independent options which can both be used at once)
+-   -V/--market : like --value=end
+-   -X COMM/--exchange COMM : like --value=end,COMM
+
+See Cost reporting and Valuation for more about these.
 
 Combining balance report types
 
@@ -490,8 +495,8 @@ Budget report
 
 The --budget report type activates extra columns showing any budget
 goals for each account and period. The budget goals are defined by
-periodic transactions. This is very useful for comparing planned and
+periodic transactions. This is useful for comparing planned and actual
-actual income, expenses, time usage, etc.
+income, expenses, time usage, etc.
 
 For example, you can take average monthly expenses in the common expense
 categories to construct a minimal monthly budget:
@@ -749,21 +754,21 @@ select from multiple budgets defined in your journal.
 
 Data layout
 
-The --layout option affects how balance reports show commodity symbols
+The --layout option affects how balance reports show multi-commodity
-and multi-commodity amounts, which can improve readability. It can also
+amounts and commodity symbols, which can improve readability. It can
-normalise the data for easy consumption by other programs. It has four
+also normalise the data for easy consumption by other programs. It has
-possible values:
+four possible values:
 
 -   --layout=wide[,WIDTH]: commodities are shown on a single line,
-    possibly elided to the specified width
+    optionally elided to WIDTH
 -   --layout=tall: each commodity is shown on a separate line
--   --layout=bare: amounts are shown as bare numbers, with commodity
+-   --layout=bare: commodity symbols are in their own column, amounts
-    symbols in a separate column
+    are bare numbers
 -   --layout=tidy: data is normalised to easily-consumed "tidy" form,
-    with one row per data value (works only with CSV output)
+    with one row per data value
 
-These --layout modes are supported with some but not all of the output
+Here are the --layout modes supported by each output format; note only
-formats:
+CSV output supports all of them:
 
   -      txt   csv   html   json   sql
   ------ ----- ----- ------ ------ -----
@@ -838,7 +843,7 @@ Examples:
                       || VHT        106.00   18.00   170.00   294.00 
 
 -   Bare layout also affects CSV output, which is useful for producing
-    data that is easier to consume, eg when making charts:
+    data that is easier to consume, eg for making charts:
 
     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
     "account","commodity","balance"
@@ -856,10 +861,8 @@ Examples:
 -   Tidy layout produces normalised "tidy data", where every variable
     has its own column and each row represents a single data point. See
     https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html
-    for more.
+    for more. This is the easiest kind of data for other software to
-
+    consume. Here's how it looks:
-    This kind of output is the easiest to process with other software.
-    Here's how it looks:
 
     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
     "account","period","start_date","end_date","commodity","value"
@@ -879,12 +882,6 @@ Examples:
     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
 
-    Currently tidy layout is supported only with CSV output.
-
-    In tidy mode, row totals, row averages and column totals are not
-    shown (-T/--row-total and -A/--average flags are disabled and
-    -N/--no-total is enabled).
-
 Useful balance reports
 
 Some frequently used balance options/reports are:

hledger/Hledger/Cli/Commands/Stats.txt

@@ -32,5 +32,5 @@ Market prices            : 1000 (A)
 Run time                 : 0.12 s
 Throughput               : 8342 txns/s
 
-This command also supports output destination and output format
+This command supports the -o/--output-file option (but not
-selection.
+-O/--output-format selection).