;bal: more doc updates

hledger/Hledger/Cli/Commands/Balance.md

@@ -10,25 +10,51 @@ columns representing time periods.
 Compared to Ledger's balance command, hledger's `balance` adds the
 significant feature of multi-period reports.
 
-Note there are some easier variants of the `balance` command which 
+Note there are some higher-level variants of the `balance` command
-are more convenient for everyday financial reporting:
+with convenient defaults, which can be simpler to use:
 [`balancesheet`](#balancesheet),
 [`balancesheetequity`](#balancesheetequity),
 [`cashflow`](#cashflow) and
 [`incomestatement`](#incomestatement). 
-But when you want most control, you can use `balance`.
+When you need more control, then use `balance`. 
-It can show:
 
-- accounts as a flat list or a tree, optionally depth-limited (`-l`, `-t`, `-[1-9]`)
+Here's a quick overview of `balance` features
-- a single time period or multiple periods (`-D`, `-W`, `-M`, `-Q`, `-Y`, `-p INTERVAL`)
+(many of these work with the higher-level commands as well),
-- balance changes in each period (`--change`)
+followed by more detailed descriptions and examples. 
-- actual and planned balance changes, and their relative percentage, in each period (`--budget`)
+`balance` can show..
-- accumulated totals at the end of each period (counting from report start) (`--cumulative`)
+
-- historical end balances at the end of each period (assuming a suitable opening balances transaction) (`--historical`)
+- accounts as a [list (`-l`) or a tree (`-t`)](#list-or-tree-mode)
-- totals, averages, percentages, inverted sign (`-T`, `-A`, `-%`, `--invert`)
+- optionally depth-limited ([`-[1-9]`](#depth-limiting))
-- custom-formatted line items (in single-period reports) (`--format`)
+- sorted [by declaration order and name](#simple-balance-report),
-- transposed data - swapping the rows and columns (in multi-period reports) (`--transpose`)
+  or [by amount](#sorting-by-amount)
-- pivoted data - using a different field as the "account name" (`--pivot FIELD`) (see [PIVOTING](#pivoting)
+
+..and their..
+
+- balance changes ([`--change`](#simple-balance-report), the default report type)
+- or actual and planned balance changes ([`--budget`](#budget-report))
+- or value of balance changes ([`--change -V`](#valuation-type))
+- or change of balance value ([`--valuechange`](#report-type))
+
+..in..
+
+- one time period (the whole journal period by default)
+- or multiple periods ([`-D`, `-W`, `-M`, `-Q`, `-Y`, `-p INTERVAL`](#report-intervals))
+
+..either..
+
+- per period ([`--periodic`](#accumulation-type), the default accumulation type)
+- or accumulated since report start date ([`--cumulative`](#accumulation-type))
+- or accumulated since account creation ([`--historical/-H`](#accumulation-type))
+
+..with..
+
+- totals ([`-T`](#multi-period-balance-report)), 
+  averages ([`-A`](#multi-period-balance-report)), 
+  percentages ([`-%`](#percentages)), 
+  inverted sign ([`--invert`](#sorting-by-amount))
+- rows and columns swapped ([`--transpose`](#multi-period-balance-report))
+- another field used as account name ([`--pivot`](#multi-period-balance-report))
+- custom-formatted line items (single-period reports only) ([`--format`](#customising-single-period-balance-reports))
 
 This command supports the
 [output destination](#output-destination) and
@@ -36,8 +62,6 @@ This command supports the
 with output formats `txt`, `csv`, `json`, and (multi-period reports only:) `html`. 
 In `txt` output in a colour-supporting terminal, negative amounts are shown in red.
 
-Here are some examples of `balance` reports and features.
-
 <a name="classic-balance-report"></a>
 
 ### Simple balance report
@@ -202,6 +226,8 @@ shown, unless `-E/--empty` is used.
 - Average and/or total columns can be added with the `-A/--average` and
 `-T/--row-total` flags.
 - The `--transpose` flag can be used to exchange rows and columns.
+- The `--pivot FIELD` option causes a different transaction field to be used as
+  "account name". See [PIVOTING](#pivoting).
      
 Multi-period reports with many periods can be too wide for easy viewing in the terminal.
 Here are some ways to handle that:
@@ -311,25 +337,35 @@ For more flexible reporting, there are three important option groups:
 `hledger balance [REPORTTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...`
 
 #### Report type
-The general thing that is calculated/shown in each cell. It is one of:
+The general thing that is calculated/shown in each cell. 
+It is one of:
 
 - `--change` : show a sum of posting amounts (**default**)
 - `--budget` : like --change but also show a budget goal amount
 - `--valuechange` : show change of value of period-end historical balances
 <!-- - `--gain` : show change of value of period-end historical balances caused by market price fluctuations -->
 
-More report types are on the way.
-
 #### Accumulation type
 Which previous periods' postings should be included in calculations
 (especially in multiperiod reports).
 It is one of:
 
-- `--periodic` : postings from column start to column end. Ie, show changes in each period. Typically used when reviewing revenues/expenses. (**default for balance, incomestatement**)
+- `--periodic` : postings from column start to column end. Ie, show
+  [changes] in each period. Typically used when reviewing
+  revenues/expenses. (**default for balance, incomestatement**)
 
-- `--cumulative` : postings from report start (specified by -b/--begin, eg) to column end. Ie, show changes since start of report. Rarely used.
+- `--cumulative` : postings from report start (specified by
+  -b/--begin, eg) to column end. Ie, show [accumulated changes] since
+  start of report. Rarely used.
 
-- `--historical/-H` : postings from journal start to column end. Ie, show historical balance at end of each period. Typically used when reviewing assets/liabilities/equity. (**default for balancesheet, balancesheetequity, cashflow**)
+- `--historical/-H` : postings from journal start to column end. Ie,
+  show [historical balance] at end of each period. Typically used when
+  reviewing assets/liabilities/equity. (**default for balancesheet,
+  balancesheetequity, cashflow**)
+
+[changes]:             #balance-change-end-balance-historical-end-balance
+[accumulated changes]: #balance-change-end-balance-historical-end-balance
+[historical balance]:  #balance-change-end-balance-historical-end-balance
 
 #### Valuation type
 Which kind of [valuation], [valuation date(s)] and optionally a target [valuation commodity] to use.