doc: update generated docs

hledger-lib/doc/hledger_journal.5

@@ -464,18 +464,17 @@ the calculations yourself, instead of just reading it.
 .SS Prices
 .SS Transaction prices
 .PP
-When recording a transaction, you can also record an amount\[aq]s price
+Within a transaction posting, you can record an amount\[aq]s price in
-in another commodity.
+another commodity.
-This documents the exchange rate, cost (of a purchase), or selling price
+This can be used to document the cost (for a purchase), or selling price
-(of a sale) that was in effect within this particular transaction (or
+(for a sale), or the exchange rate that was used, for this transaction.
-more precisely, within the particular posting).
+These transaction prices are fixed, and do not change over time.
-These transaction prices are fixed, and do not change.
 .PP
-Such priced amounts can be displayed in their transaction price\[aq]s
+Amounts with transaction prices can be displayed in the transaction
-commodity, by using the \f[C]\-\-cost/\-B\f[] flag (B for "cost Basis"),
+price\[aq]s commodity, by using the \f[C]\-\-cost/\-B\f[] flag supported
-supported by most hledger commands.
+by most hledger commands (mnemonic: "cost Basis").
 .PP
-There are three ways to specify a transaction price:
+There are several ways to record a transaction price:
 .IP "1." 3
 Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[]
 after the amount:
@@ -532,27 +531,31 @@ rate of purchases made in a foreign currency.
 .SS Market prices
 .PP
 Market prices are not tied to a particular transaction; they represent
-historical exchange rates between two commodities, usually from some
+historical exchange rates between two commodities.
-public market which publishes such rates.
+(Ledger calls them historical prices.) For example, the prices published
+by a stock exchange or the foreign exchange market.
+Some commands (balance, currently) can use this information to show the
+market value of things at a given date.
 .PP
-When market prices are known, the \f[C]\-V/\-\-value\f[] option will use
+To record market prices, use P directives in the main journal or in an
-them to convert reported amounts to their market value as of the report
+included file.
-end date.
+Their format is:
-This option is currently available only with the balance command.
-.PP
-You record market prices (Ledger calls them historical prices) with a P
-directive, in the journal or perhaps in a separate included file.
-Market price directives have the format:
 .IP
 .nf
 \f[C]
-P\ DATE\ COMMODITYSYMBOL\ UNITPRICE
+P\ DATE\ COMMODITYBEINGPRICED\ UNITPRICE
 \f[]
 .fi
 .PP
-For example, the following directives say that the euro\[aq]s exchange
+DATE is a simple date as usual.
-rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
+COMMODITYBEINGPRICED is the symbol of the commodity being priced (just
-unknown before 2009).
+the symbol, no quantity).
+UNITPRICE is an ordinary amount (symbol and quantity) in a second
+commodity, specifying the unit price or conversion rate for the first
+commodity in terms of the second, on the given date.
+.PP
+For example, the following directives say that one euro was worth 1.35
+US dollars during 2009, and $1.40 from 2010 onward:
 .IP
 .nf
 \f[C]
@@ -560,8 +563,6 @@ P\ 2009/1/1\ €\ $1.35
 P\ 2010/1/1\ €\ $1.40
 \f[]
 .fi
-.PP
-Example use for market prices: tracking the value of stocks.
 .SS Comments
 .PP
 Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash

hledger-lib/doc/hledger_journal.5.info

@@ -494,17 +494,17 @@ File: hledger_journal.5.info,  Node: Transaction prices,  Next: Market prices,
 1.8.1 Transaction prices
 ------------------------
 
-When recording a transaction, you can also record an amount's price in
+Within a transaction posting, you can record an amount's price in
-another commodity. This documents the exchange rate, cost (of a
+another commodity. This can be used to document the cost (for a
-purchase), or selling price (of a sale) that was in effect within this
+purchase), or selling price (for a sale), or the exchange rate that was
-particular transaction (or more precisely, within the particular
+used, for this transaction. These transaction prices are fixed, and do
-posting). These transaction prices are fixed, and do not change.
+not change over time.
 
-   Such priced amounts can be displayed in their transaction price's
+   Amounts with transaction prices can be displayed in the transaction
-commodity, by using the `--cost/-B' flag (B for "cost Basis"),
+price's commodity, by using the `--cost/-B' flag supported by most
-supported by most hledger commands.
+hledger commands (mnemonic: "cost Basis").
 
