;doc: update command help

hledger/Hledger/Cli/Commands/Check.txt

@@ -21,13 +21,12 @@ these checks, providing instant feedback as you edit the journal.
 
 Here are the checks currently available:
 
-Basic checks
+Default checks
 
-These checks are always run automatically, by (almost) all hledger
+These checks are run automatically by (almost) all hledger commands:
-commands, including check:
 
--   parseable - data files are well-formed and can be successfully
+-   parseable - data files are in a supported format, with no syntax
-    parsed
+    errors and no invalid include directives.
 
 -   autobalanced - all transactions are balanced, after converting to
     cost. Missing amounts and missing costs are inferred automatically
@@ -42,19 +41,18 @@ These additional checks are run when the -s/--strict (strict mode) flag
 is used. Or, they can be run by giving their names as arguments to
 check:
 
--   accounts - all account names used by transactions have been declared
-
--   commodities - all commodity symbols used have been declared
-
 -   balanced - all transactions are balanced after converting to cost,
     without inferring missing costs. If conversion costs are required,
     they must be explicit.
 
+-   accounts - all account names used by transactions have been declared
+
+-   commodities - all commodity symbols used have been declared
+
 Other checks
 
 These checks can be run only by giving their names as arguments to
-check. They are more specialised and not desirable for everyone,
+check. They are more specialised and not desirable for everyone:
-therefore optional:
 
 -   ordereddates - transactions are ordered by date within each file
 

hledger/Hledger/Cli/Commands/Roi.txt

@@ -15,9 +15,11 @@ be an empty query (--pnl "" or --pnl STR where STR does not match any of
 your accounts).
 
 This command will compute and display the internalized rate of return
-(IRR) and time-weighted rate of return (TWR) for your investments for
+(IRR, also known as money-weighted rate of return) and time-weighted
-the time period requested. Both rates of return are annualized before
+rate of return (TWR) for your investments for the time period requested.
-display, regardless of the length of reporting interval.
+IRR is always annualized due to the way it is computed, but TWR is
+reported both as a rate over the chosen reporting period and as an
+annual rate.
 
 Price directives will be taken into account if you supply appropriate
 --cost or --value flags (see VALUATION).
@@ -115,14 +117,15 @@ different ways to compute rate of return, and this command implements
 two of them: IRR and TWR.
 
 Internal rate of return, or "IRR" (also called "money-weighted rate of
-return") takes into account effects of in-flows and out-flows. Naively,
+return") takes into account effects of in-flows and out-flows, and the
-if you are withdrawing from your investment, your future gains would be
+time between them. Investment at a particular fixed interest rate is
-smaller (in absolute numbers), and will be a smaller percentage of your
+going to give you more interest than the same amount invested at the
-initial investment, and if you are adding to your investment, you will
+same interest rate, but made later in time. If you are withdrawing from
-receive bigger absolute gains (but probably at the same rate of return).
+your investment, your future gains would be smaller (in absolute
-IRR is a way to compute rate of return for each period between in-flow
+numbers), and will be a smaller percentage of your initial investment,
-or out-flow of money, and then combine them in a way that gives you a
+so your IRR will be smaller. And if you are adding to your investment,
-compound annual rate of return that investment is expected to generate.
+you will receive bigger absolute gains, which will be a bigger
+percentage of your initial investment, so your IRR will be larger.
 
 As mentioned before, in-flows and out-flows would be any cash that you
 personally put in or withdraw, and for the "roi" command, these are the
@@ -141,25 +144,27 @@ present value, and tries to find a discount rate that makes net present
 value of all the cash flows of your investment to add up to zero. This
 could be hard to wrap your head around, especially if you haven't done
 discounted cash flow analysis before. Implementation of IRR in hledger
-should produce results that match the XIRR formula in Excel.
+should produce results that match the =XIRR formula in Excel.
 
 Second way to compute rate of return that roi command implements is
-called "time-weighted rate of return" or "TWR". Like IRR, it will also
+called "time-weighted rate of return" or "TWR". Like IRR, it will
-break the history of your investment into periods between in-flows,
+account for the effect of your in-flows and out-flows, but unlike IRR it
-out-flows and value changes, to compute rate of return per each period
+will try to compute the true rate of return of the underlying asset,
-and then a compound rate of return. However, internal workings of TWR
+compensating for the effect that deposits and withdrawas have on the
-are quite different.
+apparent rate of growth of your investment.
 
 TWR represents your investment as an imaginary "unit fund" where
 in-flows/ out-flows lead to buying or selling "units" of your investment
 and changes in its value change the value of "investment unit". Change
 in "unit price" over the reporting period gives you rate of return of
-your investment.
+your investment, and make TWR less sensitive than IRR to the effects of
+cash in-flows and out-flows.
 
 References:
 
 -   Explanation of rate of return
 -   Explanation of IRR
 -   Explanation of TWR
+-   IRR vs TWR
 -   Examples of computing IRR and TWR and discussion of the limitations
     of both metrics