;doc: update command docs

hledger/Hledger/Cli/Commands/Add.txt

@@ -25,22 +25,21 @@ 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,
-    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.
 - 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
   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:
 

hledger/Hledger/Cli/Commands/Balance.txt

@@ -74,16 +74,16 @@ 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..
 
@@ -122,8 +122,7 @@ balance can show..
 
 ..with..
 
--   totals (-T), averages (-A), percentages (-%), inverted sign
+- totals (-T), averages (-A), percentages (-%), inverted sign (--invert)
-    (--invert)
 - rows and columns swapped (--transpose)
 - another field used as account name (--pivot)
 - custom-formatted line items (single-period reports only) (--format)
@@ -210,8 +209,8 @@ interpolated like so:
 
 - 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
   - total - the account's balance/posted total, right justified
 
@@ -272,17 +271,16 @@ $ 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
   separately.
@@ -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,13 +384,13 @@ 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).
 - Leading and trailing periods (columns) containing all zeroes are not
   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
   --no-elide is used.
 - Average and/or total columns can be added with the -A/--average and
@@ -399,9 +398,9 @@ Notes:
 - 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.
--   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:
@@ -412,8 +411,7 @@ in the terminal. Here are some ways to handle that:
 - Use a more compact layout like --layout=bare
 - Maximize the terminal window
 - 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
   (hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
   (M-x csv-mode, C-c C-a), or a spreadsheet
@@ -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,15 +461,15 @@ 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)
--   --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
   values (caused by deposits, withdrawals, and/or market price
   fluctuations)
@@ -479,56 +477,61 @@ The basic calculation to perform for each table cell. It is one of:
   balance minus each amount's original cost)
 - --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
   end, ie "previous columns plus this column". Typically used to show
   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,
   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)
+- 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
+- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on another
-    another date
+  date
 
-or one of the equivalent simpler flags:
+or with the legacy -B/-V/-X options, which are equivalent and easier to
+type:
 
--   -B/--cost : like --value=cost (though, note --cost and --value are
+- -B/--cost : like --value=cost
-    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 Value reporting for more about these.
+Note that --value can also convert to cost, as a convenience; but
+actually --cost and --value are independent options, and could be used
+together.
 
-Combining balance report types
+Combining balance report modes
 
-Most combinations of these options should produce reasonable reports,
+Most combinations of these modes should produce reasonable reports, but
-but if you find any that seem wrong or misleading, let us know. The
+if you find any that seem wrong or misleading, let us know. The
 following restrictions are applied:
 
 - --valuechange implies --value=end
@@ -564,8 +567,8 @@ 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
 - Accounts which don't have budget goals are hidden by default.
@@ -628,11 +631,11 @@ 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
   not shown since they have no budget goal of their own, but they
@@ -647,11 +650,10 @@ troubleshooting.
 - --depth or depth: can be used to limit report depth in the usual way
   (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.
 
 - In the periodic rules used for setting budget goals, unbalanced
@@ -662,8 +664,8 @@ troubleshooting.
   (The <unbudgeted> account is occasionally hard to exclude; this is
   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,
   --layout bare can be helpful.
 
@@ -765,11 +767,11 @@ four possible values:
 - --layout=wide[,WIDTH]: commodities are shown on a single line,
   optionally elided to WIDTH
 - --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

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -61,8 +61,7 @@ types). Or if no such accounts are declared, it shows accounts
 
 - under a top-level account named asset (case insensitive, plural
   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

@@ -28,79 +28,79 @@ These important checks are performed by default, by almost all hledger
 commands:
 
 - 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.
-    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
   passing

hledger/Hledger/Cli/Commands/Close.txt

@@ -137,8 +137,7 @@ close customisation
 In all modes, the following things can be overridden:
 
 - 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
   --open-desc=DESC
 - the transaction's tag value, with a --MODE=NEW option argument

hledger/Hledger/Cli/Commands/Import.txt

@@ -94,8 +94,7 @@ works:
 
 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
   balances with your bank.
 - hledger print -f FILE.csv will show all recently downloaded
@@ -190,5 +189,5 @@ data):
 
 - Two or more of the new CSV records are identical, and generate
   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
@@ -86,8 +87,8 @@ styles:
 
 - --round=none show amounts with original precisions (default)
 - --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
 
 soft is good for non-lossy cleanup, formatting amounts more consistently
@@ -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,8 +145,8 @@ 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
   double-quote-escaped and wrapped in double quotes.
 - Transaction tags are copied to Beancount #tag format.
@@ -150,12 +154,12 @@ follows:
   currency symbols like $ are converted to the corresponding currency
   names.
 - 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:
 
@@ -182,13 +186,13 @@ $ hledger print -Ocsv
 
 - There is one CSV record per posting, with the parent transaction's
   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"
   (numeric quantity) fields.
 - The numeric amount is repeated in either the "credit" or "debit"
   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/Rewrite.txt

@@ -127,8 +127,8 @@ 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
-    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
   printed. print --auto's query limits which transactions are printed.

hledger/Hledger/Cli/Commands/Roi.txt

@@ -72,8 +72,8 @@ 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
-    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
     assets:cash          -$100
@@ -171,5 +171,5 @@ References:
 - Explanation of IRR
 - Explanation of 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

@@ -35,8 +35,8 @@ a simple syntax:
   without the usual hledger first word
 - empty lines are 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
   exit or quit ends the run.
 

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

@@ -20,9 +20,8 @@ It also shows some run time statistics:
 - throughput: the number of transactions processed per second
 - 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.
-    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