From 18e5c9d5c9b1d379d4d38ec84ba3c67c32f89b08 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 3 May 2018 13:11:17 -0700 Subject: [PATCH] doc: move market price docs under directives --- hledger-lib/hledger_journal.m4.md | 85 ++++++++++++++++--------------- hledger/hledger_options.m4.md | 10 ++-- 2 files changed, 49 insertions(+), 46 deletions(-) diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 5380c1126..57703e5d3 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -302,7 +302,7 @@ Though journal may contain mixed styles to represent amount, when hledger displa - otherwise the format is inferred from the first posting amount in that commodity in the journal, and the precision (number of decimal places) 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 `$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. ## Virtual Postings @@ -459,17 +459,13 @@ to know the exact amount posted, you have to run hledger or do the calculations instead of just reading it. -## Prices - -### Transaction prices +## 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](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices) -for fixed prices, `{=UNITPRICE}`, 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](#market-prices), which represent prevailing exchange rates on a certain date. There are several ways to record a transaction price: @@ -498,11 +494,13 @@ There are several ways to record a transaction price: assets:dollars $-135 ; for $135 ``` -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: +(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). + +Use the [`-B/--cost`](hledger.html#reporting-options) 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: ```shell $ hledger bal -N --flat @@ -529,33 +527,6 @@ $ hledger bal -N --flat -B €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](https://en.wikipedia.org/wiki/Stock_exchange) -or the [foreign exchange market](https://en.wikipedia.org/wiki/Foreign_exchange_market). -hledger can use these prices to show the market value of things at a given date, see [market value](#market-value). - -To record market prices, use P directives in the main journal or -in an [included](#including-other-files) file. Their format is: -```journal -P DATE COMMODITYBEINGPRICED UNITPRICE -``` - -DATE is a [simple date](#simple-dates) as usual. -COMMODITYBEINGPRICED is the symbol of the commodity being priced. -UNITPRICE is an ordinary [amount](#amounts) (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: -```journal -P 2009/1/1 € $1.35 -P 2010/1/1 € $1.40 -``` - ## Comments Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or @@ -728,9 +699,9 @@ Towards this end, amounts in commodity directives must always be written with a ### Default commodity -The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). +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. +The commodity and display format will be applied to all subsequent commodity-less amounts, or until the next `D` directive. ```journal # commodity-less amounts should be treated as dollars @@ -744,6 +715,36 @@ D $1,000.00 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](https://en.wikipedia.org/wiki/Stock_exchange), +cryptocurrency exchange, or the +[foreign exchange market](https://en.wikipedia.org/wiki/Foreign_exchange_market). + +Here is the format: + +```journal +P DATE COMMODITYA COMMODITYBAMOUNT +``` +- DATE is a [simple date](#simple-dates) +- COMMODITYA is the symbol of the commodity being priced +- COMMODITYBAMOUNT is an [amount](#amounts) (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: +```journal +P 2009/1/1 € $1.35 +P 2010/1/1 € $1.40 +``` + +The [`-V/--value`](manual.html#market-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 `account ACCTNAME`, eg: diff --git a/hledger/hledger_options.m4.md b/hledger/hledger_options.m4.md index adcf27dc7..6b2cd7532 100644 --- a/hledger/hledger_options.m4.md +++ b/hledger/hledger_options.m4.md @@ -378,10 +378,12 @@ if they have a [transaction price](/journal.html#transaction-prices) specified. ## Market value -The `-V/--value` flag converts reported amounts to their current market value. -Specifically, when there is a [market price](journal.html#market-prices) (P directive) for the amount's commodity, -dated on or before today's date (or the [report end date](#report-start-end-date) if specified), -the amount will be converted to the price's commodity. +The `-V/--value` flag converts reported amounts to their current market value. +Specifically, when there is a +[market price](journal.html#market-prices) (P directive) for the +amount's commodity, dated on or before today's date (or the +[report end date](#report-start-end-date) if specified), the amount +will be converted to the price's commodity. When there are multiple applicable P directives, -V chooses the most recent one, or in case of equal dates, the last-parsed one.