;doc: update command docs

hledger/Hledger/Cli/Commands/Add.txt

@@ -19,42 +19,41 @@ control-d or control-c to exit.
 
 Features:
 
--   add tries to provide useful defaults, using the most similar (by
+- add tries to provide useful defaults, using the most similar (by
-    description) recent transaction (filtered by the query, if any) as a
+  description) recent transaction (filtered by the query, if any) as a
-    template.
+  template.
--   You can also set the initial defaults with command line arguments.
+- You can also set the initial defaults with command line arguments.
--   Readline-style edit keys can be used during data entry.
+- Readline-style edit keys can be used during data entry.
--   The tab key will auto-complete whenever possible - accounts,
+- The tab key will auto-complete whenever possible - accounts,
-    payees/descriptions, dates (yesterday, today, tomorrow). If the
+  payees/descriptions, dates (yesterday, today, tomorrow). If the input
-    input area is empty, it will insert the default value.
+  area is empty, it will insert the default value.
--   A parenthesised transaction code may be entered following a date.
+- A parenthesised transaction code may be entered following a date.
--   Comments and tags may be entered following a description or amount.
+- Comments and tags may be entered following a description or amount.
--   If you make a mistake, enter < at any prompt to go one step
+- If you make a mistake, enter < at any prompt to go one step backward.
-    backward.
+- Input prompts are displayed in a different colour when the terminal
--   Input prompts are displayed in a different colour when the terminal
+  supports it.
-    supports it.
 
 Notes:
 
--   If you enter a number with no commodity symbol, and you have
+- If you enter a number with no commodity symbol, and you have declared
-    declared a default commodity with a D directive, you might expect
+  a default commodity with a D directive, you might expect add to add
-    add to add this symbol for you. It does not do this; we assume that
+  this symbol for you. It does not do this; we assume that if you are
-    if you are using a D directive you prefer not to see the commodity
+  using a D directive you prefer not to see the commodity symbol
-    symbol repeated on amounts in the journal.
+  repeated on amounts in the journal.
 
 Examples:
 
--   Record new transactions, saving to the default journal file:
+- Record new transactions, saving to the default journal file:
 
-    hledger add
+  hledger add
 
--   Add transactions to 2024.journal, but also load 2023.journal for
+- Add transactions to 2024.journal, but also load 2023.journal for
-    completions:
+  completions:
 
-    hledger add --file 2024.journal --file 2023.journal
+  hledger add --file 2024.journal --file 2023.journal
 
--   Provide answers for the first four prompts:
+- Provide answers for the first four prompts:
 
-    hledger add today 'best buy' expenses:supplies '$20'
+  hledger add today 'best buy' expenses:supplies '$20'
 
 There is a detailed tutorial at https://hledger.org/add.html.

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -63,12 +63,12 @@ $ hledger areg checking date:jul
 
 Each aregister line item shows:
 
--   the transaction's date (or the relevant posting's date if different,
+- the transaction's date (or the relevant posting's date if different,
-    see below)
+  see below)
--   the names of all the other account(s) involved in this transaction
+- the names of all the other account(s) involved in this transaction
-    (probably abbreviated)
+  (probably abbreviated)
--   the total change to this account's balance from this transaction
+- the total change to this account's balance from this transaction
--   the account's historical running balance after 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.

hledger/Hledger/Cli/Commands/Balance.txt

@@ -74,60 +74,59 @@ listing account balances, balance changes, values, value changes and
 more, during one time period or many. Generally it shows a table, with
 rows representing accounts, and columns representing periods.
 
-Note there are some higher-level variants of the balance command with
+Note there are some variants of the balance command with convenient
-convenient defaults, which can be simpler to use: balancesheet,
+defaults, which are simpler to use: balancesheet, balancesheetequity,
-balancesheetequity, cashflow and incomestatement. When you need more
+cashflow and incomestatement. When you need more control, then use
-control, then use balance.
+balance.
 
 balance features
 
 Here's a quick overview of the balance command's features, followed by
 more detailed descriptions and examples. Many of these work with the
-higher-level commands as well.
+other balance-like commands as well (bs, cf, is..).
 
 balance can show..
 
--   accounts as a list (-l) or a tree (-t)
+- accounts as a list (-l) or a tree (-t)
--   optionally depth-limited (-[1-9])
+- optionally depth-limited (-[1-9])
--   sorted by declaration order and name, or by amount
+- sorted by declaration order and name, or by amount
 
 ..and their..
 
--   balance changes (the default)
+- balance changes (the default)
--   or actual and planned balance changes (--budget)
+- or actual and planned balance changes (--budget)
--   or value of balance changes (-V)
+- or value of balance changes (-V)
--   or change of balance values (--valuechange)
+- or change of balance values (--valuechange)
--   or unrealised capital gain/loss (--gain)
+- or unrealised capital gain/loss (--gain)
--   or balance changes from sibling postings (--related/-r)
+- or balance changes from sibling postings (--related/-r)
--   or postings count (--count)
+- or postings count (--count)
 
 ..in..
 
--   one time period (the whole journal period by default)
+- one time period (the whole journal period by default)
--   or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
+- or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
 
 ..either..
 
--   per period (the default)
+- per period (the default)
--   or accumulated since report start date (--cumulative)
+- or accumulated since report start date (--cumulative)
--   or accumulated since account creation (--historical/-H)
+- or accumulated since account creation (--historical/-H)
 
 ..possibly converted to..
 
--   cost (--value=cost[,COMM]/--cost/-B)
+- cost (--value=cost[,COMM]/--cost/-B)
--   or market value, as of transaction dates (--value=then[,COMM])
+- or market value, as of transaction dates (--value=then[,COMM])
--   or at period ends (--value=end[,COMM])
+- or at period ends (--value=end[,COMM])
--   or now (--value=now)
+- or now (--value=now)
--   or at some other date (--value=YYYY-MM-DD)
+- or at some other date (--value=YYYY-MM-DD)
 
 ..with..
 
--   totals (-T), averages (-A), percentages (-%), inverted sign
+- totals (-T), averages (-A), percentages (-%), inverted sign (--invert)
-    (--invert)
+- rows and columns swapped (--transpose)
--   rows and columns swapped (--transpose)
+- another field used as account name (--pivot)
--   another field used as account name (--pivot)
+- custom-formatted line items (single-period reports only) (--format)
--   custom-formatted line items (single-period reports only) (--format)
+- commodities displayed on the same line or multiple lines (--layout)
--   commodities displayed on the same line or multiple lines (--layout)
 
 This command supports the output destination and output format options,
 with output formats txt, csv, tsv (Added in 1.32), json, and
