;doc: update manuals

hledger-lib/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2023}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2023}})m4_dnl

hledger-ui/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2023}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2023}})m4_dnl

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER-UI" "1" "August 2023" "hledger-ui-1.30.99 " "hledger User Manuals"
+.TH "HLEDGER-UI" "1" "September 2023" "hledger-ui-1.31.99 " "hledger User Manuals"
 
 
 
@@ -15,7 +15,7 @@ hledger-ui - robust, friendly plain text accounting (TUI version)
 \f[V]hledger ui -- [OPTS] [QUERYARGS]\f[R]
 .SH DESCRIPTION
 .PP
-This manual is for hledger\[aq]s terminal interface, version 1.30.99.
+This manual is for hledger\[aq]s terminal interface, version 1.31.99.
 See also the hledger manual for common concepts and file formats.
 .PP
 hledger is a robust, user-friendly, cross-platform set of programs for

hledger-ui/hledger-ui.info

@@ -16,7 +16,7 @@ hledger-ui - robust, friendly plain text accounting (TUI version)
    'hledger-ui [OPTS] [QUERYARGS]'
 'hledger ui -- [OPTS] [QUERYARGS]'
 
-   This manual is for hledger's terminal interface, version 1.30.99.
+   This manual is for hledger's terminal interface, version 1.31.99.
 See also the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs

hledger-ui/hledger-ui.txt

@@ -9,7 +9,7 @@ SYNOPSIS
        hledger ui -- [OPTS] [QUERYARGS]
 
 DESCRIPTION
-       This  manual is for hledger's terminal interface, version 1.30.99.  See
+       This  manual is for hledger's terminal interface, version 1.31.99.  See
        also the hledger manual for common concepts and file formats.
 
        hledger is a robust, user-friendly, cross-platform set of programs  for
@@ -527,4 +527,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.30.99                August 2023                    HLEDGER-UI(1)
+hledger-ui-1.31.99              September 2023                   HLEDGER-UI(1)

hledger-web/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2023}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2023}})m4_dnl

hledger-web/hledger-web.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER-WEB" "1" "August 2023" "hledger-web-1.30.99 " "hledger User Manuals"
+.TH "HLEDGER-WEB" "1" "September 2023" "hledger-web-1.31.99 " "hledger User Manuals"
 
 
 
@@ -15,7 +15,7 @@ hledger-web - robust, friendly plain text accounting (Web version)
 \f[V]hledger web -- [--serve|--serve-api] [OPTS] [ARGS]\f[R]
 .SH DESCRIPTION
 .PP
-This manual is for hledger\[aq]s web interface, version 1.30.99.
+This manual is for hledger\[aq]s web interface, version 1.31.99.
 See also the hledger manual for common concepts and file formats.
 .PP
 hledger is a robust, user-friendly, cross-platform set of programs for

hledger-web/hledger-web.info

@@ -16,7 +16,7 @@ hledger-web - robust, friendly plain text accounting (Web version)
    'hledger-web [--serve|--serve-api] [OPTS] [ARGS]'
 'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]'
 
-   This manual is for hledger's web interface, version 1.30.99.  See
+   This manual is for hledger's web interface, version 1.31.99.  See
 also the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs

hledger-web/hledger-web.txt

@@ -9,7 +9,7 @@ SYNOPSIS
        hledger web -- [--serve|--serve-api] [OPTS] [ARGS]
 
 DESCRIPTION
-       This  manual is for hledger's web interface, version 1.30.99.  See also
+       This  manual is for hledger's web interface, version 1.31.99.  See also
        the hledger manual for common concepts and file formats.
 
        hledger is a robust, user-friendly, cross-platform set of programs  for
@@ -567,4 +567,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.30.99               August 2023                   HLEDGER-WEB(1)
+hledger-web-1.31.99             September 2023                  HLEDGER-WEB(1)

hledger/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2023}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2023}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "August 2023" "hledger-1.30.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "September 2023" "hledger-1.31.99 " "hledger User Manuals"
 
 
 
