;regen manuals

hledger-ui/hledger-ui.1

@@ -139,12 +139,19 @@ show items with zero amount, normally hidden (and vice-versa in
 hledger-ui/hledger-web)
 .TP
 \f[B]\f[CB]-B --cost\f[B]\f[R]
-convert amounts to their cost at transaction time (using the transaction
+convert amounts to their cost/selling amount at transaction time
-price, if any)
 .TP
-\f[B]\f[CB]-V --value\f[B]\f[R]
+\f[B]\f[CB]-V --market\f[B]\f[R]
-convert amounts to their market value on the report end date (using the
+convert amounts to their market value in default valuation commodities
-most recent applicable market price, if any)
+.TP
+\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R]
+convert amounts to their market value in commodity COMM
+.TP
+\f[B]\f[CB]--value\f[B]\f[R]
+convert amounts to cost or market value, more flexibly than -B/-V/-X
+.TP
+\f[B]\f[CB]--infer-value\f[B]\f[R]
+with -V/-X/--value, also infer market prices from transactions
 .TP
 \f[B]\f[CB]--auto\f[B]\f[R]
 apply automated posting rules to modify transactions.

hledger-ui/hledger-ui.info

@@ -152,12 +152,21 @@ the data.
      hledger-ui/hledger-web)
 '-B --cost'
 
-     convert amounts to their cost at transaction time (using the
+     convert amounts to their cost/selling amount at transaction time
-     transaction price, if any)
+'-V --market'
-'-V --value'
 
-     convert amounts to their market value on the report end date (using
+     convert amounts to their market value in default valuation
-     the most recent applicable market price, if any)
+     commodities
+'-X --exchange=COMM'
+
+     convert amounts to their market value in commodity COMM
+'--value'
+
+     convert amounts to cost or market value, more flexibly than
+     -B/-V/-X
+'--infer-value'
+
+     with -V/-X/-value, also infer market prices from transactions
 '--auto'
 
      apply automated posting rules to modify transactions.
@@ -501,24 +510,24 @@ Tag Table:
 Node: Top71
 Node: OPTIONS1470
 Ref: #options1567
-Node: KEYS4998
+Node: KEYS5182
-Ref: #keys5093
+Ref: #keys5277
-Node: SCREENS9369
+Node: SCREENS9553
-Ref: #screens9474
+Ref: #screens9658
-Node: Accounts screen9564
+Node: Accounts screen9748
-Ref: #accounts-screen9692
+Ref: #accounts-screen9876
-Node: Register screen11908
+Node: Register screen12092
-Ref: #register-screen12063
+Ref: #register-screen12247
-Node: Transaction screen14060
+Node: Transaction screen14244
-Ref: #transaction-screen14218
+Ref: #transaction-screen14402
-Node: Error screen15088
+Node: Error screen15272
-Ref: #error-screen15210
+Ref: #error-screen15394
-Node: ENVIRONMENT15454
+Node: ENVIRONMENT15638
-Ref: #environment15568
+Ref: #environment15752
-Node: FILES16375
+Node: FILES16559
-Ref: #files16474
+Ref: #files16658
-Node: BUGS16687
+Node: BUGS16871
-Ref: #bugs16764
+Ref: #bugs16948
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -135,12 +135,21 @@ OPTIONS
               hledger-ui/hledger-web)
 
        -B --cost
-              convert amounts to their cost at  transaction  time  (using  the
+              convert amounts to their cost/selling amount at transaction time
-              transaction price, if any)
 
-       -V --value
+       -V --market
-              convert  amounts  to  their  market value on the report end date
+              convert amounts to their market value in default valuation  com-
-              (using the most recent applicable market price, if any)
+              modities
+
+       -X --exchange=COMM
+              convert amounts to their market value in commodity COMM
+
+       --value
+              convert  amounts  to  cost  or  market value, more flexibly than
+              -B/-V/-X
+
+       --infer-value
+              with -V/-X/--value, also infer market prices from transactions
 
        --auto apply automated posting rules to modify transactions.
 

hledger-web/hledger-web.1

@@ -165,12 +165,19 @@ show items with zero amount, normally hidden (and vice-versa in
 hledger-ui/hledger-web)
 .TP
 \f[B]\f[CB]-B --cost\f[B]\f[R]
-convert amounts to their cost at transaction time (using the transaction
+convert amounts to their cost/selling amount at transaction time
-price, if any)
 .TP
-\f[B]\f[CB]-V --value\f[B]\f[R]
+\f[B]\f[CB]-V --market\f[B]\f[R]
-convert amounts to their market value on the report end date (using the
+convert amounts to their market value in default valuation commodities
-most recent applicable market price, if any)
+.TP
+\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R]
+convert amounts to their market value in commodity COMM
+.TP
+\f[B]\f[CB]--value\f[B]\f[R]
+convert amounts to cost or market value, more flexibly than -B/-V/-X
+.TP
+\f[B]\f[CB]--infer-value\f[B]\f[R]
+with -V/-X/--value, also infer market prices from transactions
 .TP
 \f[B]\f[CB]--auto\f[B]\f[R]
 apply automated posting rules to modify transactions.

hledger-web/hledger-web.info

@@ -176,12 +176,21 @@ before options, as shown in the synopsis above.
      hledger-ui/hledger-web)
 '-B --cost'
 
-     convert amounts to their cost at transaction time (using the
+     convert amounts to their cost/selling amount at transaction time
-     transaction price, if any)
+'-V --market'
-'-V --value'
 
-     convert amounts to their market value on the report end date (using
+     convert amounts to their market value in default valuation
-     the most recent applicable market price, if any)
+     commodities
+'-X --exchange=COMM'
+
+     convert amounts to their market value in commodity COMM
+'--value'
+
+     convert amounts to cost or market value, more flexibly than
+     -B/-V/-X
+'--infer-value'
+
+     with -V/-X/-value, also infer market prices from transactions
 '--auto'
 
      apply automated posting rules to modify transactions.
