slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: clarify some transaction price details

Browse Source 
- remove inaccurate print examples
- note #551
- note Ledger's fixed price syntax
- note how posting order can affect -B
- edits for clarity
This commit is contained in:
Simon Michael 2017-05-22 17:32:33 -07:00
parent 7bc5ef3df0
commit a5b545c4eb
4 changed files with 208 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
hledger-lib/doc/hledger_journal.5
View File

@ -470,70 +470,93 @@ the calculations yourself, instead of just reading it.
.SS Prices .SS Prices
.SS Transaction prices .SS Transaction prices
.PP .PP
Within a transaction posting, you can record an amount\[aq]s price in Within a transaction, you can note an amount\[aq]s price in another
another commodity. commodity.
This can be used to document the cost (for a purchase), or selling price This can be used to document the cost (in a purchase) or selling price
(for a sale), or the exchange rate that was used, for this transaction. (in a sale).
These transaction prices are fixed, and do not change over time. For example, transaction prices are useful to record purchases of a
foreign currency.
.PP .PP
Amounts with transaction prices can be displayed in the transaction Transaction prices are fixed, and do not change over time.
price\[aq]s commodity, by using the \f[C]\-\-cost/\-B\f[] flag supported (Ledger users: Ledger uses a different syntax for fixed prices,
by most hledger commands (mnemonic: "cost Basis"). \f[C]{=UNITPRICE}\f[], which hledger currently ignores).
.PP .PP
There are several ways to record a transaction price: There are several ways to record a transaction price:
.IP "1." 3 .IP "1." 3
Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[] Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount:
after the amount:
.RS 4 .RS 4
.IP .IP
.nf .nf
\f[C] \f[C]
2009/1/1 2009/1/1
\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each \ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each
\ \ assets:cash \ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00
\f[] \f[]
.fi .fi
.RE .RE
.IP "2." 3 .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 .RS 4
.IP .IP
.nf .nf
\f[C] \f[C]
2009/1/1 2009/1/1
\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot \ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot
\ \ assets:cash \ \ assets:dollars
\f[] \f[]
.fi .fi
.RE .RE
.IP "3." 3 .IP "3." 3
Or let hledger infer the price so as to balance the transaction. Specify amounts for all postings, using exactly two commodities, and let
To permit this, you must fully specify all posting amounts, and their hledger infer the price that balances the transaction:
sum must have a non\-zero amount in exactly two commodities:
.RS 4 .RS 4
.IP .IP
.nf .nf
\f[C] \f[C]
2009/1/1 2009/1/1
\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros \ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135 \ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135
\f[] \f[]
.fi .fi
.RE .RE
.PP .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 .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ print\ \-B $\ hledger\ bal\ \-N\ \-\-flat
2009/01/01 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars
\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00 $\ hledger\ bal\ \-N\ \-\-flat\ \-B
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost
\f[] \f[]
.fi .fi
.PP .PP
Example use for transaction prices: recording the effective conversion Note \-B is sensitive to the order of postings when a transaction price
rate of purchases made in a foreign currency. 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 .SS Market prices
.PP .PP
Market prices are not tied to a particular transaction; they represent Market prices are not tied to a particular transaction; they represent

138
hledger-lib/doc/hledger_journal.5.info
View File