@@ -27,7 +27,7 @@ hledger is inspired by and largely compatible with ledger(1), and
 largely interconvertible with beancount(1).
 .PP
 This manual is for hledger\[aq]s command line interface, version
-1.30.99.
+1.31.99.
 It also describes the common options, file formats and concepts used by
 all hledger programs.
 It might accidentally teach you some bookkeeping/accounting as well!
@@ -3097,8 +3097,8 @@ including directories, but this can be done, eg:
 \f[V]include */**/*.journal\f[R].
 .PP
 The path may also be prefixed to force a specific file format,
-overriding the file extension (as described in hledger.1 -> Input
+overriding the file extension (as described in Data formats):
-files): \f[V]include timedot:\[ti]/notes/2023*.md\f[R].
+\f[V]include timedot:\[ti]/notes/2023*.md\f[R].
 .SS \f[V]P\f[R] directive
 .PP
 The \f[V]P\f[R] directive declares a market price, which is a conversion
@@ -9857,13 +9857,12 @@ If you are an Emacs user, you can also configure flycheck-hledger to run
 these checks, providing instant feedback as you edit the journal.
 .PP
 Here are the checks currently available:
-.SS Basic checks
+.SS Default checks
 .PP
-These checks are always run automatically, by (almost) all hledger
+These checks are run automatically by (almost) all hledger commands:
-commands, including \f[V]check\f[R]:
 .IP \[bu] 2
-\f[B]parseable\f[R] - data files are well-formed and can be successfully
+\f[B]parseable\f[R] - data files are in a supported format, with no
-parsed
+syntax errors and no invalid include directives.
 .IP \[bu] 2
 \f[B]autobalanced\f[R] - all transactions are balanced, after converting
 to cost.
@@ -9881,20 +9880,19 @@ These additional checks are run when the \f[V]-s\f[R]/\f[V]--strict\f[R]
 Or, they can be run by giving their names as arguments to
 \f[V]check\f[R]:
 .IP \[bu] 2
+\f[B]balanced\f[R] - all transactions are balanced after converting to
+cost, without inferring missing costs.
+If conversion costs are required, they must be explicit.
+.IP \[bu] 2
 \f[B]accounts\f[R] - all account names used by transactions have been
 declared
 .IP \[bu] 2
 \f[B]commodities\f[R] - all commodity symbols used have been declared
-.IP \[bu] 2
-\f[B]balanced\f[R] - all transactions are balanced after converting to
-cost, without inferring missing costs.
-If conversion costs are required, they must be explicit.
 .SS Other checks
 .PP
 These checks can be run only by giving their names as arguments to
 \f[V]check\f[R].
-They are more specialised and not desirable for everyone, therefore
+They are more specialised and not desirable for everyone:
-optional:
 .IP \[bu] 2
 \f[B]ordereddates\f[R] - transactions are ordered by date within each
 file
@@ -11081,10 +11079,11 @@ or do not require computation of time-weighted return (TWR),
 accounts).
 .PP
 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.
+rate of return (TWR) for your investments for the time period requested.
-Both rates of return are annualized before display, regardless of the
+IRR is always annualized due to the way it is computed, but TWR is
-length of reporting interval.
+reported both as a rate over the chosen reporting period and as an
+annual rate.
 .PP
 Price directives will be taken into account if you supply appropriate
 \f[V]--cost\f[R] or \f[V]--value\f[R] flags (see VALUATION).
@@ -11210,15 +11209,16 @@ return, and this command implements two of them: IRR and TWR.
 .PP
 Internal rate of return, or \[dq]IRR\[dq] (also called
 \[dq]money-weighted rate of return\[dq]) takes into account effects of