@@ -566,20 +575,20 @@ Tag Table:
 Node: Top72
 Node: OPTIONS1746
 Ref: #options1851
-Node: PERMISSIONS8195
+Node: PERMISSIONS8379
-Ref: #permissions8334
+Ref: #permissions8518
-Node: EDITING UPLOADING DOWNLOADING9546
+Node: EDITING UPLOADING DOWNLOADING9730
-Ref: #editing-uploading-downloading9727
+Ref: #editing-uploading-downloading9911
-Node: RELOADING10561
+Node: RELOADING10745
-Ref: #reloading10695
+Ref: #reloading10879
-Node: JSON API11128
+Node: JSON API11312
-Ref: #json-api11242
+Ref: #json-api11426
-Node: ENVIRONMENT16723
+Node: ENVIRONMENT16907
-Ref: #environment16839
+Ref: #environment17023
-Node: FILES17572
+Node: FILES17756
-Ref: #files17672
+Ref: #files17856
-Node: BUGS17885
+Node: BUGS18069
-Ref: #bugs17963
+Ref: #bugs18147
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -156,12 +156,21 @@ OPTIONS
               hledger-ui/hledger-web)
 
        -B --cost
-              convert amounts to their cost at  transaction  time  (using  the
+              convert amounts to their cost/selling amount at transaction time
-              transaction price, if any)
 
-       -V --value
+       -V --market
-              convert  amounts  to  their  market value on the report end date
+              convert amounts to their market value in default valuation  com-
-              (using the most recent applicable market price, if any)
+              modities
+
+       -X --exchange=COMM
+              convert amounts to their market value in commodity COMM
+
+       --value
+              convert  amounts  to  cost  or  market value, more flexibly than
+              -B/-V/-X
+
+       --infer-value
+              with -V/-X/--value, also infer market prices from transactions
 
        --auto apply automated posting rules to modify transactions.
 

hledger/hledger.1

@@ -617,12 +617,19 @@ show items with zero amount, normally hidden (and vice-versa in
 hledger-ui/hledger-web)
 .TP
 \f[B]\f[CB]-B --cost\f[B]\f[R]
-convert amounts to their cost at transaction time (using the transaction
+convert amounts to their cost/selling amount at transaction time
-price, if any)
 .TP
-\f[B]\f[CB]-V --value\f[B]\f[R]
+\f[B]\f[CB]-V --market\f[B]\f[R]
-convert amounts to their market value on the report end date (using the
+convert amounts to their market value in default valuation commodities
-most recent applicable market price, if any)
+.TP
+\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R]
+convert amounts to their market value in commodity COMM
+.TP
+\f[B]\f[CB]--value\f[B]\f[R]
+convert amounts to cost or market value, more flexibly than -B/-V/-X
+.TP
+\f[B]\f[CB]--infer-value\f[B]\f[R]
+with -V/-X/--value, also infer market prices from transactions
 .TP
 \f[B]\f[CB]--auto\f[B]\f[R]
 apply automated posting rules to modify transactions.
@@ -1671,47 +1678,143 @@ $ hledger balance --pivot member acct:.
 .fi
 .SS Valuation
 .PP
-hledger can show cost reports, where amounts are converted to their cost
+Instead of reporting amounts in their original commodity, hledger can
-or sale amount at transaction time; or value reports, where amounts are
+convert them to:
-converted to their market value in another currency/commodity at a
+.IP \[bu] 2
-specified date (using market prices inferred from your transactions, or
+cost (or sale amount), using the conversion rate recorded as part of the
-declared with P directives).
+transaction (transaction price).
+.IP \[bu] 2
+value, using the market prices in effect on certain date(s).
 .PP
-We call this \[dq]valuation\[dq], and it is controlled by the
+We call this \[dq]valuation\[dq], and it is controlled in full by the
 \f[C]--value=VALUATIONTYPE[,COMMODITY]\f[R] option.
-It can get a little involved, so we cover all the details below.
+But we also provide simpler, Ledger-compatible
-But most of the time, all you need to do is use these simpler flags
+\f[C]-B\f[R]/\f[C]-V\f[R]/\f[C]-X\f[R] flags, and usually one of these
-instead:
+is all you need:
-.IP \[bu] 2
-\f[C]-B\f[R] to convert to cost/sale amount, or
-.IP \[bu] 2
-\f[C]-V\f[R] to convert to market value in your base currency.
-Or occasionally,
-.IP \[bu] 2
-\f[C]-X COMMODITY\f[R] to convert to market value in some other
-currency.
 .SS -B: Cost
 .PP
 The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale
 amount at transaction time, if they have a transaction price specified.
-(It is equivalent to \f[C]--value=cost\f[R].)
 .SS -V: Value
 .PP
-The \f[C]-V/--market\f[R] flag converts reported amounts to market value
+The \f[C]-V/--market\f[R] flag converts amounts to market value in their
-in their \f[I]default valuation commodity\f[R], using the market prices
+default \f[I]valuation commodity\f[R], using the market prices in effect
-in effect on a \f[I]default valuation date\f[R].
+on the \f[I]valuation date(s)\f[R], if any.
-(More on these below.)
+More on these things in a minute.
+.SS -X: Value in specified commodity
 .PP
-The default valuation commodity is the one referenced in the latest
+The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R] except the
-applicable market price dated on or before the valuation date.
+desired valuation currency is specified explicitly.
-Typically your P declarations or currency exchange transactions
+.SS Valuation date
-reference a single base currency, and -V will pick that.
 .PP
