<!--
      (Do not remove this comment block.)
  Version: 1.8.4
  Last modified: April 10th 2004
  Maintainers: 
               Chris Lyttle <chris@wilddev.net>
  Author:
  		Jon Lapham <lapham@extracta.com.br>
  Originally designed by Carol Champagne.
  Translators:
               (translators put your name and email here)
-->
 <chapter id="chapter8">
 <title>Investments</title>
 <para>
 This chapter explains how to manage your investments with GnuCash. Most people have an investment plan, whether its just putting money into a CD account, investing through a company sponsored plan at your workplace or buying and selling stocks and bonds through a brokerage. GnuCash gives you tools to help you manage these investments such as the <emphasis>Price Editor </emphasis> which allows you to record changes in the prices of stocks you own.
  </para>
 <sect1 id="invest_concepts1">
 <title>Basic Concepts</title>
 <para>
An investment is something that you purchase in the hopes of generating income, or that you hope to sell in the future for more than you paid.  Using this simple definition, many things could be considered investments: the house you live in, a valuable painting, stocks in publicly traded companies, your savings account at the bank, or a certificate of deposit.  These many types of investments will be discussed in this chapter in terms of how to track them using GnuCash.
 </para>

 <sect2 id="invest_terms2">
 <title>Terminology</title>
  <para>
Before discussing investments specifically, it will be helpful to present a glossary of investment terminology.  The terms presented below represent some of the basic concepts of investing.  It is a good idea to become familiar with these terms, or at least, refer back to this list if you encounter an unfamiliar word in the later sections.
  </para>

  <itemizedlist>

  <listitem>
  <para>
<emphasis>Capital gains</emphasis> is the difference between the purchase and selling prices of an investment.  If the selling price is lower than the purchase price, this is called a <emphasis>capital loss</emphasis>.  Also known as <emphasis>realized gain/loss</emphasis>.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Commission</emphasis> is the fee you pay to a broker to buy or sell securities.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Common stock</emphasis> is a security that represents a certain fractional ownership of a company.  This is what you buy when you "buy stock" in a company on the open market.  This is also sometimes known as <emphasis>capital stock</emphasis>. 
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Compounding</emphasis> is the concept that the reinvested interest can later earn interest of its own (interest on interest).  This is often referred to as <emphasis>compound interest</emphasis>.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Dividends</emphasis> are cash payments a company makes to shareholders.  The amount of this payment is usually determined as some amount of the profits the company.  Note that not all common stocks give dividends.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Equities</emphasis> are investments in which the investor becomes part (or whole) owner in something.  This includes common stock in a company, or real estate.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Interest</emphasis> is what a borrower pays a lender for the use of their money.  Normally, this is expressed in terms of a percentage of the principal per year.  For example, a savings account with 1% interest (you are the lender, the bank is the borrower) will pay you $1 for every $100 you keep there per year. 
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Liquidity</emphasis> is a measure of how easily convertible an investment is to cash.  Money in a savings account is very liquid, while money invested in a house has low liquidity because it takes time to sell a house.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Principal</emphasis> is the original amount of money invested or borrowed.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Realized vs Unrealized Gain/Loss</emphasis>, unrealized gain or loss occurs when you've got a change in price of an asset.  You realize the gain/loss when you actually sell the asset.  See also <emphasis>capital gain/loss</emphasis>.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Return</emphasis> is the total income plus capital gains or losses of an investment.  See yield.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Risk</emphasis> is the probability that the return on investment is different from what was expected.  Investments are often grouped on a scale from low risk (savings account, government bonds) to high risk (common stock, junk bonds).  As a general rule of thumb, the higher the risk the higher the possible return.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Shareholder</emphasis> is a person who holds common stock in a company.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Stock split</emphasis> occurs when a company offers to issue some additional multiple of shares for each existing stock.  For example, a "2 for 1" stock split means that if you own 100 shares of a stock, you will receive an additional 100 at no cost to you.  The unit price of the share will be adjusted so there is no net change in the value, so in this example the price per share will be halved.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Valuation</emphasis> is the process of determining the sell value of an investment.
 </para>
 </listitem>

  <listitem>
  <para>
