diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index e1ef686f4..4351d9508 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -470,70 +470,93 @@ the calculations yourself, instead of just reading it. .SS Prices .SS Transaction prices .PP -Within a transaction posting, you can record an amount\[aq]s price in -another commodity. -This can be used to document the cost (for a purchase), or selling price -(for a sale), or the exchange rate that was used, for this transaction. -These transaction prices are fixed, and do not change over time. +Within a transaction, you can note an amount\[aq]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. .PP -Amounts with transaction prices can be displayed in the transaction -price\[aq]s commodity, by using the \f[C]\-\-cost/\-B\f[] flag supported -by most hledger commands (mnemonic: "cost Basis"). +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). .PP 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: +Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount: .RS 4 .IP .nf \f[C] 2009/1/1 -\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each -\ \ assets:cash +\ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each +\ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00 \f[] .fi .RE .IP "2." 3 -Or write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: +Write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: .RS 4 .IP .nf \f[C] 2009/1/1 -\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot -\ \ assets:cash +\ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot +\ \ assets:dollars \f[] .fi .RE .IP "3." 3 -Or let hledger infer the price so as to balance the transaction. -To permit this, you must fully specify all posting amounts, and their -sum must have a non\-zero amount in exactly two commodities: +Specify amounts for all postings, using exactly two commodities, and let +hledger infer the price that balances the transaction: .RS 4 .IP .nf \f[C] 2009/1/1 -\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros -\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135 +\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased +\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135 \f[] .fi .RE .PP -With any of the above examples we get: +Amounts with transaction prices can be displayed in the transaction +price\[aq]s commodity by using the \f[C]\-B/\-\-cost\f[] flag (except +for #551) ("B" is from "cost Basis"). +Eg for the above, here is how \-B affects the balance report: .IP .nf \f[C] -$\ hledger\ print\ \-B -2009/01/01 -\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00 -\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00 +$\ hledger\ bal\ \-N\ \-\-flat +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +$\ hledger\ bal\ \-N\ \-\-flat\ \-B +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost \f[] .fi .PP -Example use for transaction prices: recording the effective conversion -rate of purchases made in a foreign currency. +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\[aq]s postings are reversed, while the transaction is +equivalent, \-B shows something different: +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ 135\ dollars\ sold +\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ for\ 100\ euros +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ bal\ \-N\ \-\-flat\ \-B +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €\-100\ \ assets:dollars\ \ #\ <\-\ the\ dollars\[aq]\ selling\ price +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi .SS Market prices .PP Market prices are not tied to a particular transaction; they represent diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info index 96989bad4..8d6f1db4f 100644 --- a/hledger-lib/doc/hledger_journal.5.info +++ b/hledger-lib/doc/hledger_journal.5.info @@ -488,48 +488,60 @@ File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, 1.8.1 Transaction prices ------------------------ -Within a transaction posting, you can record an amount's price in -another commodity. This can be used to document the cost (for a -purchase), or selling price (for a sale), or the exchange rate that was -used, for this transaction. These transaction prices are fixed, and do -not change over time. +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. - Amounts with transaction prices can be displayed in the transaction -price's commodity, by using the '--cost/-B' flag supported by most -hledger commands (mnemonic: "cost Basis"). + 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). There are several ways to record a transaction price: - 1. Write the unit price (aka exchange rate), as '@ UNITPRICE' after - the amount: + 1. Write the price per unit, as '@ UNITPRICE' after the amount: 2009/1/1 - assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each - assets:cash + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 - 2. Or write the total price, as '@@ TOTALPRICE' after the amount: + 2. Write the total price, as '@@ TOTALPRICE' after the amount: 2009/1/1 - assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot - assets:cash + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars - 3. Or let hledger infer the price so as to balance the transaction. - To permit this, you must fully specify all posting amounts, and - their sum must have a non-zero amount in exactly two commodities: + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction: 2009/1/1 - assets:foreign currency €100 ; one hundred euros - assets:cash $-135 ; exchanged for $135 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 - With any of the above examples we get: + 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: -$ hledger print -B -2009/01/01 - assets:foreign currency $135.00 - assets:cash $-135.00 +$ hledger bal -N --flat + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost - Example use for transaction prices: recording the effective -conversion rate of purchases made in a foreign currency. + 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: + +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N --flat -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros  File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices @@ -1001,41 +1013,41 @@ Node: Prices18072 Ref: #prices18205 Node: Transaction prices18256 Ref: #transaction-prices18401 -Node: Market prices19978 -Ref: #market-prices20113 -Node: Comments21073 -Ref: #comments21195 -Node: Tags22308 -Ref: #tags22428 -Node: Implicit tags23857 -Ref: #implicit-tags23965 -Node: Directives24482 -Ref: #directives24597 -Node: Account aliases24790 -Ref: #account-aliases24936 -Node: Basic aliases25540 -Ref: #basic-aliases25685 -Node: Regex aliases26375 -Ref: #regex-aliases26545 -Node: Multiple aliases27260 -Ref: #multiple-aliases27434 -Node: end aliases27932 -Ref: #end-aliases28074 -Node: account directive28175 -Ref: #account-directive28357 -Node: apply account directive28653 -Ref: #apply-account-directive28851 -Node: Multi-line comments29510 -Ref: #multi-line-comments29702 -Node: commodity directive29830 -Ref: #commodity-directive30016 -Node: Default commodity30888 -Ref: #default-commodity31063 -Node: Default year31600 -Ref: #default-year31767 -Node: Including other files32190 -Ref: #including-other-files32349 -Node: EDITOR SUPPORT32746 -Ref: #editor-support32866 +Node: Market prices20557 +Ref: #market-prices20692 +Node: Comments21652 +Ref: #comments21774 +Node: Tags22887 +Ref: #tags23007 +Node: Implicit tags24436 +Ref: #implicit-tags24544 +Node: Directives25061 +Ref: #directives25176 +Node: Account aliases25369 +Ref: #account-aliases25515 +Node: Basic aliases26119 +Ref: #basic-aliases26264 +Node: Regex aliases26954 +Ref: #regex-aliases27124 +Node: Multiple aliases27839 +Ref: #multiple-aliases28013 +Node: end aliases28511 +Ref: #end-aliases28653 +Node: account directive28754 +Ref: #account-directive28936 +Node: apply account directive29232 +Ref: #apply-account-directive29430 +Node: Multi-line comments30089 +Ref: #multi-line-comments30281 +Node: commodity directive30409 +Ref: #commodity-directive30595 +Node: Default commodity31467 +Ref: #default-commodity31642 +Node: Default year32179 +Ref: #default-year32346 +Node: Including other files32769 +Ref: #including-other-files32928 +Node: EDITOR SUPPORT33325 +Ref: #editor-support33445  End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index 990f53bc6..fee3fff22 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -380,61 +380,72 @@ instead of just reading it. ### Transaction prices -Within a transaction posting, you can record an amount's price in another commodity. -This can be used to document the cost (for a purchase), or selling price (for a sale), -or the exchange rate that was used, for this transaction. -These transaction prices are fixed, and do not change over time. - - +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. -Amounts with transaction prices can be displayed in the transaction price's -commodity, by using the [`--cost/-B`](hledger.html#reporting-options) flag -supported by most hledger commands (mnemonic: "cost Basis"). +Transaction prices are fixed, and do not change over time. +(Ledger users: Ledger uses a different [syntax](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices) +for fixed prices, `{=UNITPRICE}`, which hledger currently ignores). There are several ways to record a transaction price: -1. Write the unit price (aka exchange rate), as `@ UNITPRICE` after the amount: +1. Write the price per unit, as `@ UNITPRICE` after the amount: ```journal 2009/1/1 - assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each - assets:cash + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 ``` -2. Or write the total price, as `@@ TOTALPRICE` after the amount: +2. Write the total price, as `@@ TOTALPRICE` after the amount: ```journal 2009/1/1 - assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot - assets:cash + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars ``` -3. Or let hledger infer the price so as to balance the transaction. - To permit this, you must fully specify all posting amounts, and - their sum must have a non-zero amount in exactly two commodities: +3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction: ```journal 2009/1/1 - assets:foreign currency €100 ; one hundred euros - assets:cash $-135 ; exchanged for $135 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 ``` -With any of the above examples we get: +Amounts with transaction prices can be displayed in the transaction price's +commodity by using the [`-B/--cost`](hledger.html#reporting-options) flag +(except for [#551](https://github.com/simonmichael/hledger/issues/551)) +("B" is from "cost Basis"). +Eg for the above, here is how -B affects the balance report: ```shell -$ hledger print -B -2009/01/01 - assets:foreign currency $135.00 - assets:cash $-135.00 +$ hledger bal -N --flat + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N --flat -B + $-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 amount. +So if example 3's postings are reversed, while the transaction +is equivalent, -B shows something different: + +```journal +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros +``` +```shell +$ hledger bal -N --flat -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros ``` -Example use for transaction prices: recording the effective conversion -rate of purchases made in a foreign currency. ### Market prices diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index 24e62bcf1..d3585059e 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -364,48 +364,60 @@ FILE FORMAT Prices Transaction prices - Within a transaction posting, you can record an amount's price in - another commodity. This can be used to document the cost (for a pur- - chase), or selling price (for a sale), or the exchange rate that was - used, for this transaction. These transaction prices are fixed, and do - not change over time. + 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. - Amounts with transaction prices can be displayed in the transaction - price's commodity, by using the --cost/-B flag supported by most - hledger commands (mnemonic: "cost Basis"). + 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). There are several ways to record a transaction price: - 1. Write the unit price (aka exchange rate), as @ UNITPRICE after the - amount: + 1. Write the price per unit, as @ UNITPRICE after the amount: 2009/1/1 - assets:foreign currency 100 @ $1.35 ; one hundred euros at $1.35 each - assets:cash + assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 - 2. Or write the total price, as @@ TOTALPRICE after the amount: + 2. Write the total price, as @@ TOTALPRICE after the amount: 2009/1/1 - assets:foreign currency 100 @@ $135 ; one hundred euros at $135 for the lot - assets:cash + assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars - 3. Or let hledger infer the price so as to balance the transaction. To - permit this, you must fully specify all posting amounts, and their - sum must have a non-zero amount in exactly two commodities: + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction: 2009/1/1 - assets:foreign currency 100 ; one hundred euros - assets:cash $-135 ; exchanged for $135 + assets:euros 100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 - With any of the above examples we get: + 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: - $ hledger print -B - 2009/01/01 - assets:foreign currency $135.00 - assets:cash $-135.00 + $ hledger bal -N --flat + $-135 assets:dollars + 100 assets:euros + $ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost - Example use for transaction prices: recording the effective conversion - rate of purchases made in a foreign currency. + 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: + + 2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros 100 ; for 100 euros + + $ hledger bal -N --flat -B + -100 assets:dollars # <- the dollars' selling price + 100 assets:euros Market prices Market prices are not tied to a particular transaction; they represent @@ -734,6 +746,7 @@ EDITOR SUPPORT ting-started Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub- lime-Text + Textmate https://github.com/ledger/ledger/wiki/Using-Text- Mate-2 Text Wrangler https://github.com/ledger/ledger/wiki/Edit-