gnucash-docs maint: Elaborate and correct the descriptions of the report price source option.
John Ralls
jralls at code.gnucash.org
Thu Aug 30 17:27:57 EDT 2018
Updated via https://github.com/Gnucash/gnucash-docs/commit/05227420 (commit)
from https://github.com/Gnucash/gnucash-docs/commit/a201379d (commit)
commit 052274207e2b565fb13c6ea8b415668b878d326d
Author: John Ralls <jralls at ceridwen.us>
Date: Thu Aug 30 14:26:56 2018 -0700
Elaborate and correct the descriptions of the report price source option.
diff --git a/guide/C/ch_invest.xml b/guide/C/ch_invest.xml
index 0934f37..90b9b91 100644
--- a/guide/C/ch_invest.xml
+++ b/guide/C/ch_invest.xml
@@ -1470,14 +1470,12 @@ Income
</sect2>
<sect2 id="invest-stockprice-report">
- <title>Selecting <quote>Price Source</quote> in Stock Value Reports</title>
+ <title>The <quote>Price Source</quote> in Reports</title>
- <para>Most <application>&app;</application> Asset reports have options to set/modify a number of parameters for the report. The
- Options windows is displayed by selecting the report tab then clicking on either the <guibutton>Options</guibutton>
+ <para>Most <application>&app;</application> reports have options to set/modify a number of parameters for the report. The
+ Options dialog box is displayed by selecting the report tab then clicking on either the <guibutton>Options</guibutton>
icon in the <emphasis>Menubar</emphasis> or selecting <menuchoice><guimenu>Edit</guimenu><guimenuitem>Report Options</guimenuitem></menuchoice>.
- The <guilabel>General</guilabel> tab in the
- resulting window contains various parameters for the report. One of these is <quote>Price Source</quote> which of offers
- three alternatives to determine stock prices in reports:</para>
+ <guilabel>Price Source</guilabel> determines how accounts denominated in commodities different from the report currency are converted to the report currency. Depending on the report the selector may appear in either the <guilabel>General</guilabel>, the <guilabel>Commodities</guilabel>, or the <guilabel>Display</guilabel> tab of the <guilabel>Report Options</guilabel> dialog box.
<note>
<para>In the example below, the report is a customization of
the <emphasis role="strong">Average Balance</emphasis> report
@@ -1487,41 +1485,46 @@ Income
<mediaobject>
<imageobject>
<imagedata fileref="figures/invest_stockvalue_report_options.png"
- format="PNG" srccredit="Dave Herman" ></imagedata>
+ format="PNG" srccredit="John Ralls" ></imagedata>
</imageobject>
<textobject>
- <phrase>Determining Stock Price Source in Reports</phrase>
+ <phrase>Determining Stock Price/Currency Exchange Rate Source in Reports</phrase>
</textobject>
- <caption><para>Determining the value of a stock commodity in a
- report by setting the Price Source option.</para></caption>
+ <caption><para>Determining the value of a stock commodity or
+ a currency other than the report currency in a report by
+ setting the Price Source option.</para></caption>
</mediaobject>
</screenshot>
<itemizedlist>
<listitem>
- <para><guilabel>Weighted Average</guilabel> - gives you a graph of
- the weighted price of all <emphasis>transactions</emphasis>. It will
- <emphasis>not</emphasis> take into account prices defined in the
- price editor.</para>
+ <para><guilabel>Weighted Average</guilabel>: Calculates the price by summing the absolute value of the amount and the absolute value of every split in every account denominated in the commodity, excluding those splits with a zero amount, and dividing the sum of values by the sum of amounts to obtain a price. For example, if you had a buy transaction for 200 shares of XYZ for a total of 2000 and a sell of 100 for 1300 the weighted average would be 3300/300 or 11/share.
+ </para>
+ <note><para>Gain/Loss splits have an amount of 0 and are <emphasis>not</emphasis> included in this calculation.</para></note>
</listitem>
-
<listitem>
- <para><guilabel>Most recent</guilabel> - displays the changing value
- of your stocks based solely on <emphasis>the most recent</emphasis>
- price available from the price editor. The price figuring in your
- stock transactions is <emphasis>not</emphasis> considered.</para>
+ <para><guilabel>Average Cost</guilabel>: Calculates the price by summing the amounts and values of every split in every account denominated in the commodity, including the zero amount splits. In the example above, with an additional split (either part of the sale transaction or in a separate transaction) booking the gain at 0 shares and a 300 gain, the average cost is 1000/100 (2000 original cost - 1300 proceeds from the sale + 300 gain)/(200 - 100) shares or 10/share.
+ </para>
+
+ <note><para>Gain/Loss splits <emphasis>are</emphasis> included in this calculation.
+ </para></note>
+ <note><para>This is the <emphasis>only</emphasis> <guilabel>Price Source</guilabel> that will balance the <guilabel>Trial Balance Report</guilabel> and in order for it to balance you <emphasis>must</emphasis> correctly book your gains and losses.
+ </para></note>
+ </listitem>
+ <listitem>
+ <para><guilabel>Most Recent</guilabel>: Uses the latest price from the price database.</para>
</listitem>
<listitem>
- <para><guilabel>Nearest in time</guilabel> - the graph is
- exclusively based on the prices available from the price editor. The
- value of your stock at each step and point in time is calculated
- based on the nearest available price in the price editor.</para>
+ <para><guilabel>Nearest in time</guilabel>: Uses the price nearest in time to the report date—the datum date for time series reports like <guilabel>Assets Over Time</guilabel>—from the price database.
+ </para>
+ <note><para>The nearest date isn’t necessarily before the date in question.
+ </para></note>
</listitem>
</itemizedlist>
-
+ </para>
<screenshot id="invest-stockvalue-report">
<mediaobject>
<imageobject>
diff --git a/guide/C/figures/invest_stockvalue_report_options.png b/guide/C/figures/invest_stockvalue_report_options.png
index 69dfbf8..2672d69 100644
Binary files a/guide/C/figures/invest_stockvalue_report_options.png and b/guide/C/figures/invest_stockvalue_report_options.png differ
diff --git a/help/C/Help_ch_Reports.xml b/help/C/Help_ch_Reports.xml
index 01847d5..a7c6451 100644
--- a/help/C/Help_ch_Reports.xml
+++ b/help/C/Help_ch_Reports.xml
@@ -278,9 +278,14 @@
</listitem>
<listitem>
- <para>Price Source: Select how stock and currency prices are calculated in this
- report. Choose between a weighted average of prices over all transactions, prices
- at current values, or prices at the time of the report date.</para>
+ <para>Price Source: Select how stock and currency prices are calculated in this report. Choose between:
+ <itemizedlist>
+ <listitem><para>Nearest in time (default for most reports): A price retreived from the prices database on the date nearest to the date of the report or of the datum for time-series reports.</para></listitem>
+ <listitem><para>Most recent: The latest price in the price database.</para></listitem>
+ <listitem><para>Average Cost: The amount-weighted<emphasis>net</emphasis> average of <emphasis>all</emphasis> splits exchanging the commodity for another <emphasis>regardless of account</emphasis>. Gain/loss splits are included in the calculation.</para></listitem>
+ <listitem><para>Weighted Average: The <emphasis>gross</emphasis> amount-weighted average price of <emphasis>all</emphasis> splits exchanging the commodity for another <emphasis>regardless of account</emphasis>. Gain/Loss splits are <emphasis>not</emphasis> in the calculation.</para></listitem>
+ </itemizedlist>
+ More information on Average Cost and Weighted Average may be found in the Investments chapter of The Tutorial and Concepts Guide.</para>
</listitem>
<listitem>
@@ -1168,11 +1173,10 @@
<tgroup cols="2">
<tbody>
<row><entry>Average Cost</entry><entry>The
- volume-weighted average cost of purchases</entry>
+ volume-weighted net average price of all exchanges.</entry>
</row>
<row><entry>Weighted Average (default)</entry><entry>
- The weighted average of all currency transactions
- in the past</entry>
+ The volume-weighted gross average price of all exchanges up to the date of the report</entry>
</row>
<row><entry>Most recent</entry><entry>The most recent
recorded price</entry>
@@ -1360,11 +1364,10 @@
<tgroup cols="2">
<tbody>
<row><entry>Average Cost</entry><entry>The
- volume-weighted average cost of purchases</entry>
+ volume-weighted net average price of all exchanges</entry>
</row>
<row><entry>Weighted Average (default)</entry><entry>
- The weighted average of all currency transactions
- in the past</entry>
+ The volume-weighted gross average price of all exchagnes</entry>
</row>
<row><entry>Most recent</entry><entry>The most recent
recorded price</entry>
Summary of changes:
guide/C/ch_invest.xml | 51 +++++++++++----------
.../C/figures/invest_stockvalue_report_options.png | Bin 57391 -> 81599 bytes
help/C/Help_ch_Reports.xml | 21 +++++----
3 files changed, 39 insertions(+), 33 deletions(-)
More information about the gnucash-changes
mailing list