-   There are three ways to specify a transaction price:
+   There are several ways to record a transaction price:
 
   1. Write the unit price (aka exchange rate), as `@ UNITPRICE' after
      the amount:
@@ -549,30 +549,31 @@ File: hledger_journal.5.info,  Node: Market prices,  Prev: Transaction prices,
 -------------------
 
 Market prices are not tied to a particular transaction; they represent
-historical exchange rates between two commodities, usually from some
+historical exchange rates between two commodities. (Ledger calls them
-public market which publishes such rates.
+historical prices.) For example, the prices published by a stock
+exchange or the foreign exchange market. Some commands (balance,
+currently) can use this information to show the market value of things
+at a given date.
 
-   When market prices are known, the `-V/--value' option will use them
+   To record market prices, use P directives in the main journal or in
-to convert reported amounts to their market value as of the report end
+an included file. Their format is:
-date. This option is currently available only with the balance command.
-
-   You record market prices (Ledger calls them historical prices) with
-a P directive, in the journal or perhaps in a separate included file.
-Market price directives have the format:
 
 
-P DATE COMMODITYSYMBOL UNITPRICE
+P DATE COMMODITYBEINGPRICED UNITPRICE
 
-   For example, the following directives say that the euro's exchange
+   DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of
-rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
+the commodity being priced (just the symbol, no quantity). UNITPRICE is
-unknown before 2009).
+an ordinary amount (symbol and quantity) in a second commodity,
+specifying the unit price or conversion rate for the first commodity in
+terms of the second, on the given date.
+
+   For example, the following directives say that one euro was worth
+1.35 US dollars during 2009, and $1.40 from 2010 onward:
 
 
 P 2009/1/1 € $1.35
 P 2010/1/1 € $1.40
 
-   Example use for market prices: tracking the value of stocks.
-
 
 File: hledger_journal.5.info,  Node: Comments,  Next: Tags,  Prev: Prices,  Up: FILE FORMAT
 
@@ -997,39 +998,39 @@ Node: Prices17327
 Ref: #prices17460
 Node: Transaction prices17511
 Ref: #transaction-prices17656
-Node: Market prices19263
+Node: Market prices19236
-Ref: #market-prices19398
+Ref: #market-prices19371
-Node: Comments20286
+Node: Comments20371
-Ref: #comments20408
+Ref: #comments20493
-Node: Tags21520
+Node: Tags21605
-Ref: #tags21640
+Ref: #tags21725
-Node: Directives22563
+Node: Directives22648
-Ref: #directives22678
+Ref: #directives22763
-Node: Account aliases22871
+Node: Account aliases22956
-Ref: #account-aliases23017
+Ref: #account-aliases23102
-Node: Basic aliases23619
+Node: Basic aliases23704
-Ref: #basic-aliases23764
+Ref: #basic-aliases23849
-Node: Regex aliases24452
+Node: Regex aliases24537
-Ref: #regex-aliases24622
+Ref: #regex-aliases24707
-Node: Multiple aliases25392
+Node: Multiple aliases25477
-Ref: #multiple-aliases25566
+Ref: #multiple-aliases25651
-Node: end aliases26062
+Node: end aliases26147
-Ref: #end-aliases26204
+Ref: #end-aliases26289
-Node: account directive26306
+Node: account directive26391
-Ref: #account-directive26488
+Ref: #account-directive26573
-Node: apply account directive26784
+Node: apply account directive26869
-Ref: #apply-account-directive26982
+Ref: #apply-account-directive27067
-Node: Multi-line comments27642
+Node: Multi-line comments27727
-Ref: #multi-line-comments27834
+Ref: #multi-line-comments27919
-Node: commodity directive27961
+Node: commodity directive28046
-Ref: #commodity-directive28147
+Ref: #commodity-directive28232
-Node: Default commodity29020
+Node: Default commodity29105
-Ref: #default-commodity29195
+Ref: #default-commodity29280
-Node: Default year29731
+Node: Default year29816
-Ref: #default-year29898
+Ref: #default-year29983
-Node: Including other files30321
+Node: Including other files30406
-Ref: #including-other-files30480
+Ref: #including-other-files30565
-Node: EDITOR SUPPORT30876
+Node: EDITOR SUPPORT30961
-Ref: #editor-support30996
+Ref: #editor-support31081
 
 End Tag Table

hledger-lib/doc/hledger_journal.5.txt

@@ -359,17 +359,17 @@ FILE FORMAT
 
    Prices
    Transaction prices
-       When recording a transaction, you can also record an amount's price  in
+       Within a transaction posting, you  can  record  an  amount's  price  in
-       another  commodity.   This documents the exchange rate, cost (of a pur-
+       another  commodity.   This can be used to document the cost (for a pur-
-       chase), or selling price (of a sale) that was  in  effect  within  this
+       chase), or selling price (for a sale), or the exchange  rate  that  was
-       particular  transaction (or more precisely, within the particular post-
+       used, for this transaction.  These transaction prices are fixed, and do
-       ing).  These transaction prices are fixed, and do not change.
+       not change over time.
 
