From 549823a7836ddfed0754cde440901ff0ddb41290 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 11 Sep 2023 09:57:30 +0100 Subject: [PATCH] ;doc: update manuals --- hledger-lib/.date.m4 | 2 +- hledger-ui/.date.m4 | 2 +- hledger-ui/hledger-ui.1 | 4 +- hledger-ui/hledger-ui.info | 2 +- hledger-ui/hledger-ui.txt | 4 +- hledger-web/.date.m4 | 2 +- hledger-web/hledger-web.1 | 4 +- hledger-web/hledger-web.info | 2 +- hledger-web/hledger-web.txt | 4 +- hledger/.date.m4 | 2 +- hledger/hledger.1 | 71 +-- hledger/hledger.info | 960 ++++++++++++++++++----------------- hledger/hledger.txt | 100 ++-- 13 files changed, 584 insertions(+), 575 deletions(-) diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 0908cb747..38fac93ee 100644 --- a/hledger-lib/.date.m4 +++ b/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 diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index 0908cb747..38fac93ee 100644 --- a/hledger-ui/.date.m4 +++ b/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 diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 94a3d0d1e..198b26ade 100644 --- a/hledger-ui/hledger-ui.1 +++ b/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 diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index d8fcf918c..b1547951b 100644 --- a/hledger-ui/hledger-ui.info +++ b/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 diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index dd71dfd35..233230f38 100644 --- a/hledger-ui/hledger-ui.txt +++ b/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) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 0908cb747..38fac93ee 100644 --- a/hledger-web/.date.m4 +++ b/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 diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index ff32a9b60..ddd8fb668 100644 --- a/hledger-web/hledger-web.1 +++ b/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 diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index ee52c89ec..faa649582 100644 --- a/hledger-web/hledger-web.info +++ b/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 diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 88d3f3cb6..8ace89e72 100644 --- a/hledger-web/hledger-web.txt +++ b/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) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 0908cb747..38fac93ee 100644 --- a/hledger/.date.m4 +++ b/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 diff --git a/hledger/hledger.1 b/hledger/hledger.1 index e64240919..0333e9c05 100644 --- a/hledger/hledger.1 +++ b/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 -files): \f[V]include timedot:\[ti]/notes/2023*.md\f[R]. +overriding the file extension (as described in Data formats): +\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 -commands, including \f[V]check\f[R]: +These checks are run automatically by (almost) all hledger commands: .IP \[bu] 2 -\f[B]parseable\f[R] - data files are well-formed and can be successfully -parsed +\f[B]parseable\f[R] - data files are in a supported format, with no +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 -optional: +They are more specialised and not desirable for everyone: .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 -the time period requested. -Both rates of return are annualized before display, regardless of the -length of reporting interval. +(IRR, also known as money-weighted rate of return) and time-weighted +rate of return (TWR) for your investments for the time period requested. +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. .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. -Naively, if you are withdrawing from your investment, your future gains -would be smaller (in absolute numbers), and will be a smaller percentage -of your initial investment, and if you are adding to your investment, -you will receive bigger absolute gains (but probably at the same rate of -return). -IRR is a way to compute rate of return for each period between in-flow -or out-flow of money, and then combine them in a way that gives you a -compound annual rate of return that investment is expected to generate. +in-flows and out-flows, and the time between them. +Investment at a particular fixed interest rate is going to give you more +interest than the same amount invested at the same interest rate, but +made later in time. +If you are withdrawing from your investment, your future gains would be +smaller (in absolute numbers), and will be a smaller percentage of your +initial investment, so your IRR will be smaller. +And if you are adding to your investment, you will receive bigger +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 -between in-flows, out-flows and value changes, to compute rate of return -per each period and then a compound rate of return. -However, internal workings of TWR are quite different. +Like IRR, it will account for the effect of your in-flows and out-flows, +but unlike IRR it will try to compute the true rate of return of the +underlying asset, compensating for the effect that deposits and +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 diff --git a/hledger/hledger.info b/hledger/hledger.info index 6b8fdc59f..a620ee92d 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -23,7 +23,7 @@ accounting and a simple, editable file format. hledger is inspired by 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 bookkeeping/accounting as well! You don't need to know everything in @@ -2789,8 +2789,8 @@ since you have to avoid include cycles and including directories, but this can be done, eg: 'include */**/*.journal'. The path may also be prefixed to force a specific file format, -overriding the file extension (as described in hledger.1 -> Input -files): 'include timedot:~/notes/2023*.md'. +overriding the file extension (as described in Data formats): 'include +timedot:~/notes/2023*.md'.  File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal @@ -8637,23 +8637,22 @@ run these checks, providing instant feedback as you edit the journal. * Menu: -* Basic checks:: +* Default checks:: * Strict checks:: * Other checks:: * Custom checks:: * More about specific checks::  -File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check +File: hledger.info, Node: Default checks, Next: Strict checks, Up: check -23.10.1 Basic checks --------------------- +23.10.1 Default checks +---------------------- -These checks are always run automatically, by (almost) all hledger -commands, including 'check': +These checks are run automatically by (almost) all hledger commands: - * *parseable* - data files are well-formed and can be successfully - parsed + * *parseable* - data files are in a supported format, with no syntax + errors and no invalid include directives. * *autobalanced* - all transactions are balanced, after converting to cost. Missing amounts and missing costs are inferred automatically @@ -8663,7 +8662,7 @@ commands, including 'check': (This check can be disabled with '-I'/'--ignore-assertions'.)  -File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check +File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Default checks, Up: check 23.10.2 Strict checks --------------------- @@ -8672,15 +8671,15 @@ 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': + * *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 - * *balanced* - all transactions are balanced after converting to - cost, without inferring missing costs. If conversion costs are - required, they must be explicit. -  File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check @@ -8688,8 +8687,7 @@ File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict che -------------------- These checks can be run only by giving their names as arguments to -'check'. They are more specialised and not desirable for everyone, -therefore optional: +'check'. They are more specialised and not desirable for everyone: * *ordereddates* - transactions are ordered by date within each file @@ -9804,9 +9802,11 @@ manually, or do not require computation of time-weighted return (TWR), 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 -the time period requested. Both rates of return are annualized before -display, regardless of the length of reporting interval. +(IRR, also known as money-weighted rate of return) and time-weighted +rate of return (TWR) for your investments for the time period requested. +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). @@ -9923,15 +9923,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, if you are withdrawing from your investment, your future gains -would be smaller (in absolute numbers), and will be a smaller percentage -of your initial investment, and if you are adding to your investment, -you will receive bigger absolute gains (but probably at the same rate of -return). IRR is a way to compute rate of return for each period between -in-flow or out-flow of money, and then combine them in a way that gives -you a compound annual rate of return that investment is expected to -generate. +of return") takes into account effects of in-flows and out-flows, and +the time between them. Investment at a particular fixed interest rate +is going to give you more interest than the same amount invested at the +same interest rate, but made later in time. If you are withdrawing from +your investment, your future gains would be smaller (in absolute +numbers), and will be a smaller percentage of your initial investment, +so your IRR will be smaller. And if you are adding to your investment, +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 @@ -9950,26 +9950,28 @@ 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 -break the history of your investment into periods between in-flows, -out-flows and value changes, to compute rate of return per each period -and then a compound rate of return. However, internal workings of TWR -are quite different. +called "time-weighted rate of return" or "TWR". Like IRR, it will +account for the effect of your in-flows and out-flows, but unlike IRR it +will try to compute the true rate of return of the underlying asset, +compensating for the effect that deposits and withdrawas have on the +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 @@ -10804,448 +10806,448 @@ Node: decimal-mark directive98510 Ref: #decimal-mark-directive98692 Node: include directive99089 Ref: #include-directive99253 -Node: P directive100177 -Ref: #p-directive100322 -Node: payee directive101211 -Ref: #payee-directive101360 -Node: tag directive101676 -Ref: #tag-directive101831 -Node: Periodic transactions102299 -Ref: #periodic-transactions102464 -Node: Periodic rule syntax104170 -Ref: #periodic-rule-syntax104348 -Node: Periodic rules and relative dates104993 -Ref: #periodic-rules-and-relative-dates105259 -Node: Two spaces between period expression and description!105770 -Ref: #two-spaces-between-period-expression-and-description106047 -Node: Auto postings106731 -Ref: #auto-postings106879 -Node: Auto postings and multiple files109316 -Ref: #auto-postings-and-multiple-files109480 -Node: Auto postings and dates109881 -Ref: #auto-postings-and-dates110129 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions110304 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions110660 -Node: Auto posting tags111163 -Ref: #auto-posting-tags111445 -Node: Auto postings on forecast transactions only112081 -Ref: #auto-postings-on-forecast-transactions-only112327 -Node: Other syntax112574 -Ref: #other-syntax112690 -Node: Balance assignments113317 -Ref: #balance-assignments113473 -Node: Balance assignments and prices114846 -Ref: #balance-assignments-and-prices115061 -Node: Balance assignments and multiple files115272 -Ref: #balance-assignments-and-multiple-files115503 -Node: Bracketed posting dates115696 -Ref: #bracketed-posting-dates115880 -Node: D directive116394 -Ref: #d-directive116562 -Node: apply account directive118162 -Ref: #apply-account-directive118342 -Node: Y directive119029 -Ref: #y-directive119189 -Node: Secondary dates120017 -Ref: #secondary-dates120171 -Node: Star comments120985 -Ref: #star-comments121145 -Node: Valuation expressions121677 -Ref: #valuation-expressions121854 -Node: Virtual postings121976 -Ref: #virtual-postings122153 -Node: Other Ledger directives123590 -Ref: #other-ledger-directives123753 -Node: CSV124319 -Ref: #csv124412 -Node: CSV rules cheatsheet126492 -Ref: #csv-rules-cheatsheet126621 -Node: source128419 -Ref: #source128542 -Node: separator129422 -Ref: #separator129535 -Node: skip130075 -Ref: #skip130183 -Node: date-format130727 -Ref: #date-format130848 -Node: timezone131572 -Ref: #timezone131695 -Node: newest-first132700 -Ref: #newest-first132838 -Node: intra-day-reversed133415 -Ref: #intra-day-reversed133569 -Node: decimal-mark134017 -Ref: #decimal-mark134158 -Node: fields list134497 -Ref: #fields-list134636 -Node: Field assignment136307 -Ref: #field-assignment136451 -Node: Field names137478 -Ref: #field-names137609 -Node: date field138812 -Ref: #date-field138930 -Node: date2 field138978 -Ref: #date2-field139119 -Node: status field139175 -Ref: #status-field139318 -Node: code field139367 -Ref: #code-field139512 -Node: description field139557 -Ref: #description-field139717 -Node: comment field139776 -Ref: #comment-field139931 -Node: account field140224 -Ref: #account-field140374 -Node: amount field140944 -Ref: #amount-field141093 -Node: currency field143785 -Ref: #currency-field143938 -Node: balance field144195 -Ref: #balance-field144327 -Node: if block144699 -Ref: #if-block144820 -Node: Matchers146228 -Ref: #matchers146342 -Node: if table147824 -Ref: #if-table147946 -Node: balance-type149368 -Ref: #balance-type149497 -Node: include150197 -Ref: #include150324 -Node: Working with CSV150768 -Ref: #working-with-csv150915 -Node: Rapid feedback151322 -Ref: #rapid-feedback151455 -Node: Valid CSV151907 -Ref: #valid-csv152053 -Node: File Extension152785 -Ref: #file-extension152958 -Node: Reading CSV from standard input153522 -Ref: #reading-csv-from-standard-input153746 -Node: Reading multiple CSV files153910 -Ref: #reading-multiple-csv-files154141 -Node: Reading files specified by rule154382 -Ref: #reading-files-specified-by-rule154610 -Node: Valid transactions155781 -Ref: #valid-transactions155980 -Node: Deduplicating importing156608 -Ref: #deduplicating-importing156803 -Node: Setting amounts157839 -Ref: #setting-amounts158010 -Node: Amount signs160368 -Ref: #amount-signs160538 -Node: Setting currency/commodity161435 -Ref: #setting-currencycommodity161639 -Node: Amount decimal places162813 -Ref: #amount-decimal-places163019 -Node: Referencing other fields163331 -Ref: #referencing-other-fields163544 -Node: How CSV rules are evaluated164441 -Ref: #how-csv-rules-are-evaluated164658 -Node: Well factored rules166111 -Ref: #well-factored-rules166279 -Node: CSV rules examples166603 -Ref: #csv-rules-examples166738 -Node: Bank of Ireland166803 -Ref: #bank-of-ireland166940 -Node: Coinbase168402 -Ref: #coinbase168540 -Node: Amazon169587 -Ref: #amazon169712 -Node: Paypal171431 -Ref: #paypal171539 -Node: Timeclock179183 -Ref: #timeclock179288 -Node: Timedot181466 -Ref: #timedot181589 -Node: PART 3 REPORTING CONCEPTS186458 -Ref: #part-3-reporting-concepts186622 -Node: Time periods186622 -Ref: #time-periods186756 -Node: Report start & end date186874 -Ref: #report-start-end-date187026 -Node: Smart dates188685 -Ref: #smart-dates188838 -Node: Report intervals190706 -Ref: #report-intervals190861 -Node: Date adjustment191279 -Ref: #date-adjustment191439 -Node: Period expressions192290 -Ref: #period-expressions192431 -Node: Period expressions with a report interval194195 -Ref: #period-expressions-with-a-report-interval194429 -Node: More complex report intervals194643 -Ref: #more-complex-report-intervals194888 -Node: Multiple weekday intervals196689 -Ref: #multiple-weekday-intervals196878 -Node: Depth197700 -Ref: #depth197802 -Node: Queries198098 -Ref: #queries198200 -Node: Query types199325 -Ref: #query-types199446 -Node: Combining query terms202782 -Ref: #combining-query-terms202959 -Node: Queries and command options204227 -Ref: #queries-and-command-options204426 -Node: Queries and valuation204675 -Ref: #queries-and-valuation204870 -Node: Querying with account aliases205099 -Ref: #querying-with-account-aliases205310 -Node: Querying with cost or value205440 -Ref: #querying-with-cost-or-value205617 -Node: Pivoting205918 -Ref: #pivoting206032 -Node: Generating data207809 -Ref: #generating-data207941 -Node: Forecasting209524 -Ref: #forecasting209649 -Node: --forecast210180 -Ref: #forecast210311 -Node: Inspecting forecast transactions211357 -Ref: #inspecting-forecast-transactions211559 -Node: Forecast reports212689 -Ref: #forecast-reports212862 -Node: Forecast tags213798 -Ref: #forecast-tags213958 -Node: Forecast period in detail214418 -Ref: #forecast-period-in-detail214612 -Node: Forecast troubleshooting215506 -Ref: #forecast-troubleshooting215674 -Node: Budgeting216577 -Ref: #budgeting216697 -Node: Cost reporting217134 -Ref: #cost-reporting217268 -Node: Recording costs217929 -Ref: #recording-costs218065 -Node: Reporting at cost219656 -Ref: #reporting-at-cost219831 -Node: Equity conversion postings220421 -Ref: #equity-conversion-postings220635 -Node: Inferring equity conversion postings223066 -Ref: #inferring-equity-conversion-postings223329 -Node: Combining costs and equity conversion postings224081 -Ref: #combining-costs-and-equity-conversion-postings224391 -Node: Requirements for detecting equity conversion postings225379 -Ref: #requirements-for-detecting-equity-conversion-postings225701 -Node: Infer cost and equity by default ?226901 -Ref: #infer-cost-and-equity-by-default227130 -Node: Value reporting227338 -Ref: #value-reporting227480 -Node: -V Value228254 -Ref: #v-value228386 -Node: -X Value in specified commodity228581 -Ref: #x-value-in-specified-commodity228782 -Node: Valuation date228931 -Ref: #valuation-date229108 -Node: Finding market price229545 -Ref: #finding-market-price229756 -Node: --infer-market-prices market prices from transactions230926 -Ref: #infer-market-prices-market-prices-from-transactions231208 -Node: Valuation commodity233970 -Ref: #valuation-commodity234189 -Node: Simple valuation examples235402 -Ref: #simple-valuation-examples235606 -Node: --value Flexible valuation236265 -Ref: #value-flexible-valuation236475 -Node: More valuation examples238119 -Ref: #more-valuation-examples238334 -Node: Interaction of valuation and queries240333 -Ref: #interaction-of-valuation-and-queries240580 -Node: Effect of valuation on reports241052 -Ref: #effect-of-valuation-on-reports241255 -Node: PART 4 COMMANDS248952 -Ref: #part-4-commands249101 -Node: Commands overview249480 -Ref: #commands-overview249614 -Node: DATA ENTRY249793 -Ref: #data-entry249917 -Node: DATA CREATION250116 -Ref: #data-creation250270 -Node: DATA MANAGEMENT250388 -Ref: #data-management250553 -Node: REPORTS FINANCIAL250674 -Ref: #reports-financial250849 -Node: REPORTS VERSATILE251154 -Ref: #reports-versatile251327 -Node: REPORTS BASIC251580 -Ref: #reports-basic251732 -Node: HELP252241 -Ref: #help252363 -Node: ADD-ONS252473 -Ref: #add-ons252579 -Node: accounts253158 -Ref: #accounts253291 -Node: activity255178 -Ref: #activity255297 -Node: add255671 -Ref: #add255781 -Node: aregister258592 -Ref: #aregister258713 -Node: aregister and custom posting dates261601 -Ref: #aregister-and-custom-posting-dates261767 -Node: balance262319 -Ref: #balance262445 -Node: balance features263430 -Ref: #balance-features263570 -Node: Simple balance report265529 -Ref: #simple-balance-report265714 -Node: Balance report line format267339 -Ref: #balance-report-line-format267541 -Node: Filtered balance report269699 -Ref: #filtered-balance-report269891 -Node: List or tree mode270218 -Ref: #list-or-tree-mode270386 -Node: Depth limiting271731 -Ref: #depth-limiting271897 -Node: Dropping top-level accounts272498 -Ref: #dropping-top-level-accounts272698 -Node: Showing declared accounts273008 -Ref: #showing-declared-accounts273207 -Node: Sorting by amount273738 -Ref: #sorting-by-amount273905 -Node: Percentages274575 -Ref: #percentages274734 -Node: Multi-period balance report275282 -Ref: #multi-period-balance-report275482 -Node: Balance change end balance277757 -Ref: #balance-change-end-balance277966 -Node: Balance report types279394 -Ref: #balance-report-types279575 -Node: Calculation type280073 -Ref: #calculation-type280228 -Node: Accumulation type280777 -Ref: #accumulation-type280957 -Node: Valuation type281859 -Ref: #valuation-type282047 -Node: Combining balance report types283048 -Ref: #combining-balance-report-types283242 -Node: Budget report285080 -Ref: #budget-report285242 -Node: Budget report start date290896 -Ref: #budget-report-start-date291074 -Node: Budgets and subaccounts292406 -Ref: #budgets-and-subaccounts292613 -Node: Selecting budget goals296053 -Ref: #selecting-budget-goals296252 -Node: Budget vs forecast297287 -Ref: #budget-vs-forecast297446 -Node: Balance report layout299076 -Ref: #balance-report-layout299256 -Node: Useful balance reports307441 -Ref: #useful-balance-reports307601 -Node: balancesheet308686 -Ref: #balancesheet308831 -Node: balancesheetequity310151 -Ref: #balancesheetequity310309 -Node: cashflow311698 -Ref: #cashflow311829 -Node: check313257 -Ref: #check313371 -Node: Basic checks314173 -Ref: #basic-checks314293 -Node: Strict checks314780 -Ref: #strict-checks314923 -Node: Other checks315403 -Ref: #other-checks315545 -Node: Custom checks316098 -Ref: #custom-checks316255 -Node: More about specific checks316672 -Ref: #more-about-specific-checks316834 -Node: close317540 -Ref: #close317651 -Node: close and balance assertions321116 -Ref: #close-and-balance-assertions321294 -Node: Example retain earnings322445 -Ref: #example-retain-earnings322662 -Node: Example migrate balances to a new file323094 -Ref: #example-migrate-balances-to-a-new-file323359 -Node: Example excluding closing/opening transactions323935 -Ref: #example-excluding-closingopening-transactions324184 -Node: codes325402 -Ref: #codes325519 -Node: commodities326383 -Ref: #commodities326511 -Node: demo326581 -Ref: #demo326702 -Node: descriptions327618 -Ref: #descriptions327748 -Node: diff328039 -Ref: #diff328154 -Node: files329196 -Ref: #files329305 -Node: help329446 -Ref: #help-1329555 -Node: import330928 -Ref: #import331051 -Node: Deduplication332137 -Ref: #deduplication332262 -Node: Import testing334220 -Ref: #import-testing334385 -Node: Importing balance assignments335228 -Ref: #importing-balance-assignments335434 -Node: Commodity display styles336083 -Ref: #commodity-display-styles336256 -Node: incomestatement336385 -Ref: #incomestatement336527 -Node: notes337848 -Ref: #notes337970 -Node: payees338332 -Ref: #payees338447 -Node: prices338966 -Ref: #prices339081 -Node: print339379 -Ref: #print339494 -Node: register344838 -Ref: #register344960 -Node: Custom register output349991 -Ref: #custom-register-output350122 -Node: rewrite351459 -Ref: #rewrite351577 -Node: Re-write rules in a file353475 -Ref: #re-write-rules-in-a-file353638 -Node: Diff output format354787 -Ref: #diff-output-format354970 -Node: rewrite vs print --auto356062 -Ref: #rewrite-vs.-print---auto356222 -Node: roi356778 -Ref: #roi356885 -Node: Spaces and special characters in --inv and --pnl358606 -Ref: #spaces-and-special-characters-in---inv-and---pnl358846 -Node: Semantics of --inv and --pnl359334 -Ref: #semantics-of---inv-and---pnl359573 -Node: IRR and TWR explained361423 -Ref: #irr-and-twr-explained361583 -Node: stats364669 -Ref: #stats364777 -Node: tags366164 -Ref: #tags-1366271 -Node: test367280 -Ref: #test367373 -Node: PART 5 COMMON TASKS368115 -Ref: #part-5-common-tasks368261 -Node: Getting help368559 -Ref: #getting-help368700 -Node: Constructing command lines369460 -Ref: #constructing-command-lines369661 -Node: Starting a journal file370318 -Ref: #starting-a-journal-file370520 -Node: Setting LEDGER_FILE371722 -Ref: #setting-ledger_file371914 -Node: Setting opening balances372871 -Ref: #setting-opening-balances373072 -Node: Recording transactions376213 -Ref: #recording-transactions376402 -Node: Reconciling376958 -Ref: #reconciling377110 -Node: Reporting379367 -Ref: #reporting379516 -Node: Migrating to a new file383501 -Ref: #migrating-to-a-new-file383658 -Node: BUGS383957 -Ref: #bugs384047 -Node: Troubleshooting384926 -Ref: #troubleshooting385026 +Node: P directive100165 +Ref: #p-directive100310 +Node: payee directive101199 +Ref: #payee-directive101348 +Node: tag directive101664 +Ref: #tag-directive101819 +Node: Periodic transactions102287 +Ref: #periodic-transactions102452 +Node: Periodic rule syntax104158 +Ref: #periodic-rule-syntax104336 +Node: Periodic rules and relative dates104981 +Ref: #periodic-rules-and-relative-dates105247 +Node: Two spaces between period expression and description!105758 +Ref: #two-spaces-between-period-expression-and-description106035 +Node: Auto postings106719 +Ref: #auto-postings106867 +Node: Auto postings and multiple files109304 +Ref: #auto-postings-and-multiple-files109468 +Node: Auto postings and dates109869 +Ref: #auto-postings-and-dates110117 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions110292 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions110648 +Node: Auto posting tags111151 +Ref: #auto-posting-tags111433 +Node: Auto postings on forecast transactions only112069 +Ref: #auto-postings-on-forecast-transactions-only112315 +Node: Other syntax112562 +Ref: #other-syntax112678 +Node: Balance assignments113305 +Ref: #balance-assignments113461 +Node: Balance assignments and prices114834 +Ref: #balance-assignments-and-prices115049 +Node: Balance assignments and multiple files115260 +Ref: #balance-assignments-and-multiple-files115491 +Node: Bracketed posting dates115684 +Ref: #bracketed-posting-dates115868 +Node: D directive116382 +Ref: #d-directive116550 +Node: apply account directive118150 +Ref: #apply-account-directive118330 +Node: Y directive119017 +Ref: #y-directive119177 +Node: Secondary dates120005 +Ref: #secondary-dates120159 +Node: Star comments120973 +Ref: #star-comments121133 +Node: Valuation expressions121665 +Ref: #valuation-expressions121842 +Node: Virtual postings121964 +Ref: #virtual-postings122141 +Node: Other Ledger directives123578 +Ref: #other-ledger-directives123741 +Node: CSV124307 +Ref: #csv124400 +Node: CSV rules cheatsheet126480 +Ref: #csv-rules-cheatsheet126609 +Node: source128407 +Ref: #source128530 +Node: separator129410 +Ref: #separator129523 +Node: skip130063 +Ref: #skip130171 +Node: date-format130715 +Ref: #date-format130836 +Node: timezone131560 +Ref: #timezone131683 +Node: newest-first132688 +Ref: #newest-first132826 +Node: intra-day-reversed133403 +Ref: #intra-day-reversed133557 +Node: decimal-mark134005 +Ref: #decimal-mark134146 +Node: fields list134485 +Ref: #fields-list134624 +Node: Field assignment136295 +Ref: #field-assignment136439 +Node: Field names137466 +Ref: #field-names137597 +Node: date field138800 +Ref: #date-field138918 +Node: date2 field138966 +Ref: #date2-field139107 +Node: status field139163 +Ref: #status-field139306 +Node: code field139355 +Ref: #code-field139500 +Node: description field139545 +Ref: #description-field139705 +Node: comment field139764 +Ref: #comment-field139919 +Node: account field140212 +Ref: #account-field140362 +Node: amount field140932 +Ref: #amount-field141081 +Node: currency field143773 +Ref: #currency-field143926 +Node: balance field144183 +Ref: #balance-field144315 +Node: if block144687 +Ref: #if-block144808 +Node: Matchers146216 +Ref: #matchers146330 +Node: if table147812 +Ref: #if-table147934 +Node: balance-type149356 +Ref: #balance-type149485 +Node: include150185 +Ref: #include150312 +Node: Working with CSV150756 +Ref: #working-with-csv150903 +Node: Rapid feedback151310 +Ref: #rapid-feedback151443 +Node: Valid CSV151895 +Ref: #valid-csv152041 +Node: File Extension152773 +Ref: #file-extension152946 +Node: Reading CSV from standard input153510 +Ref: #reading-csv-from-standard-input153734 +Node: Reading multiple CSV files153898 +Ref: #reading-multiple-csv-files154129 +Node: Reading files specified by rule154370 +Ref: #reading-files-specified-by-rule154598 +Node: Valid transactions155769 +Ref: #valid-transactions155968 +Node: Deduplicating importing156596 +Ref: #deduplicating-importing156791 +Node: Setting amounts157827 +Ref: #setting-amounts157998 +Node: Amount signs160356 +Ref: #amount-signs160526 +Node: Setting currency/commodity161423 +Ref: #setting-currencycommodity161627 +Node: Amount decimal places162801 +Ref: #amount-decimal-places163007 +Node: Referencing other fields163319 +Ref: #referencing-other-fields163532 +Node: How CSV rules are evaluated164429 +Ref: #how-csv-rules-are-evaluated164646 +Node: Well factored rules166099 +Ref: #well-factored-rules166267 +Node: CSV rules examples166591 +Ref: #csv-rules-examples166726 +Node: Bank of Ireland166791 +Ref: #bank-of-ireland166928 +Node: Coinbase168390 +Ref: #coinbase168528 +Node: Amazon169575 +Ref: #amazon169700 +Node: Paypal171419 +Ref: #paypal171527 +Node: Timeclock179171 +Ref: #timeclock179276 +Node: Timedot181454 +Ref: #timedot181577 +Node: PART 3 REPORTING CONCEPTS186446 +Ref: #part-3-reporting-concepts186610 +Node: Time periods186610 +Ref: #time-periods186744 +Node: Report start & end date186862 +Ref: #report-start-end-date187014 +Node: Smart dates188673 +Ref: #smart-dates188826 +Node: Report intervals190694 +Ref: #report-intervals190849 +Node: Date adjustment191267 +Ref: #date-adjustment191427 +Node: Period expressions192278 +Ref: #period-expressions192419 +Node: Period expressions with a report interval194183 +Ref: #period-expressions-with-a-report-interval194417 +Node: More complex report intervals194631 +Ref: #more-complex-report-intervals194876 +Node: Multiple weekday intervals196677 +Ref: #multiple-weekday-intervals196866 +Node: Depth197688 +Ref: #depth197790 +Node: Queries198086 +Ref: #queries198188 +Node: Query types199313 +Ref: #query-types199434 +Node: Combining query terms202770 +Ref: #combining-query-terms202947 +Node: Queries and command options204215 +Ref: #queries-and-command-options204414 +Node: Queries and valuation204663 +Ref: #queries-and-valuation204858 +Node: Querying with account aliases205087 +Ref: #querying-with-account-aliases205298 +Node: Querying with cost or value205428 +Ref: #querying-with-cost-or-value205605 +Node: Pivoting205906 +Ref: #pivoting206020 +Node: Generating data207797 +Ref: #generating-data207929 +Node: Forecasting209512 +Ref: #forecasting209637 +Node: --forecast210168 +Ref: #forecast210299 +Node: Inspecting forecast transactions211345 +Ref: #inspecting-forecast-transactions211547 +Node: Forecast reports212677 +Ref: #forecast-reports212850 +Node: Forecast tags213786 +Ref: #forecast-tags213946 +Node: Forecast period in detail214406 +Ref: #forecast-period-in-detail214600 +Node: Forecast troubleshooting215494 +Ref: #forecast-troubleshooting215662 +Node: Budgeting216565 +Ref: #budgeting216685 +Node: Cost reporting217122 +Ref: #cost-reporting217256 +Node: Recording costs217917 +Ref: #recording-costs218053 +Node: Reporting at cost219644 +Ref: #reporting-at-cost219819 +Node: Equity conversion postings220409 +Ref: #equity-conversion-postings220623 +Node: Inferring equity conversion postings223054 +Ref: #inferring-equity-conversion-postings223317 +Node: Combining costs and equity conversion postings224069 +Ref: #combining-costs-and-equity-conversion-postings224379 +Node: Requirements for detecting equity conversion postings225367 +Ref: #requirements-for-detecting-equity-conversion-postings225689 +Node: Infer cost and equity by default ?226889 +Ref: #infer-cost-and-equity-by-default227118 +Node: Value reporting227326 +Ref: #value-reporting227468 +Node: -V Value228242 +Ref: #v-value228374 +Node: -X Value in specified commodity228569 +Ref: #x-value-in-specified-commodity228770 +Node: Valuation date228919 +Ref: #valuation-date229096 +Node: Finding market price229533 +Ref: #finding-market-price229744 +Node: --infer-market-prices market prices from transactions230914 +Ref: #infer-market-prices-market-prices-from-transactions231196 +Node: Valuation commodity233958 +Ref: #valuation-commodity234177 +Node: Simple valuation examples235390 +Ref: #simple-valuation-examples235594 +Node: --value Flexible valuation236253 +Ref: #value-flexible-valuation236463 +Node: More valuation examples238107 +Ref: #more-valuation-examples238322 +Node: Interaction of valuation and queries240321 +Ref: #interaction-of-valuation-and-queries240568 +Node: Effect of valuation on reports241040 +Ref: #effect-of-valuation-on-reports241243 +Node: PART 4 COMMANDS248940 +Ref: #part-4-commands249089 +Node: Commands overview249468 +Ref: #commands-overview249602 +Node: DATA ENTRY249781 +Ref: #data-entry249905 +Node: DATA CREATION250104 +Ref: #data-creation250258 +Node: DATA MANAGEMENT250376 +Ref: #data-management250541 +Node: REPORTS FINANCIAL250662 +Ref: #reports-financial250837 +Node: REPORTS VERSATILE251142 +Ref: #reports-versatile251315 +Node: REPORTS BASIC251568 +Ref: #reports-basic251720 +Node: HELP252229 +Ref: #help252351 +Node: ADD-ONS252461 +Ref: #add-ons252567 +Node: accounts253146 +Ref: #accounts253279 +Node: activity255166 +Ref: #activity255285 +Node: add255659 +Ref: #add255769 +Node: aregister258580 +Ref: #aregister258701 +Node: aregister and custom posting dates261589 +Ref: #aregister-and-custom-posting-dates261755 +Node: balance262307 +Ref: #balance262433 +Node: balance features263418 +Ref: #balance-features263558 +Node: Simple balance report265517 +Ref: #simple-balance-report265702 +Node: Balance report line format267327 +Ref: #balance-report-line-format267529 +Node: Filtered balance report269687 +Ref: #filtered-balance-report269879 +Node: List or tree mode270206 +Ref: #list-or-tree-mode270374 +Node: Depth limiting271719 +Ref: #depth-limiting271885 +Node: Dropping top-level accounts272486 +Ref: #dropping-top-level-accounts272686 +Node: Showing declared accounts272996 +Ref: #showing-declared-accounts273195 +Node: Sorting by amount273726 +Ref: #sorting-by-amount273893 +Node: Percentages274563 +Ref: #percentages274722 +Node: Multi-period balance report275270 +Ref: #multi-period-balance-report275470 +Node: Balance change end balance277745 +Ref: #balance-change-end-balance277954 +Node: Balance report types279382 +Ref: #balance-report-types279563 +Node: Calculation type280061 +Ref: #calculation-type280216 +Node: Accumulation type280765 +Ref: #accumulation-type280945 +Node: Valuation type281847 +Ref: #valuation-type282035 +Node: Combining balance report types283036 +Ref: #combining-balance-report-types283230 +Node: Budget report285068 +Ref: #budget-report285230 +Node: Budget report start date290884 +Ref: #budget-report-start-date291062 +Node: Budgets and subaccounts292394 +Ref: #budgets-and-subaccounts292601 +Node: Selecting budget goals296041 +Ref: #selecting-budget-goals296240 +Node: Budget vs forecast297275 +Ref: #budget-vs-forecast297434 +Node: Balance report layout299064 +Ref: #balance-report-layout299244 +Node: Useful balance reports307429 +Ref: #useful-balance-reports307589 +Node: balancesheet308674 +Ref: #balancesheet308819 +Node: balancesheetequity310139 +Ref: #balancesheetequity310297 +Node: cashflow311686 +Ref: #cashflow311817 +Node: check313245 +Ref: #check313359 +Node: Default checks314163 +Ref: #default-checks314289 +Node: Strict checks314786 +Ref: #strict-checks314931 +Node: Other checks315411 +Ref: #other-checks315553 +Node: Custom checks316086 +Ref: #custom-checks316243 +Node: More about specific checks316660 +Ref: #more-about-specific-checks316822 +Node: close317528 +Ref: #close317639 +Node: close and balance assertions321104 +Ref: #close-and-balance-assertions321282 +Node: Example retain earnings322433 +Ref: #example-retain-earnings322650 +Node: Example migrate balances to a new file323082 +Ref: #example-migrate-balances-to-a-new-file323347 +Node: Example excluding closing/opening transactions323923 +Ref: #example-excluding-closingopening-transactions324172 +Node: codes325390 +Ref: #codes325507 +Node: commodities326371 +Ref: #commodities326499 +Node: demo326569 +Ref: #demo326690 +Node: descriptions327606 +Ref: #descriptions327736 +Node: diff328027 +Ref: #diff328142 +Node: files329184 +Ref: #files329293 +Node: help329434 +Ref: #help-1329543 +Node: import330916 +Ref: #import331039 +Node: Deduplication332125 +Ref: #deduplication332250 +Node: Import testing334208 +Ref: #import-testing334373 +Node: Importing balance assignments335216 +Ref: #importing-balance-assignments335422 +Node: Commodity display styles336071 +Ref: #commodity-display-styles336244 +Node: incomestatement336373 +Ref: #incomestatement336515 +Node: notes337836 +Ref: #notes337958 +Node: payees338320 +Ref: #payees338435 +Node: prices338954 +Ref: #prices339069 +Node: print339367 +Ref: #print339482 +Node: register344826 +Ref: #register344948 +Node: Custom register output349979 +Ref: #custom-register-output350110 +Node: rewrite351447 +Ref: #rewrite351565 +Node: Re-write rules in a file353463 +Ref: #re-write-rules-in-a-file353626 +Node: Diff output format354775 +Ref: #diff-output-format354958 +Node: rewrite vs print --auto356050 +Ref: #rewrite-vs.-print---auto356210 +Node: roi356766 +Ref: #roi356873 +Node: Spaces and special characters in --inv and --pnl358685 +Ref: #spaces-and-special-characters-in---inv-and---pnl358925 +Node: Semantics of --inv and --pnl359413 +Ref: #semantics-of---inv-and---pnl359652 +Node: IRR and TWR explained361502 +Ref: #irr-and-twr-explained361662 +Node: stats364915 +Ref: #stats365023 +Node: tags366410 +Ref: #tags-1366517 +Node: test367526 +Ref: #test367619 +Node: PART 5 COMMON TASKS368361 +Ref: #part-5-common-tasks368507 +Node: Getting help368805 +Ref: #getting-help368946 +Node: Constructing command lines369706 +Ref: #constructing-command-lines369907 +Node: Starting a journal file370564 +Ref: #starting-a-journal-file370766 +Node: Setting LEDGER_FILE371968 +Ref: #setting-ledger_file372160 +Node: Setting opening balances373117 +Ref: #setting-opening-balances373318 +Node: Recording transactions376459 +Ref: #recording-transactions376648 +Node: Reconciling377204 +Ref: #reconciling377356 +Node: Reporting379613 +Ref: #reporting379762 +Node: Migrating to a new file383747 +Ref: #migrating-to-a-new-file383904 +Node: BUGS384203 +Ref: #bugs384293 +Node: Troubleshooting385172 +Ref: #troubleshooting385272  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index e6df317ef..ce7382c9c 100644 --- a/hledger/hledger.txt +++ b/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- - clude timedot:~/notes/2023*.md. + ing the file extension (as described in Data formats): include time- + 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 - These checks are always run automatically, by (almost) all hledger com- - mands, including check: + Default checks + These checks are run automatically by (almost) all hledger commands: - 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 - cost. Missing amounts and missing costs are inferred automatically + o autobalanced - all transactions are balanced, after converting to + 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 - check. They are more specialised and not desirable for everyone, - therefore optional: + These checks can be run only by giving their names as arguments to + check. They are more specialised and not desirable for everyone: 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 - the time period requested. Both rates of return are annualized before - display, regardless of the length of reporting interval. + (IRR, also known as money-weighted rate of return) and time-weighted + rate of return (TWR) for your investments for the time period re- + 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. - Naively, if you are withdrawing from your investment, your future gains - would be smaller (in absolute numbers), and will be a smaller percent- - age of your initial investment, and if you are adding to your invest- - ment, you will receive bigger absolute gains (but probably at the same - rate of return). IRR is a way to compute rate of return for each pe- - riod between in-flow or out-flow of money, and then combine them in a - way that gives you a compound annual rate of return that investment is - expected to generate. + return") takes into account effects of in-flows and out-flows, and the + time between them. Investment at a particular fixed interest rate is + going to give you more interest than the same amount invested at the + same interest rate, but made later in time. If you are withdrawing + from your investment, your future gains would be smaller (in absolute + numbers), and will be a smaller percentage of your initial investment, + so your IRR will be smaller. And if you are adding to your investment, + you will receive bigger absolute gains, which will be a bigger percent- + 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 - transactions that balance them against "profit and loss" (or "unreal- - 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 - of return, you will need to record the value of your investement on or + If you manually record changes in the value of your investment as + transactions that balance them against "profit and loss" (or "unreal- + 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 + 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 - called "time-weighted rate of return" or "TWR". Like IRR, it will also - break the history of your investment into periods between in-flows, - out-flows and value changes, to compute rate of return per each period - and then a compound rate of return. However, internal workings of TWR - are quite different. + Second way to compute rate of return that roi command implements is + called "time-weighted rate of return" or "TWR". Like IRR, it will ac- + count for the effect of your in-flows and out-flows, but unlike IRR it + will try to compute the true rate of return of the underlying asset, + compensating for the effect that deposits and withdrawas have on the + 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)