<emphasis>Yield</emphasis> is a measure of the amount of money you earn from an investment (IE: how much income you receive from the investment).  Typically this is reported as a percentage of the principal amount.  Yield does not include capital gains or loses (see Return).  Eg: A stock sells for $100 and gives $2 in dividends per year has a yield of 2%.
 </para>
 </listitem>

 </itemizedlist>
  </sect2>


 <sect2 id="invest_types2">
 <title>Types of Investments</title>
  <para>
Below is presented some of the broad types of investments available, and examples of each type.  
 </para>
  <itemizedlist>
  <listitem>
  <para>
<emphasis>Interest-bearing account or instrument</emphasis>
  </para>
  <para>
This type of investment usually allows you immediate access to your money, and will typically pay you interest every month based on the amount of money you have saved.  Examples are bank savings accounts (and some interest bearing checking accounts) and cash accounts at your brokerage.  This is a very low risk investment, in the US these accounts are often insured against loss.
  </para>
  <para>
Sometimes an interest bearing investment is <emphasis>time-locked</emphasis>.  This type of investment requires you to commit your money to be invested for a given period of time for which you receive a set rate of return.  Usually, the longer you commit the higher the interest rates.  If you withdraw your money before the maturity date, you will usually have to pay an early withdrawal penalty.  This is a low risk investment.  Examples are certificates of deposit or some government bonds.
  </para>
  </listitem>
  <listitem>
  <para>
<emphasis>Stocks and Mutual Funds</emphasis>
  </para>
  <para>
This is an investment you make in a company, in which you effectively become a part owner.  There is usually no time lock on publicly traded stock, however there may be changes in the tax rates you pay on capital gains depending on how long you hold the stock.  Thus, stocks are typically quite liquid, you can access your money relatively quickly.  This investment is high risk, as you have no guarantee what the future price of a stock could be.
  </para>
  <para>
A mutual fund is a group investment mechanism in which you can buy into many stocks simultaneously.  For example, a "S&amp;P 500 index fund" is a fund which purchases all 500 stocks listed in the Standard and Poor's index.  When you buy a share of this fund, you are really buying a small amount of each of the 500 stocks contained within the fund.  Mutual funds are treated exactly like a single stock, both for tax purposes and in accounting.
  </para>
  </listitem>
  <listitem>
  <para>
<emphasis>Fixed Assets</emphasis>
  </para>
  <para>
An asset that increase in value over time are another form of investment.  Examples include a house, a plot of land, or a valuable painting.  This type of investment is very difficult to determine the value of until you sell it.  The tax implications of selling these items is varied, depending on the item.  For example, you may have tax relief from selling a house if it is your primary residence, but may would not receive this tax break on an expensive painting.
  </para>
  <para>Fixed asset investments are discussed in the chapter on "Depreciation and Capital Gains".  Typically, there is not much to do in terms of accounting for fixed asset investments except record the buying and selling transactions.</para>
  </listitem>
  </itemizedlist>

 </sect2>
 </sect1>

 <sect1 id="invest_accounts1">
 <title>Setting Up Accounts</title>
 <para>
To setup investment accounts in GnuCash you can either use the predefined investment account hierarchy or create your own.  The minimum you need to do to track investments is to setup an asset account for each type of investment you own.  However, as we have seen in previous chapters, it is usually more logical to create a structured account hierarchy, grouping related investments together.  For example, you may want to group all your publicly traded stocks under a parent account named after the brokerage firm you used to buy the stocks.
 </para>
 <para>