@ -488,48 +488,60 @@ File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices,
1.8.1 Transaction prices 1.8.1 Transaction prices
------------------------ ------------------------
Within a transaction posting, you can record an amount's price in Within a transaction, you can note an amount's price in another
another commodity. This can be used to document the cost (for a commodity. This can be used to document the cost (in a purchase) or
purchase), or selling price (for a sale), or the exchange rate that was selling price (in a sale). For example, transaction prices are useful
used, for this transaction. These transaction prices are fixed, and do to record purchases of a foreign currency.
not change over time.
Amounts with transaction prices can be displayed in the transaction Transaction prices are fixed, and do not change over time. (Ledger
price's commodity, by using the '--cost/-B' flag supported by most users: Ledger uses a different syntax for fixed prices, '{=UNITPRICE}',
hledger commands (mnemonic: "cost Basis"). which hledger currently ignores).
There are several ways to record a transaction price: There are several ways to record a transaction price:
1. Write the unit price (aka exchange rate), as '@ UNITPRICE' after 1. Write the price per unit, as '@ UNITPRICE' after the amount:
the amount:
2009/1/1 2009/1/1
assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:cash 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 2009/1/1
assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
assets:cash assets:dollars
3. Or let hledger infer the price so as to balance the transaction. 3. Specify amounts for all postings, using exactly two commodities,
To permit this, you must fully specify all posting amounts, and and let hledger infer the price that balances the transaction:
their sum must have a non-zero amount in exactly two commodities:
2009/1/1 2009/1/1
assets:foreign currency €100 ; one hundred euros assets:euros €100 ; one hundred euros purchased
assets:cash $-135 ; exchanged for $135 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 $ hledger bal -N --flat
2009/01/01 $-135 assets:dollars
assets:foreign currency $135.00 €100 assets:euros
assets:cash $-135.00 $ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
Example use for transaction prices: recording the effective Note -B is sensitive to the order of postings when a transaction
conversion rate of purchases made in a foreign currency. 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 File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices
@ -1001,41 +1013,41 @@ Node: Prices18072
Ref: #prices18205 Ref: #prices18205
Node: Transaction prices18256 Node: Transaction prices18256
Ref: #transaction-prices18401 Ref: #transaction-prices18401
Node: Market prices19978 Node: Market prices20557
Ref: #market-prices20113 Ref: #market-prices20692
Node: Comments21073 Node: Comments21652
Ref: #comments21195 Ref: #comments21774
Node: Tags22308 Node: Tags22887
Ref: #tags22428 Ref: #tags23007
Node: Implicit tags23857 Node: Implicit tags24436
Ref: #implicit-tags23965 Ref: #implicit-tags24544
Node: Directives24482 Node: Directives25061
Ref: #directives24597 Ref: #directives25176
Node: Account aliases24790 Node: Account aliases25369
Ref: #account-aliases24936 Ref: #account-aliases25515
Node: Basic aliases25540 Node: Basic aliases26119
Ref: #basic-aliases25685 Ref: #basic-aliases26264
Node: Regex aliases26375 Node: Regex aliases26954
Ref: #regex-aliases26545 Ref: #regex-aliases27124
Node: Multiple aliases27260 Node: Multiple aliases27839
Ref: #multiple-aliases27434 Ref: #multiple-aliases28013
Node: end aliases27932 Node: end aliases28511
Ref: #end-aliases28074 Ref: #end-aliases28653
Node: account directive28175 Node: account directive28754
Ref: #account-directive28357 Ref: #account-directive28936
Node: apply account directive28653 Node: apply account directive29232
Ref: #apply-account-directive28851 Ref: #apply-account-directive29430
Node: Multi-line comments29510 Node: Multi-line comments30089
Ref: #multi-line-comments29702 Ref: #multi-line-comments30281
Node: commodity directive29830 Node: commodity directive30409
Ref: #commodity-directive30016 Ref: #commodity-directive30595
Node: Default commodity30888 Node: Default commodity31467
Ref: #default-commodity31063 Ref: #default-commodity31642
Node: Default year31600 Node: Default year32179
Ref: #default-year31767 Ref: #default-year32346
Node: Including other files32190 Node: Including other files32769
Ref: #including-other-files32349 Ref: #including-other-files32928
Node: EDITOR SUPPORT32746 Node: EDITOR SUPPORT33325
Ref: #editor-support32866 Ref: #editor-support33445
 
End Tag Table End Tag Table

75
hledger-lib/doc/hledger_journal.5.m4.md
View File

