From 06c174b2362d9621267c22afbe1288f51ebd05d2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 19 Jun 2020 17:17:49 -0700 Subject: [PATCH] ;valuation: doc edits --- hledger/hledger.m4.md | 62 ++++++++++++++----------------------------- 1 file changed, 20 insertions(+), 42 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 0e3844614..48761beeb 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1124,18 +1124,12 @@ $ hledger balance --pivot member acct:. ## Valuation Instead of reporting amounts in their original commodity, -hledger can convert them to: - -- cost (or sale amount), using the conversion rate recorded as part of - the transaction - ([transaction price](journal.html#transaction-prices)). - -- value, using the [market prices](#market-prices) in effect on certain date(s). - -We call this "valuation", and it is controlled in full by the -`--value=VALUATIONTYPE[,COMMODITY]` option. -But we also provide simpler, Ledger-compatible `-B`/`-V`/`-X` flags, -and usually one of these is all you need: +hledger can convert them to +cost/sale amount (using the conversion rate recorded in the transaction), +or to market value (using some market price on a certain date). +This is controlled by the `--value=TYPE[,COMMODITY]` option, +but we also provide the simpler `-B`/`-V`/`-X` flags, +and usually one of those is all you need. ### -B: Cost @@ -1147,15 +1141,19 @@ if they have a [transaction price](journal.html#transaction-prices) specified. The `-V/--market` flag converts amounts to market value in their default *valuation commodity*, using the [market prices](#market-prices) in effect on the *valuation date(s)*, if any. -More on these things in a minute. +More on these in a minute. ### -X: Value in specified commodity -The `-X/--exchange` option is like `-V` except the desired valuation -currency is specified explicitly. +The `-X/--exchange=COMM` option is like `-V`, except you tell it which +currency you want to convert to, and it tries to convert everything to that. ### Valuation date +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which +market prices will be used. + For single period reports, if an explicit [report end date](#report-start-end-date) is specified, that will be used as the valuation date; otherwise the valuation date is "today". @@ -1190,15 +1188,6 @@ in this order of preference Amounts for which no applicable market price can be found, are not converted. - - - - - - - - - ### --infer-value: market prices from transactions *(experimental)* @@ -1215,10 +1204,10 @@ Adding the `--infer-value` flag to `-V`, `-X` or `--value` enables this. So for example, `hledger bs -V --infer-value` will get market prices both from P directives and from transactions. -There is a downside to this: value reports can be affected in +There is a downside: value reports can sometimes be affected in confusing/undesired ways by your journal entries. If this happens to you, read all of this [Valuation](#valuation) section carefully, -and try adding `--debug` or `--debug=2` to troubleshoot the reason. +and try adding `--debug` or `--debug=2` to troubleshoot. `--infer-value` can infer market prices from: @@ -1254,26 +1243,15 @@ follows, in this order of preference: `--infer-value` flag is used: the price commodity from the latest transaction-inferred price for A on or before valuation date. -Amounts for which no valuation commodity can be found are not converted. - This means: -- If you have any [P directives](journal.html#declaring-market-prices), - they alone determine which commodities `-V` will convert, and to what. +- If you have [P directives](journal.html#declaring-market-prices), + they determine which commodities `-V` will convert, and to what. -- If you have no P directives, and you add the `--infer-value` flag, - [transaction prices](journal.html#transaction-prices) determine - what `-V` converts. +- If you have no P directives, and use the `--infer-value` flag, + [transaction prices](journal.html#transaction-prices) determine it. -- `-X` tries harder to convert everything to just one commodity. - - - - - - - - +Amounts for which no valuation commodity can be found are not converted. ### Simple valuation examples