-       Such priced amounts can be displayed in their transaction price's  com-
+       Amounts with transaction prices can be  displayed  in  the  transaction
-       modity,  by using the --cost/-B flag (B for "cost Basis"), supported by
+       price's  commodity,  by  using  the  --cost/-B  flag  supported by most
-       most hledger commands.
+       hledger commands (mnemonic: "cost Basis").
 
-       There are three ways to specify a transaction price:
+       There are several ways to record a transaction price:
 
        1. Write the unit price (aka exchange rate), as @ UNITPRICE  after  the
           amount:
@@ -404,29 +404,29 @@ FILE FORMAT
 
    Market prices
        Market prices are not tied to a particular transaction; they  represent
-       historical  exchange  rates  between two commodities, usually from some
+       historical  exchange rates between two commodities.  (Ledger calls them
-       public market which publishes such rates.
+       historical prices.) For  example,  the  prices  published  by  a  stock
+       exchange  or the foreign exchange market.  Some commands (balance, cur-
+       rently) can use this information to show the market value of things  at
+       a given date.
 
-       When market prices are known, the -V/--value option will  use  them  to
+       To  record market prices, use P directives in the main journal or in an
-       convert  reported  amounts  to  their market value as of the report end
+       included file.  Their format is:
-       date.  This option is currently available only with  the  balance  com-
-       mand.
 
-       You record market prices (Ledger calls them historical prices) with a P
+              P DATE COMMODITYBEINGPRICED UNITPRICE
-       directive, in the journal or perhaps in a separate included file.  Mar-
-       ket price directives have the format:
 
-              P DATE COMMODITYSYMBOL UNITPRICE
+       DATE is a simple date as usual.  COMMODITYBEINGPRICED is the symbol  of
+       the  commodity  being priced (just the symbol, no quantity).  UNITPRICE
+       is an ordinary amount (symbol and  quantity)  in  a  second  commodity,
+       specifying the unit price or conversion rate for the first commodity in
+       terms of the second, on the given date.
 
-       For example, the following directives say that the euro's exchange rate
+       For example, the following directives say that one euro was worth  1.35
-       was 1.35 US dollars during  2009,  and  $1.40  from  2010  onward  (and
+       US dollars during 2009, and $1.40 from 2010 onward:
-       unknown before 2009).
 
               P 2009/1/1  $1.35
               P 2010/1/1  $1.40
 