-in-flows and out-flows.
+in-flows and out-flows, and the time between them.
-Naively, if you are withdrawing from your investment, your future gains
+Investment at a particular fixed interest rate is going to give you more
-would be smaller (in absolute numbers), and will be a smaller percentage
+interest than the same amount invested at the same interest rate, but
-of your initial investment, and if you are adding to your investment,
+made later in time.
-you will receive bigger absolute gains (but probably at the same rate of
+If you are withdrawing from your investment, your future gains would be
-return).
+smaller (in absolute numbers), and will be a smaller percentage of your
-IRR is a way to compute rate of return for each period between in-flow
+initial investment, so your IRR will be smaller.
-or out-flow of money, and then combine them in a way that gives you a
+And if you are adding to your investment, you will receive bigger
-compound annual rate of return that investment is expected to generate.
+absolute gains, which will be a bigger percentage of your initial
+investment, so your IRR will be larger.
 .PP
 As mentioned before, in-flows and out-flows would be any cash that you
 personally put in or withdraw, and for the \[dq]roi\[dq] command, these
@@ -11238,22 +11238,23 @@ 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\[aq]t done discounted cash flow analysis before.
 Implementation of IRR in hledger should produce results that match the
-\f[V]XIRR\f[R] formula in Excel.
+\f[V]=XIRR\f[R] formula in Excel.
 .PP
 Second way to compute rate of return that \f[V]roi\f[R] command
 implements is called \[dq]time-weighted rate of return\[dq] or
 \[dq]TWR\[dq].
-Like IRR, it will also break the history of your investment into periods
+Like IRR, it will account for the effect of your in-flows and out-flows,
-between in-flows, out-flows and value changes, to compute rate of return
+but unlike IRR it will try to compute the true rate of return of the
-per each period and then a compound rate of return.
+underlying asset, compensating for the effect that deposits and
-However, internal workings of TWR are quite different.
+withdrawas have on the apparent rate of growth of your investment.
 .PP
 TWR represents your investment as an imaginary \[dq]unit fund\[dq] where
 in-flows/ out-flows lead to buying or selling \[dq]units\[dq] of your
 investment and changes in its value change the value of \[dq]investment
 unit\[dq].
 Change in \[dq]unit price\[dq] over the reporting period gives you rate
-of return of your investment.
+of return of your investment, and make TWR less sensitive than IRR to
+the effects of cash in-flows and out-flows.
 .PP
 References:
 .IP \[bu] 2
@@ -11263,6 +11264,8 @@ Explanation of IRR
 .IP \[bu] 2
 Explanation of TWR
 .IP \[bu] 2
+IRR vs TWR
+.IP \[bu] 2
 Examples of computing IRR and TWR and discussion of the limitations of
 both metrics
 .SS stats

hledger/hledger.txt

@@ -16,7 +16,7 @@ DESCRIPTION
        and largely compatible with  ledger(1),  and  largely  interconvertible
        with beancount(1).
 
-       This  manual  is for hledger's command line interface, version 1.30.99.
+       This  manual  is for hledger's command line interface, version 1.31.99.
        It also describes the common options, file formats and concepts used by
        all hledger programs.  It might accidentally teach you  some  bookkeep-
        ing/accounting  as  well!  You don't need to know everything in here to
@@ -2201,8 +2201,8 @@ Journal
        this can be done, eg: include */**/*.journal.
 
        The path may also be prefixed to force a specific file format, overrid-
-       ing the file extension (as described in hledger.1 -> Input files):  in-
+       ing the file extension (as described in Data  formats):  include  time-
-       clude timedot:~/notes/2023*.md.
+       dot:~/notes/2023*.md.
 
    P directive
        The P directive declares a market price, which is a conversion rate be-
@@ -7089,36 +7089,35 @@ PART 4: COMMANDS
 
        Here are the checks currently available:
 
-   Basic checks
+   Default checks
-       These checks are always run automatically, by (almost) all hledger com-
+       These checks are run automatically by (almost) all hledger commands:
-       mands, including check:
 
-       o parseable - data files are well-formed and can be successfully parsed
+       o parseable  - data files are in a supported format, with no syntax er-
+         rors and no invalid include directives.
 