@@ -204,23 +203,23 @@ interpolated like so:
 
 %[MIN][.MAX](FIELDNAME)
 
--   MIN pads with spaces to at least this width (optional)
+- MIN pads with spaces to at least this width (optional)
 
--   MAX truncates at this width (optional)
+- MAX truncates at this width (optional)
 
--   FIELDNAME must be enclosed in parentheses, and can be one of:
+- FIELDNAME must be enclosed in parentheses, and can be one of:
 
-    -   depth_spacer - a number of spaces equal to the account's depth,
+  - depth_spacer - a number of spaces equal to the account's depth, or
-        or if MIN is specified, MIN * depth spaces.
+    if MIN is specified, MIN * depth spaces.
-    -   account - the account's name
+  - account - the account's name
-    -   total - the account's balance/posted total, right justified
+  - 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, bottom-aligned (the default)
--   %^ - render on multiple lines, top-aligned
+- %^ - render on multiple lines, top-aligned
--   %, - render on one line, comma-separated
+- %, - 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
@@ -228,14 +227,14 @@ be needed to get pleasing results.
 
 Some example formats:
 
--   %(total) - the account's total
+- %(total) - the account's total
--   %-20.20(account) - the account's name, left justified, padded to 20
+- %-20.20(account) - the account's name, left justified, padded to 20
-    characters and clipped at 20 characters
+  characters and clipped at 20 characters
--   %,%-50(account)  %25(total) - account name padded to 50 characters,
+- %,%-50(account)  %25(total) - account name padded to 50 characters,
-    total padded to 20 characters, with multiple commodities rendered on
+  total padded to 20 characters, with multiple commodities rendered on
-    one line
+  one line
--   %20(total)  %2(depth_spacer)%-(account) - the default format for the
+- %20(total)  %2(depth_spacer)%-(account) - the default format for the
-    single-column balance report
+  single-column balance report
 
 Filtered balance report
 
@@ -272,20 +271,19 @@ $ hledger -f examples/sample.journal balance
 
 Notes:
 
--   "Boring" accounts are combined with their subaccount for more
+- "Boring" accounts are combined with their subaccount for more compact
-    compact output, unless --no-elide is used. Boring accounts have no
+  output, unless --no-elide is used. Boring accounts have no balance of
-    balance of their own and just one subaccount (eg assets:bank and
+  their own and just one subaccount (eg assets:bank and liabilities
-    liabilities above).
+  above).
 
--   All balances shown are "inclusive", ie including the balances from
+- All balances shown are "inclusive", ie including the balances from all
-    all subaccounts. Note this means some repetition in the output,
+  subaccounts. Note this means some repetition in the output, which
-    which requires explanation when sharing reports with
+  requires explanation when sharing reports with
-    non-plaintextaccounting-users. A tree mode report's final total is
+  non-plaintextaccounting-users. A tree mode report's final total is the
-    the sum of the top-level balances shown, not of all the balances
+  sum of the top-level balances shown, not of all the balances shown.
-    shown.
 
--   Each group of sibling accounts (ie, under a common parent) is sorted
+- Each group of sibling accounts (ie, under a common parent) is sorted
-    separately.
+  separately.
 
 Depth limiting
 
@@ -342,8 +340,9 @@ commodity, it is treated as 0).
 
 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 higher-level reports, which flip
+to flip the signs. Or you could use one of the higher-level balance
-the sign automatically. Eg: hledger incomestatement -MAS).
+reports (bs, is..), which flip the sign automatically (eg:
+hledger is -MAS).
 
 Percentages
 
@@ -385,41 +384,40 @@ Balance changes in 2008:
 
 Notes:
 
--   The report's start/end dates will be expanded, if necessary, to
+- The report's start/end dates will be expanded, if necessary, to fully
-    fully encompass the displayed subperiods (so that the first and last
+  encompass the displayed subperiods (so that the first and last
-    subperiods have the same duration as the others).
+  subperiods have the same duration as the others).
--   Leading and trailing periods (columns) containing all zeroes are not
+- Leading and trailing periods (columns) containing all zeroes are not
-    shown, unless -E/--empty is used.
+  shown, unless -E/--empty is used.
--   Accounts (rows) containing all zeroes are not shown, unless
+- Accounts (rows) containing all zeroes are not shown, unless -E/--empty
-    -E/--empty is used.
+  is used.
--   Amounts with many commodities are shown in abbreviated form, unless
+- Amounts with many commodities are shown in abbreviated form, unless
-    --no-elide is used.
+  --no-elide is used.
--   Average and/or total columns can be added with the -A/--average and
+- Average and/or total columns can be added with the -A/--average and
-    -T/--row-total flags.
+  -T/--row-total flags.
--   The --transpose flag can be used to exchange rows and columns.
+- The --transpose flag can be used to exchange rows and columns.
--   The --pivot FIELD option causes a different transaction field to be
+- The --pivot FIELD option causes a different transaction field to be
-    used as "account name". See PIVOTING.
+  used as "account name". See PIVOTING.
--   The --summary-only flag (--summary also works) hides all but the
+- The --summary-only flag (--summary also works) hides all but the Total
-    Total and Average columns (those should be enabled with --row-total
+  and Average columns (those should be enabled with --row-total and
-    and -A/--average).
+  -A/--average).
 
 Multi-period reports with many periods can be too wide for easy viewing
 in the terminal. Here are some ways to handle that:
 