-The default valuation date is today for single period reports
+For single period reports, if an explicit report end date is specified,
-(equivalent to \f[C]--value=now\f[R]), or the last day of each subperiod
+that will be used as the valuation date; otherwise the valuation date is
-for multiperiod reports (equivalent to \f[C]--value=end\f[R]).
+\[dq]today\[dq].
 .PP
-An example:
+For multiperiod reports, each column/period is valued on the last day of
+the period.
+.SS Market prices
+.PP
+\f[I](experimental)\f[R]
+.PP
+To convert a commodity A to its market value in another commodity B,
+hledger looks for a suitable market price (exchange rate) as follows, in
+this order of preference :
+.IP "1." 3
+A \f[I]declared market price\f[R] or \f[I]inferred market price\f[R]:
+A\[aq]s latest market price in B on or before the valuation date as
+declared by a P directive, or (if the \f[C]--infer-value\f[R] flag is
+used) inferred from transaction prices.
+.IP "2." 3
+A \f[I]reverse market price\f[R]: the inverse of a declared or inferred
+market price from B to A.
+.IP "3." 3
+A \f[I]chained market price\f[R]: a synthetic price formed by combining
+the shortest chain of market prices (any of the above types) leading
+from A to B.
+.PP
+Amounts for which no applicable market price can be found, are not
+converted.
+.SS --infer-value: market prices from transactions
+.PP
+\f[I](experimental)\f[R]
+.PP
+Normally, market value in hledger is fully controlled by, and requires,
+P directives in your journal.
+Since adding and updating those can be a chore, and since transactions
+usually take place at close to market value, why not use the recorded
+transaction prices as additional market prices (as Ledger does) ?
+We could produce value reports without needing P directives at all.
+.PP
+Adding the \f[C]--infer-value\f[R] flag to \f[C]-V\f[R], \f[C]-X\f[R] or
+\f[C]--value\f[R] enables this.
+So for example, \f[C]hledger bs -V --infer-value\f[R] will get market
+prices both from P directives and from transactions.
+.PP
+There is a downside to this: value reports can be affected in
+confusing/undesired ways by your journal entries.
+If this happens to you, read all of this Valuation section carefully,
+and try adding \f[C]--debug\f[R] or \f[C]--debug=2\f[R] to troubleshoot
+the reason.
+.PP
+\f[C]--infer-value\f[R] can infer market prices from:
+.IP \[bu] 2
+multicommodity transactions with explicit prices
+(\f[C]\[at]\f[R]/\f[C]\[at]\[at]\f[R])
+.IP \[bu] 2
+multicommodity transactions with implicit prices (no \f[C]\[at]\f[R],
+two commodities, unbalanced).
+(With these, the order of postings matters.
+\f[C]hledger print -x\f[R] can be useful for troubleshooting.)
+.IP \[bu] 2
+but not, currently, from \[dq]more correct\[dq] multicommodity
+transactions (no \f[C]\[at]\f[R], multiple commodities, balanced).
+.SS Valuation commodity
+.PP
+\f[I](experimental)\f[R]
+.PP
+\f[B]When you specify a valuation commodity (\f[CB]-X COMM\f[B] or
+\f[CB]--value TYPE,COMM\f[B]):\f[R]
+.PD 0
+.P
+.PD
+hledger will convert all amounts to COMM, wherever it can find a
+suitable market price (including by reversing or chaining prices).
+.PP
+\f[B]When you leave the valuation commodity unspecified (\f[CB]-V\f[B]
+or \f[CB]--value TYPE\f[B]):\f[R]
+.PD 0
+.P
+.PD
+For each commodity A, hledger picks a default valuation commodity as
+follows, in this order of preference:
+.IP "1." 3
+The price commodity from the latest P-declared market price for A on or
+before valuation date.
+.IP "2." 3
+The price commodity from the latest P-declared market price for A on any
+date.
+(Allows conversion to proceed when there are inferred prices before the
+valuation date.)
+.IP "3." 3
+If there are no P directives at all (any commodity or date) and the
+\f[C]--infer-value\f[R] flag is used: the price commodity from the
+latest transaction-inferred price for A on or before valuation date.
+.PP
+Amounts for which no valuation commodity can be found are not converted.
+.PP
+This means:
+.IP \[bu] 2
+If you have any P directives, they alone determine which commodities
+\f[C]-V\f[R] will convert, and to what.
+.IP \[bu] 2
+If you have no P directives, and you add the \f[C]--infer-value\f[R]
+flag, transaction prices determine what \f[C]-V\f[R] converts.
+.IP \[bu] 2
+\f[C]-X\f[R] tries harder to convert everything to just one commodity.
+.SS Simple valuation examples
+.PP
+Here are some quick examples of \f[C]-V\f[R]:
 .IP
 .nf
 \f[C]
@@ -1755,39 +1858,8 @@ $ hledger -f t.j bal -N euros -V
              $103.00  assets:euros
 \f[R]
 .fi
-.SS -X: Market value in specified commodity
-.PP
-The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R], except it
-specifies the target commodity you would like to convert to.
-(It is equivalent to \f[C]--value=now,COMM\f[R] or
-\f[C]--value=end,COMM\f[R].)
-.SS Market prices
-.PP
-To convert a commodity A to commodity B, hledger looks for a suitable
-market price (exchange rate) in the following ways, in this order of
-preference:
-.IP "1." 3
-a \f[I]declared market price\f[R] - the latest P directive specifying
-the exchange rate from A to B, dated on or before the valuation date.
-.IP "2." 3
-a \f[I]transaction-implied market price\f[R] - a market price matching
-the transaction price used in the latest transaction where A is
-converted to B, dated on or before the valuation date.
-(\f[I]since hledger 1.18; experimental\f[R])
-.IP "3." 3
-a \f[I]reverse declared market price\f[R] - calculated by inverting a
-declared market price from B to A.
-.IP "4." 3
-a \f[I]reverse transaction-implied market price\f[R] - calculated by
-inverting a transaction-implied market price from B to A.
-.IP "5." 3
-an \f[I]indirect market price\f[R] - calculated by combining the
-shortest chain of market prices (any of the above types) leading from A
-to B.
 .SS --value: Flexible valuation
 .PP