-       o autobalanced  -  all  transactions  are balanced, after converting to
+       o autobalanced - all transactions are  balanced,  after  converting  to
-         cost.  Missing amounts and missing costs are  inferred  automatically
+         cost.   Missing  amounts and missing costs are inferred automatically
          where possible.
 
-       o assertions  -  all  balance  assertions  in  the journal are passing.
+       o assertions - all balance  assertions  in  the  journal  are  passing.
          (This check can be disabled with -I/--ignore-assertions.)
 
    Strict checks
        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
+       is  used.   Or,  they  can be run by giving their names as arguments to
        check:
 
+       o balanced - all transactions are balanced after  converting  to  cost,
+         without  inferring  missing costs.  If conversion costs are required,
+         they must be explicit.
+
        o accounts - all account names used by transactions have been declared
 
        o commodities - all commodity symbols used have been declared
 
-       o balanced  -  all  transactions are balanced after converting to cost,
-         without inferring missing costs.  If conversion costs  are  required,
-         they must be explicit.
-
    Other checks
-       These  checks  can  be  run  only by giving their names as arguments to
+       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:
 
        o ordereddates - transactions are ordered by date within each file
 
@@ -8054,9 +8053,11 @@ PART 4: COMMANDS
        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 re-
-       display, regardless of the length of reporting interval.
+       quested.  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).
@@ -8154,47 +8155,48 @@ PART 4: COMMANDS
        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.
+       return")  takes into account effects of in-flows and out-flows, and the
-       Naively, if you are withdrawing from your investment, your future gains
+       time between them.  Investment at a particular fixed interest  rate  is
-       would be smaller (in absolute numbers), and will be a smaller  percent-
+       going  to  give  you more interest than the same amount invested at the
-       age  of  your initial investment, and if you are adding to your invest-
+       same interest rate, but made later in time.   If  you  are  withdrawing
-       ment, you will receive bigger absolute gains (but probably at the  same
+       from  your  investment, your future gains would be smaller (in absolute
-       rate  of  return).  IRR is a way to compute rate of return for each pe-
+       numbers), and will be a smaller percentage of your initial  investment,
-       riod between in-flow or out-flow of money, and then combine them  in  a
+       so your IRR will be smaller.  And if you are adding to your investment,
-       way  that gives you a compound annual rate of return that investment is
+       you will receive bigger absolute gains, which will be a bigger percent-
-       expected to generate.
+       age of your initial investment, so your IRR will be larger.
 
-       As mentioned before, in-flows and out-flows would be any cash that  you
+       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
-       postings  that  match  the query in the--inv argument and NOT match the
+       postings that match the query in the--inv argument and  NOT  match  the
        query in the--pnl argument.
 
-       If you manually record changes in  the  value  of  your  investment  as
+       If  you  manually  record  changes  in  the value of your investment as
-       transactions  that  balance them against "profit and loss" (or "unreal-
+       transactions that balance them against "profit and loss"  (or  "unreal-
-       ized gains") account or use price directives, then in order for IRR  to
+       ized  gains") account or use price directives, then in order for IRR to
-       compute  the  precise effect of your in-flows and out-flows on the rate
+       compute the precise effect of your in-flows and out-flows on  the  rate
-       of return, you will need to record the value of your investement on  or
+       of  return, you will need to record the value of your investement on or
        close to the days when in- or out-flows occur.
 
-       In  technical  terms,  IRR uses the same approach as computation of net
+       In technical terms, IRR uses the same approach as  computation  of  net
        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
+       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
+       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 ac-
-       break the history of your investment  into  periods  between  in-flows,
+       count 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:
 
@@ -8204,6 +8206,8 @@ PART 4: COMMANDS
 
        o Explanation of TWR
 
+       o IRR vs TWR
+
        o Examples of computing IRR and TWR and discussion of  the  limitations
          of both metrics
 
@@ -8777,4 +8781,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-1.30.99                   August 2023                       HLEDGER(1)
+hledger-1.31.99                 September 2023                      HLEDGER(1)