@ -380,61 +380,72 @@ instead of just reading it.
### Transaction prices ### Transaction prices
Within a transaction posting, you can record an amount's price in another commodity. Within a transaction, you can note an amount's price in another commodity.
This can be used to document the cost (for a purchase), or selling price (for a sale), This can be used to document the cost (in a purchase) or selling price (in a sale).
or the exchange rate that was used, for this transaction. For example, transaction prices are useful to record purchases of a foreign currency.
These transaction prices are fixed, and do not change over time.
<!--
This is different from Ledger, where transaction prices fluctuate by
default. Ledger has a different syntax for specifying
[fixed prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices):
`{=PRICE}`. hledger parses that syntax, and (currently) ignores it.
-->
<!-- hledger treats this as an alternate spelling of `@ PRICE`, for greater compatibility with Ledger files. -->
Amounts with transaction prices can be displayed in the transaction price's Transaction prices are fixed, and do not change over time.
commodity, by using the [`--cost/-B`](hledger.html#reporting-options) flag (Ledger users: Ledger uses a different [syntax](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices)
supported by most hledger commands (mnemonic: "cost Basis"). for fixed prices, `{=UNITPRICE}`, which hledger currently ignores).
There are several ways to record 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: 1. Write the price per unit, as `@ UNITPRICE` after the amount:
```journal ```journal
2009/1/1 2009/1/1
assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:cash 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 ```journal
2009/1/1 2009/1/1
assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
assets:cash assets:dollars
``` ```
3. Or let hledger infer the price so as to balance the transaction. 3. Specify amounts for all postings, using exactly two commodities,
To permit this, you must fully specify all posting amounts, and and let hledger infer the price that balances the transaction:
their sum must have a non-zero amount in exactly two commodities:
```journal ```journal
2009/1/1 2009/1/1
assets:foreign currency €100 ; one hundred euros assets:euros €100 ; one hundred euros purchased
assets:cash $-135 ; exchanged for $135 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 ```shell
$ hledger print -B $ hledger bal -N --flat
2009/01/01 $-135 assets:dollars
assets:foreign currency $135.00 €100 assets:euros
assets:cash $-135.00 $ 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 ### Market prices

67
hledger-lib/doc/hledger_journal.5.txt
View File

@ -364,48 +364,60 @@ FILE FORMAT
Prices Prices
Transaction prices Transaction prices
Within a transaction posting, you can record an amount's price in Within a transaction, you can note an amount's price in another commod-
another commodity. This can be used to document the cost (for a pur- ity. This can be used to document the cost (in a purchase) or selling
chase), or selling price (for a sale), or the exchange rate that was price (in a sale). For example, transaction prices are useful to
used, for this transaction. These transaction prices are fixed, and do record purchases of a foreign currency.
not change over time.
Amounts with transaction prices can be displayed in the transaction Transaction prices are fixed, and do not change over time. (Ledger
price's commodity, by using the --cost/-B flag supported by most users: Ledger uses a different syntax for fixed prices, {=UNITPRICE},
hledger commands (mnemonic: "cost Basis"). which hledger currently ignores).
There are several ways to record a transaction price: There are several ways to record a transaction price:
1. Write the unit price (aka exchange rate), as @ UNITPRICE after the 1. Write the price per unit, as @ UNITPRICE after the amount:
amount:
2009/1/1 2009/1/1
assets:foreign currency 100 @ $1.35 ; one hundred euros at $1.35 each assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:cash 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 2009/1/1
assets:foreign currency 100 @@ $135 ; one hundred euros at $135 for the lot assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot
assets:cash assets:dollars
3. Or let hledger infer the price so as to balance the transaction. To 3. Specify amounts for all postings, using exactly two commodities, and
permit this, you must fully specify all posting amounts, and their let hledger infer the price that balances the transaction:
sum must have a non-zero amount in exactly two commodities:
2009/1/1 2009/1/1
assets:foreign currency 100 ; one hundred euros assets:euros 100 ; one hundred euros purchased
assets:cash $-135 ; exchanged for $135 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 $ hledger bal -N --flat
2009/01/01 $-135 assets:dollars
assets:foreign currency $135.00 100 assets:euros
assets:cash $-135.00 $ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
Example use for transaction prices: recording the effective conversion Note -B is sensitive to the order of postings when a transaction price
rate of purchases made in a foreign currency. 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
Market prices are not tied to a particular transaction; they represent Market prices are not tied to a particular transaction; they represent
@ -734,6 +746,7 @@ EDITOR SUPPORT
ting-started ting-started
Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub- Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub-
lime-Text lime-Text
Textmate https://github.com/ledger/ledger/wiki/Using-Text- Textmate https://github.com/ledger/ledger/wiki/Using-Text-
Mate-2 Mate-2
Text Wrangler https://github.com/ledger/ledger/wiki/Edit- Text Wrangler https://github.com/ledger/ledger/wiki/Edit-