From 42f47e2b6bbc834665cf809fe5d2ef9f78b414d1 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 8 Jun 2018 17:26:58 -0700 Subject: [PATCH] update embedded manuals [ci skip] --- hledger-lib/hledger_journal.5 | 147 ++++++++----- hledger-lib/hledger_journal.info | 348 +++++++++++++++++-------------- hledger-lib/hledger_journal.txt | 276 +++++++++++++----------- hledger/hledger.1 | 3 + hledger/hledger.info | 205 +++++++++--------- hledger/hledger.txt | 9 +- 6 files changed, 551 insertions(+), 437 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 6480feed9..22eaa4baf 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -439,8 +439,9 @@ will be the maximum from all posting amounts in that commmodity or if there are no such amounts in the journal, a default format is used (like \f[C]$1000.00\f[]). .PP -Price amounts and amounts in D directives usually don't affect amount -format inference, but in some situations they can do so indirectly. +Price amounts and amounts in \f[C]D\f[] directives usually don't affect +amount format inference, but in some situations they can do so +indirectly. (Eg when D's default commodity is applied to a commodity\-less amount, or when an amountless posting is balanced using a price's commodity, or when \-V is used.) If you find this causing problems, set the desired @@ -627,7 +628,6 @@ assignment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. -.SS Prices .SS Transaction prices .PP Within a transaction, you can note an amount's price in another @@ -636,10 +636,10 @@ This can be used to document the cost (in a purchase) or selling price (in a sale). For example, transaction prices are useful to record purchases of a foreign currency. -.PP -Transaction prices are fixed, and do not change over time. -(Ledger users: Ledger uses a different syntax for fixed prices, -\f[C]{=UNITPRICE}\f[], which hledger currently ignores). +Note transaction prices are fixed at the time of the transaction, and do +not change over time. +See also market prices, which represent prevailing exchange rates on a +certain date. .PP There are several ways to record a transaction price: .IP "1." 3 @@ -680,10 +680,13 @@ hledger infer the price that balances the transaction: .fi .RE .PP -Amounts with transaction prices can be displayed in the transaction -price's commodity by using the \f[C]\-B/\-\-cost\f[] flag (except for -#551) (\[lq]B\[rq] is from \[lq]cost Basis\[rq]). -Eg for the above, here is how \-B affects the balance report: +(Ledger users: Ledger uses a different syntax for fixed prices, +\f[C]{=UNITPRICE}\f[], which hledger currently ignores). +.PP +Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their +transaction price's commodity, if any. +(mnemonic: \[lq]B\[rq] is from \[lq]cost Basis\[rq], as in Ledger). +Eg here is how \-B affects the balance report for the example above: .IP .nf \f[C] @@ -717,40 +720,6 @@ $\ hledger\ bal\ \-N\ \-\-flat\ \-B \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros \f[] .fi -.SS Market prices -.PP -Market prices are not tied to a particular transaction; they represent -historical exchange rates between two commodities. -(Ledger calls them historical prices.) For example, the prices published -by a stock exchange or the foreign exchange market. -hledger can use these prices to show the market value of things at a -given date, see market value. -.PP -To record market prices, use P directives in the main journal or in an -included file. -Their format is: -.IP -.nf -\f[C] -P\ DATE\ COMMODITYBEINGPRICED\ UNITPRICE -\f[] -.fi -.PP -DATE is a simple date as usual. -COMMODITYBEINGPRICED is the symbol of the commodity being priced. -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] -P\ 2009/1/1\ €\ $1.35 -P\ 2010/1/1\ €\ $1.40 -\f[] -.fi .SS Comments .PP Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash @@ -853,6 +822,53 @@ For example, the following transaction has three tags (\f[C]A\f[], Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. .SS Directives +.PP +A directive is a line in the journal beginning with a special keyword, +that influences how the journal is processed. +Some directives may also have indented sub\-directives on the following +lines (\f[C]commodity\f[]). +.SS Directive scope, multiple files +.PP +Directives vary in which journal entries they affect: +.IP \[bu] 2 +some form a begin/end pair, and affect the enclosed journal entries (and +included files): +.PD 0 +.P +.PD +\f[C]alias\f[] & \f[C]end\ aliases\f[]; \f[C]comment\f[] & +\f[C]end\ comment\f[] +.IP \[bu] 2 +some affect the subsequent journal entries (and included files) in the +current file: +.PD 0 +.P +.PD +\f[C]alias\f[] or \f[C]comment\f[] without an end directive, \f[C]Y\f[] +.IP \[bu] 2 +some affect all journal entries (and included files) anywhere in the +current file: +.PD 0 +.P +.PD +\f[C]account\f[], \f[C]commodity\f[], \f[C]D\f[], \f[C]P\f[]. +.PP +It's important to note that directives can affect the current file and +child (included) files, but not sibling or parent (including) files. +This is by design, for simplicity and predictability of reports, but it +can be surprising at times. +Eg, in: +.IP +.nf +\f[C] +hledger\ \-f\ a.prices\ \-f\ b.journal +\f[] +.fi +.PP +the prices defined in a.prices will not be effective in b.journal (a +sibling file). +Instead, you have to include (or inline) a.prices in b.journal, or vice +versa. .SS Comment blocks .PP A line containing just \f[C]comment\f[] starts a commented region of the @@ -946,11 +962,11 @@ with a decimal point (a period or comma, followed by 0 or more decimal digits). .SS Default commodity .PP -The D directive sets a default commodity (and display format), to be -used for amounts without a commodity symbol (ie, plain numbers). +The \f[C]D\f[] directive sets a default commodity (and display format), +to be used for amounts without a commodity symbol (ie, plain numbers). (Note this differs from Ledger's default commodity directive.) The commodity and display format will be applied to all subsequent -commodity\-less amounts, or until the next D directive. +commodity\-less amounts, or until the next \f[C]D\f[] directive. .IP .nf \f[C] @@ -966,6 +982,41 @@ D\ $1,000.00 .PP As with the \f[C]commodity\f[] directive, the amount must always be written with a decimal point. +.SS Market prices +.PP +The \f[C]P\f[] directive declares a market price, which is an exchange +rate between two commodities on a certain date. +(In Ledger, they are called \[lq]historical prices\[rq].) These are +often obtained from a stock exchange, cryptocurrency exchange, or the +foreign exchange market. +.PP +Here is the format: +.IP +.nf +\f[C] +P\ DATE\ COMMODITYA\ COMMODITYBAMOUNT +\f[] +.fi +.IP \[bu] 2 +DATE is a simple date +.IP \[bu] 2 +COMMODITYA is the symbol of the commodity being priced +.IP \[bu] 2 +COMMODITYBAMOUNT is an amount (symbol and quantity) in a second +commodity, giving the price in commodity B of one unit of commodity A. +.PP +These two market price directives say that one euro was worth 1.35 US +dollars during 2009, and $1.40 from 2010 onward: +.IP +.nf +\f[C] +P\ 2009/1/1\ €\ $1.35 +P\ 2010/1/1\ €\ $1.40 +\f[] +.fi +.PP +The \f[C]\-V/\-\-value\f[] flag can be used to convert reported amounts +to another commodity using these prices. .SS Declaring accounts .PP The \f[C]account\f[] directive predeclares account names. diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index cadf1e8fa..337ccf7e0 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -77,7 +77,7 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: To * Virtual Postings:: * Balance Assertions:: * Balance Assignments:: -* Prices:: +* Transaction prices:: * Comments:: * Tags:: * Directives:: @@ -400,12 +400,12 @@ written). The display format is chosen as follows: * or if there are no such amounts in the journal, a default format is used (like '$1000.00'). - Price amounts and amounts in D directives usually don't affect amount -format inference, but in some situations they can do so indirectly. (Eg -when D's default commodity is applied to a commodity-less amount, or -when an amountless posting is balanced using a price's commodity, or -when -V is used.) If you find this causing problems, set the desired -format with a commodity directive. + Price amounts and amounts in 'D' directives usually don't affect +amount format inference, but in some situations they can do so +indirectly. (Eg when D's default commodity is applied to a +commodity-less amount, or when an amountless posting is balanced using a +price's commodity, or when -V is used.) If you find this causing +problems, set the desired format with a commodity directive.  File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT @@ -569,7 +569,7 @@ virtual. They are not affected by the '--real/-R' flag or 'real:' query.  -File: hledger_journal.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT +File: hledger_journal.info, Node: Balance Assignments, Next: Transaction prices, Prev: Balance Assertions, Up: FILE FORMAT 1.10 Balance Assignments ======================== @@ -602,30 +602,18 @@ little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it.  -File: hledger_journal.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT +File: hledger_journal.info, Node: Transaction prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT -1.11 Prices -=========== - -* Menu: - -* Transaction prices:: -* Market prices:: - - -File: hledger_journal.info, Node: Transaction prices, Next: Market prices, Up: Prices - -1.11.1 Transaction prices -------------------------- +1.11 Transaction prices +======================= Within a transaction, you can note an amount's price in another commodity. This can be used to document the cost (in a purchase) or selling price (in a sale). For example, transaction prices are useful -to record purchases of a foreign currency. - - Transaction prices are fixed, and do not change over time. (Ledger -users: Ledger uses a different syntax for fixed prices, '{=UNITPRICE}', -which hledger currently ignores). +to record purchases of a foreign currency. Note transaction prices are +fixed at the time of the transaction, and do not change over time. See +also market prices, which represent prevailing exchange rates on a +certain date. There are several ways to record a transaction price: @@ -648,10 +636,13 @@ which hledger currently ignores). assets:euros €100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - Amounts with transaction prices can be displayed in the transaction -price's commodity by using the '-B/--cost' flag (except for #551) ("B" -is from "cost Basis"). Eg for the above, here is how -B affects the -balance report: + (Ledger users: Ledger uses a different syntax for fixed prices, +'{=UNITPRICE}', which hledger currently ignores). + + Use the '-B/--cost' flag to convert amounts to their transaction +price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in +Ledger). Eg here is how -B affects the balance report for the example +above: $ hledger bal -N --flat $-135 assets:dollars @@ -674,36 +665,7 @@ $ hledger bal -N --flat -B €100 assets:euros  -File: hledger_journal.info, Node: Market prices, Prev: Transaction prices, Up: Prices - -1.11.2 Market prices --------------------- - -Market prices are not tied to a particular transaction; they represent -historical exchange rates between two commodities. (Ledger calls them -historical prices.) For example, the prices published by a stock -exchange or the foreign exchange market. hledger can use these prices -to show the market value of things at a given date, see market value. - - To record market prices, use P directives in the main journal or in -an included file. Their format is: - -P DATE COMMODITYBEINGPRICED UNITPRICE - - DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol -of the commodity being priced. 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 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 - - -File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT +File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Transaction prices, Up: FILE FORMAT 1.12 Comments ============= @@ -792,21 +754,55 @@ File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Pr 1.14 Directives =============== +A directive is a line in the journal beginning with a special keyword, +that influences how the journal is processed. Some directives may also +have indented sub-directives on the following lines ('commodity'). * Menu: +* Directive scope multiple files:: * Comment blocks:: * Including other files:: * Default year:: * Declaring commodities:: * Default commodity:: +* Market prices:: * Declaring accounts:: * Rewriting accounts:: * Default parent account::  -File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives +File: hledger_journal.info, Node: Directive scope multiple files, Next: Comment blocks, Up: Directives -1.14.1 Comment blocks +1.14.1 Directive scope, multiple files +-------------------------------------- + +Directives vary in which journal entries they affect: + + * some form a begin/end pair, and affect the enclosed journal entries + (and included files): + 'alias' & 'end aliases'; 'comment' & 'end comment' + * some affect the subsequent journal entries (and included files) in + the current file: + 'alias' or 'comment' without an end directive, 'Y' + * some affect all journal entries (and included files) anywhere in + the current file: + 'account', 'commodity', 'D', 'P'. + + It's important to note that directives can affect the current file +and child (included) files, but not sibling or parent (including) files. +This is by design, for simplicity and predictability of reports, but it +can be surprising at times. Eg, in: + +hledger -f a.prices -f b.journal + + the prices defined in a.prices will not be effective in b.journal (a +sibling file). Instead, you have to include (or inline) a.prices in +b.journal, or vice versa. + + +File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directive scope multiple files, Up: Directives + +1.14.2 Comment blocks --------------------- A line containing just 'comment' starts a commented region of the file, @@ -816,7 +812,7 @@ file) ends it. See also comments.  File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives -1.14.2 Including other files +1.14.3 Including other files ---------------------------- You can pull in the content of additional files by writing an include @@ -833,7 +829,7 @@ include journal, timeclock or timedot files, but not CSV files.  File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives -1.14.3 Default year +1.14.4 Default year ------------------- You can set a default year to be used for subsequent dates which don't @@ -859,7 +855,7 @@ Y2010 ; change default year to 2010  File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives -1.14.4 Declaring commodities +1.14.5 Declaring commodities ---------------------------- The 'commodity' directive declares commodities which may be used in the @@ -895,16 +891,16 @@ always be written with a decimal point (a period or comma, followed by 0 or more decimal digits).  -File: hledger_journal.info, Node: Default commodity, Next: Declaring accounts, Prev: Declaring commodities, Up: Directives +File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives -1.14.5 Default commodity +1.14.6 Default commodity ------------------------ -The D directive sets a default commodity (and display format), to be +The 'D' directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note this differs from Ledger's default commodity directive.) The commodity and display format will be applied to all subsequent commodity-less -amounts, or until the next D directive. +amounts, or until the next 'D' directive. # commodity-less amounts should be treated as dollars # (and displayed with symbol on the left, thousands separators and two decimal places) @@ -918,9 +914,39 @@ D $1,000.00 with a decimal point.  -File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Default commodity, Up: Directives +File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives -1.14.6 Declaring accounts +1.14.7 Market prices +-------------------- + +The 'P' directive declares a market price, which is an exchange rate +between two commodities on a certain date. (In Ledger, they are called +"historical prices".) These are often obtained from a stock exchange, +cryptocurrency exchange, or the foreign exchange market. + + Here is the format: + +P DATE COMMODITYA COMMODITYBAMOUNT + + * DATE is a simple date + * COMMODITYA is the symbol of the commodity being priced + * COMMODITYBAMOUNT is an amount (symbol and quantity) in a second + commodity, giving the price in commodity B of one unit of commodity + A. + + These two market price 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 + + The '-V/--value' flag can be used to convert reported amounts to +another commodity using these prices. + + +File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives + +1.14.8 Declaring accounts ------------------------- The 'account' directive predeclares account names. The simplest form is @@ -962,7 +988,7 @@ account assets:bank:checking 1110  File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives -1.14.7 Rewriting accounts +1.14.9 Rewriting accounts ------------------------- You can define aliases which rewrite your account names (after reading @@ -987,7 +1013,7 @@ be useful for:  File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -1.14.7.1 Basic aliases +1.14.9.1 Basic aliases ...................... To set an account alias, use the 'alias' directive in your journal file. @@ -1010,7 +1036,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts -1.14.7.2 Regex aliases +1.14.9.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, @@ -1035,7 +1061,7 @@ whitespace.  File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts -1.14.7.3 Multiple aliases +1.14.9.3 Multiple aliases ......................... You can define as many aliases as you like using directives or @@ -1051,7 +1077,7 @@ following order:  File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts -1.14.7.4 'end aliases' +1.14.9.4 'end aliases' ...................... You can clear (forget) all currently defined aliases with the 'end @@ -1062,8 +1088,8 @@ end aliases  File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives -1.14.8 Default parent account ------------------------------ +1.14.10 Default parent account +------------------------------ You can specify a parent account which will be prepended to all accounts within a section of the journal. Use the 'apply account' and 'end apply @@ -1204,87 +1230,87 @@ Tag Table: Node: Top76 Node: FILE FORMAT2376 Ref: #file-format2500 -Node: Transactions2772 -Ref: #transactions2893 -Node: Postings3577 -Ref: #postings3704 -Node: Dates4699 -Ref: #dates4814 -Node: Simple dates4879 -Ref: #simple-dates5005 -Node: Secondary dates5371 -Ref: #secondary-dates5525 -Node: Posting dates7088 -Ref: #posting-dates7217 -Node: Status8591 -Ref: #status8711 -Node: Description10419 -Ref: #description10557 -Node: Payee and note10876 -Ref: #payee-and-note10990 -Node: Account names11232 -Ref: #account-names11375 -Node: Amounts11862 -Ref: #amounts11998 -Node: Virtual Postings15013 -Ref: #virtual-postings15172 -Node: Balance Assertions16392 -Ref: #balance-assertions16567 -Node: Assertions and ordering17463 -Ref: #assertions-and-ordering17649 -Node: Assertions and included files18349 -Ref: #assertions-and-included-files18590 -Node: Assertions and multiple -f options18923 -Ref: #assertions-and-multiple--f-options19177 -Node: Assertions and commodities19309 -Ref: #assertions-and-commodities19544 -Node: Assertions and subaccounts20240 -Ref: #assertions-and-subaccounts20472 -Node: Assertions and virtual postings20993 -Ref: #assertions-and-virtual-postings21200 -Node: Balance Assignments21342 -Ref: #balance-assignments21511 -Node: Prices22631 -Ref: #prices22764 -Node: Transaction prices22815 -Ref: #transaction-prices22960 -Node: Market prices25116 -Ref: #market-prices25251 -Node: Comments26211 -Ref: #comments26333 -Node: Tags27503 -Ref: #tags27621 -Node: Directives29023 -Ref: #directives29166 -Node: Comment blocks29359 -Ref: #comment-blocks29504 -Node: Including other files29680 -Ref: #including-other-files29860 -Node: Default year30249 -Ref: #default-year30418 -Node: Declaring commodities30841 -Ref: #declaring-commodities31024 -Node: Default commodity32251 -Ref: #default-commodity32432 -Node: Declaring accounts33064 -Ref: #declaring-accounts33244 -Node: Rewriting accounts34591 -Ref: #rewriting-accounts34776 -Node: Basic aliases35380 -Ref: #basic-aliases35526 -Node: Regex aliases36216 -Ref: #regex-aliases36387 -Node: Multiple aliases37105 -Ref: #multiple-aliases37280 -Node: end aliases37778 -Ref: #end-aliases37925 -Node: Default parent account38026 -Ref: #default-parent-account38192 -Node: Periodic transactions38851 -Ref: #periodic-transactions39030 -Node: Automated postings40329 -Ref: #automated-postings40483 -Node: EDITOR SUPPORT41616 -Ref: #editor-support41734 +Node: Transactions2784 +Ref: #transactions2905 +Node: Postings3589 +Ref: #postings3716 +Node: Dates4711 +Ref: #dates4826 +Node: Simple dates4891 +Ref: #simple-dates5017 +Node: Secondary dates5383 +Ref: #secondary-dates5537 +Node: Posting dates7100 +Ref: #posting-dates7229 +Node: Status8603 +Ref: #status8723 +Node: Description10431 +Ref: #description10569 +Node: Payee and note10888 +Ref: #payee-and-note11002 +Node: Account names11244 +Ref: #account-names11387 +Node: Amounts11874 +Ref: #amounts12010 +Node: Virtual Postings15027 +Ref: #virtual-postings15186 +Node: Balance Assertions16406 +Ref: #balance-assertions16581 +Node: Assertions and ordering17477 +Ref: #assertions-and-ordering17663 +Node: Assertions and included files18363 +Ref: #assertions-and-included-files18604 +Node: Assertions and multiple -f options18937 +Ref: #assertions-and-multiple--f-options19191 +Node: Assertions and commodities19323 +Ref: #assertions-and-commodities19558 +Node: Assertions and subaccounts20254 +Ref: #assertions-and-subaccounts20486 +Node: Assertions and virtual postings21007 +Ref: #assertions-and-virtual-postings21214 +Node: Balance Assignments21356 +Ref: #balance-assignments21537 +Node: Transaction prices22657 +Ref: #transaction-prices22826 +Node: Comments25094 +Ref: #comments25228 +Node: Tags26398 +Ref: #tags26516 +Node: Directives27918 +Ref: #directives28061 +Node: Directive scope multiple files28517 +Ref: #directive-scope-multiple-files28705 +Node: Comment blocks29655 +Ref: #comment-blocks29839 +Node: Including other files30015 +Ref: #including-other-files30195 +Node: Default year30584 +Ref: #default-year30753 +Node: Declaring commodities31176 +Ref: #declaring-commodities31359 +Node: Default commodity32586 +Ref: #default-commodity32762 +Node: Market prices33398 +Ref: #market-prices33563 +Node: Declaring accounts34404 +Ref: #declaring-accounts34580 +Node: Rewriting accounts35927 +Ref: #rewriting-accounts36112 +Node: Basic aliases36716 +Ref: #basic-aliases36862 +Node: Regex aliases37552 +Ref: #regex-aliases37723 +Node: Multiple aliases38441 +Ref: #multiple-aliases38616 +Node: end aliases39114 +Ref: #end-aliases39261 +Node: Default parent account39362 +Ref: #default-parent-account39530 +Node: Periodic transactions40189 +Ref: #periodic-transactions40368 +Node: Automated postings41667 +Ref: #automated-postings41821 +Node: EDITOR SUPPORT42954 +Ref: #editor-support43072  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 15c49fc25..ef0d47a70 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -466,16 +466,14 @@ FILE FORMAT less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. - Prices Transaction prices Within a transaction, you can note an amount's price in another commod- ity. This can be used to document the cost (in a purchase) or selling price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. - - Transaction prices are fixed, and do not change over time. (Ledger - users: Ledger uses a different syntax for fixed prices, {=UNITPRICE}, - which hledger currently ignores). + record purchases of a foreign currency. Note transaction prices are + fixed at the time of the transaction, and do not change over time. See + also market prices, which represent prevailing exchange rates on a cer- + tain date. There are several ways to record a transaction price: @@ -498,10 +496,12 @@ FILE FORMAT assets:euros 100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - Amounts with transaction prices can be displayed in the transaction - price's commodity by using the -B/--cost flag (except for #551) ("B" is - from "cost Basis"). Eg for the above, here is how -B affects the bal- - ance report: + (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- + PRICE}, which hledger currently ignores). + + Use the -B/--cost flag to convert amounts to their transaction price's + commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). + Eg here is how -B affects the balance report for the example above: $ hledger bal -N --flat $-135 assets:dollars @@ -510,8 +510,8 @@ FILE FORMAT $-135 assets:dollars $135 assets:euros # <- the euros' cost - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last amount. So if example 3's postings are reversed, while the transaction is equivalent, -B shows something different: @@ -523,40 +523,16 @@ FILE FORMAT -100 assets:dollars # <- the dollars' selling price 100 assets:euros - Market prices - Market prices are not tied to a particular transaction; they represent - historical exchange rates between two commodities. (Ledger calls them - historical prices.) For example, the prices published by a stock - exchange or the foreign exchange market. hledger can use these prices - to show the market value of things at a given date, see market value. - - To record market prices, use P directives in the main journal or in an - included file. Their format is: - - P DATE COMMODITYBEINGPRICED UNITPRICE - - DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of - the commodity being priced. UNITPRICE is an ordinary amount (symbol - and quantity) in a second commodity, specifying the unit price or con- - version 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 - Comments Lines in the journal beginning with a semicolon (;) or hash (#) or star - (*) are comments, and will be ignored. (Star comments cause org-mode - nodes to be ignored, allowing emacs users to fold and navigate their + (*) are comments, and will be ignored. (Star comments cause org-mode + nodes to be ignored, allowing emacs users to fold and navigate their journals with org-mode or orgstruct-mode.) - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. Transaction and posting comments must begin with a semicolon (;). Some examples: @@ -580,24 +556,24 @@ FILE FORMAT ; another comment line for posting 2 ; a file comment (because not indented) - You can also comment larger regions of a file using comment and + You can also comment larger regions of a file using comment and end comment directives. Tags - Tags are a way to add extra labels or labelled data to postings and + Tags are a way to add extra labels or labelled data to postings and transactions, which you can then search or pivot on. - A simple tag is a word (which may contain hyphens) followed by a full + A simple tag is a word (which may contain hyphens) followed by a full colon, written inside a transaction or posting comment line: 2017/1/16 bought groceries ; sometag: - Tags can have a value, which is the text after the colon, up to the + Tags can have a value, which is the text after the colon, up to the next comma or end of line, with leading/trailing whitespace removed: expenses:food $10 ; a-posting-tag: the tag value - Note this means hledger's tag values can not contain commas or new- + Note this means hledger's tag values can not contain commas or new- lines. Ending at commas means you can write multiple short tags on one line, comma separated: @@ -611,39 +587,69 @@ FILE FORMAT o "tag2" is another tag, whose value is "some value ..." - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, third-tag) and the posting has four (those plus posting-tag): 1/1 a transaction ; A:, TAG2: ; third-tag: a third transaction tag, <- with a value (a) $1 ; posting-tag: - Tags are like Ledger's metadata feature, except hledger's tag values + Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. Directives + A directive is a line in the journal beginning with a special keyword, + that influences how the journal is processed. Some directives may also + have indented sub-directives on the following lines (commodity). + + Directive scope, multiple files + Directives vary in which journal entries they affect: + + o some form a begin/end pair, and affect the enclosed journal entries + (and included files): + alias & end aliases; comment & end comment + + o some affect the subsequent journal entries (and included files) in + the current file: + alias or comment without an end directive, Y + + o some affect all journal entries (and included files) anywhere in the + current file: + account, commodity, D, P. + + It's important to note that directives can affect the current file and + child (included) files, but not sibling or parent (including) files. + This is by design, for simplicity and predictability of reports, but it + can be surprising at times. Eg, in: + + hledger -f a.prices -f b.journal + + the prices defined in a.prices will not be effective in b.journal (a + sibling file). Instead, you have to include (or inline) a.prices in + b.journal, or vice versa. + Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional files by writing an include directive, like this: include path/to/file.journal - If the path does not begin with a slash, it is relative to the current + If the path does not begin with a slash, it is relative to the current file. Glob patterns (*) are not currently supported. - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -663,8 +669,8 @@ FILE FORMAT assets Declaring commodities - The commodity directive declares commodities which may be used in the - journal (though currently we do not enforce this). It may be written + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -674,8 +680,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both places: ; commodity SYMBOL @@ -687,19 +693,19 @@ FILE FORMAT commodity INR format INR 9,99,99,999.00 - Commodity directives have a second purpose: they define the standard + Commodity directives have a second purpose: they define the standard display format for amounts in the commodity. Normally the display for- - mat is inferred from journal entries, but this can be unpredictable; - declaring it with a commodity directive overrides this and removes - ambiguity. Towards this end, amounts in commodity directives must - always be written with a decimal point (a period or comma, followed by + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Default commodity - The D directive sets a default commodity (and display format), to be + The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. # commodity-less amounts should be treated as dollars @@ -713,13 +719,39 @@ FILE FORMAT As with the commodity directive, the amount must always be written with a decimal point. + Market prices + The P directive declares a market price, which is an exchange rate + between two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, + cryptocurrency exchange, or the foreign exchange market. + + Here is the format: + + P DATE COMMODITYA COMMODITYBAMOUNT + + o DATE is a simple date + + o COMMODITYA is the symbol of the commodity being priced + + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + modity, giving the price in commodity B of one unit of commodity A. + + These two market price 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 + + The -V/--value flag can be used to convert reported amounts to another + commodity using these prices. + Declaring accounts - The account directive predeclares account names. The simplest form is + The account directive predeclares account names. The simplest form is account ACCTNAME, eg: account assets:bank:checking - Currently this mainly helps with account name autocompletion in eg + Currently this mainly helps with account name autocompletion in eg hledger add, hledger-iadd, hledger-web, and ledger-mode. In future it will also help detect misspelled accounts. @@ -731,13 +763,13 @@ FILE FORMAT account revenues 4000 account expenses 6000 - This affects account display order in reports: accounts with codes are - listed before accounts without codes, in increasing code order. (Oth- - erwise, accounts are listed alphabetically.) Account codes should be - all numeric digits, unique, and separated from the account name by at - least two spaces (since account names may contain single spaces). By - convention, often the first digit indicates the type of account, as in - this numbering scheme and the example above. In future, we might use + This affects account display order in reports: accounts with codes are + listed before accounts without codes, in increasing code order. (Oth- + erwise, accounts are listed alphabetically.) Account codes should be + all numeric digits, unique, and separated from the account name by at + least two spaces (since account names may contain single spaces). By + convention, often the first digit indicates the type of account, as in + this numbering scheme and the example above. In future, we might use this to recognize account types. An account directive can also have indented subdirectives following it, @@ -751,7 +783,7 @@ FILE FORMAT some-tag:12345 Rewriting accounts - You can define aliases which rewrite your account names (after reading + You can define aliases which rewrite your account names (after reading the journal, before generating reports). hledger's account aliases can be useful for: @@ -768,8 +800,8 @@ FILE FORMAT See also Cookbook: Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -777,54 +809,54 @@ FILE FORMAT Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are full account names. hledger will replace any occur- - rence of the old account name with the new one. Subaccounts are also + OLD and NEW are full account names. hledger will replace any occur- + rence of the old account name with the new one. Subaccounts are also affected. Eg: alias checking = assets:bank:wells fargo:checking # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, + There is also a more powerful variant that uses a regular expression, indicated by the forward slashes: alias /REGEX/ = REPLACEMENT or --alias '/REGEX/=REPLACEMENT'. - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- erenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - Also note that REPLACEMENT continues to the end of line (or on command - line, to end of option argument), so it can contain trailing white- + Also note that REPLACEMENT continues to the end of line (or on command + line, to end of option argument), so it can contain trailing white- space. Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where aliases are non-recursive by default). Aliases are applied in the fol- lowing order: - 1. alias directives, most recently seen first (recent directives take + 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored) 2. alias options, in the order they appear on the command line end aliases - You can clear (forget) all currently defined aliases with the + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -841,7 +873,7 @@ FILE FORMAT home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -850,13 +882,13 @@ FILE FORMAT apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. Periodic transactions Periodic transaction rules (enabled by --forecast or --budget) describe - recurring transactions. They look like a transaction where the first - line is a tilde (~) followed by a period expression (mnemonic: ~ is + recurring transactions. They look like a transaction where the first + line is a tilde (~) followed by a period expression (mnemonic: ~ is like a recurring sine wave): ~ weekly @@ -865,29 +897,29 @@ FILE FORMAT Periodic transactions have a dual purpose: - o With --forecast, each periodic transaction rule generates future - transactions, recurring at the specified interval, which can be seen - in reports. Forecast transactions begin the day after the latest + o With --forecast, each periodic transaction rule generates future + transactions, recurring at the specified interval, which can be seen + in reports. Forecast transactions begin the day after the latest recorded journal transaction (or today, if there are no transactions) - and end 6 months from today (or at the report end date, if speci- + and end 6 months from today (or at the report end date, if speci- fied). - o With --budget (supported by the balance command), each periodic - transaction rule declares recurring budget goals for the specified - accounts, which can be seen in budget reports. Eg the example above - declares the goal of receiving $400 from income:acme inc (and also, + o With --budget (supported by the balance command), each periodic + transaction rule declares recurring budget goals for the specified + accounts, which can be seen in budget reports. Eg the example above + declares the goal of receiving $400 from income:acme inc (and also, depositing $400 into assets:bank:checking) every week. - (Actually, you can generate one-off transactions too, by writing a + (Actually, you can generate one-off transactions too, by writing a period expression with no report interval.) - For more details, see: balance: Budget report and Cookbook: Budgeting + For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. Automated postings Automated postings (enabled by --auto) are postings added automatically - by rule to certain transactions. An automated posting rule looks like - a transaction where the first line is an equal sign (=) followed by a + by rule to certain transactions. An automated posting rule looks like + a transaction where the first line is an equal sign (=) followed by a query (mnemonic: = tests for matching transactions, and also looks like posting lines): @@ -895,13 +927,13 @@ FILE FORMAT budget:gifts *-1 assets:budget *1 - The posting amounts can be of the form *N, which means "the amount of - the matched transaction's first posting, multiplied by N". They can + The posting amounts can be of the form *N, which means "the amount of + the matched transaction's first posting, multiplied by N". They can also be ordinary fixed amounts. Fixed amounts with no commodity symbol - will be given the same commodity as the matched transaction's first + will be given the same commodity as the matched transaction's first posting. - This example adds a corresponding (unbalanced) budget posting to every + This example adds a corresponding (unbalanced) budget posting to every transaction involving the expenses:gifts account: = expenses:gifts @@ -917,16 +949,16 @@ FILE FORMAT (budget:gifts) $-20 assets - Like postings recorded by hand, automated postings participate in + Like postings recorded by hand, automated postings participate in transaction balancing, missing amount inference and balance assertions. EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- - nal files easier. They add colour, navigation aids and helpful com- - mands. For hledger users who edit the journal file directly (the + nal files easier. They add colour, navigation aids and helpful com- + mands. For hledger users who edit the journal file directly (the majority), using one of these modes is quite recommended. - These were written with Ledger in mind, but also work with hledger + These were written with Ledger in mind, but also work with hledger files: @@ -945,7 +977,7 @@ EDITOR SUPPORT REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -959,7 +991,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 5ccfd0831..3a241cf0e 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -962,6 +962,9 @@ transaction time, if they have a transaction price specified. .PP The \f[C]\-V/\-\-value\f[] flag converts reported amounts to their current market value. +.PD 0 +.P +.PD Specifically, when there is a market price (P directive) for the amount's commodity, dated on or before today's date (or the report end date if specified), the amount will be converted to the price's diff --git a/hledger/hledger.info b/hledger/hledger.info index 1ee86ce82..ea91d46b4 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -645,7 +645,8 @@ File: hledger.info, Node: Market value, Next: Combining -B and -V, Prev: Cost ================= The '-V/--value' flag converts reported amounts to their current market -value. Specifically, when there is a market price (P directive) for the +value. +Specifically, when there is a market price (P directive) for the amount's commodity, dated on or before today's date (or the report end date if specified), the amount will be converted to the price's commodity. @@ -2464,106 +2465,106 @@ Node: Cost21487 Ref: #cost21595 Node: Market value21713 Ref: #market-value21848 -Node: Combining -B and -V23215 -Ref: #combining--b-and--v23378 -Node: Output destination23525 -Ref: #output-destination23687 -Node: Output format23970 -Ref: #output-format24122 -Node: Regular expressions24507 -Ref: #regular-expressions24644 -Node: QUERIES26005 -Ref: #queries26107 -Node: COMMANDS30069 -Ref: #commands30181 -Node: accounts31163 -Ref: #accounts31261 -Node: activity32507 -Ref: #activity32617 -Node: add32977 -Ref: #add33076 -Node: balance35737 -Ref: #balance35848 -Node: Classic balance report38931 -Ref: #classic-balance-report39104 -Node: Customising the classic balance report40473 -Ref: #customising-the-classic-balance-report40701 -Node: Colour support42775 -Ref: #colour-support42942 -Node: Flat mode43115 -Ref: #flat-mode43263 -Node: Depth limited balance reports43676 -Ref: #depth-limited-balance-reports43876 -Node: Multicolumn balance report44332 -Ref: #multicolumn-balance-report44530 -Node: Budget report49710 -Ref: #budget-report49853 -Ref: #output-format-152887 -Node: balancesheet52965 -Ref: #balancesheet53101 -Node: balancesheetequity55412 -Ref: #balancesheetequity55561 -Node: cashflow56098 -Ref: #cashflow56226 -Node: check-dates58349 -Ref: #check-dates58476 -Node: check-dupes58593 -Ref: #check-dupes58717 -Node: close58854 -Ref: #close58961 -Node: help59291 -Ref: #help59391 -Node: import60465 -Ref: #import60579 -Node: incomestatement61309 -Ref: #incomestatement61443 -Node: prices63847 -Ref: #prices63962 -Node: print64005 -Ref: #print64115 -Node: print-unique69009 -Ref: #print-unique69135 -Node: register69203 -Ref: #register69330 -Node: Custom register output73831 -Ref: #custom-register-output73960 -Node: register-match75190 -Ref: #register-match75324 -Node: rewrite75507 -Ref: #rewrite75624 -Node: stats75693 -Ref: #stats75796 -Node: tags76666 -Ref: #tags76764 -Node: test77000 -Ref: #test77084 -Node: ADD-ON COMMANDS77452 -Ref: #add-on-commands77562 -Node: Official add-ons78849 -Ref: #official-add-ons78989 -Node: api79076 -Ref: #api79165 -Node: ui79217 -Ref: #ui79316 -Node: web79374 -Ref: #web79463 -Node: Third party add-ons79509 -Ref: #third-party-add-ons79684 -Node: diff79819 -Ref: #diff79916 -Node: iadd80015 -Ref: #iadd80129 -Node: interest80212 -Ref: #interest80333 -Node: irr80428 -Ref: #irr80526 -Node: Experimental add-ons80604 -Ref: #experimental-add-ons80756 -Node: autosync81036 -Ref: #autosync81147 -Node: chart81386 -Ref: #chart81505 -Node: check81576 -Ref: #check81678 +Node: Combining -B and -V23214 +Ref: #combining--b-and--v23377 +Node: Output destination23524 +Ref: #output-destination23686 +Node: Output format23969 +Ref: #output-format24121 +Node: Regular expressions24506 +Ref: #regular-expressions24643 +Node: QUERIES26004 +Ref: #queries26106 +Node: COMMANDS30068 +Ref: #commands30180 +Node: accounts31162 +Ref: #accounts31260 +Node: activity32506 +Ref: #activity32616 +Node: add32976 +Ref: #add33075 +Node: balance35736 +Ref: #balance35847 +Node: Classic balance report38930 +Ref: #classic-balance-report39103 +Node: Customising the classic balance report40472 +Ref: #customising-the-classic-balance-report40700 +Node: Colour support42774 +Ref: #colour-support42941 +Node: Flat mode43114 +Ref: #flat-mode43262 +Node: Depth limited balance reports43675 +Ref: #depth-limited-balance-reports43875 +Node: Multicolumn balance report44331 +Ref: #multicolumn-balance-report44529 +Node: Budget report49709 +Ref: #budget-report49852 +Ref: #output-format-152886 +Node: balancesheet52964 +Ref: #balancesheet53100 +Node: balancesheetequity55411 +Ref: #balancesheetequity55560 +Node: cashflow56097 +Ref: #cashflow56225 +Node: check-dates58348 +Ref: #check-dates58475 +Node: check-dupes58592 +Ref: #check-dupes58716 +Node: close58853 +Ref: #close58960 +Node: help59290 +Ref: #help59390 +Node: import60464 +Ref: #import60578 +Node: incomestatement61308 +Ref: #incomestatement61442 +Node: prices63846 +Ref: #prices63961 +Node: print64004 +Ref: #print64114 +Node: print-unique69008 +Ref: #print-unique69134 +Node: register69202 +Ref: #register69329 +Node: Custom register output73830 +Ref: #custom-register-output73959 +Node: register-match75189 +Ref: #register-match75323 +Node: rewrite75506 +Ref: #rewrite75623 +Node: stats75692 +Ref: #stats75795 +Node: tags76665 +Ref: #tags76763 +Node: test76999 +Ref: #test77083 +Node: ADD-ON COMMANDS77451 +Ref: #add-on-commands77561 +Node: Official add-ons78848 +Ref: #official-add-ons78988 +Node: api79075 +Ref: #api79164 +Node: ui79216 +Ref: #ui79315 +Node: web79373 +Ref: #web79462 +Node: Third party add-ons79508 +Ref: #third-party-add-ons79683 +Node: diff79818 +Ref: #diff79915 +Node: iadd80014 +Ref: #iadd80128 +Node: interest80211 +Ref: #interest80332 +Node: irr80427 +Ref: #irr80525 +Node: Experimental add-ons80603 +Ref: #experimental-add-ons80755 +Node: autosync81035 +Ref: #autosync81146 +Node: chart81385 +Ref: #chart81504 +Node: check81575 +Ref: #check81677  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index a6a24f800..b42eff475 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -611,10 +611,11 @@ OPTIONS Market value The -V/--value flag converts reported amounts to their current market - value. Specifically, when there is a market price (P directive) for - the amount's commodity, dated on or before today's date (or the report - end date if specified), the amount will be converted to the price's - commodity. + value. + Specifically, when there is a market price (P directive) for the + amount's commodity, dated on or before today's date (or the report end + date if specified), the amount will be converted to the price's commod- + ity. When there are multiple applicable P directives, -V chooses the most recent one, or in case of equal dates, the last-parsed one.