--   Hide the totals row with -N/--no-total
+- Hide the totals row with -N/--no-total
--   Filter to a single currency with cur:
+- Filter to a single currency with cur:
--   Convert to a single currency with -V [--infer-market-price]
+- Convert to a single currency with -V [--infer-market-price]
--   Use a more compact layout like --layout=bare
+- Use a more compact layout like --layout=bare
--   Maximize the terminal window
+- Maximize the terminal window
--   Reduce the terminal's font size
+- Reduce the terminal's font size
--   View with a pager like less, eg:
+- View with a pager like less, eg: hledger bal -D --color=yes | less -RS
-    hledger bal -D --color=yes | less -RS
+- Output as CSV and use a CSV viewer like visidata
--   Output as CSV and use a CSV viewer like visidata
+  (hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
-    (hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
+  (M-x csv-mode, C-c C-a), or a spreadsheet
-    (M-x csv-mode, C-c C-a), or a spreadsheet
+  (hledger bal -D -o a.csv && open a.csv)
-    (hledger bal -D -o a.csv && open a.csv)
+- Output as HTML and view with a browser:
--   Output as HTML and view with a browser:
+  hledger bal -D -o a.html && open a.html
-    hledger bal -D -o a.html && open a.html
 
 Balance change, end balance
 
@@ -454,7 +452,7 @@ balances:
     flag. (-H causes report start date to be ignored when summing
     postings.)
 
-Balance report types
+Balance report modes
 
 The balance command is quite flexible; here is the full detail on how to
 control what it reports. If the following seems complicated, don't
@@ -463,78 +461,83 @@ experimentation to get familiar with all the report modes.
 
 There are three important option groups:
 
-hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
+hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ...
 
-Calculation type
+Calculation mode
 
 The basic calculation to perform for each table cell. It is one of:
 
--   --sum : sum the posting amounts (default)
+- --sum : sum the posting amounts (default)
--   --budget : sum the amounts, but also show the budget goal amount
+- --budget : sum the amounts, but also show the budget goal amount (for
-    (for each account/period)
+  each account/period)
--   --valuechange : show the change in period-end historical balance
+- --valuechange : show the change in period-end historical balance
-    values (caused by deposits, withdrawals, and/or market price
+  values (caused by deposits, withdrawals, and/or market price
-    fluctuations)
+  fluctuations)
--   --gain : show the unrealised capital gain/loss, (the current valued
+- --gain : show the unrealised capital gain/loss, (the current valued
-    balance minus each amount's original cost)
+  balance minus each amount's original cost)
--   --count : show the count of postings
+- --count : show the count of postings
 
-Accumulation type
+Accumulation mode
 
 How amounts should accumulate across a report's subperiods/columns.
 Another way to say it: which time period's postings should contribute to
 each cell's calculation. It is one of:
 
--   --change : calculate with postings from column start to column end,
+- --change : calculate with postings from column start to column end, ie
-    ie "just this column". Typically used to see revenues/expenses.
+  "just this column". Typically used to see revenues/expenses. (default
-    (default for balance, cashflow, incomestatement)
+  for balance, cashflow, incomestatement)
 
--   --cumulative : calculate with postings from report start to column
+- --cumulative : calculate with postings from report start to column
-    end, ie "previous columns plus this column". Typically used to show
+  end, ie "previous columns plus this column". Typically used to show
-    changes accumulated since the report's start date. Not often used.
+  changes accumulated since the report's start date. Not often used.
 
--   --historical/-H : calculate with postings from journal start to
+- --historical/-H : calculate with postings from journal start to column
-    column end, ie "all postings from before report start date until
+  end, ie "all postings from before report start date until this
-    this column's end". Typically used to see historical end balances of
+  column's end". Typically used to see historical end balances of
-    assets/liabilities/equity. (default for balancesheet,
+  assets/liabilities/equity. (default for balancesheet,
-    balancesheetequity)
+  balancesheetequity)
 
-Valuation type
+Valuation mode
 
 Which kind of value or cost conversion should be applied, if any, before
-displaying the report. It is one of:
+displaying the report. See Cost reporting and Value reporting for more
+about conversions.
 
--   no valuation type : don't convert to cost or value (default)
+A valuation (or cost) mode can be selected with the --value option:
--   --value=cost[,COMM] : convert amounts to cost (then optionally to
-    some other commodity)
--   --value=then[,COMM] : convert amounts to market value on transaction
-    dates
--   --value=end[,COMM] : convert amounts to market value on period end
-    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 the equivalent simpler flags:
+- no conversion : don't convert to cost or value (default)
+- --value=cost[,COMM] : convert amounts to cost (then optionally to some
+  other commodity)
+- --value=then[,COMM] : convert amounts to market value on transaction
+  dates
+- --value=end[,COMM] : convert amounts to market value on period end
+  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
 
--   -B/--cost : like --value=cost (though, note --cost and --value are
+or with the legacy -B/-V/-X options, which are equivalent and easier to
-    independent options which can both be used at once)
+type:
--   -V/--market : like --value=end
--   -X COMM/--exchange COMM : like --value=end,COMM
 
-See Cost reporting and Value reporting for more about these.
+- -B/--cost : like --value=cost
+- -V/--market : like --value=end
+- -X COMM/--exchange COMM : like --value=end,COMM
 
-Combining balance report types
+Note that --value can also convert to cost, as a convenience; but
+actually --cost and --value are independent options, and could be used
+together.
 
-Most combinations of these options should produce reasonable reports,
+Combining balance report modes
-but if you find any that seem wrong or misleading, let us know. The
+
+Most combinations of these modes should produce reasonable reports, but
+if you find any that seem wrong or misleading, let us know. The
 following restrictions are applied:
 
--   --valuechange implies --value=end
+- --valuechange implies --value=end
--   --valuechange makes --change the default when used with the
+- --valuechange makes --change the default when used with the
-    balancesheet/balancesheetequity commands
+  balancesheet/balancesheetequity commands
--   --cumulative or --historical disables --row-total/-T
+- --cumulative or --historical disables --row-total/-T
 
 For reference, here is what the combinations of accumulation and
 valuation show:
@@ -564,11 +567,11 @@ valuation show:
 
 Budget report
 
-The --budget report type is like a regular balance report, but with two
+The --budget report is like a regular balance report, but with two main
-main differences:
+differences:
 
--   Budget goals and performance percentages are also shown, in brackets
+- Budget goals and performance percentages are also shown, in brackets
--   Accounts which don't have budget goals are hidden by default.
+- Accounts which don't have budget goals are hidden by default.
 
 This is useful for comparing planned and actual income, expenses, time
 usage, etc.
@@ -628,47 +631,46 @@ version should be relatively robust and intuitive, but you may still
 find surprises. Here are more notes to help with learning and
 troubleshooting.
 
--   In the above example, expenses:bus and expenses:food are shown
+- In the above example, expenses:bus and expenses:food are shown because
-    because they have budget goals during the report period.
+  they have budget goals during the report period.
 
--   Their parent expenses is also shown, with budget goals aggregated
+- Their parent expenses is also shown, with budget goals aggregated from
-    from the children.
+  the children.
 
--   The subaccounts expenses:food:groceries and expenses:food:dining are
+- The subaccounts expenses:food:groceries and expenses:food:dining are
-    not shown since they have no budget goal of their own, but they
+  not shown since they have no budget goal of their own, but they
-    contribute to expenses:food's actual amount.
+  contribute to expenses:food's actual amount.
 
--   Unbudgeted accounts expenses:movies and expenses:gifts are also not
+- Unbudgeted accounts expenses:movies and expenses:gifts are also not
-    shown, but they contribute to expenses's actual amount.
+  shown, but they contribute to expenses's actual amount.
 
--   The other unbudgeted accounts income and assets:bank:checking are
+- The other unbudgeted accounts income and assets:bank:checking are
-    grouped as <unbudgeted>.
+  grouped as <unbudgeted>.
 
--   --depth or depth: can be used to limit report depth in the usual way
+- --depth or depth: can be used to limit report depth in the usual way
-    (but will not reveal unbudgeted subaccounts).
+  (but will not reveal unbudgeted subaccounts).
 
--   Amounts are always inclusive of subaccounts (even in -l/--list
+- Amounts are always inclusive of subaccounts (even in -l/--list mode).
-    mode).
 
--   Numbers displayed in a --budget report will not always agree with
+- Numbers displayed in a --budget report will not always agree with the
-    the totals, because of hidden unbudgeted accounts; this is normal.
+  totals, because of hidden unbudgeted accounts; this is normal.
-    -E/--empty can be used to reveal the hidden accounts.
+  -E/--empty can be used to reveal the hidden accounts.
 
--   In the periodic rules used for setting budget goals, unbalanced
+- In the periodic rules used for setting budget goals, unbalanced
-    postings are convenient.
+  postings are convenient.
 
--   You can filter budget reports with the usual queries, eg to focus on
+- You can filter budget reports with the usual queries, eg to focus on
-    particular accounts. It's common to restrict them to just expenses.
+  particular accounts. It's common to restrict them to just expenses.
-    (The <unbudgeted> account is occasionally hard to exclude; this is
+  (The <unbudgeted> account is occasionally hard to exclude; this is
-    because of date surprises, discussed below.)
+  because of date surprises, discussed below.)
 
--   When you have multiple currencies, you may want to convert them to
+- When you have multiple currencies, you may want to convert them to one
-    one (-X COMM --infer-market-prices) and/or show just one at a time
+  (-X COMM --infer-market-prices) and/or show just one at a time
-    (cur:COMM). If you do need to show multiple currencies at once,
+  (cur:COMM). If you do need to show multiple currencies at once,
-    --layout bare can be helpful.
+  --layout bare can be helpful.
 
--   You can "roll over" amounts (actual and budgeted) to the next period
+- You can "roll over" amounts (actual and budgeted) to the next period
-    with --cumulative.
+  with --cumulative.
 
 See also: https://hledger.org/budgeting.html.
 
@@ -762,14 +764,14 @@ commands show multi-commodity amounts and commodity symbols. It can
 improve readability, for humans and/or machines (other software). It has
 four possible values:
 
--   --layout=wide[,WIDTH]: commodities are shown on a single line,
+- --layout=wide[,WIDTH]: commodities are shown on a single line,
-    optionally elided to WIDTH
+  optionally elided to WIDTH
--   --layout=tall: each commodity is shown on a separate line
+- --layout=tall: each commodity is shown on a separate line
--   --layout=bare: commodity symbols are in their own column, amounts
+- --layout=bare: commodity symbols are in their own column, amounts are
-    are bare numbers
+  bare numbers
--   --layout=tidy: data is normalised to easily-consumed "tidy" form,
+- --layout=tidy: data is normalised to easily-consumed "tidy" form, with
-    with one row per data value. (This one is currently supported only
+  one row per data value. (This one is currently supported only by the
-    by the balance command.)
+  balance command.)
 
 Here are the --layout modes supported by each output format Only CSV
 output supports all of them:
@@ -901,9 +903,8 @@ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layo
 Balance report output
 
 As noted in Output format, if you choose HTML output (by using -O html
-or -o somefile.html), it will use the UTF-8 text encoding, And you can
+or -o somefile.html), you can create a hledger.css file in the same
-create a hledger.css file in the same directory to customise the
+directory to customise the report's appearance.
-report's appearance.
 
 The HTML and FODS output formats can generate hyperlinks to a
 hledger-web register view for each account and period. E.g. if your
@@ -916,33 +917,33 @@ Some useful balance reports
 
 Some frequently used balance options/reports are:
 
--   bal -M revenues expenses
+- bal -M revenues expenses
-    Show revenues/expenses in each month. Also available as the
+  Show revenues/expenses in each month. Also available as the
-    incomestatement command.
+  incomestatement command.
 
--   bal -M -H assets liabilities
+- bal -M -H assets liabilities
-    Show historical asset/liability balances at each month end. Also
+  Show historical asset/liability balances at each month end. Also
-    available as the balancesheet command.
+  available as the balancesheet command.
 
--   bal -M -H assets liabilities equity
+- bal -M -H assets liabilities equity
-    Show historical asset/liability/equity balances at each month end.
+  Show historical asset/liability/equity balances at each month end.
-    Also available as the balancesheetequity command.
+  Also available as the balancesheetequity command.
 
--   bal -M assets not:receivable
+- bal -M assets not:receivable
-    Show changes to liquid assets in each month. Also available as the
+  Show changes to liquid assets in each month. Also available as the
-    cashflow command.
+  cashflow command.
 
 Also:
 
--   bal -M expenses -2 -SA
+- bal -M expenses -2 -SA
-    Show monthly expenses summarised to depth 2 and sorted by average
+  Show monthly expenses summarised to depth 2 and sorted by average
-    amount.
+  amount.
 
--   bal -M --budget expenses
+- bal -M --budget expenses
-    Show monthly expenses and budget goals.
+  Show monthly expenses and budget goals.
 
--   bal -M --valuechange investments
+- bal -M --valuechange investments
-    Show monthly change in market value of investment assets.
+  Show monthly change in market value of investment assets.
 
--   bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
+- bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
-    Show top gainers [or losers] last week
+  Show top gainers [or losers] last week

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -59,10 +59,9 @@ Flags:
 This report shows accounts declared with the Cash type (see account
 types). Or if no such accounts are declared, it shows accounts
 
--   under a top-level account named asset (case insensitive, plural
+- under a top-level account named asset (case insensitive, plural
-    allowed)
+  allowed)
--   whose name contains some variation of cash, bank, checking or
+- whose name contains some variation of cash, bank, checking or saving.
-    saving.
 
 More precisely: all accounts matching this case insensitive regular
 expression:

hledger/Hledger/Cli/Commands/Check.txt

@@ -27,80 +27,80 @@ Basic checks
 These important checks are performed by default, by almost all hledger
 commands:
 
--   parseable - data files are in a supported format, with no syntax
+- parseable - data files are in a supported format, with no syntax
-    errors and no invalid include directives. This ensures that all
+  errors and no invalid include directives. This ensures that all files
-    files exist and are readable.
+  exist and are readable.
 
--   autobalanced - all transactions are balanced, after inferring
+- autobalanced - all transactions are balanced, after automatically
-    missing amounts and conversion costs where possible, and then
+  inferring missing amounts and conversion rates and then converting
-    converting to cost. This ensures that each individual transaction is
+  amounts to cost. This ensures that each transaction's entry is well
-    well formed.
+  formed.
 
--   assertions - all balance assertions in the journal are passing.
+- assertions - all balance assertions in the journal are passing.
-    Balance assertions are like canaries in your journal, they catch
+  Balance assertions are a strong defense against errors; they help
-    many problems. They can get in the way sometimes; you can disable
+  catch many problems. If this check gets in your way, you can disable
-    them temporarily with -I/--ignore-assertions (unless overridden with
+  it with -I/--ignore-assertions. Or you can add that to your config
-    -s/--strict or hledger check assertions).
+  file to disable it by default (and then use -s/--strict or
+  hledger check assertions to enable it).
 
 Strict checks
 
-These additional checks are performed by any command when the
+These additional checks are performed by all commands when the
--s/--strict flag is used (strict mode). Strict mode always enables the
+-s/--strict flag is used (strict mode). They provide extra
-balance assertions check, also. These provide extra error-catching power
+error-catching power to keep your data clean and correct. Strict mode
-when you are serious about keeping your data clean and free of typos:
+also always enables the assertions check.
 
--   balanced - like autobalanced, but in conversion transactions, costs
+- balanced - like autobalanced, but all conversions between commodities
-    must be written explicitly. This ensures some redundancy in the
+  must use explicit cost notation or equity postings. This prevents
-    entry, which helps prevent typos.
+  wrong conversions caused by typos.
 
--   commodities - all commodity symbols used must be declared. This
+- commodities - all commodity symbols used must be declared. This guards
-    guards against mistyping or omitting commodity symbols.
+  against mistyping or omitting commodity symbols. Declaring commodities
+  also sets their precision for display and transaction balancing.
 
--   accounts - all account names used must be declared. This prevents
+- accounts - all account names used must be declared. This prevents the
-    the use of mis-spelled or outdated account names.
+  use of mis-spelled or outdated account names.
 
 Other checks
 
-These other checks are not wanted by everyone, but can be run using the
+These are not wanted by everyone, but can be run using the check
-check command:
+command:
 
--   ordereddates - within each file, transactions are ordered by date.
+- tags - all tags used must be declared. This prevents mis-spelled tag
-    This is a simple and effective error catcher, and you should use it.
+  names. Note hledger fairly often finds unintended tags in comments.
-    Alas! not everyone wants it. If you do, use
-    hledger check -s ordereddates. When enabled, this check is performed
-    early, before balance assertions (because copy-pasted dates are
-    often the root cause of balance assertion failures).
 
--   payees - all payees used by transactions must be declared. This will
+- payees - all payees used in transactions must be declared. This will
-    force you to always use known/declared payee names. For most people
+  force you to declare any new payee name before using it. Most people
-    this is a bit too restrictive.
+  will probably find this a bit too strict.
 
--   tags - all tags used by transactions must be declared. This prevents
+- ordereddates - within each file, transactions must be ordered by date.
-    mistyped tag names.
+  This is a simple and effective error catcher. It's not included in
+  strict mode, but you can add it by running
+  hledger check -s ordereddates. If enabled, this check is performed
+  before balance assertions.
 
--   recentassertions - all accounts with balance assertions must have a
+- recentassertions - all accounts with balance assertions must have one
-    balance assertion within the last 7 days before their latest
+  that's within the 7 days before their latest posting. This will
-    posting. This encourages you to add balance assertions fairly
+  encourage adding balance assertions for your active asset/liability
-    regularly for your active asset/liability accounts, which in turn
+  accounts, which in turn should encourage you to reconcile regularly
-    should encourage you to check and reconcile with their real world
+  with those real world balances - another strong defense against
-    balances fairly regularly. close --assert can be helpful. (The older
+  errors. hledger close --assert can help generate assertion entries.
-    balance assertions become redundant; you can remove them
+  Over time the older assertions become somewhat redundant, and you can
-    periodically, or leave them in place, perhaps commented, as
+  remove them if you like (they don't affect performance much, but they
-    documentation.)
+  add some noise to the journal).
 
--   uniqueleafnames - no two accounts may have the same leaf name. The
+- uniqueleafnames - no two accounts may have the same last account name
-    leaf name is the last colon-separated part of an account name, eg
+  part (eg the checking in assets:bank:checking). This ensures each
-    checking in assets:bank:checking. This encourages you to keep those
+  account can be matched by a unique short name, easier to remember and
-    unique, effectively giving each account a short name which is easier
+  to type.
-    to remember and to type in reporting commands.
 
 Custom checks
 
 You can build your own custom checks with add-on command scripts. See
 also Cookbook > Scripting. Here are some examples from hledger/bin/:
 
--   hledger-check-tagfiles - all tag values containing / (a forward
+- hledger-check-tagfiles - all tag values containing / (a forward slash)
-    slash) exist as file paths
+  exist as file paths
 
--   hledger-check-fancyassertions - more complex balance assertions are
+- hledger-check-fancyassertions - more complex balance assertions are
-    passing
+  passing

hledger/Hledger/Cli/Commands/Close.txt

@@ -136,13 +136,12 @@ close customisation
 
 In all modes, the following things can be overridden:
 
--   the accounts to be closed/opened, with account query arguments
+- the accounts to be closed/opened, with account query arguments
--   the balancing account, with --close-acct=ACCT and/or
+- the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
-    --open-acct=ACCT
+- the transaction descriptions, with --close-desc=DESC and
--   the transaction descriptions, with --close-desc=DESC and
+  --open-desc=DESC
-    --open-desc=DESC
+- the transaction's tag value, with a --MODE=NEW option argument
--   the transaction's tag value, with a --MODE=NEW option argument
+- the closing/opening dates, with -e OPENDATE
--   the closing/opening dates, with -e OPENDATE
 
 By default, the closing date is yesterday, or the journal's end date,
 whichever is later; and the opening date is always one day after the

hledger/Hledger/Cli/Commands/Import.txt

@@ -77,35 +77,34 @@ Overlap detection is automatic, and shouldn't require much attention
 from you, except perhaps at first import (see below). But here's how it
 works:
 
--   For each FILE being imported from:
+- For each FILE being imported from:
 
-    1.  hledger reads a file named .latest.FILE file in the same
+  1.  hledger reads a file named .latest.FILE file in the same
-        directory, if any. This file contains the latest record date
+      directory, if any. This file contains the latest record date
-        previously imported from FILE, in YYYY-MM-DD format. If multiple
+      previously imported from FILE, in YYYY-MM-DD format. If multiple
-        records with that date were imported, the date is repeated on N
+      records with that date were imported, the date is repeated on N
-        lines.
+      lines.
 
-    2.  hledger reads records from FILE. If a latest date was found in
+  2.  hledger reads records from FILE. If a latest date was found in
-        step 1, any records before that date, and the first N records on
+      step 1, any records before that date, and the first N records on
-        that date, are skipped.
+      that date, are skipped.
 
--   After a successful import from all FILEs, without error and without
+- After a successful import from all FILEs, without error and without
-    --dry-run, hledger updates each FILE's .latest.FILE for next time.
+  --dry-run, hledger updates each FILE's .latest.FILE for next time.
 
 If this goes wrong, it's relatively easy to repair:
 
--   You'll notice it before import when you preview with
+- You'll notice it before import when you preview with import --dry-run.
-    import --dry-run.
+- Or after import when you try to reconcile your hledger account
--   Or after import when you try to reconcile your hledger account
+  balances with your bank.
-    balances with your bank.
+- hledger print -f FILE.csv will show all recently downloaded
--   hledger print -f FILE.csv will show all recently downloaded
+  transactions. Compare these with your journal. Copy/paste if needed.
-    transactions. Compare these with your journal. Copy/paste if needed.
+- Update your conversion rules and print again, if needed.
--   Update your conversion rules and print again, if needed.
+- You can manually update or remove the .latest file, or use
--   You can manually update or remove the .latest file, or use
+  import --catchup FILE.
-    import --catchup FILE.
+- Download and import more often, eg twice a week, at least while you
--   Download and import more often, eg twice a week, at least while you
+  are learning. It's easier to review and troubleshoot when there are
-    are learning. It's easier to review and troubleshoot when there are
+  fewer transactions.
-    fewer transactions.
 
 First import
 
@@ -188,7 +187,7 @@ Here are two kinds of "deduplication" which import does not handle (and
 generally should not, since these can happen legitimately in financial
 data):
 
--   Two or more of the new CSV records are identical, and generate
+- Two or more of the new CSV records are identical, and generate
-    identical new journal entries.
+  identical new journal entries.
--   A new CSV record generates a journal entry identical to one(s)
+- A new CSV record generates a journal entry identical to one(s) already
-    already in the journal.
+  in the journal.

hledger/Hledger/Cli/Commands/Print.md

@@ -25,11 +25,11 @@ Flags:
      --base-url=URLPREFIX   in html output, generate links to hledger-web,
                             with this prefix. (Usually the base url shown by
                             hledger-web; can also be relative.)
+     --location             add file/line number tags to print output
   -O --output-format=FMT    select the output format. Supported formats:
                             txt, beancount, csv, tsv, html, fods, json, sql.
   -o --output-file=FILE     write output to FILE. A file extension matching
                             one of the above formats selects that format.
-     --location             add file/line number tags to print output.
 ```
 
 The print command displays full journal entries (transactions) 

hledger/Hledger/Cli/Commands/Print.txt

@@ -24,6 +24,7 @@ Flags:
      --base-url=URLPREFIX   in html output, generate links to hledger-web,
                             with this prefix. (Usually the base url shown by
                             hledger-web; can also be relative.)
+     --location             add file/line number tags to print output
   -O --output-format=FMT    select the output format. Supported formats:
                             txt, beancount, csv, tsv, html, fods, json, sql.
   -o --output-file=FILE     write output to FILE. A file extension matching
@@ -84,11 +85,11 @@ With the --round (Added in 1.32) option, print will try increasingly
 hard to display decimal digits according to the commodity display
 styles:
 
--   --round=none show amounts with original precisions (default)
+- --round=none show amounts with original precisions (default)
--   --round=soft add/remove decimal zeros in amounts (except costs)
+- --round=soft add/remove decimal zeros in amounts (except costs)
--   --round=hard round amounts (except costs), possibly hiding
+- --round=hard round amounts (except costs), possibly hiding significant
-    significant digits
+  digits
--   --round=all round all amounts and costs
+- --round=all round all amounts and costs
 
 soft is good for non-lossy cleanup, formatting amounts more consistently
 where it's safe to do so.
@@ -110,10 +111,10 @@ $ hledger print assets:cash | hledger -f- -I reg expenses:food
 
 There are some situations where print's output can become unparseable:
 
--   Value reporting affects posting amounts but not balance assertion or
+- Value reporting affects posting amounts but not balance assertion or
-    balance assignment amounts, potentially causing those to fail.
+  balance assignment amounts, potentially causing those to fail.
--   Auto postings can generate postings with too many missing amounts.
+- Auto postings can generate postings with too many missing amounts.
--   Account aliases can generate bad account names.
+- Account aliases can generate bad account names.
 
 print, other features
 
@@ -132,6 +133,9 @@ description is most similar to DESC. DESC should contain at least two
 characters. If there is no similar-enough match, no transaction will be
 shown and the program exit code will be non-zero.
 
+With --location, print adds the source file and line number to every
+transaction, as a tag.
+
 print output format
 
 This command also supports the output destination and output format
@@ -141,28 +145,28 @@ csv, tsv (Added in 1.32), json and sql.
 The beancount format tries to produce Beancount-compatible output, as
 follows:
 
--   Transaction and postings with unmarked status are converted to
+- Transaction and postings with unmarked status are converted to cleared
-    cleared (*) status.
+  (*) status.
--   Transactions' payee and note are backslash-escaped and
+- Transactions' payee and note are backslash-escaped and
-    double-quote-escaped and wrapped in double quotes.
+  double-quote-escaped and wrapped in double quotes.
--   Transaction tags are copied to Beancount #tag format.
+- Transaction tags are copied to Beancount #tag format.
--   Commodity symbols are converted to upper case, and a small number of
+- Commodity symbols are converted to upper case, and a small number of
-    currency symbols like $ are converted to the corresponding currency
+  currency symbols like $ are converted to the corresponding currency
-    names.
+  names.
--   Account name parts are capitalised and unsupported characters are
+- Account name parts are capitalised and unsupported characters are
-    replaced with -. If an account name part does not begin with a
+  replaced with -. If an account name part does not begin with a letter,
-    letter, or if the first part is not Assets, Liabilities, Equity,
+  or if the first part is not Assets, Liabilities, Equity, Income, or
-    Income, or Expenses, an error is raised. (Use --alias options to
+  Expenses, an error is raised. (Use --alias options to bring your
-    bring your accounts into compliance.)
+  accounts into compliance.)
--   An open directive is generated for each account used, on the
+- An open directive is generated for each account used, on the earliest
-    earliest transaction date.
+  transaction date.
 
 Some limitations:
 
--   Balance assertions are removed.
+- Balance assertions are removed.
--   Balance assignments become missing amounts.
+- Balance assignments become missing amounts.
--   Virtual and balanced virtual postings become regular postings.
+- Virtual and balanced virtual postings become regular postings.
--   Directives are not converted.
+- Directives are not converted.
 
 Here's an example of print's CSV output:
 
@@ -180,15 +184,15 @@ $ hledger print -Ocsv
 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
 
--   There is one CSV record per posting, with the parent transaction's
+- There is one CSV record per posting, with the parent transaction's
-    fields repeated.
+  fields repeated.
--   The "txnidx" (transaction index) field shows which postings belong
+- The "txnidx" (transaction index) field shows which postings belong to
-    to the same transaction. (This number might change if transactions
+  the same transaction. (This number might change if transactions are
-    are reordered within the file, files are parsed/included in a
+  reordered within the file, files are parsed/included in a different
-    different order, etc.)
+  order, etc.)
--   The amount is separated into "commodity" (the symbol) and "amount"
+- The amount is separated into "commodity" (the symbol) and "amount"
-    (numeric quantity) fields.
+  (numeric quantity) fields.
--   The numeric amount is repeated in either the "credit" or "debit"
+- The numeric amount is repeated in either the "credit" or "debit"
-    column, for convenience. (Those names are not accurate in the
+  column, for convenience. (Those names are not accurate in the
-    accounting sense; it just puts negative amounts under credit and
+  accounting sense; it just puts negative amounts under credit and zero
-    zero or greater amounts under debit.)
+  or greater amounts under debit.)

hledger/Hledger/Cli/Commands/Repl.txt

@@ -22,19 +22,19 @@ until you exit and restart the REPL.
 
 The command syntax is the same as with run:
 
--   enter one hledger command at a time, without the usual hledger first
+- enter one hledger command at a time, without the usual hledger first
-    word
+  word
--   empty lines and comment text from # to end of line are ignored
+- empty lines and comment text from # to end of line are ignored
--   use single or double quotes to quote arguments when needed
+- use single or double quotes to quote arguments when needed
--   type exit or quit or control-D to exit the REPL.
+- type exit or quit or control-D to exit the REPL.
 
 While it is running, the REPL remembers your command history, and you
 can navigate in the usual ways:
 
--   Keypad or Emacs navigation keys to edit the current command line
+- Keypad or Emacs navigation keys to edit the current command line
--   UP/DOWN or control-P/control-N to step back/forward through history
+- UP/DOWN or control-P/control-N to step back/forward through history
--   control-R to search for a past command
+- control-R to search for a past command
--   TAB to complete file paths.
+- TAB to complete file paths.
 
 Generally repl command lines should feel much like the normal hledger
 CLI, but you may find differences. repl is a little stricter; eg it

hledger/Hledger/Cli/Commands/Rewrite.txt

@@ -126,12 +126,12 @@ rewrite vs. print --auto
 This command predates print --auto, and currently does much the same
 thing, but with these differences:
 
--   with multiple files, rewrite lets rules in any file affect all other
+- with multiple files, rewrite lets rules in any file affect all other
-    files. print --auto uses standard directive scoping; rules affect
+  files. print --auto uses standard directive scoping; rules affect only
-    only child files.
+  child files.
 
--   rewrite's query limits which transactions can be rewritten; all are
+- rewrite's query limits which transactions can be rewritten; all are
-    printed. print --auto's query limits which transactions are printed.
+  printed. print --auto's query limits which transactions are printed.
 
--   rewrite applies rules specified on command line or in the journal.
+- rewrite applies rules specified on command line or in the journal.
-    print --auto applies rules specified in the journal.
+  print --auto applies rules specified in the journal.

hledger/Hledger/Cli/Commands/Roi.txt

@@ -31,19 +31,19 @@ Price directives will be taken into account if you supply appropriate
 
 Note, in some cases this report can fail, for these reasons:
 
--   Error (NotBracketed): No solution for Internal Rate of Return (IRR).
+- Error (NotBracketed): No solution for Internal Rate of Return (IRR).
-    Possible causes: IRR is huge (>1000000%), balance of investment
+  Possible causes: IRR is huge (>1000000%), balance of investment
-    becomes negative at some point in time.
+  becomes negative at some point in time.
--   Error (SearchFailed): Failed to find solution for Internal Rate of
+- Error (SearchFailed): Failed to find solution for Internal Rate of
-    Return (IRR). Either search does not converge to a solution, or
+  Return (IRR). Either search does not converge to a solution, or
-    converges too slowly.
+  converges too slowly.
 
 Examples:
 
--   Using roi to compute total return of investment in stocks:
+- Using roi to compute total return of investment in stocks:
-    https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger
+  https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger
 
--   Cookbook > Return on Investment: https://hledger.org/roi.html
+- Cookbook > Return on Investment: https://hledger.org/roi.html
 
 Spaces and special characters in --inv and --pnl
 
@@ -71,23 +71,23 @@ sorted into two categories: "cash flow" and "profit and loss", as ROI
 needs to know which part of the investment value is your contributions
 and which is due to the return on investment.
 
--   "Cash flow" is depositing or withdrawing money, buying or selling
+- "Cash flow" is depositing or withdrawing money, buying or selling
-    assets, or otherwise converting between your investment commodity
+  assets, or otherwise converting between your investment commodity and
-    and any other commodity. Example:
+  any other commodity. Example:
 
-    2019-01-01 Investing in Snake Oil
+  2019-01-01 Investing in Snake Oil
-      assets:cash          -$100
+    assets:cash          -$100
-      investment:snake oil
+    investment:snake oil
 
-    2020-01-01 Selling my Snake Oil
+  2020-01-01 Selling my Snake Oil
-      assets:cash           $10
+    assets:cash           $10
-      investment:snake oil  = 0
+    investment:snake oil  = 0
 
--   "Profit and loss" is change in the value of your investment:
+- "Profit and loss" is change in the value of your investment:
 
-    2019-06-01 Snake Oil falls in value
+  2019-06-01 Snake Oil falls in value
-      investment:snake oil  = $57
+    investment:snake oil  = $57
-      equity:unrealized profit or loss
+    equity:unrealized profit or loss
 
 All non-investment postings are assumed to be "cash flow", unless they
 match --pnl query. Changes in value of your investment due to "profit
@@ -167,9 +167,9 @@ cash in-flows and out-flows.
 
 References:
 
--   Explanation of rate of return
+- Explanation of rate of return
--   Explanation of IRR
+- Explanation of IRR
--   Explanation of TWR
+- Explanation of TWR
--   IRR vs TWR
+- IRR vs TWR
--   Examples of computing IRR and TWR and discussion of the limitations
+- Examples of computing IRR and TWR and discussion of the limitations of
-    of both metrics
+  both metrics

hledger/Hledger/Cli/Commands/Run.txt

@@ -10,11 +10,11 @@ This command is experimental and could change in the future.
 
 You can use run in three ways:
 
--   hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
+- hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
-    line, separated by --
+  line, separated by --
--   hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
+- hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
-    files
+  files
--   cat SCRIPTFILE1 | hledger run - read commands from standard input.
+- cat SCRIPTFILE1 | hledger run - read commands from standard input.
 
 run first loads the input file(s) specified by LEDGER_FILE or by -f
 options, in the usual way. Then it runs each command in turn, each using
@@ -31,14 +31,14 @@ twice as fast).
 Command scripts, whether in a file or written on the command line, have
 a simple syntax:
 
--   each line may contain a single hledger command and its arguments,
+- each line may contain a single hledger command and its arguments,
-    without the usual hledger first word
+  without the usual hledger first word
--   empty lines are ignored
+- empty lines are ignored
--   text from # to end of line is a comment, and ignored
+- text from # to end of line is a comment, and ignored
--   you can use single or double quotes to quote arguments when needed,
+- you can use single or double quotes to quote arguments when needed, as
-    as on the command line
+  on the command line
--   these extra commands are available: echo TEXT prints some text, and
+- these extra commands are available: echo TEXT prints some text, and
-    exit or quit ends the run.
+  exit or quit ends the run.
 
 On unix systems you can use #!/usr/bin/env hledger run in the first line
 of a command file to make it a runnable script. If that gives an error,

hledger/Hledger/Cli/Commands/Setup.txt

@@ -1,6 +1,61 @@
 setup
 
-Check and help set up various installation things.
+Check the status of the hledger installation.
 
 Flags:
 no command-specific flags
+
+setup tests your hledger installation and prints a list of results,
+sometimes with helpful hints. This is a good first command to run after
+installing hledger. Also after upgrading, or when something's not
+working, or just when you want a reminder of where things are.
+
+It makes one network request to detect the latest hledger release
+version. It's ok if this fails or times out. It will use ANSI color by
+default, unless disabled by NO_COLOR or --color=n. It does not use a
+pager or a config file.
+
+It expects that the hledger version you are running is installed in your
+PATH. If not, it will stop until you have done that (to keep things
+simple).
+
+Example:
+
+$ hledger setup
+Checking your hledger setup..
+Legend: good, neutral, unknown, warning
+
+hledger
+* is a released version ?                   no  hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64
+* is up to date ?                          yes  1.42.99 installed, latest is 1.42.1
+* is a native binary for this machine ?    yes  aarch64
+* is installed in PATH ?                   yes  /Users/simon/.local/bin/hledger
+* has a system text encoding configured ?  yes  UTF-8, data files should use this encoding
+* has a user config file ? (optional)       no  
+* current directory has a local config ?   yes  /Users/simon/src/hledger/hledger.conf
+* the config file is readable ?            yes  /Users/simon/src/hledger/hledger.conf
+
+terminal
+* the NO_COLOR variable is defined ?        no  
+* --color is configured by config file ?    no  
+* hledger will use color by default ?      yes  
+* the PAGER variable is defined ?          yes  less
+* --pager is configured by config file ?    no  
+* hledger will use a pager when needed ?   yes  /opt/homebrew/bin/less
+* the LESS variable is defined ?           yes  
+* the HLEDGER_LESS variable is defined ?    no  
+* adjusting LESS variable for color etc. ? yes  
+* --pretty is enabled by config file ?      no  tables will use ASCII characters
+* bash shell completions are installed ?     ?  
+* zsh shell completions are installed ?      ?  
+
+journal
+* the LEDGER_FILE variable is defined ?    yes  /Users/simon/finance/2025/2025.journal
+* a default journal file is readable ?     yes  /Users/simon/finance/2025/2025.journal
+* it includes additional files ?           yes  15
+* all commodities are declared ?           yes  10
+* all accounts are declared ?              yes  160
+* all accounts have types ?                 no  14 untyped
+* accounts of each type were detected ?    yes  ALERXCV
+* commodities/accounts are checked ?        no  use -s to check commodities/accounts
+* balance assertions are checked ?         yes  use -I to ignore assertions

hledger/Hledger/Cli/Commands/Stats.txt

@@ -16,13 +16,12 @@ included files, and commodity names.
 
 It also shows some run time statistics:
 
--   elapsed time
+- elapsed time
--   throughput: the number of transactions processed per second
+- throughput: the number of transactions processed per second
--   live: the peak memory in use by the program to do its work
+- live: the peak memory in use by the program to do its work
--   alloc: the peak memory allocation from the OS as seen by GHC.
+- alloc: the peak memory allocation from the OS as seen by GHC.
-    Measuring this externally, eg with GNU time, is more accurate;
+  Measuring this externally, eg with GNU time, is more accurate; usually
-    usually that will be a larger number; sometimes (with swapping?)
+  that will be a larger number; sometimes (with swapping?) smaller.
-    smaller.
 
 The stats command's run time is similar to that of a balance report.
 

hledger/Hledger/Cli/Commands/Test.txt

@@ -14,11 +14,12 @@ sanity-check the installed hledger executable on your platform. All
 tests are expected to pass - if you ever see a failure, please report as
 a bug!
 
-This command also accepts tasty test runner options, written after a --
+Any arguments before a -- argument will be passed to the tasty test
-(double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
+runner as test-selecting -p patterns, and any arguments after -- will be
-ANSI colour codes disabled:
+passed to tasty unchanged.
 
-$ hledger test -- -pData.Amount --color=never
+Examples:
 
-For help on these, see https://github.com/feuerbach/tasty#options
+$ hledger test               # run all unit tests
-(-- --help currently doesn't show them).
+$ hledger test balance       # run tests with "balance" in their name
+$ hledger test -- -h         # show tasty's options