Regardless of how you setup your account hierarchy, remember that you can always move accounts around later (without losing the work you've put into them), so your initial account hierarchy does not have to be perfect.
 </para>

 <sect2 id="invest_predefined2">
 <title>Predefined Accounts</title>
 <para>
To use the predefined investment account hierarchy, you must create a new GnuCash file.   This will run the <guilabel>New Account Hierarchy Setup</guilabel> druid.  After choosing the default currency to use, you will be asked to <guilabel>Choose accounts to create</guilabel>.  At this point, choose the "Investment Accounts" option (along with any others you are interested in).  This will create an account hierarchy as shown below.
 <literallayout>
- Assets
   - Investments
      - Brokerage Accounts
         - Mutual Funds
         - Market Index
         - Stock
         - Bond
- Income
   - Interest Income
      - Bond Interest
   - Dividend Income
- Expenses
   - Commissions
 </literallayout>
 </para>
 <para>
You will probably at least want to add a <emphasis>Bank</emphasis> account to the Assets and probably an <emphasis>Equity:Starting Values</emphasis> account, as we have done in previous chapters.
 </para>
 </sect2>

 <sect2 id="invest_custom2">
 <title>Custom Accounts Example</title>
 <para>
You can also manually setup your own investment account hierarchy.  The following is a somewhat more complicated example of setting up GnuCash to track your investments, which has the advantage that it groups each different investment under the brokerage that deals with the investments.  This way it is easier to compare the statements you get from your brokerage with the accounts you have in GnuCash and spot where GnuCash differs from the statement.
 <literallayout>
- Assets
   - Investments
      - Brokerage Accounts
         - I*Trade
            - Stocks
               - ACME Corp
            - Money Market Funds
               - I*Trade Municipal Fund
            - Cash
         - My Stockbroker
            - Money Market Funds
               - Active Assets Fund
            - Government Securities
               - Treas Bond xxx
               - Treas Note yyy
            - Mutual Funds
               - Fund A
               - Fund B
            - Cash
- Income
   - Investments
      - Brokerage Accounts
         - Capital Gains
            - I*Trade
            - My Stockbroker
         - Dividends
            - I*Trade
               - Taxable
               - Non-taxable
            - My Stockbroker
               - Taxable
               - Non-taxable
         - Interest Income
            - I*Trade
               - Taxable
               - Non-taxable
            - My Stockbroker
               - Taxable
               - Non-taxable
- Expenses
   - Investment Expenses
      - Commissions
         - I*Trade
         - My Stockbroker
      - Management Fees
         - I*Trade
         - My Stockbroker
 </literallayout>
 </para>
 <para>
There really is no unique way to set up your investment account hierarchy.  Play around, try different layouts until you find something which divides your investment accounts into logical groups which make sense to you.
 </para>

 </sect2>
 </sect1>


 <sect1 id="invest_int1">
 <title>Interest Bearing Accounts</title>
 <para>
Investments which have a fixed or variable rate of interest are one of the simplest and most common form of investments available.  Interest bearing investments include your bank account, a certificate of deposit, or any other kind of investment in which you receive interest from the principal.  This section will describe how to handle these kinds of investments in GnuCash.
 </para>
 <sect2 id="invest_intacct2">
 <title>Account Setup</title>
 <para>
When you purchase the interest bearing investment, you must create an asset account to record the purchase of the investment, an income account to record earnings from interest, and an expense account to record bank charges.  Below is an account layout example, in which you have an interest bearing savings account and a certificate of deposit at your bank.
 </para>
  <literallayout>
-Asset
   -Bank
      -CD
      -Savings
-Expenses
   -Bank
      -Charges
-Income
   -Bank
      -Interest
  </literallayout>
  <para>
As usual, this account hierarchy is simply presented as an example, you should create your accounts in a form which best matches your actual situation.
  </para>
  </sect2>
 <sect2 id="invest_intex2">
 <title>Example</title>
 <para>
Now let's populate these accounts with real numbers.  Let's assume that you start with $10000 in your bank account, which pays 1% interest and you buy a $5000 certificate of deposit with a 1 year maturity date and a 2% yield.  Clearly, it is much better to keep your money in the CD than in the savings account.  After the initial purchase, your accounts should look something like this:
 </para>
	<screenshot id="invest_int">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_int1.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Setup Interest Investment</phrase>
	    </textobject>
	    <caption>
	       <para>This image the creation of the interest investment account
	       </para>
	    </caption>
          </mediaobject>
        </screenshot>

  <para>
Now, during the course of the next year, you receive monthly bank statements which describe the activity of your account.  In our fictional example, we do nothing with the money at this bank, so the only activity is income from interest and bank charges.  The monthly bank charges are $2.  After 12 months, the register window for the CD should look like this:
  </para>
	<screenshot id="invest_int2">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_int2.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Setup Interest Investment</phrase>
	    </textobject>
	    <caption>
	       <para>This image the creation of the interest investment account
	       </para>
	    </caption>
          </mediaobject>
        </screenshot>
  <para>
And this is the main GnuCash window:
  </para> 
	<screenshot id="invest_int3">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_int3.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Setup Interest Investment</phrase>
	    </textobject>
	    <caption>
	       <para>This image the creation of the interest investment account
	       </para>
	    </caption>
          </mediaobject>
        </screenshot>
  <para>
From the above image of the main GnuCash account window you see a nice summary of what happened to these investments over the 6 months.  While the yield on the CD is double that of the savings account, the return on the CD was $50.21 versus $13.03 for the savings account, or almost 4 times more.  Why?  Because of the pesky $2 bank charges that hit the savings account (which counted for $12 over 6 months).
  </para> 
  <para>
After this 6 month period, the CD has reached maturity which means you may sell it with no early withdrawal penalty.  To do so, simply transfer the $5050.21 from the CD account into the savings account.
  </para>
  </sect2>
 </sect1>

 <sect1 id="invest_setup1">
 <title>Setup Stock Portfolio</title>
 <para>
Now that you have build an account hierarchy in the previous section, this section will show you how to populate the accounts with your stock portfolio.  During this initial setup of your portfolio, you may have stocks purchased from before you started using GnuCash.  For these stocks, follow the instructions in the <emphasis>Setup Your Pre-existing Stocks</emphasis> section below.  If your have just purchased your stocks, then use the <emphasis>Buying New Stocks</emphasis> section.
 </para>

 <sect2 id="invest_setup_preexisting2">
 <title>Setup Preexisting Stocks</title>
 <para>
This section will show you how to add stocks to GnuCash assuming that you purchased these stocks from before you started using GnuCash.  In this section, we will assume you are using the basic predefined account setup introduced in the previous section, but the principles can be applied to any account hierarchy.
 </para>
 <para>
You should have within the top level <guilabel>Asset</guilabel> account, a few levels down, an account entitled <guilabel>Stock</guilabel>.  Open the account tree to this level by clicking on the + (plus) signs next to the account names until the tree to fully opened.  You will need to create a sub-account (of type <emphasis>stock</emphasis>) under the Stock account for every stock you own.  Every stock is a separate account.  The naming of these stock accounts is usually done using the stock ticker abbreviation.  So, for example, you could name your accounts <emphasis>AMZN</emphasis> and <emphasis>IBM</emphasis> for your Amazon and IBM stocks respectively.  Below is a schematic model of the layout (only showing the Assets sub-accounts).
 </para>
 <literallayout>
- Assets
   - Investments
      - Brokerage Accounts
         - Mutual Funds
         - Market Index
         - Stock
            - AMZN
            - IBM
         - Bond
 </literallayout>
 </sect2>

 <sect2 id="invest_setup_example2">
 <title>Example Stock Account</title>

 <para>As an example, let's assume that you currently own 100 shares of Amazon stock.  First, create the stock account AMZN by selecting the <guilabel>Stock</guilabel> account and click on the menu <guimenu>File</guimenu> -> <guimenu>New Account</guimenu>.  The New Account dialog will appear, follow the step below to setup your new stock account.</para>
  <orderedlist>
  <listitem>
  <para><emphasis>Name the Account</emphasis> - Usually, use the stock ticker abbreviation, IE: <quote>AMZN</quote></para>
  </listitem>

  <listitem>
  <para><emphasis>Create the New Commodity</emphasis> - To use a new stock, you must create the stock as a new commodity</para>

  <orderedlist>
  <listitem>
  <para><emphasis>Select Commodity</emphasis> - Click on the <quote>Select</quote> button next to the <guilabel>Commodity</guilabel> line.  We must change the commodity from the default (your default currency) to this specific stock.  This will bring up the <quote>Select currency/security</quote> dialog.</para>
  </listitem>
  <listitem>
  <para><emphasis>Commodity Type</emphasis> - Change the <guilabel>type</guilabel> from CURRENCY to (in this example) NASDAQ. </para>
  </listitem>
  <listitem>
  <para><emphasis>Create the Commodity</emphasis> - Click on the <guilabel>New...</guilabel> button and enter the appropriate information for this stock.  The <guilabel>Full name:</guilabel> is <quote>Amazon.com Inc</quote>, the <guilabel>Symbol/abbreviation:</guilabel> is <quote>AMZN</quote>, the <guilabel>Type:</guilabel> should already be <quote>NASDAQ</quote>, the <guilabel>CUSIP or other code</guilabel> is where you can enter some other coding number or text (leave it blank in this example), and finally the <guilabel>Fraction traded</guilabel> should be adjusted to the smallest fraction of this commodity which can be traded, usually 1/100 or 1/10000.  Below is what this window should look like when finished:
  	<screenshot id="invest_newsecurity">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_newsecurity.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>New Security Window</phrase>
	    </textobject>
	    <caption>
	       <para>New Security Window
	       </para>
	    </caption>
          </mediaobject>
        </screenshot>
  </para>
   </listitem>
   <listitem>
   <para><emphasis>Save Commodity</emphasis> - Click on the <guilabel>OK</guilabel> button to save this new commodity</para>
   </listitem>
   </orderedlist>
   </listitem>

  <listitem>
  <para><emphasis>Select the Commodity</emphasis> - you should now see the newly create commodity available in the pull down menu for <guilabel>Currency/security</guilabel>.  Select it (it is probably already selected) and click on <guilabel>OK</guilabel>.</para>
  </listitem>
  <listitem>
  <para><emphasis>Finished</emphasis> - You should now have been automatically returned to the New Account dialog, with the <guilabel>Commodity:</guilabel> line set to <quote>AMZN (Amazon.com Inc)</quote>.  Click on <guilabel>OK</guilabel> to save this new stock account.</para>
   </listitem>

  </orderedlist>

  <para>You have now create the Amazon stock account, your main account should look something like this (notice that there are a few extra account here, a bank account, and an equity account):</para>
	<screenshot id="invest_setup_current">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_setup_current.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Setup Current Portfolio</phrase>
	    </textobject>
	    <caption>
	       <para>This image the creation of the first stock account
	       </para>
	    </caption>
          </mediaobject>
        </screenshot>
 <para>
Open the account register window for this AMZN stock account (double click on it).  Here you see the <emphasis role="strong">Portfolio</emphasis> view. This gives  you an overview of your stock portfolio including the number of shares bought and sold.  Obviously, we have not bought or sold any stocks yet, so the Portfolio view should not contain any transactions.
 </para>
 <para>
To register the initial 100 shares of this stock that you purchased previously, on the first transaction line, enter the date of the purchase (eg: Jan. 1 2001), a description (eg: Initial Purchase), transfer from <emphasis>Equity: Opening Balances</emphasis>, Shares (eg: 100), and Price (eg: $20).  You do not need to fill in the <guilabel>Buy</guilabel> column, as it will be calculated for you.  Your AMZN Portfolio view should now appear like this:
 </para>
	<screenshot id="invest_setup_portfolio1">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_setup_portfolio1.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Setup Current Portfolio</phrase>
	    </textobject>
	    <caption>
	       <para>This image the creation of the first stock account</para>
	    </caption>
          </mediaobject>
        </screenshot>
  <para>
Notice that the <guilabel>Balance</guilabel> is in the units of the commodity (AMZN shares) not in currency units.  Thus, the balance is 100 (AMZN units) rather than $2000.  This is how it should be.
  </para>
 </sect2>

 <sect2 id="invest_setup_new2">
 <title>Buying New Investments</title>
 <para>
The only difference between setting up a new investment purchase versus the setup for preexisting stocks as described in the previous section is that instead of transferring the money used to purchase the stock from the Equity:Starting Balances account, you use your Asset:Bank account.
 </para>
 </sect2>

 </sect1>

 <sect1 id="invest_stockprice1">
 <title>Setting Stock Price</title>
 <para>
The value of a commodity, such as a stock, must be explicitly set.  The stock accounts track the quantity of stocks you own, but the value of the stock is stored in the <emphasis>Price Editor</emphasis>.  The values set in the Price Editor can be updated manually or automatically.
 </para>

 <sect2 id="invest_stockprice_initial2">
 <title>Initial Price Editor Setup</title>
 <para>To use the Price Editor to track a stock value, you must initially insert the stock.  To do so, open the Price Editor (<guimenu>Tools</guimenu> -> <guimenu>Price Editor</guimenu>) and click on <guibutton>Add</guibutton> button.  Select the appropriate Commodity you want to insert into the Price Editor.  At this point, you can input the price of the commodity manually.  There are 5 fields in the New Commodity window:</para>
 <itemizedlist>
 <listitem>
 <para><guilabel>Commodity</guilabel> - the name of the commodity, must be chosen from the <guibutton>Select...</guibutton> list</para>
 </listitem>
 <listitem>
 <para><guilabel>Currency</guilabel> - the currency the in which the Price is expressed.</para>
 </listitem>
 <listitem>
 <para><guilabel>Date</guilabel> - date that the price is valid</para>
 </listitem>
 <listitem>
 <para><guilabel>Type</guilabel> - one of: <guilabel>Bid</guilabel> (the market buying price), <guilabel>Ask</guilabel> (the market selling price), <guilabel>Last</guilabel> (the last transaction price), <guilabel>Net Asset Value</guilabel> (mutual fund price per share), or <guilabel>Unknown</guilabel>.  Stocks and currencies will usually give their quotes as one of bid, ask or last.  Mutual funds are often given as net asset value.  For other commodities, simply choose "Unknown".  This option is for informational purposes only, it is not used by GnuCash.</para>
 </listitem>
 <listitem>
 <para><guilabel>Price</guilabel> - the price of one unit of this commodity.</para>
 </listitem>
 </itemizedlist>
 
	<screenshot id="invest_peditor">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_peditor.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Price Editor</phrase>
	    </textobject>
	    <caption>
	       <para>Adding the AMZN commodity to the price editor, with an initial value of $40.50 per share.</para>
	    </caption>
          </mediaobject>
        </screenshot>

 <para>Click <guibutton>OK</guibutton> when finished.  Once you have performed this initial placement of the commodity into the Price Editor, you will not have to do it again, even if you use the same commodity in another account.</para>

	<screenshot id="invest_peditor2">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_peditor2.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Price Editor</phrase>
	    </textobject>
	    <caption>
	       <para>The main price editor window, showing the list of all known commodities.</para>
	    </caption>
          </mediaobject>
        </screenshot>
 </sect2>

 <sect2 id="invest_stockprice_manual2">
 <title>Setting Stock Price Manually</title>
 <para>
If the value of the commodity (stock) changes, you can adjust the value by entering the Price Editor, selecting the commodity, clicking on <guibutton>edit</guibutton> and entering the new price.
 </para>
 </sect2>

 <sect2 id="invest_stockprice_auto2">
 <title>Setting Stock Price Automatically</title>
 <para>If you have many commodities, you will tire of having to update their prices constantly.  GnuCash has the ability to automatically determine the most recent price for your commodities using the Internet.  This is accomplished through the Perl module Finance::Quote, which must be installed in order to activate this feature.  </para>
 <para>To determine if the Perl module Finance::Quote is already installed on your system, type <quote>perldoc Finance::Quote</quote> in a terminal window and look to see if there is any documentation available.  If you see the documentation, then the module is installed, if you do not see the documentation, then it has not been installed.</para>
  <sect3 id="invest_stockprice_auto_install3">
  <title>Installing Finance::Quote</title>
 <para>To install Finance::Quote begin by first closing any GnuCash applications you have running.  Second, open a root shell and run the command <quote>update-finance-quote</quote> (without the quotation marks).  This will launch a Perl CPAN update session that will go out onto the Internet and install the Finance::Quote module on your system.  The update-finance-quote program is interactive, however, with most systems you should be able to answer "no" to the first question: <quote>Are you ready for manual configuration? [yes]</quote> and the update will continue automatically from that point.</para>
 <para>After installation is complete, you should run the "dump-finance-quote" test program distributed with GnuCash to test if Finance::Quote is installed and working properly.</para>
  <note>
  <para>If you feel uncomfortable about performing any of these steps, please either email the GnuCash-user mailing list (gnucash-user@gnucash.org) for help or come to the GnuCash IRC channel on irc.gnome.org. You can also leave out this step and manually update your stock prices.</para>
 </note>
  </sect3>
  <sect3 id="invest_stockprice_auto_configure3">
  <title>Configuring Finance::Quote</title>
  <para>With Finance::Quote installed and functioning correctly, you must configure your GnuCash stock accounts to use this feature to obtain updated price information automatically.  For stock accounts that have already been setup, <guibutton>edit</guibutton> the account and select the <guilabel>Get Online Quotes</guilabel> box.  You should now be able to modify the popup menus <guilabel>The source for price quotes</guilabel> and <guilabel>The timezone for these quotes</guilabel>.  When finished editing the stock account, return to the price editor and click on the <guibutton>Get Quotes</guibutton> button to update your stock prices on the internet.</para>
  <para>The command "gnucash --add-price-quotes $HOME/gnucash.xac" can be used to fetch the current prices of your stocks. This can be automated by creating a crontab entry. For example, to update your file every Friday evening after the Wall Street markets close (modify the time accordingly for your time zone), you could add the following to your personal crontab:</para>
<para>0 16 * * 5      gnucash --add-price-quotes $HOME/gnucash.xac &gt; /dev/null 2&gt;&amp;1 </para>
  </sect3>
  </sect2>

 <sect2 id="invest_stockprice_view2">
 <title>Displaying Stock Value</title>
 <para>
The main account window will by default only shows the quantity of each commodity that you own, under the column heading <guilabel>Total</guilabel>.  In the case of stocks, this commodity is the number of shares.  Often, however, you will want to see the value of your stocks expressed in terms of some monetary unit.  This is easily accomplished by entering the main window account options, by clicking on the tool bar <guibutton>Options</guibutton> button, and select to display the account field <quote>Total in Report Currency</quote>.  You will see a new column in the main window entitled <guilabel>Total (Report)</guilabel> that will express the value of all commodities in the report currency.
 </para>

	<screenshot id="invest_stockvalue">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_stockvalue.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Viewing Stock Value</phrase>
	    </textobject>
	    <caption>
	       <para>Viewing the value of a stock commodity in the main window using the Total in Report Currency option.</para>
	    </caption>
          </mediaobject>
        </screenshot>

 </sect2>

 <sect2 id="invest_stockprice_report">
 <title>Making Stock Value Reports</title>
 <para>
Gnucash offers three alternatives to determine stock prices in reports:
 </para>

	<screenshot id="invest_stockvalue_report_options">
        <mediaobject>
            <imageobject>
                <imagedata fileref="figures/invest_stockvalue_report_options.png" 
                           srccredit="Tomas Pospisek" format="PNG"/>
            </imageobject>
            <textobject>
                <phrase>Determining Stock Price 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>
        </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>
   </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>
   </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>
   </listitem>
 </itemizedlist>

	<screenshot id="invest_stockvalue_report">
        <mediaobject>
            <imageobject>
                <imagedata fileref="figures/invest_stockvalue_report.png" 
                           srccredit="Tomas Pospisek" format="PNG"/>
            </imageobject>
            <textobject>
                <phrase>An Asset Barchart Report based on the <guilabel>Nearest in time</guilabel> Price Source.</phrase>
            </textobject>
            <caption>
                <para>Tracking what value your stocks would've had on the stock exchanges.</para>
            </caption>
        </mediaobject>
    </screenshot>

 </sect2>

  </sect1>

 <sect1 id="invest_dividends1">
 <title>Dividends</title>
 <para>Some companies or mutual funds pay periodic dividends to shareholders.  Dividends are typically given in one of two ways, either they are automatically reinvested into the commodity or they are given as cash.  Mutual funds are often setup to automatically reinvest the dividend, while common stock dividends usually pay cash.</para>
 <para>If you receive the dividend in the form of an automatic reinvestment, the transaction to account for this should be handled within the stock or mutual fund account as income from "Income:Dividend" for the appropriate number of reinvested shares.</para>
  <para>If the dividend is presented as cash, you should record the transaction directly in the bank account that received the money, as income from "Income::Dividends" with a note mentioning from which commodity it was derived.  There is no simple way to show this transaction from within the stock or mutual fund account itself.</para>
 <note>
 <para>If you want to track dividends on a per-stock basis, you would need to create an Income:Dividends:STOCKSYMBOL account for each stock you own that pays dividends.</para>
 </note>
 </sect1>

 <sect1 id="invest_sell1">
 <title>Selling Stocks</title>
 <para>Entering an investment you are selling is done in the same way as buying one except the total cost of the transaction is entered in the <emphasis>Sell</emphasis> column and the <emphasis>Shares</emphasis> column is entered as a negative amount.  The proceeds from the sale should be transferred from the stock account to your bank account.</para>
 <para>The proper recording of the stock sale *must* be done using a split transaction.  In the split transaction, you must account for the profit (or loss) as coming from an Income:Capital Gains account (or Expense:Capital Loss).  To balance this income, you will need to enter the stock asset twice in the split.  Once to record the actual sale (using the correct number of shares and correct price per share) and once to balance the income profit (setting the number of shares to 0 and price per share to 0).</para>
 <para>In the split transaction scheme presented below, the symbol NUM_SHARES is the number of shares you are selling, SELL_PRICE is the price for which you sold the shares, GROSS_TOTAL is the total price for which you sold shares, equal to NUM_SHARES*SELL_PRICE.  PROFIT is the amount of money you made on the sale.  COMMISSIONS are the brokerage commissions.  NET_SALE is the net amount of money received from the sale, equal to GROSS_TOTAL - COMMISSIONS.</para>
 <table>
 <title>Selling Stock Split Transaction Scheme</title>
 <tgroup cols="3">
 <tbody>
 <row>
 <entry><emphasis>Account</emphasis></entry>
 <entry><emphasis>Number of Shares</emphasis></entry>
 <entry><emphasis>Share Price</emphasis></entry>
 <entry><emphasis>Total Buy</emphasis></entry>
 <entry><emphasis>Total Sell</emphasis></entry>
 </row>
 <row>
 <entry>Asset:Bank</entry>
 <entry></entry>
 <entry></entry>
 <entry>NET_SALE</entry>
 <entry></entry>
 </row>
 <row>
 <entry>Asset:Stock:SYMBOL</entry>
 <entry>-NUM_SHARES</entry>
 <entry>SELL_PRICE</entry>
 <entry></entry>
 <entry>GROSS_SALE</entry>
 </row>
 <row>
 <entry>Asset:Stock:SYMBOL</entry>
 <entry></entry>
 <entry></entry>
 <entry>PROFIT</entry>
 <entry></entry>
 </row>
 <row>
 <entry>Income:Capital Gains</entry>
 <entry></entry>
 <entry></entry>
 <entry></entry>
 <entry>PROFIT</entry>
 </row>
 <row>
 <entry>Expenses:Commissions</entry>
 <entry></entry>
 <entry></entry>
 <entry>COMMISSION</entry>
 <entry></entry>
 </row>
 </tbody>
 </tgroup>
 </table>

 <para>If you will be recording the sale of the stock as a capital gain (or loss), please see the chapter "Depreciation and Capital Gains" for more information on this topic.</para>

 <sect2 id="invest_sellexample2">
 <title>Example</title>

 <para>As an example, assume you bought 100 shares of a stock for $20 per share, then later sell them all for $30 per share.  In the split transaction scheme above, PRICEBUY is $20 (the original buying price), NUMSHARES is 100, TOTALBUY is $2000 (the original buying price), TOTALPROFIT is $1000, and finally TOTALSALE is $3000.</para>

 <screenshot id="invest_sellstock2">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/invest_sellstock.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Selling Stock Example</phrase>
	    </textobject>
	    <caption>
	       <para>An example of selling stock.  You bought 100 shares of AMZN for $20 per share, and sold for $30.</para>
	    </caption>
          </mediaobject>
        </screenshot>


 </sect2>
 </sect1>

 <sect1 id="invest_todo1">
 <title>To-do</title>
 <para>
These are the remaining documentation sections that originally appeared in the 1.8.4 documentation which require being written up.
 </para>

 <itemizedlist>
 <listitem>
 <para>Recording Stock Splits and Mergers (How-To)</para>
 </listitem>
 <listitem>
 <para>Recording Employee Stock Plans (Discussion)</para>
 </listitem>
 <listitem>
 <para>Stock Options (How-To)</para>
 </listitem>
 <listitem>
 <para>Reconciling with the Brokerage Statement (How-To)</para>
 </listitem>
 </itemizedlist>

 </sect1>

 </chapter>