-\f[I](experimental, added 201905)\f[R]
-.PP
 \f[C]-B\f[R], \f[C]-V\f[R] and \f[C]-X\f[R] are special cases of the
 more general \f[C]--value\f[R] option:
 .IP
@@ -1804,52 +1876,38 @@ more general \f[C]--value\f[R] option:
 \f[R]
 .fi
 .PP
-The TYPE part basically selects either \[dq]cost\[dq], or \[dq]market
+The TYPE part selects cost or value and valuation date:
-value\[dq] plus a valuation date:
 .TP
 \f[B]\f[CB]--value=cost\f[B]\f[R]
 Convert amounts to cost, using the prices recorded in transactions.
 .TP
 \f[B]\f[CB]--value=then\f[B]\f[R]
-Convert amounts to their value in a default valuation commodity, using
+Convert amounts to their value in the default valuation commodity, using
 market prices on each posting\[aq]s date.
 This is currently supported only by the print and register commands.
 .TP
 \f[B]\f[CB]--value=end\f[B]\f[R]
-Convert amounts to their value in a default valuation commodity, using
+Convert amounts to their value in the default valuation commodity, using
 market prices on the last day of the report period (or if unspecified,
 the journal\[aq]s end date); or in multiperiod reports, market prices on
 the last day of each subperiod.
 .TP
 \f[B]\f[CB]--value=now\f[B]\f[R]
-Convert amounts to their value in default valuation commodity using
+Convert amounts to their value in the default valuation commodity using
 current market prices (as of when report is generated).
 .TP
 \f[B]\f[CB]--value=YYYY-MM-DD\f[B]\f[R]
-Convert amounts to their value in default valuation commodity using
+Convert amounts to their value in the default valuation commodity using
 market prices on this date.
 .PP
-The default valuation commodity is the commodity mentioned in the most
-recent applicable market price declaration.
-When all your price declarations lead to a single home currency, this
-will usually do what you want.
-.PP
 To select a different valuation commodity, add the optional
 \f[C],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol.
 Eg: \f[B]\f[CB]--value=now,EUR\f[B]\f[R].
-hledger will do its best to convert amounts to this commodity, using:
+hledger will do its best to convert amounts to this commodity, deducing
-.IP \[bu] 2
+market prices as described above.
-declared prices (from source commodity to valuation commodity)
+.SS More valuation examples
-.IP \[bu] 2
-reverse prices (declared prices from valuation to source commodity,
-inverted)
-.IP \[bu] 2
-indirect prices (prices calculated from the shortest chain of declared
-or reverse prices from source to valuation commodity)
 .PP
-in that order.
+Here are some examples showing the effect of \f[C]--value\f[R], as seen
-.PP
-Here are some examples showing the effect of \f[C]--value\f[R] as seen
 with \f[C]print\f[R]:
 .IP
 .nf
@@ -1997,13 +2055,12 @@ $ hledger print -X A
     b          -0.50A
 \f[R]
 .fi
-.SS Effect of --value on reports
+.SS Effect of valuation on reports
 .PP
-Here is a reference for how \f[C]--value\f[R] currently affects each
+Here is a reference for how valuation is supposed to affect each part of
-part of hledger\[aq]s reports.
+hledger\[aq]s reports (and a glossary).
-It\[aq]s work in progress, but may be useful for troubleshooting or
+(It\[aq]s wide, you\[aq]ll have to scroll sideways.) It may be useful
-reporting bugs.
+when troubleshooting.
-See also the definitions and notes below.
 If you find problems, please report them, ideally with a reproducible
 example.
 Related: #329, #1083.
@@ -2254,7 +2311,7 @@ T}@T{
 T}
 .TE
 .PP
-\f[B]Additional notes\f[R]
+\f[B]Glossary:\f[R]
 .TP
 \f[I]cost\f[R]
 calculated using price(s) recorded in the transaction(s).

hledger/hledger.info

@@ -610,12 +610,21 @@ by most hledger commands, run 'hledger -h'.
      hledger-ui/hledger-web)
 '-B --cost'
 
-     convert amounts to their cost at transaction time (using the
+     convert amounts to their cost/selling amount at transaction time
-     transaction price, if any)
+'-V --market'
-'-V --value'
 
-     convert amounts to their market value on the report end date (using
+     convert amounts to their market value in default valuation
-     the most recent applicable market price, if any)
+     commodities
+'-X --exchange=COMM'
+
+     convert amounts to their market value in commodity COMM
+'--value'
+
+     convert amounts to cost or market value, more flexibly than
+     -B/-V/-X
+'--infer-value'
+
+     with -V/-X/-value, also infer market prices from transactions
 '--auto'
 
      apply automated posting rules to modify transactions.
@@ -1363,30 +1372,32 @@ File: hledger.info,  Node: Valuation,  Prev: Pivoting,  Up: OPTIONS
 2.17 Valuation
 ==============
 
-hledger can show cost reports, where amounts are converted to their cost
+Instead of reporting amounts in their original commodity, hledger can
-or sale amount at transaction time; or value reports, where amounts are
+convert them to:
-converted to their market value in another currency/commodity at a
-specified date (using market prices inferred from your transactions, or
-declared with P directives).
 
-   We call this "valuation", and it is controlled by the
+   * cost (or sale amount), using the conversion rate recorded as part
-'--value=VALUATIONTYPE[,COMMODITY]' option.  It can get a little
+     of the transaction (transaction price).
-involved, so we cover all the details below.  But most of the time, all
-you need to do is use these simpler flags instead:
 