-       Example use for market prices: tracking the value of stocks.
-
    Comments
        Lines  in  the  journal  beginning  with a semicolon (;) or hash (#) or
        asterisk (*) are comments, and will  be  ignored.   (Asterisk  comments

hledger-ui/doc/hledger-ui.1

@@ -203,7 +203,8 @@ show items with zero amount, normally hidden
 .RE
 .TP
 .B \f[C]\-B\ \-\-cost\f[]
-show amounts in their cost price\[aq]s commodity
+convert amounts to their cost at transaction time (using the transaction
+price, if any)
 .RS
 .RE
 .TP
@@ -211,8 +212,6 @@ show amounts in their cost price\[aq]s commodity
 will transform the journal before any other processing by replacing the
 account name of every posting having the tag TAG with content VALUE by
 the account name "TAG:VALUE".
-.RS
-.RE
 The TAG will only match if it is a full\-length match.
 The pivot will only happen if the TAG is on a posting, not if it is on
 the transaction.

hledger-ui/doc/hledger-ui.1.info

@@ -139,16 +139,17 @@ the data.
      show items with zero amount, normally hidden
 
 `-B --cost'
-     show amounts in their cost price's commodity
+     convert amounts to their cost at transaction time (using the
+     transaction price, if any)
 
 `--pivot TAG'
      will transform the journal before any other processing by
      replacing the account name of every posting having the tag TAG
-     with content VALUE by the account name "TAG:VALUE".  The TAG will
+     with content VALUE by the account name "TAG:VALUE". The TAG will
      only match if it is a full-length match. The pivot will only
-     happen if the TAG is on a posting, not if it is on the transaction.
+     happen if the TAG is on a posting, not if it is on the
-     If the tag value is a multi:level:account:name the new account
+     transaction. If the tag value is a multi:level:account:name the
-     name will be "TAG:multi:level:account:name".
+     new account name will be "TAG:multi:level:account:name".
 
 `--anon'
      show anonymized accounts and payees
@@ -360,17 +361,17 @@ Tag Table:
 Node: Top88
 Node: OPTIONS823
 Ref: #options922
-Node: KEYS3956
+Node: KEYS4003
-Ref: #keys4053
+Ref: #keys4100
-Node: SCREENS6623
+Node: SCREENS6670
-Ref: #screens6710
+Ref: #screens6757
-Node: Accounts screen6800
+Node: Accounts screen6847
-Ref: #accounts-screen6930
+Ref: #accounts-screen6977
-Node: Register screen8968
+Node: Register screen9015
-Ref: #register-screen9125
+Ref: #register-screen9172
-Node: Transaction screen11013
+Node: Transaction screen11060
-Ref: #transaction-screen11173
+Ref: #transaction-screen11220
-Node: Error screen12040
+Node: Error screen12087
-Ref: #error-screen12164
+Ref: #error-screen12211
 
 End Tag Table

hledger-ui/doc/hledger-ui.1.txt

@@ -133,16 +133,17 @@ OPTIONS
               show items with zero amount, normally hidden
 
        -B --cost
-              show amounts in their cost price's commodity
+              convert  amounts  to  their  cost at transaction time (using the
+              transaction price, if any)
 
        --pivot TAG
-              will  transform  the  journal  before  any  other  processing by
+              will transform  the  journal  before  any  other  processing  by
-              replacing the account name of every posting having the  tag  TAG
+              replacing  the  account name of every posting having the tag TAG
-              with content VALUE by the account name "TAG:VALUE".
+              with content VALUE by the account  name  "TAG:VALUE".   The  TAG
-       The  TAG  will only match if it is a full-length match.  The pivot will
+              will  only  match  if it is a full-length match.  The pivot will
-       only happen if the TAG is on a posting, not if it is  on  the  transac-
+              only happen if the TAG is on a posting, not  if  it  is  on  the
-       tion.   If  the tag value is a multi:level:account:name the new account
+              transaction.  If the tag value is a multi:level:account:name the
-       name will be "TAG:multi:level:account:name".
+              new account name will be "TAG:multi:level:account:name".
 
        --anon show anonymized accounts and payees
 

hledger-web/doc/hledger-web.1

@@ -261,7 +261,8 @@ show items with zero amount, normally hidden
 .RE
 .TP
 .B \f[C]\-B\ \-\-cost\f[]
-show amounts in their cost price\[aq]s commodity
+convert amounts to their cost at transaction time (using the transaction
+price, if any)
 .RS
 .RE
 .TP
@@ -269,8 +270,6 @@ show amounts in their cost price\[aq]s commodity
 will transform the journal before any other processing by replacing the
 account name of every posting having the tag TAG with content VALUE by
 the account name "TAG:VALUE".
-.RS
-.RE
 The TAG will only match if it is a full\-length match.
 The pivot will only happen if the TAG is on a posting, not if it is on
 the transaction.

hledger-web/doc/hledger-web.1.info

@@ -185,16 +185,17 @@ before options as shown above.
      show items with zero amount, normally hidden
 
 `-B --cost'
-     show amounts in their cost price's commodity
+     convert amounts to their cost at transaction time (using the
+     transaction price, if any)
 
 `--pivot TAG'
      will transform the journal before any other processing by
      replacing the account name of every posting having the tag TAG
-     with content VALUE by the account name "TAG:VALUE".  The TAG will
+     with content VALUE by the account name "TAG:VALUE". The TAG will
      only match if it is a full-length match. The pivot will only
-     happen if the TAG is on a posting, not if it is on the transaction.
+     happen if the TAG is on a posting, not if it is on the
-     If the tag value is a multi:level:account:name the new account
+     transaction. If the tag value is a multi:level:account:name the
-     name will be "TAG:multi:level:account:name".
+     new account name will be "TAG:multi:level:account:name".
 
 `--anon'
      show anonymized accounts and payees

hledger-web/doc/hledger-web.1.txt

@@ -181,16 +181,17 @@ OPTIONS
               show items with zero amount, normally hidden
 
        -B --cost
-              show amounts in their cost price's commodity
+              convert amounts to their cost at  transaction  time  (using  the
+              transaction price, if any)
 
        --pivot TAG
-              will transform  the  journal  before  any  other  processing  by
+              will  transform  the  journal  before  any  other  processing by
-              replacing  the  account name of every posting having the tag TAG
+              replacing the account name of every posting having the  tag  TAG
-              with content VALUE by the account name "TAG:VALUE".
+              with  content  VALUE  by  the account name "TAG:VALUE".  The TAG
-       The TAG will only match if it is a full-length match.  The  pivot  will
+              will only match if it is a full-length match.   The  pivot  will
-       only  happen  if  the TAG is on a posting, not if it is on the transac-
+              only  happen  if  the  TAG  is on a posting, not if it is on the
-       tion.  If the tag value is a multi:level:account:name the  new  account
+              transaction.  If the tag value is a multi:level:account:name the
-       name will be "TAG:multi:level:account:name".
+              new account name will be "TAG:multi:level:account:name".
 
        --anon show anonymized accounts and payees
 

hledger/doc/hledger.1

@@ -373,7 +373,8 @@ show items with zero amount, normally hidden
 .RE
 .TP
 .B \f[C]\-B\ \-\-cost\f[]
-show amounts in their cost price\[aq]s commodity
+convert amounts to their cost at transaction time (using the transaction
+price, if any)
 .RS
 .RE
 .TP
@@ -381,8 +382,6 @@ show amounts in their cost price\[aq]s commodity
 will transform the journal before any other processing by replacing the
 account name of every posting having the tag TAG with content VALUE by
 the account name "TAG:VALUE".
-.RS
-.RE
 The TAG will only match if it is a full\-length match.
 The pivot will only happen if the TAG is on a posting, not if it is on
 the transaction.
@@ -558,6 +557,68 @@ T{
 T}@T{
 T}
 .TE
+.SS Report start & end date
+.PP
+Most hledger reports show the full span of time represented by the
+journal data, by default.
+So, the effective report start and end dates will be the earliest and
+latest transaction or posting dates found in the journal.
+.PP
+Often you will want to see a shorter time span, such as the current
+month.
+You can specify a start and/or end date using \f[C]\-b/\-\-begin\f[],
+\f[C]\-e/\-\-end\f[], \f[C]\-p/\-\-period\f[] or a \f[C]date:\f[] query
+(described below).
+All of these accept the smart date syntax.
+One important thing to be aware of when specifying end dates: as in
+Ledger, end dates are exclusive, so you need to write the date
+\f[I]after\f[] the last day you want to include.
+.PP
+Examples:
+.PP
+.TS
+tab(@);
+l l.
+T{
+\f[C]\-b\ 2016/3/17\f[]
+T}@T{
+begin on St.
+Patrick\[aq]s day 2016
+T}
+T{
+\f[C]\-e\ 12/1\f[]
+T}@T{
+end at the start of december 1st of the current year (11/30 will be the
+last date included)
+T}
+T{
+\f[C]\-b\ thismonth\f[]
+T}@T{
+all transactions on or after the 1st of the current month
+T}
+T{
+\f[C]\-p\ thismonth\f[]
+T}@T{
+all transactions in the current month
+T}
+T{
+\f[C]date:2016/3/17\-\f[]
+T}@T{
+the above written as queries instead
+T}
+T{
+\f[C]date:\-12/1\f[]
+T}@T{
+T}
+T{
+\f[C]date:thismonth\-\f[]
+T}@T{
+T}
+T{
+\f[C]date:thismonth\f[]
+T}@T{
+T}
+.TE
 .SS Report intervals
 .PP
 A report interval can be specified so that commands like register,
@@ -566,6 +627,7 @@ The basic intervals can be selected with one of \f[C]\-D/\-\-daily\f[],
 \f[C]\-W/\-\-weekly\f[], \f[C]\-M/\-\-monthly\f[],
 \f[C]\-Q/\-\-quarterly\f[], or \f[C]\-Y/\-\-yearly\f[].
 More complex intervals may be specified with a period expression.
+Report intervals can not be specified with a query, currently.
 .SS Period expressions
 .PP
 The \f[C]\-p/\-\-period\f[] option accepts period expressions, a
@@ -1125,8 +1187,8 @@ is depth\-clipped (default in multicolumn reports)
 .RE
 .TP
 .B \f[C]\-V\ \-\-value\f[]
-convert amounts to current market value in their default valuation
+convert amounts to their market value on the report end date (using the
-commodity
+most recent applicable market price, if any)
 .RS
 .RE
 .TP
@@ -1380,15 +1442,64 @@ Balance\ changes\ in\ 2008:
 .fi
 .SS Market value
 .PP
-The \f[C]\-V/\-\-value\f[] flag converts all the reported amounts to
+The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their
-their "current market value" using their default market price.
+market value on the report end date, using the most recent applicable
-That is the latest market price (P directive) found in the journal (or
+market prices, when known.
-an included file), for the amount\[aq]s commodity, dated on or before
+Specifically, when there is a market price (P directive) for the
-the report end date.
+amount\[aq]s commodity, dated on or before the report end date (see
+hledger \-> Report start & end date), the amount will be converted to
+the price\[aq]s commodity.
+If multiple applicable prices are defined, the latest\-dated one is used
+(and if dates are equal, the one last parsed).
+.PP
+For example:
+.IP
+.nf
+\f[C]
+#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1
+P\ 2016/11/01\ €\ $1.10
+
+#\ purchase\ some\ euros\ on\ nov\ 3
+2016/11/3
+\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100
+\ \ \ \ assets:checking
+
+#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21
+P\ 2016/12/21\ €\ $1.03
+\f[]
+.fi
+.PP
+How many euros do I have ?
+.IP
+.nf
+\f[C]
+$\ hledger\ \-f\ t.j\ bal\ euros
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
+\f[]
+.fi
+.PP
+What are they worth on nov 3 ?
+(no report end date specified, defaults to the last date in the journal)
+.IP
+.nf
+\f[C]
+$\ hledger\ \-f\ t.j\ bal\ euros\ \-V
+\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros
+\f[]
+.fi
+.PP
+What are they worth on dec 21 ?
+.IP
+.nf
+\f[C]
+$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21
+\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros
+\f[]
+.fi
+.PP
+Currently, hledger\[aq]s \-V only uses market prices recorded with P
+directives, not transaction prices (unlike Ledger).
 .PP
-Unlike Ledger, hledger\[aq]s \-V only uses the market prices recorded
-with P directives, ignoring transaction prices recorded as part of
-posting amounts (which \-B/\-\-cost uses).
 Using \-B and \-V together is allowed.
 .SS Custom balance output
 .PP

hledger/doc/hledger.1.info

@@ -202,6 +202,7 @@ cur:\\\\$'.
 * Input files::
 * Depth limiting::
 * Smart dates::
+* Report start & end date::
 * Report intervals::
 * Period expressions::
 * Regular expressions::
@@ -300,16 +301,17 @@ Common reporting options, must be written after COMMAND.
      show items with zero amount, normally hidden
 
 `-B --cost'
-     show amounts in their cost price's commodity
+     convert amounts to their cost at transaction time (using the
+     transaction price, if any)
 
 `--pivot TAG'
      will transform the journal before any other processing by
      replacing the account name of every posting having the tag TAG
-     with content VALUE by the account name "TAG:VALUE".  The TAG will
+     with content VALUE by the account name "TAG:VALUE". The TAG will
      only match if it is a full-length match. The pivot will only
-     happen if the TAG is on a posting, not if it is on the transaction.
+     happen if the TAG is on a posting, not if it is on the
-     If the tag value is a multi:level:account:name the new account
+     transaction. If the tag value is a multi:level:account:name the
-     name will be "TAG:multi:level:account:name".
+     new account name will be "TAG:multi:level:account:name".
 
 `--anon'
      show anonymized accounts and payees
@@ -381,7 +383,7 @@ register will show only the uppermost accounts in the account tree, down
 to level N. Use this when you want a summary with less detail.
 
 
-File: hledger.1.info,  Node: Smart dates,  Next: Report intervals,  Prev: Depth limiting,  Up: OPTIONS
+File: hledger.1.info,  Node: Smart dates,  Next: Report start & end date,  Prev: Depth limiting,  Up: OPTIONS
 
 2.5 Smart dates
 ===============
@@ -404,21 +406,51 @@ omitted (defaulting to 1).
 `today', `yesterday', `tomorrow'                   
 
 
-File: hledger.1.info,  Node: Report intervals,  Next: Period expressions,  Prev: Smart dates,  Up: OPTIONS
+File: hledger.1.info,  Node: Report start & end date,  Next: Report intervals,  Prev: Smart dates,  Up: OPTIONS
 
-2.6 Report intervals
+2.6 Report start & end date
+===========================
+
+Most hledger reports show the full span of time represented by the
+journal data, by default. So, the effective report start and end dates
+will be the earliest and latest transaction or posting dates found in
+the journal.
+
+   Often you will want to see a shorter time span, such as the current
+month. You can specify a start and/or end date using `-b/--begin',
+`-e/--end', `-p/--period' or a `date:' query (described below). All of
+these accept the smart date syntax. One important thing to be aware of
+when specifying end dates: as in Ledger, end dates are exclusive, so
+you need to write the date _after_ the last day you want to include.
+
+   Examples:
+
+`-b 2016/3/17'      begin on St. Patrick's day 2016
+`-e 12/1'           end at the start of december 1st of the current year (11/30 will be the last date included)
+`-b thismonth'      all transactions on or after the 1st of the current month
+`-p thismonth'      all transactions in the current month
+`date:2016/3/17-'   the above written as queries instead
+`date:-12/1'        
+`date:thismonth-'   
+`date:thismonth'    
+
+
+File: hledger.1.info,  Node: Report intervals,  Next: Period expressions,  Prev: Report start & end date,  Up: OPTIONS
+
+2.7 Report intervals
 ====================
 
 A report interval can be specified so that commands like register,
 balance and activity will divide their reports into multiple subperiods.
 The basic intervals can be selected with one of `-D/--daily',
 `-W/--weekly', `-M/--monthly', `-Q/--quarterly', or `-Y/--yearly'. More
-complex intervals may be specified with a period expression.
+complex intervals may be specified with a period expression. Report
+intervals can not be specified with a query, currently.
 
 
 File: hledger.1.info,  Node: Period expressions,  Next: Regular expressions,  Prev: Report intervals,  Up: OPTIONS
 
-2.7 Period expressions
+2.8 Period expressions
 ======================
 
 The `-p/--period' option accepts period expressions, a shorthand way of
@@ -493,7 +525,7 @@ start date and exclusive end date):
 
 File: hledger.1.info,  Node: Regular expressions,  Prev: Period expressions,  Up: OPTIONS
 
-2.8 Regular expressions
+2.9 Regular expressions
 =======================
 
 hledger uses regular expressions in a number of places:
@@ -873,8 +905,8 @@ Show accounts and their balances. Alias: bal.
      account is depth-clipped (default in multicolumn reports)
 
 `-V --value'
-     convert amounts to current market value in their default valuation
+     convert amounts to their market value on the report end date
-     commodity
+     (using the most recent applicable market price, if any)
 
 `-A --average'
      show a row average column (in multicolumn mode)
@@ -1101,16 +1133,52 @@ File: hledger.1.info,  Node: Market value,  Next: Custom balance output,  Prev:
 4.4.4 Market value
 ------------------
 
-The `-V/--value' flag converts all the reported amounts to their
+The `-V/--value' flag converts the reported amounts to their market
-"current market value" using their default market price. That is the
+value on the report end date, using the most recent applicable market
-latest market price (P directive) found in the journal (or an included
+prices, when known. Specifically, when there is a market price (P
-file), for the amount's commodity, dated on or before the report end
+directive) for the amount's commodity, dated on or before the report end
-date.
+date (see hledger -> Report start & end date), the amount will be
+converted to the price's commodity. If multiple applicable prices are
+defined, the latest-dated one is used (and if dates are equal, the one
+last parsed).
 
-   Unlike Ledger, hledger's -V only uses the market prices recorded
+   For example:
-with P directives, ignoring transaction prices recorded as part of
+
-posting amounts (which -B/-cost uses). Using -B and -V together is
+
-allowed.
+# one euro is worth this many dollars from nov 1
+P 2016/11/01 € $1.10
+
+# purchase some euros on nov 3
+2016/11/3
+    assets:euros        €100
+    assets:checking
+
+# the euro is worth fewer dollars by dec 21
+P 2016/12/21 € $1.03
+
+   How many euros do I have ?
+
+
+$ hledger -f t.j bal euros
+                €100  assets:euros
+
+   What are they worth on nov 3 ? (no report end date specified,
+defaults to the last date in the journal)
+
+
+$ hledger -f t.j bal euros -V
+             $110.00  assets:euros
+
+   What are they worth on dec 21 ?
+
+
+$ hledger -f t.j bal euros -V -e 2016/12/21
+             $103.00  assets:euros
+
+   Currently, hledger's -V only uses market prices recorded with P
+directives, not transaction prices (unlike Ledger).
+
+   Using -B and -V together is allowed.
 
 
 File: hledger.1.info,  Node: Custom balance output,  Next: Output destination,  Prev: Market value,  Up: balance
@@ -2163,97 +2231,99 @@ Node: EXAMPLES1873
 Ref: #examples1975
 Node: OPTIONS3979
 Ref: #options4083
-Node: General options6683
+Node: General options6711
-Ref: #general-options6812
+Ref: #general-options6840
-Node: Reporting options7583
+Node: Reporting options7611
-Ref: #reporting-options7736
+Ref: #reporting-options7764
-Node: Input files9512
+Node: Input files9587
-Ref: #input-files9652
+Ref: #input-files9727
-Node: Depth limiting11489
+Node: Depth limiting11564
-Ref: #depth-limiting11629
+Ref: #depth-limiting11704
-Node: Smart dates11830
+Node: Smart dates11905
-Ref: #smart-dates11969
+Ref: #smart-dates12051
-Node: Report intervals12966
+Node: Report start & end date13048
-Ref: #report-intervals13119
+Ref: #report-start-end-date13220
-Node: Period expressions13455
+Node: Report intervals14296
-Ref: #period-expressions13620
+Ref: #report-intervals14461
-Node: Regular expressions15955
+Node: Period expressions14860
-Ref: #regular-expressions16097
+Ref: #period-expressions15025
-Node: QUERIES17580
+Node: Regular expressions17360
-Ref: #queries17684
+Ref: #regular-expressions17502
-Node: COMMANDS21323
+Node: QUERIES18985
-Ref: #commands21437
+Ref: #queries19089
-Node: accounts22110
+Node: COMMANDS22728
-Ref: #accounts22210
+Ref: #commands22842
-Node: activity23192
+Node: accounts23515
-Ref: #activity23304
+Ref: #accounts23615
-Node: add23663
+Node: activity24597
-Ref: #add23764
+Ref: #activity24709
-Node: balance26423
+Node: add25068
-Ref: #balance26536
+Ref: #add25169
-Node: Flat mode29509
+Node: balance27828
-Ref: #flat-mode29636
+Ref: #balance27941
-Node: Depth limited balance reports30055
+Node: Flat mode30954
-Ref: #depth-limited-balance-reports30258
+Ref: #flat-mode31081
-Node: Multicolumn balance reports30679
+Node: Depth limited balance reports31500
-Ref: #multicolumn-balance-reports30881
+Ref: #depth-limited-balance-reports31703
-Node: Market value35530
+Node: Multicolumn balance reports32124
-Ref: #market-value35694
+Ref: #multicolumn-balance-reports32326
-Node: Custom balance output36187
+Node: Market value36975
-Ref: #custom-balance-output36360
+Ref: #market-value37139
-Node: Output destination38464
+Node: Custom balance output38440
-Ref: #output-destination38629
+Ref: #custom-balance-output38613
-Node: CSV output38899
+Node: Output destination40717
-Ref: #csv-output39018
+Ref: #output-destination40882
-Node: balancesheet39415
+Node: CSV output41152
-Ref: #balancesheet39543
+Ref: #csv-output41271
-Node: cashflow40195
+Node: balancesheet41668
-Ref: #cashflow40312
+Ref: #balancesheet41796
-Node: help41002
+Node: cashflow42448
-Ref: #help41114
+Ref: #cashflow42565
-Node: incomestatement41951
+Node: help43255
-Ref: #incomestatement42081
+Ref: #help43367
-Node: info42808
+Node: incomestatement44204
-Ref: #info42915
+Ref: #incomestatement44334
-Node: man43277
+Node: info45061
-Ref: #man43374
+Ref: #info45168
-Node: print43777
+Node: man45530
-Ref: #print43882
+Ref: #man45627
-Node: register45228
+Node: print46030
-Ref: #register45341
+Ref: #print46135
-Node: Custom register output49833
+Node: register47481
-Ref: #custom-register-output49964
+Ref: #register47594
-Node: stats51261
+Node: Custom register output52086
-Ref: #stats51367
+Ref: #custom-register-output52217
-Node: test52243
+Node: stats53514
-Ref: #test52330
+Ref: #stats53620
-Node: ADD-ON COMMANDS52697
+Node: test54496
-Ref: #add-on-commands52833
+Ref: #test54583
-Node: api54121
+Node: ADD-ON COMMANDS54950
-Ref: #api54213
+Ref: #add-on-commands55086
-Node: autosync54247
+Node: api56374
-Ref: #autosync54362
+Ref: #api56466
-Node: diff56677
+Node: autosync56500
-Ref: #diff56787
+Ref: #autosync56615
-Node: equity57451
+Node: diff58930
-Ref: #equity57565
+Ref: #diff59040
-Node: interest58893
+Node: equity59704
-Ref: #interest59010
+Ref: #equity59818
-Node: irr62094
+Node: interest61146
-Ref: #irr62207
+Ref: #interest61263
-Node: print-unique64582
+Node: irr64347
-Ref: #print-unique64712
+Ref: #irr64460
-Node: rewrite64970
+Node: print-unique66835
-Ref: #rewrite65089
+Ref: #print-unique66965
-Node: ui65618
+Node: rewrite67223
-Ref: #ui65718
+Ref: #rewrite67342
-Node: web65759
+Node: ui67871
-Ref: #web65847
+Ref: #ui67971
-Node: TROUBLESHOOTING65880
+Node: web68012
-Ref: #troubleshooting65999
+Ref: #web68100
-Node: Run-time problems66053
+Node: TROUBLESHOOTING68133
-Ref: #run-time-problems66196
+Ref: #troubleshooting68252
-Node: Known limitations68140
+Node: Run-time problems68306
-Ref: #known-limitations68283
+Ref: #run-time-problems68449
+Node: Known limitations70393
+Ref: #known-limitations70536
 
 End Tag Table