-   * '-B' to convert to cost/sale amount, or
+   * value, using the market prices in effect on certain date(s).
-   * '-V' to convert to market value in your base currency.  Or
+
-     occasionally,
+   We call this "valuation", and it is controlled in full by the
-   * '-X COMMODITY' to convert to market value in some other currency.
+'--value=VALUATIONTYPE[,COMMODITY]' option.  But we also provide
+simpler, Ledger-compatible '-B'/'-V'/'-X' flags, and usually one of
+these is all you need:
 
 * Menu:
 
 * -B Cost::
 * -V Value::
-* -X Market value in specified commodity::
+* -X Value in specified commodity::
+* Valuation date::
 * Market prices::
+* --infer-value market prices from transactions::
+* Valuation commodity::
+* Simple valuation examples::
 * --value Flexible valuation::
-* Effect of --value on reports::
+* More valuation examples::
+* Effect of valuation on reports::
 
 
 File: hledger.info,  Node: -B Cost,  Next: -V Value,  Up: Valuation
@@ -1395,29 +1406,151 @@ File: hledger.info,  Node: -B Cost,  Next: -V Value,  Up: Valuation
 ---------------
 
 The '-B/--cost' flag converts amounts to their cost or sale amount at
-transaction time, if they have a transaction price specified.  (It is
+transaction time, if they have a transaction price specified.
-equivalent to '--value=cost'.)
 
 
-File: hledger.info,  Node: -V Value,  Next: -X Market value in specified commodity,  Prev: -B Cost,  Up: Valuation
+File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Prev: -B Cost,  Up: Valuation
 
 2.17.2 -V: Value
 ----------------
 
-The '-V/--market' flag converts reported amounts to market value in
+The '-V/--market' flag converts amounts to market value in their default
-their _default valuation commodity_, using the market prices in effect
+_valuation commodity_, using the market prices in effect on the
-on a _default valuation date_.  (More on these below.)
+_valuation date(s)_, if any.  More on these things in a minute.
 
-   The default valuation commodity is the one referenced in the latest
+
-applicable market price dated on or before the valuation date.
+File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: Valuation
-Typically your P declarations or currency exchange transactions
-reference a single base currency, and -V will pick that.
 
-   The default valuation date is today for single period reports
+2.17.3 -X: Value in specified commodity
-(equivalent to '--value=now'), or the last day of each subperiod for
+---------------------------------------
-multiperiod reports (equivalent to '--value=end').
 
-   An example:
+The '-X/--exchange' option is like '-V' except the desired valuation
+currency is specified explicitly.
+
+
+File: hledger.info,  Node: Valuation date,  Next: Market prices,  Prev: -X Value in specified commodity,  Up: Valuation
+
+2.17.4 Valuation date
+---------------------
+
+For single period reports, if an explicit report end date is specified,
+that will be used as the valuation date; otherwise the valuation date is
+"today".
+
+   For multiperiod reports, each column/period is valued on the last day
+of the period.
+
+
+File: hledger.info,  Node: Market prices,  Next: --infer-value market prices from transactions,  Prev: Valuation date,  Up: Valuation
+
+2.17.5 Market prices
+--------------------
+
+_(experimental)_
+
+   To convert a commodity A to its market value in another commodity B,
+hledger looks for a suitable market price (exchange rate) as follows, in
+this order of preference :
+
+  1. A _declared market price_ or _inferred market price_: A's latest
+     market price in B on or before the valuation date as declared by a
+     P directive, or (if the '--infer-value' flag is used) inferred from
+     transaction prices.
+
+  2. A _reverse market price_: the inverse of a declared or inferred
+     market price from B to A.
+
+  3. A _chained market price_: a synthetic price formed by combining the
+     shortest chain of market prices (any of the above types) leading
+     from A to B.
+
+   Amounts for which no applicable market price can be found, are not
+converted.
+
+
+File: hledger.info,  Node: --infer-value market prices from transactions,  Next: Valuation commodity,  Prev: Market prices,  Up: Valuation
+
+2.17.6 -infer-value: market prices from transactions
+----------------------------------------------------
+
+_(experimental)_
+
+   Normally, market value in hledger is fully controlled by, and
+requires, P directives in your journal.  Since adding and updating those
+can be a chore, and since transactions usually take place at close to
+market value, why not use the recorded transaction prices as additional
+market prices (as Ledger does) ?  We could produce value reports without
+needing P directives at all.
+
+   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
+confusing/undesired ways by your journal entries.  If this happens to
+you, read all of this Valuation section carefully, and try adding
+'--debug' or '--debug=2' to troubleshoot the reason.
+
+   '--infer-value' can infer market prices from:
+
+   * multicommodity transactions with explicit prices ('@'/'@@')
+
+   * multicommodity transactions with implicit prices (no '@', two
+     commodities, unbalanced).  (With these, the order of postings
+     matters.  'hledger print -x' can be useful for troubleshooting.)
+
+   * but not, currently, from "more correct" multicommodity transactions
+     (no '@', multiple commodities, balanced).
+
+
+File: hledger.info,  Node: Valuation commodity,  Next: Simple valuation examples,  Prev: --infer-value market prices from transactions,  Up: Valuation
+
+2.17.7 Valuation commodity
+--------------------------
+
+_(experimental)_
+
+   *When you specify a valuation commodity ('-X COMM' or '--value
+TYPE,COMM'):*
+hledger will convert all amounts to COMM, wherever it can find a
+suitable market price (including by reversing or chaining prices).
+
+   *When you leave the valuation commodity unspecified ('-V' or '--value
+TYPE'):*
+For each commodity A, hledger picks a default valuation commodity as
+follows, in this order of preference:
+
+  1. The price commodity from the latest P-declared market price for A
+     on or before valuation date.
+
+  2. The price commodity from the latest P-declared market price for A
+     on any date.  (Allows conversion to proceed when there are inferred
+     prices before the valuation date.)
+
+  3. If there are no P directives at all (any commodity or date) and the
+     '--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, they alone determine which
+     commodities '-V' will convert, and to what.
+
+   * If you have no P directives, and you add the '--infer-value' flag,
+     transaction prices determine what '-V' converts.
+
+   * '-X' tries harder to convert everything to just one commodity.
+
+
+File: hledger.info,  Node: Simple valuation examples,  Next: --value Flexible valuation,  Prev: Valuation commodity,  Up: Valuation
+
+2.17.8 Simple valuation examples
+--------------------------------
+
+Here are some quick examples of '-V':
 
 ; one euro is worth this many dollars from nov 1
 P 2016/11/01 € $1.10
@@ -1447,52 +1580,12 @@ $ hledger -f t.j bal -N euros -V
              $103.00  assets:euros
 
 
-File: hledger.info,  Node: -X Market value in specified commodity,  Next: Market prices,  Prev: -V Value,  Up: Valuation
+File: hledger.info,  Node: --value Flexible valuation,  Next: More valuation examples,  Prev: Simple valuation examples,  Up: Valuation
 
-2.17.3 -X: Market value in specified commodity
+2.17.9 -value: Flexible valuation
-----------------------------------------------
-
-The '-X/--exchange' option is like '-V', except it specifies the target
-commodity you would like to convert to.  (It is equivalent to
-'--value=now,COMM' or '--value=end,COMM'.)
-
-
-File: hledger.info,  Node: Market prices,  Next: --value Flexible valuation,  Prev: -X Market value in specified commodity,  Up: Valuation
-
-2.17.4 Market prices
---------------------
-
-To convert a commodity A to commodity B, hledger looks for a suitable
-market price (exchange rate) in the following ways, in this order of
-preference:
-
-  1. a _declared market price_ - the latest P directive specifying the
-     exchange rate from A to B, dated on or before the valuation date.
-
-  2. a _transaction-implied market price_ - a market price matching the
-     transaction price used in the latest transaction where A is
-     converted to B, dated on or before the valuation date.  (_since
-     hledger 1.18; experimental_)
-
-  3. a _reverse declared market price_ - calculated by inverting a
-     declared market price from B to A.
-
-  4. a _reverse transaction-implied market price_ - calculated by
-     inverting a transaction-implied market price from B to A.
-
-  5. an _indirect market price_ - calculated by combining the shortest
-     chain of market prices (any of the above types) leading from A to
-     B.
-
-
-File: hledger.info,  Node: --value Flexible valuation,  Next: Effect of --value on reports,  Prev: Market prices,  Up: Valuation
-
-2.17.5 -value: Flexible valuation
 ---------------------------------
 
-_(experimental, added 201905)_
+'-B', '-V' and '-X' are special cases of the more general '--value'
-
-   '-B', '-V' and '-X' are special cases of the more general '--value'
 option:
 
  --value=TYPE[,COMM]  TYPE is cost, then, end, now or YYYY-MM-DD.
@@ -1504,51 +1597,43 @@ option:
                       - default valuation commodity (or COMM) using current market prices
                       - default valuation commodity (or COMM) using market prices at some date
 
-   The TYPE part basically selects either "cost", or "market value" plus
+   The TYPE part selects cost or value and valuation date:
-a valuation date:
 
 '--value=cost'
 
      Convert amounts to cost, using the prices recorded in transactions.
 '--value=then'
 
-     Convert amounts to their value in a default valuation commodity,
+     Convert amounts to their value in the default valuation commodity,
      using market prices on each posting's date.  This is currently
      supported only by the print and register commands.
 '--value=end'
 
-     Convert amounts to their value in a default valuation commodity,
+     Convert amounts to their value in the default valuation commodity,
      using market prices on the last day of the report period (or if
      unspecified, the journal's end date); or in multiperiod reports,
      market prices on the last day of each subperiod.
 '--value=now'
 
-     Convert amounts to their value in default valuation commodity using
+     Convert amounts to their value in the default valuation commodity
-     current market prices (as of when report is generated).
+     using current market prices (as of when report is generated).
 '--value=YYYY-MM-DD'
 
-     Convert amounts to their value in default valuation commodity using
+     Convert amounts to their value in the default valuation commodity
-     market prices on this date.
+     using market prices on this date.
-
-   The default valuation commodity is the commodity mentioned in the
-most recent applicable market price declaration.  When all your price
-declarations lead to a single home currency, this will usually do what
-you want.
 
    To select a different valuation commodity, add the optional ',COMM'
 part: a comma, then the target commodity's symbol.  Eg:
 *'--value=now,EUR'*.  hledger will do its best to convert amounts to
-this commodity, using:
+this commodity, deducing market prices as described above.
 
-   * declared prices (from source commodity to valuation commodity)
+
-   * reverse prices (declared prices from valuation to source commodity,
+File: hledger.info,  Node: More valuation examples,  Next: Effect of valuation on reports,  Prev: --value Flexible valuation,  Up: Valuation
-     inverted)
-   * indirect prices (prices calculated from the shortest chain of
-     declared or reverse prices from source to valuation commodity)
 
-   in that order.
+2.17.10 More valuation examples
+-------------------------------
 
-   Here are some examples showing the effect of '--value' as seen with
+Here are some examples showing the effect of '--value', as seen with
 'print':
 
 P 2000-01-01 A  1 B
@@ -1657,16 +1742,16 @@ $ hledger print -X A
     b          -0.50A
 
 
-File: hledger.info,  Node: Effect of --value on reports,  Prev: --value Flexible valuation,  Up: Valuation
+File: hledger.info,  Node: Effect of valuation on reports,  Prev: More valuation examples,  Up: Valuation
 
-2.17.6 Effect of -value on reports
+2.17.11 Effect of valuation on reports
-----------------------------------
+--------------------------------------
 
-Here is a reference for how '--value' currently affects each part of
+Here is a reference for how valuation is supposed to affect each part of
-hledger's reports.  It's work in progress, but may be useful for
+hledger's reports (and a glossary).  (It's wide, you'll have to scroll
-troubleshooting or reporting bugs.  See also the definitions and notes
+sideways.)  It may be useful when troubleshooting.  If you find
-below.  If you find problems, please report them, ideally with a
+problems, please report them, ideally with a reproducible example.
-reproducible example.  Related: #329, #1083.
+Related: #329, #1083.
 
 Report       '-B',        '-V', '-X'   '--value=then' '--value=end' '--value=DATE',
 type         '--value=cost'                                         '--value=now'
@@ -1739,7 +1824,7 @@ total/averageof column    of column    supported      of column     of
              totals       totals                      totals        column
                                                                     totals
 
-   *Additional notes*
+   *Glossary:*
 
 _cost_
 
@@ -3798,165 +3883,175 @@ Node: OPTIONS16853
 Ref: #options16960
 Node: General options17330
 Ref: #general-options17455
-Node: Command options20225
+Node: Command options20409
-Ref: #command-options20376
+Ref: #command-options20560
-Node: Command arguments20774
+Node: Command arguments20958
-Ref: #command-arguments20921
+Ref: #command-arguments21105
-Node: Queries21801
+Node: Queries21985
-Ref: #queries21956
+Ref: #queries22140
-Node: Special characters in arguments and queries25918
+Node: Special characters in arguments and queries26102
-Ref: #special-characters-in-arguments-and-queries26146
+Ref: #special-characters-in-arguments-and-queries26330
-Node: More escaping26597
+Node: More escaping26781
-Ref: #more-escaping26759
+Ref: #more-escaping26943
-Node: Even more escaping27055
+Node: Even more escaping27239
-Ref: #even-more-escaping27249
+Ref: #even-more-escaping27433
-Node: Less escaping27920
+Node: Less escaping28104
-Ref: #less-escaping28082
+Ref: #less-escaping28266
-Node: Unicode characters28327
+Node: Unicode characters28511
-Ref: #unicode-characters28509
+Ref: #unicode-characters28693
-Node: Input files29921
+Node: Input files30105
-Ref: #input-files30064
+Ref: #input-files30248
-Node: Output destination31993
+Node: Output destination32177
-Ref: #output-destination32145
+Ref: #output-destination32329
-Node: Output format32570
+Node: Output format32754
-Ref: #output-format32720
+Ref: #output-format32904
-Node: Regular expressions34302
+Node: Regular expressions34486
-Ref: #regular-expressions34459
+Ref: #regular-expressions34643
-Node: Smart dates36195
+Node: Smart dates36379
-Ref: #smart-dates36346
+Ref: #smart-dates36530
-Node: Report start & end date37707
+Node: Report start & end date37891
-Ref: #report-start-end-date37879
+Ref: #report-start-end-date38063
-Node: Report intervals39376
+Node: Report intervals39560
-Ref: #report-intervals39541
+Ref: #report-intervals39725
-Node: Period expressions39931
+Node: Period expressions40115
-Ref: #period-expressions40091
+Ref: #period-expressions40275
-Node: Depth limiting44227
+Node: Depth limiting44411
-Ref: #depth-limiting44371
+Ref: #depth-limiting44555
-Node: Pivoting44703
+Node: Pivoting44887
-Ref: #pivoting44826
+Ref: #pivoting45010
-Node: Valuation46502
+Node: Valuation46686
-Ref: #valuation46604
+Ref: #valuation46788
-Node: -B Cost47524
+Node: -B Cost47588
-Ref: #b-cost47628
+Ref: #b-cost47692
-Node: -V Value47800
+Node: -V Value47825
-Ref: #v-value47953
+Ref: #v-value47971
-Node: -X Market value in specified commodity49226
+Node: -X Value in specified commodity48173
-Ref: #x-market-value-in-specified-commodity49445
+Ref: #x-value-in-specified-commodity48372
-Node: Market prices49623
+Node: Valuation date48476
-Ref: #market-prices49808
+Ref: #valuation-date48644
-Node: --value Flexible valuation50733
+Node: Market prices48888
-Ref: #value-flexible-valuation50934
+Ref: #market-prices49068
-Node: Effect of --value on reports55439
+Node: --infer-value market prices from transactions49845
-Ref: #effect-of---value-on-reports55620
+Ref: #infer-value-market-prices-from-transactions50094
-Node: COMMANDS61166
+Node: Valuation commodity51385
-Ref: #commands61274
+Ref: #valuation-commodity51594
-Node: accounts62358
+Node: Simple valuation examples52919
-Ref: #accounts62456
+Ref: #simple-valuation-examples53121
-Node: activity63155
+Node: --value Flexible valuation53780
-Ref: #activity63265
+Ref: #value-flexible-valuation53988
-Node: add63648
+Node: More valuation examples55935
-Ref: #add63747
+Ref: #more-valuation-examples56144
-Node: balance66486
+Node: Effect of valuation on reports58149
-Ref: #balance66597
+Ref: #effect-of-valuation-on-reports58337
-Node: Classic balance report68055
+Node: COMMANDS63858
-Ref: #classic-balance-report68228
+Ref: #commands63966
-Node: Customising the classic balance report69597
+Node: accounts65050
-Ref: #customising-the-classic-balance-report69825
+Ref: #accounts65148
-Node: Colour support71901
+Node: activity65847
-Ref: #colour-support72068
+Ref: #activity65957
-Node: Flat mode72241
+Node: add66340
-Ref: #flat-mode72389
+Ref: #add66439
-Node: Depth limited balance reports72802
+Node: balance69178
-Ref: #depth-limited-balance-reports72987
+Ref: #balance69289
-Node: Percentages73443
+Node: Classic balance report70747
-Ref: #percentages73609
+Ref: #classic-balance-report70920
-Node: Multicolumn balance report74746
+Node: Customising the classic balance report72289
-Ref: #multicolumn-balance-report74926
+Ref: #customising-the-classic-balance-report72517
-Node: Budget report80188
+Node: Colour support74593
-Ref: #budget-report80331
+Ref: #colour-support74760
-Node: Nested budgets85597
+Node: Flat mode74933
-Ref: #nested-budgets85709
+Ref: #flat-mode75081
-Ref: #output-format-189190
+Node: Depth limited balance reports75494
-Node: balancesheet89387
+Ref: #depth-limited-balance-reports75679
-Ref: #balancesheet89523
+Node: Percentages76135
-Node: balancesheetequity90989
+Ref: #percentages76301
-Ref: #balancesheetequity91138
+Node: Multicolumn balance report77438
-Node: cashflow91861
+Ref: #multicolumn-balance-report77618
-Ref: #cashflow91989
+Node: Budget report82880
-Node: check-dates93168
+Ref: #budget-report83023
-Ref: #check-dates93295
+Node: Nested budgets88289
-Node: check-dupes93574
+Ref: #nested-budgets88401
-Ref: #check-dupes93698
+Ref: #output-format-191882
-Node: close93991
+Node: balancesheet92079
-Ref: #close94105
+Ref: #balancesheet92215
-Node: close usage95627
+Node: balancesheetequity93681
-Ref: #close-usage95720
+Ref: #balancesheetequity93830
-Node: commodities98533
+Node: cashflow94553
-Ref: #commodities98660
+Ref: #cashflow94681
-Node: descriptions98742
+Node: check-dates95860
-Ref: #descriptions98870
+Ref: #check-dates95987
-Node: diff99051
+Node: check-dupes96266
-Ref: #diff99157
+Ref: #check-dupes96390
-Node: files100204
+Node: close96683
-Ref: #files100304
+Ref: #close96797
-Node: help100451
+Node: close usage98319
-Ref: #help100551
+Ref: #close-usage98412
-Node: import101632
+Node: commodities101225
-Ref: #import101746
+Ref: #commodities101352
-Node: Importing balance assignments102639
+Node: descriptions101434
-Ref: #importing-balance-assignments102787
+Ref: #descriptions101562
-Node: incomestatement103436
+Node: diff101743
-Ref: #incomestatement103569
+Ref: #diff101849
-Node: notes105056
+Node: files102896
-Ref: #notes105169
+Ref: #files102996
-Node: payees105295
+Node: help103143
-Ref: #payees105401
+Ref: #help103243
-Node: prices105559
+Node: import104324
-Ref: #prices105665
+Ref: #import104438
-Node: print106006
+Node: Importing balance assignments105331
-Ref: #print106116
+Ref: #importing-balance-assignments105479
-Node: print-unique110902
+Node: incomestatement106128
-Ref: #print-unique111028
+Ref: #incomestatement106261
-Node: register111313
+Node: notes107748
-Ref: #register111440
+Ref: #notes107861
-Node: Custom register output115612
+Node: payees107987
-Ref: #custom-register-output115741
+Ref: #payees108093
-Node: register-match117078
+Node: prices108251
-Ref: #register-match117212
+Ref: #prices108357
-Node: rewrite117563
+Node: print108698
-Ref: #rewrite117678
+Ref: #print108808
-Node: Re-write rules in a file119533
+Node: print-unique113594
-Ref: #re-write-rules-in-a-file119667
+Ref: #print-unique113720
-Node: Diff output format120877
+Node: register114005
-Ref: #diff-output-format121046
+Ref: #register114132
-Node: rewrite vs print --auto122138
+Node: Custom register output118304
-Ref: #rewrite-vs.-print---auto122317
+Ref: #custom-register-output118433
-Node: roi122873
+Node: register-match119770
-Ref: #roi122971
+Ref: #register-match119904
-Node: stats123983
+Node: rewrite120255
-Ref: #stats124082
+Ref: #rewrite120370
-Node: tags124870
+Node: Re-write rules in a file122225
-Ref: #tags124968
+Ref: #re-write-rules-in-a-file122359
-Node: test125262
+Node: Diff output format123569
-Ref: #test125370
+Ref: #diff-output-format123738
-Node: Add-on commands126117
+Node: rewrite vs print --auto124830
-Ref: #add-on-commands126234
+Ref: #rewrite-vs.-print---auto125009
-Node: ui127577
+Node: roi125565
-Ref: #ui127665
+Ref: #roi125663
-Node: web127719
+Node: stats126675
-Ref: #web127822
+Ref: #stats126774
-Node: iadd127938
+Node: tags127562
-Ref: #iadd128049
+Ref: #tags127660
-Node: interest128131
+Node: test127954
-Ref: #interest128238
+Ref: #test128062
-Node: ENVIRONMENT128478
+Node: Add-on commands128809
-Ref: #environment128590
+Ref: #add-on-commands128926
-Node: FILES129419
+Node: ui130269
-Ref: #files-1129522
+Ref: #ui130357
-Node: LIMITATIONS129735
+Node: web130411
-Ref: #limitations129854
+Ref: #web130514
-Node: TROUBLESHOOTING130596
+Node: iadd130630
-Ref: #troubleshooting130709
+Ref: #iadd130741
+Node: interest130823
+Ref: #interest130930
+Node: ENVIRONMENT131170
+Ref: #environment131282
+Node: FILES132111
+Ref: #files-1132214
+Node: LIMITATIONS132427
+Ref: #limitations132546
+Node: TROUBLESHOOTING133288
+Ref: #troubleshooting133401
 
 End Tag Table