<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "gnc-gui-C.dtd">
<!-- (Do not remove this comment block.)
  Version: 2.0.0
  Last modified: December 7th 2009
       modified: January 10th 2007
       modified: July 9th 2006
  Maintainers:
    Alex Aycinena <alex.aycinena@gmail.com>
    Chris Lyttle <chris@wilddev.net>
  Author:
    Jon Lapham <lapham@extracta.com.br>
    Updated	Dave Herman <dvherman@bigfoot.com>
  Originally designed by Carol Champagne.
  Translators:
    (translators put your name and email here)
-->
<chapter id="chapter_invest">
  <title>Investments</title>

  <para>This chapter explains how to manage your investments with &app;. Most people have an investment
    plan, whether its just putting money into a certificate of deposit (<acronym>CD</acronym> for short) account, investing through a company sponsored
    plan at your workplace or buying and selling stocks and bonds through a brokerage. &app; gives
    you tools to help you manage these investments such as the <emphasis>Price Database</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 &app;.
    </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>

      <variablelist>
        <varlistentry>
          <term id="invest_terms2.capgain">Capital gains</term>

          <listitem>
            <para>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>
        </varlistentry>

        <varlistentry>
          <term>Commission</term>

          <listitem>
            <para>The fee you pay to a broker to buy or sell securities.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Common stock</term>

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

        <varlistentry>
          <term>Compounding</term>

          <listitem>
            <para>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>
        </varlistentry>

        <varlistentry>
          <term>Dividends</term>

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

        <varlistentry>
          <term>Equities</term>

          <listitem>
            <para>Equities 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>
        </varlistentry>

        <varlistentry>
          <term>Interest</term>

          <listitem>
            <para>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>
        </varlistentry>

        <varlistentry>
          <term>Liquidity</term>

          <listitem>
            <para>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>
        </varlistentry>

        <varlistentry>
          <term>Principal</term>

          <listitem>
            <para>The original amount of money invested or borrowed.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Realized vs Unrealized Gain/Loss</term>

          <listitem>
            <para>Unrealized gain or loss occurs when you&rsquo;ve got a change in price of an asset. You realize the
              gain/loss when you actually sell the asset. See also <xref linkend="invest_terms2.capgain" />.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term id="invest_terms2.return">Return</term>

          <listitem>
            <para>The total income plus capital gains or losses of an investment. See also <xref linkend="invest_terms2.yield" />.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Risk</term>

          <listitem>
            <para>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>
        </varlistentry>

        <varlistentry>
          <term>Shareholder</term>

          <listitem>
            <para>A shareholder is a person who holds common stock in a company.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Stock split</term>

          <listitem>
            <para>Occurs when a company offers to issue some additional multiple of shares for each existing stock.
              For example, a <quote>2 for 1</quote> 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
              shares 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>
        </varlistentry>

        <varlistentry>
          <term>Valuation</term>

          <listitem>
            <para>The process of determining the market value or the price the investment would sell at in a
              <quote>reasonable time frame</quote>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term id="invest_terms2.yield">Yield</term>

          <listitem>
            <para>A measure of the amount of money you earn from an investment (That is 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 <xref linkend="invest_terms2.return" />). For example, a stock sells for $100
              and gives $2 in dividends per year has a yield of 2%.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </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 deposited. 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, to a specified limit.
          </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 relatively lower risk
            investment. Examples are certificates of deposit or some government bonds. Other types
            of Bonds may have higher yields based on the higher risks from the quality of the
            issuer&rsquo;s <quote>credit rating</quote>.
          </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 a higher risk, as you have no guarantee on the future price of a stock.
          </para>

          <para>A mutual fund is a group investment mechanism in which you can buy into many stocks simultaneously.
            For example, a <quote>S&amp;P 500 index fund</quote> is a fund which purchases all 500 stocks listed
            in the Standard and Poor&rsquo;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>Assets 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 not receive this tax break on an expensive
            painting.
          </para>

          <para>Fixed asset investments are discussed in <xref linkend="chapter_capgain" /> and
            <xref linkend="chapter_dep" />. Typically, there is not much to do in terms of
            accounting for fixed asset investments except recording 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 &app; 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>

    <note>
      <para>Regardless of how you setup your account hierarchy, remember that you can always move accounts
        around later (without losing the work you&rsquo;ve put into them), so your initial account
        hierarchy does not have to be perfect.
      </para>
    </note>

    <sect2 id="invest_predefined2">
      <title>Using Predefined Investment Accounts</title>

      <para>The <guilabel>Investment Accounts</guilabel> option of the <guilabel>New Account Hierarchy
        Setup</guilabel> assistant will automatically create a basic investment account hierarchy
        for you. To access the predefined investment accounts hierarchy, you must make sure your
        &app; file is open, switch to the <guilabel>Accounts</guilabel> tab, and choose
        <menuchoice>
          <guimenu>Actions</guimenu><guimenuitem>New Account Hierarchy</guimenuitem>
        </menuchoice>.
        This will run the <guilabel>New Account Hierarchy Setup</guilabel> assistant and allow you
        to select additional accounts to add to your account hierarchy. Choose the
        <guilabel>Investment Accounts</guilabel> option (along with any others you are interested
        in). Assuming only investment accounts were selected, this will create an account hierarchy
        as shown below.
      </para>

      <tip>
        <para>You can also run the <guilabel>New Account Hierarchy Setup</guilabel> assistant by creating a new
          &app; file.
        </para>
      </tip>

      <figure>
        <title>A New File Containinng Only The Default Investment Accounts</title>
        <screenshot id="invest_accountspredef">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_AccountsPredef.png"
                          srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This is a screen image of the <guilabel>Accounts</guilabel> tab after creating a new file and
                selecting only the default investment accounts.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>You will probably at least want to add a <emphasis>Bank</emphasis> account to the <emphasis>Assets</emphasis> account and
        probably an <emphasis>Equity:Opening Balances</emphasis> account, as we have done in
        previous chapters. Don&rsquo;t forget to save your new account file with a relevant name!
      </para>
    </sect2>

    <sect2 id="invest_creating2">
      <title>Creating Investment Accounts Manually</title>

      <para>If you want to set up your own investment accounts hierarchy, you may of course do so. Investments
        usually have a number of associated accounts that need to be created: an asset account to
        track the investment itself; an income account to track dividend transactions; and expense
        accounts to track investment fees and commissions.
      </para>

      <para>In a typical account structure, security accounts are sub accounts of an asset account representing
        an account at a brokerage firm. The brokerage account would be denominated in your local
        currency and it would include sub accounts for each security that you trade there.
      </para>

      <para>Related purchases, sales, income and expense accounts should also be in the same currency as the
        brokerage account.
      </para>

      <para>The security sub accounts would each be configured to contain units of a single security selected
        from the master (user defined) security list and they are expected to use the same currency
        as the brokerage account.
      </para>

      <para>Security prices are kept in the <guilabel>Price Database</guilabel> of &app; (see <xref linkend="invest-stockprice1" />).
        This contains prices for individual securities (not security accounts). All prices for an
        individual security are in a single currency. If a security is traded in multiple
        currencies, then a separate security and separate accounts should be set up for each
        currency.
      </para>
    </sect2>

    <sect2 id="invest_custom2">
      <title>Custom Accounts Example</title>

      <para>The following is a somewhat more complicated example of setting up &app; 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 &app; and spot where &app; differs from the
        statement.
<screen>
 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</screen>
      </para>

      <tip>
        <para>There really is no standard 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>
      </tip>
    </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 &app;.
    </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>
<screen>
Assets
   Bank ABC
      Certificate of Deposit
      Savings
Expenses
   Bank ABC
      Charges
Income
   Interest Income
      Certificate of Deposit
      Savings</screen>

      <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&rsquo;s populate these accounts with real numbers. Let&rsquo;s assume that you start with
        $10,000 in your bank account, which pays 1% interest and you buy a $5,000 certificate of
        deposit with a 6 month maturity date and a 2% yield. Clearly, it is much better to keep your
        money in the certificate of deposit than in the savings account. After the initial purchase, your accounts
        should look something like this:
      </para>

      <figure>
        <title>The Chart Of Accounts After Investing In A Certificate Of Deposit</title>
        <screenshot id="invest-int">
          <mediaobject>
           <imageobject>
              <imagedata fileref="figures/invest_int1.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This is an image of the account register after creating and investing in a certificate of deposit investment.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>Now, during the course of the next 6 months, 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 6 months, the register window for the certificate of deposit and for the savings account
        should look like these:
      </para>

      <figure>
        <title>The CD Account After 6 Months</title>
        <screenshot id="invest-int2">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/invest_int2.png"
                         srccredit="Cristian Marchi" width="&img-w;"/>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/invest_int2.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This is an image of the register of the certificate of deposit account after 6 months.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <figure>
        <title>The Savings Account After 6 Months</title>
        <screenshot id="invest-int2-1">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/invest_int2-1.png"
                         srccredit="Cristian Marchi" width="&img-w;"/>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/invest_int2-1.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This is an image of the register of the Savings account after 6 months.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>And this is the main &app; account window:
      </para>

      <figure>
        <title>The Chart Of Accounts After 6 months</title>
        <screenshot id="invest-int3">
          <mediaobject>
           <imageobject>
              <imagedata fileref="figures/invest_int3.png"
                          srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This a screen capture of the accounts after 6 months.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>From the above image of the main &app; account window you see a nice summary of what happened to
        these investments over the 6 months. While the yield on the certificate of deposit is double that of the savings
        account, the return on the certificate of deposit 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 certificate of deposit has reached maturity which means you may sell it with no early
        withdrawal penalty. To do so, simply transfer the $5,050.21 from the certificate of deposit account into the
        savings account.
      </para>
    </sect2>
  </sect1>

  <sect1 id="invest-setup1">
    <title>Setup Investment Portfolio</title>

    <para>Now that you have built an account hierarchy in the previous section, this section will show you how
      to create and populate the accounts with your investment portfolio. After this initial setup
      of your portfolio, you may have shares of stock purchased from before you started using &app;.
      For these stocks, follow the instructions in the
      <xref linkend="invest-buy-stock2" endterm="invest-buy-stock2.title" /> section.
      If you have just purchased your stocks, then use the
      <xref linkend="invest-buy-new2" endterm="invest-buy-new2.title" /> section.
    </para>

    <sect2 id="invest-setup-stockaccounts2">
      <title>Setup Accounts for Stocks and Mutual Funds</title>

      <para>This section will show you how to add stocks and mutual fund accounts to &app;. In this section, we
        will assume you are using the basic 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 <quote>right facing triangle marker</quote> signs next to the account names until the
        tree is opened to the depth of the new account. 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, though account names may be anything that is clear to you and
        other users. So, for example, you could name your accounts <emphasis>AMZN</emphasis>,
        <emphasis>IBM</emphasis> and <emphasis>NST</emphasis> for your Amazon, IBM and NSTAR stocks
        respectively. Below is a schematic model of the layout (only showing the Assets
        sub-accounts).
      </para>
<screen>
 Assets
    Investments
       Brokerage Accounts
          Bond
          Mutual Funds
          Market Index
          Stock
             AMZN
             IBM
             NST</screen>
      <note>
        <para>If you want to track income (dividends/interest/capital gains) on a per-stock or fund basis, you
          will need to create an <emphasis>Income:Dividends:STOCKSYMBOL</emphasis>,
          <emphasis>Income:Cap Gain (Long):STOCKSYMBOL</emphasis>, <emphasis>Income:Cap Gain
          (Short):STOCKSYMBOL</emphasis> and <emphasis>Income:Interest:STOCKSYMBOL</emphasis>
          account for each stock you own that pays dividends or interest.
        </para>
      </note>
    </sect2>

    <sect2 id="invest-setup-example2">
      <title>Example Stock Account</title>

      <para>As an example, let&rsquo;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
        <menuchoice>
          <guimenu>Actions</guimenu><guimenu>New Account...</guimenu>
        </menuchoice>.
        The New Account dialog will appear, follow the steps, in the sequence below to setup your
        new stock account.
      </para>

      <figure>
        <title>The <quote>New Account</quote> Window For AMZN</title>
        <screenshot id="invest-newaccount">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_newaccount.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>

      <orderedlist>
        <listitem>
          <para><emphasis>Account Name</emphasis> - Usually, use the stock ticker abbreviation, like
            <quote><userinput>AMZN</userinput></quote>.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Account Code</emphasis> - Optional field, use CUSIP, the newspaper listing symbol, mutual
            fund family ID or code of your own choosing.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Description</emphasis> - Optional field for detailed description of the commodity/stock.
            Note this field by default is displayed in the <guilabel>Account</guilabel> tab tree.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Account Type</emphasis> - Select the type of account you are creating from the lower
            left-hand list.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Parent Account</emphasis> - Select the parent account for the new account from the right
            hand listing. Expand list of accounts if necessary.
          </para>
        </listitem>

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

          <note>
            <para>Be sure to first select Account Type <emphasis>Stock</emphasis> or <emphasis>Mutual Fund</emphasis>
              so that the <guibutton>Select...</guibutton> button brings up the list of securities
              rather than currencies.
            </para>
          </note>

          <itemizedlist>
            <listitem>
              <para><emphasis>Select Security/Currency</emphasis> - Click on the <guibutton>Select...</guibutton>
                button next to the <guilabel>Security/currency</guilabel> line. We must change the
                security from the default (your default currency) to this specific stock. This will
                bring up the <guilabel>Select Security</guilabel> dialog.
              </para>
            </listitem>

            <listitem>
              <para><emphasis>Type</emphasis> - Select the exchange where the security/commodity is traded (in this
                example NASDAQ).
              </para>

              <para>Select the <guibutton>New</guibutton> button to open the <guilabel>New Security</guilabel> window.
              </para>

              <figure>
                <title>The <quote>Select Security</quote> Window</title>
                <screenshot id="invest-selectsecurity">
                  <mediaobject>
                    <imageobject>
                      <imagedata fileref="figures/invest_selectsecurity.png"
                                  srccredit="Cristian Marchi"/>
                    </imageobject>
                  </mediaobject>
                </screenshot>
              </figure>
            </listitem>

            <listitem>
              <para><emphasis>Create the Security</emphasis> - Click on the <guibutton>New...</guibutton> button and
                enter the appropriate information for this stock on the new form <guilabel>New
                Security</guilabel>.
              </para>
<!--  Open inner most loop (#3)
-->
              <itemizedlist>
                <listitem>
                  <para>The <guilabel>Full name:</guilabel> is <userinput>Amazon.com</userinput>.
                  </para>
                </listitem>

                <listitem>
                  <para>The <guilabel>Symbol/abbreviation:</guilabel> is <userinput>AMZN</userinput>. The symbol is the stock ticker
                    used in your quote source several lines down on the form.                    <note><para>
                    Different symbols will be used on different price sources for the same stock, an
                    example is Ericsson on the Stockholm Exchange is ERIC-B while on Yahoo it is
                    ERRICB.ST.</para>
                    </note>
                  </para>
                </listitem>

                <listitem>
                  <para>The <guilabel>Type:</guilabel> should already be <guilabel>NASDAQ</guilabel>, because this is what
                    was selected in the security selector, but you can change it here, including
                    adding more categories. More information about this can be found in the &app;
                    Manual in section 8.7, <quote>Security Editor</quote>.
                  </para>
                </listitem>

                <listitem>
                  <para>The <guilabel>ISIN, CUSIP or other code</guilabel> is where you can enter some other coding number
                    or text (leave it blank in this example).
                  </para>
                </listitem>

                <listitem>
                  <para>The <guilabel>Fraction traded</guilabel> should be adjusted to the smallest fraction of this
                    security which can be traded, usually <guilabel>1/100</guilabel> or <guilabel>1/10000</guilabel>.
                  </para>
                </listitem>

                <listitem>
                  <para>The checkbox <quote>Get Online Quotes</quote>, the quote source and the timezone should be selected
                    to define the sources for updating prices on-line. See also
                    <xref linkend="invest-stockprice-auto2" />.
                  </para>

                  <note>
                    <para>If the <guibutton>Get Online Quotes</guibutton> button is not highlighted, and it is not tickable,
                      then the &app-fq; package is not installed.
                      See the chapter <ulink url="&url-docs-C;help/finance-quote.html">Setting Up the Quote Retrieval</ulink> in the manual.
                    </para>
                  </note>

                  <para>Below is what this window should look like when finished:
                  </para>
                  <figure>
                    <title>The <quote>New Security</quote> Window</title>
                      <screenshot id="invest-newsecurity">
                        <mediaobject>
                          <imageobject>
                            <imagedata fileref="figures/invest_newsecurity.png"
                                       srccredit="Cristian Marchi"/>
                          </imageobject>
                        </mediaobject>
                      </screenshot>
                    </figure>
                </listitem>

                <listitem>
                  <para><emphasis>Save Security</emphasis> - Click on the <guibutton>OK</guibutton> button to save this new
                    security, this will close the <guilabel>New Security</guilabel> window and
                    return to the <guilabel>New Account</guilabel> window.
                  </para>
                </listitem>
              </itemizedlist>
<!--  Close inner most loop
-->
            </listitem>
<!--  Close loop #2
-->
          </itemizedlist>
        </listitem>

        <listitem>
          <para><emphasis>Select the Security</emphasis> - you should now see the newly created security available
            in the pull down menu for <guilabel>Security/Currency</guilabel>. Select it (it is
            probably already selected) and click on <guibutton>OK</guibutton>.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Smallest Fraction</emphasis> - Specify the smallest fraction of the security/commodity
            that is traded.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Notes</emphasis> - Enter any notes or messages related to this security/commodity.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Tax Related</emphasis> - Go to
            <menuchoice>
              <guimenu>Edit</guimenu> <guimenuitem>Tax Report Options</guimenuitem>
            </menuchoice>
            to check this box if this account&rsquo;s transactions will relate to Income Taxes.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Placeholder</emphasis> - Check box if this account is a <quote>Placeholder</quote>, that
            is it will contain no transactions.
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Finished</emphasis> - You should now have been automatically returned to the New Account
            dialog, with the <guilabel>symbol/abbreviation:</guilabel> line set to <quote>AMZN
            (Amazon.com)</quote>. Click on <guibutton>OK</guibutton> to save this new stock account.
          </para>
        </listitem>
<!--
                    Outer list can now be closed
-->
      </orderedlist>

      <para>You have now created the Amazon stock account, your main account should look something like this
        (notice that there are a few extra accounts here, a bank account, and an equity account):
      </para>

      <figure>
        <title>The Chart of Accounts After The Creation Of The First Stock Account</title>
        <screenshot id="invest-setup-current">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_setup_current.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This image is after the creation of the first stock account (AMZN).
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>Open the account register window for this AMZN stock account (double click on it). Here you see the
        <emphasis
      role="strong">Commodity</emphasis> view. This gives you an overview of the
        transactions in this commodity including the number of units (shares for a stock or mutual
        fund) bought or sold, the net price per unit, and the total amount. Obviously, we have not
        bought or sold any shares of AMZN yet, so the register should not contain any transactions.
      </para>
    </sect2>
  </sect1>

  <sect1 id="invest-buy-stock1">
    <title>Buying Shares</title>

    <sect2 id="invest-buy-stock2">
      <title id="invest-buy-stock2.title">Entering Preexisting Shares</title>

      <para>The examples in this section use <guilabel>Transaction Journal</guilabel> view.
      </para>

      <para>To register the initial <userinput>100</userinput> shares of this stock that you purchased previously, on the first
        (transaction) line, enter the date of the purchase (for example, Jan. 1 2005) and
        <guilabel>Description</guilabel> (for example, Opening Balance). On the first split line, enter <userinput>100</userinput>
        in <guilabel>Shares</guilabel>, delete the (unit) <guilabel>Price</guilabel> (it will be
        calculated when you <keycap>Tab</keycap> out of the split) and enter <userinput>2000</userinput> in the
        <guilabel>Buy</guilabel> column.
      </para>

      <note>
        <para>It is also possible to use &app; to calculate <guilabel>Shares</guilabel> or
          <guilabel>Buy</guilabel> from the other 2 columns. But to avoid rounding errors, it is
          better to automatically calculate <guilabel>Price</guilabel>.
        </para>
      </note>

      <para><keycap>Tab</keycap> to the second split line, enter transfer from account <emphasis>Equity:Opening
        Balances</emphasis>. For simplicity, this example assumed there were no commissions on this
        transaction. Your AMZN Commodity view should now appear like this:
      </para>

      <figure>
        <title>The Transaction Register Of The AMZN Account After The First Purchase</title>
        <screenshot id="invest-setup-portfolio1">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/invest_setup_portfolio1.png"
                         srccredit="Cristian Marchi" width="&img-w;"/>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/invest_setup_portfolio1.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>This image is the transaction register of the AMZN account after the first stock
                <quote>purchase</quote>.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>Notice that the <guilabel>Balance</guilabel> (last column) is in the units of the commodity (AMZN
        shares) not in currency units. Thus, the balance is 100 (AMZN units) rather than $2,000. This
        is how it should be.
      </para>
    </sect2>

    <sect2 id="invest-buy-new2">
      <title id="invest-buy-new2.title">Buying New Shares</title>

      <para>The main difference between setting up a new stock 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 <emphasis>Equity:Opening Balances</emphasis> account, you
        transfer from your <emphasis>Assets:Bank ABC</emphasis> or <emphasis>Assets:Brokerage
        Account</emphasis> account.
      </para>

      <sect3 id="invest-buy-com">
        <title>Handling Commissions and Fees</title>

        <para>For conciseness, this document will refer to the money you pay to a broker for buying and selling
          securities as <emphasis>Commissions</emphasis>. Government fees may also be payable.
          Unless otherwise stated, fees are handled in a similar way.
        </para>

        <para>In &app; 2 alternate ways can be used to handle commissions (for simplicity this document section will
          refer to these ways as net pricing and gross pricing).</para>

		<variablelist>
        <varlistentry>
        <term>Gross Pricing</term>
	    <listitem><para>You enter the price not adjusted by commissions and enter the
	       commissions expense on a separate split in the transaction. This enables the tracking
	       of commissions but is <emphasis>not</emphasis> compatible with using
	       <xref linkend="invest-sellLots"/>. Scrubbing doesn't know to deduct commissions
	       and fees from the gains, so capital gains or losses must be manually calculated (see
	       <xref linkend="invest-sell-man"/>).
           </para>
        </listitem>
        </varlistentry>
		<varlistentry>
	    <term>Net Pricing</term>
        <listitem><para>
            You enter a net price (adjusted by commissions) when buying and
            selling securities. You do <emphasis>not</emphasis> also record commissions in a
            specific commissions account in order to later claim it as an expense, as this would
            be claiming commissions twice. This way <emphasis>is</emphasis> compatible with using
            <xref linkend="invest-sellLots"/>. This results in a slightly misleading price
            being added to the price database (the effective price you paid) but is not usually of
            any concern.
	    </para>
        </listitem>
		</varlistentry>
		</variablelist>

        <para>Please get professional advice if you are unsure which of these ways are applicable to your
          jurisdiction.
        </para>
      </sect3>

      <sect3 id="invest-buy-gross">
        <title>Example: Buying Shares with Gross Pricing</title>

        <para>In this example you will purchase 100 shares at $50 per share of IBM stock with a commission of $100. First step will be
          to create the stock account for IBM. The existing <emphasis>Expenses:Commission</emphasis>
          account will be used.
        </para>

        <para>Now for the transaction, on the first (transaction) line, enter the <guilabel>Date</guilabel> of the
          purchase (for example, Jan. 3, 2005) and <guilabel>Description</guilabel> (for example, Initial IBM
          Purchase). On the first split line, enter <userinput>50</userinput> in <guilabel>Shares</guilabel>, delete
          <guilabel>Price</guilabel> (leave it empty so it will be calculated), and enter <userinput>5000</userinput> in
          <guilabel>Buy</guilabel>. You do not need to fill in the <guilabel>Price</guilabel>
          column, as it will be calculated for you when you <keycap>Tab</keycap> to the next split.
          The next line in the split transaction will be <emphasis>Expenses:Commissions</emphasis>
          and fill <userinput>100</userinput> in <guilabel>Buy</guilabel>. The third split line will be to transfer $5,100 from
          <emphasis>Assets:Bank ABC</emphasis> account to balance the transaction. Your IBM
          Commodity view should now appear like this:
        </para>

        <figure>
          <title>The Transaction Register Of The IBM Account After The First Stock Purchase</title>
          <screenshot id="invest-setup-portfolio2">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/invest_SetupPortfolio2.png"
                            srccredit="Chris Good" width="&img-w;"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="figures/invest_SetupPortfolio2.png"
                            srccredit="Chris Good"/>
              </imageobject>
              <caption>
                <para>This image is of the transaction register of the IBM account after the first stock
                  <quote>purchase</quote> with a commission.
                </para>
              </caption>
            </mediaobject>
          </screenshot>
        </figure>
      </sect3>

      <sect3 id="invest-buy-net">
        <title>Example: Buying Shares with Net Pricing</title>

        <para>Repeating the previous example using Net Pricing instead of Gross Pricing, in Transaction Journal
          view.
        </para>

        <para>Purchase $5,000 of IBM stock being 50 Shares for $100.00 each, plus a commission of $100.
        </para>

        <para>Now for the transaction, on the first (transaction) line, enter the <guilabel>Date</guilabel> of the
          purchase (for example, Jan. 3, 2005) and <guilabel>Description</guilabel> (for example, Initial IBM
          Purchase). On the first split line, optionally enter more details in <guilabel>Memo
          </guilabel>, then <userinput>50</userinput> in <guilabel>Shares</guilabel>, delete anything in
          <guilabel>Price</guilabel> (so it will be calculated by dividing <guilabel>Buy</guilabel>
          by <guilabel>Shares</guilabel> when you <keycap>Tab</keycap> out of the split), &img-w;0 in
          <guilabel>Buy</guilabel> (50 * $100.00 + $100). Alternatively use &app; to calculate
          <guilabel>Buy</guilabel> by entering the formula <userinput>5000 + 100</userinput> or
          <userinput>(50 * 100) + 100</userinput> in <guilabel>Buy</guilabel> (
          <guilabel>Buy</guilabel> will be calculated when you <keycap>Tab</keycap> out of the
          column.) Use the <keycap>Tab</keycap> key as many times as needed to proceed to the next
          split.
        </para>

        <para>Do <emphasis>not</emphasis> enter a separate split for Commission as it has already been included in
          the <guilabel>Buy</guilabel> value. The second split line will be to transfer $5,100 from
          <emphasis>Assets:Bank ABC</emphasis> account to balance the transaction. After the splits
          are all correct, use the <keycap function="enter">Enter</keycap> key to save the
          transaction. Your IBM Commodity view should now appear like this:
        </para>

        <figure>
          <title>The IBM Account After The First Stock Purchase With A Commission</title>
          <screenshot id="invest-setup-portfolio3">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/invest_SetupPortfolio3.png"
                           srccredit="Chris Good" width="&img-w;"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="figures/invest_SetupPortfolio3.png"
                           srccredit="Chris Good"/>
              </imageobject>
              <caption>
                <para>This image is of the transaction register of the IBM account after the first stock
                  <quote>purchase</quote> with a commission.
                </para>
              </caption>
            </mediaobject>
          </screenshot>
        </figure>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="invest-stockprice1">
    <title>Setting Share 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
      Database</emphasis>. The values set in the <guilabel>Price Database</guilabel> can be updated
      manually or automatically.
    </para>

    <sect2 id="invest-stockprice-initial2">
      <title>Initial Price Database Setup</title>

      <para>To use the <guilabel>Price Database</guilabel> to track a stock value, you must initially insert the
        stock. To do so, open the <guilabel>Price Database</guilabel> (<menuchoice>
          <guimenu>Tools</guimenu><guimenuitem>Price Database</guimenuitem>
        </menuchoice>)
        and click on <guibutton>Add</guibutton> button. The first time a Commodity/Stock is
        entered this window will be blank except for the control buttons on the bottom. Select the
        appropriate Commodity you want to insert into the <guilabel>Price Database</guilabel>. At this
        point, you can input the price of the commodity manually. There are 6 fields in the New
        Commodity window:
      </para>

      <variablelist>
        <varlistentry>
          <term><guilabel>Namespace</guilabel></term>

          <listitem>
            <para>The exchange market where the security/commodity is traded (in this example NASDAQ.)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Security</guilabel></term>

          <listitem>
            <para>The name of the commodity, must be chosen from the <guibutton>Select...</guibutton> list.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Currency</guilabel></term>

          <listitem>
            <para>The currency in which the Price is expressed.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Date</guilabel></term>

          <listitem>
            <para>Date that the price is valid.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Type</guilabel></term>

          <listitem>
            <para>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, <acronym>NAV</acronym> for short), 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
              <guilabel>Unknown</guilabel>. This option is for informational purposes only, it is
              not used by &app;.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Price</guilabel></term>

          <listitem>
            <para>The price of one unit of this commodity.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>As an example of adding the AMZN commodity to the price database, with an initial value of $40.50 per
        share.
      </para>

      <figure>
        <title>Entering A Price Into The Database</title>
        <screenshot id="invest-peditor">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_peditor.png"
                          srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>Adding the AMZN commodity to the price database, with an initial value of $40.50 per share.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

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

      <note>
        <para>If you have online retrieval of quotes activated (see
          <xref linkend="invest-stockprice-auto2" />), you can initialize a commodity
          without manually making an entry. When you initially add the security in the
          <guilabel>Security Editor</guilabel>, check <guilabel>Get Online Quotes</guilabel> and
          save the security. Then, in the <guilabel>Price Database</guilabel>, click <guibutton>Get
          Quotes</guibutton>, and the new security will be inserted into the price list with the
          retrieved price.
        </para>
      </note>
    </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
        <guilabel>Price Database</guilabel>, selecting the commodity, clicking on
        <guibutton>Edit</guibutton> and entering the new price.
      </para>

      <figure>
        <title>The Price Database With The List Of All Known Commodities</title>
        <screenshot id="invest-peditor2">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/invest_peditor2.png"
                         srccredit="Cristian Marchi" width="&img-w;"/>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/invest_peditor2.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>The main price database window, showing the list of all known commodities.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>

    <sect2 id="invest-stockprice-auto2">
      <title>Configuring for Automatic Retrieval of Quotes</title>

      <para>If you have more than a couple of commodities, you will tire of having to update their prices
        constantly. &app; has the ability to automatically download the most recent price for your
        commodities using the Internet. This is accomplished through the
        <application>Perl</application> module &app-fq;, which must
        be installed in order to activate this feature.
      </para>

      <para>See the chapter
        <ulink url="&url-docs-C;help/finance-quote.html">Setting Up the Quote Retrieval</ulink>
        in the manual.
      </para>

      <sect3 id="invest-stockprice-auto-install3">
        <title>Installing &app-fq;</title>
        <para>The process of installing &app-fq; depends on the system. </para>

        <para>On &lin; and BSD it's usually simplest to use the package manager, but those seldom keep up with the latest &app-fq; releases. If you need a newer version than your package manager provides, use the following procedure with <filename>gnc-fq-update</filename></para>
        <procedure>
          <title>Installing &app-fq; on &lin; with <filename>gnc-fq-update</filename></title>
          <step><simpara>Close &app;.</simpara></step>
          <step><simpara>Run the command <command>which gnc-fq-update</command> to check <filename>gnc-fq-update</filename> program is in your PATH environment
            variable.<footnote><simpara>If you&rsquo;ve installed &app; packages provided by your distribution, <filename>gnc-fq-update</filename> must be on your PATH.</simpara></footnote>
          </simpara>
            <substeps><step id="gnc-fq-update-not-found">
                <simpara>If <filename>gnc-fq-update</filename> is not in your PATH, search the folder where &app; is 
                installed.</simpara>
                </step>
            </substeps>
          </step>
          <step><simpara>Run the command <command>sudo gnc-fq-update</command> or <command>su -c gnc-fq-update</command> in order to run it with root privilege.
            It depends on your distribution.
          If <filename>gnc-fq-update</filename> is not in your PATH, specify full path of <filename>gnc-fq-update</filename>
            instead, which is found by <xref linkend="gnc-fq-update-not-found" />.</simpara>
            <para>
              This will launch a <application>Perl</application> <acronym><ulink url="https://www.cpan.org/">CPAN</ulink></acronym><footnote>
                <simpara>See <ulink url="https://www.cpan.org/misc/cpan-faq.html">CPAN Frequently Asked Questions</ulink> for details.</simpara></footnote>
              module internally. When you launch the CPAN module for the first time, you must setup and configure it. However, on the most systems if you accept the default settings
              or answer the first question <computeroutput>Are you ready for manual
              configuration? [yes]</computeroutput> with <userinput>no</userinput>, you will be able to install &app-fq; successfully. 
              </para>
          </step>
          
          <step><simpara>Run <command>gnc-fq-dump</command> to check &app-fq; works properly.</simpara></step>
        </procedure>


        <procedure>
          <title>Installing &app-fq; on &mac;</title>
          <step><simpara>Close &app;.</simpara></step>
          <step><simpara>Install Xcode if it is not installed.</simpara>
              <simpara>XCode is an optional item from your &mac; distribution DVD.</simpara>
          </step>
          <step><simpara>Run the <emphasis>Update Finance Quote</emphasis> app in the &app; dmg.</simpara> 
              <para>You can run it from the dmg or copy it to the same
                folder to which you copied &app;.
                It will open a Terminal window and run a script for you
                which will ask lots of questions. Accept the default for each unless you know what
                you&rsquo;re doing.
            </para>
          </step>
        </procedure>

        <procedure>
          <title>Installing &app-fq; on &win;</title>
          <step><simpara>Close &app;.</simpara></step>
          <step><simpara>Run <menuchoice>
                               <guimenu>Start</guimenu>
                               <guisubmenu>&app;</guisubmenu>
                               <guimenuitem>Install Online Price Retrieval</guimenuitem></menuchoice>.
            </simpara>
          </step>
        </procedure>

        <note>
          <para>If you feel uncomfortable about performing any of these steps, please either email the &app;-user
            mailing list (<email>gnucash-user@gnucash.org</email>) for help or come to the &app; 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 Securities for Online Quotes</title>

        <para>With &app-fq; installed and functioning correctly, you must
          configure your &app; securities to use this feature to obtain updated price information
          automatically. Whether creating new securities or modifying securities that have already
          been setup, use the
          <menuchoice>
            <guimenu>Tools</guimenu><guimenuitem>Security Editor</guimenuitem>
          </menuchoice>,
          to edit the security and check the <guilabel>Get Online Quotes</guilabel> box. You will
          now be able to modify the radio buttons for <guilabel>Type of quote source</guilabel>, the
          pull-down menus to specify the specific source(s) and <guilabel>The timezone for these
          quotes</guilabel>. When finished editing, <guilabel>Close</guilabel> the Security Editor
          to return to the <guilabel>Price Database</guilabel> and click on the <guibutton>Get
          Quotes</guibutton> button to update your stock prices on the Internet.
        </para>
      </sect3>

      <sect3 id="invest-stockprice-auto-scheduler">
        <title>Configuring for Getting Online Quotes Periodically</title>

        <para>After you have verified the proper fetching of Online Quotes for your commodities, 
         you can tell your operating system to fetch the quotes periodically. See the section
        <ulink url="&url-docs-C;help/finance-quote-scheduler.html">Configuring for Getting Quotes Periodically</ulink>
        in the manual.
        </para>
      </sect3>
    </sect2>

    <sect2 id="invest-stockprice-view2">
      <title>Displaying Share Value</title>

      <para>The main account window, 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,
        selecting the <guilabel>Accounts</guilabel> tab, by clicking on the
        <emphasis>Titlebar</emphasis> <guibutton>Options</guibutton> button (the small down pointing
        arrow on the right side of the main account window titles bar), and selecting the option to
        display the account total field <quote>Total (USD)</quote>. You will see a new column in the
        main window entitled <guilabel>Total (USD)</guilabel> that will express the value of all
        commodities in the report currency.
      </para>

      <figure>
        <title>Displaying Stock Values in the Chart of Accounts</title>
        <screenshot id="invest-stockvalue">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_stockvalue.png"
                         srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>Viewing the value of a stock commodity in the main window using the Total in Report Currency option.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>

    <sect2 id="invest-stockprice-report">
      <title>The <quote>Price Source</quote> in Reports</title>

      <para>Most &app; 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 ether clicking on the
        <guibutton>Options</guibutton> icon in the <emphasis>Menubar</emphasis> or selecting
        <menuchoice>
          <guimenu>Edit</guimenu><guimenuitem>Report Options</guimenuitem>
        </menuchoice>.
        <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.
      </para>
      <note>
        <simpara>In the example the report can be customized using the
          <menuchoice><guimenu>Reports</guimenu><guisubmenu>Assets &amp; Liabilities</guisubmenu><guimenuitem>Average Balance</guimenuitem></menuchoice> menu.
        </simpara>
      </note>

<!-- ToDo: unshrink -->
      <figure>
        <title>Determining The Source Of The Stock Price/Currency Exchange Rate in Reports</title>
        <screenshot id="invest-stockvalue-report-options">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_stockvalue_report_options.png"
                         srccredit="John Ralls"/>
            </imageobject>
            <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>
      </figure>

      <variablelist>
        <varlistentry>
          <term><guilabel>Weighted Average</guilabel></term>
          <listitem><para>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>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Average Cost</guilabel></term>
          <listitem><para>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 &minus; 1300 proceeds from the sale + 300 gain)/(200 &minus;
            100) shares or 10/share.
            </para>
            <note>
              <itemizedlist>
                <listitem><simpara>Gain/Loss splits <emphasis>are</emphasis> included in this calculation.</simpara></listitem>
                <listitem><simpara>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.</simpara></listitem>
              </itemizedlist>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Most Recent</guilabel></term>
          <listitem><para>Uses the latest price from the price database.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Nearest in time</guilabel></term>
          <listitem><para>Uses the price nearest in time to the report date&mdash;the
            datum date for time series reports like <guilabel>Assets Over
            Time</guilabel>&mdash;from the price database.
              <note>
                <simpara>The nearest date isn&rsquo;t necessarily before the date in question.</simpara>
              </note>
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <figure>
        <title>An Asset Barchart Report Based On The <quote>Nearest In Time</quote> Price Source</title>
        <screenshot id="invest-stockvalue-report">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_stockvalue_report.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>Tracking what value your stocks would&rsquo;ve had on the stock exchanges.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>
  </sect1>

  <sect1 id="invest-sell1">
    <title>Selling Shares</title>

    <para>Entering an investment sale transaction is done in a similar way to entering a buy transaction (see
      <xref linkend="invest-buy-new2" />) except the amount entered in the
      <guilabel>Shares</guilabel> column is negative and the proceeds of the transaction is entered
      in the <guilabel>Sell</guilabel> column. The net proceeds from the sale should be transferred
      from the shares account to your bank or brokerage account.
    </para>

    <para>For information on handling <emphasis>commissions</emphasis> and the use of <emphasis>Net
      Pricing</emphasis> or <emphasis>Gross Pricing</emphasis>, please see
      <xref linkend="invest-buy-com" />.
      If you will be recording a capital gain or loss on the sale, please see
      <xref linkend="chapter_capgain" /> and <xref linkend="chapter_dep" /> for more information on
      this topic.
      To use the &app; <emphasis>Automatic Calculation of Capital Gain or Loss Using Lots</emphasis>
      feature, please see <xref linkend="invest-sellLots" /> otherwise continue to the next section.
    </para>

    <sect2 id="invest-sell-man">
      <title>Selling Shares with Manual Calculation of Capital Gain or Loss</title>

      <note>
        <para>In order for &app; to commit the zero-share, zero-price split for account
          <emphasis>Assets:Stock:SYMBOL</emphasis> to the transaction in the following schemes, you
          <emphasis>must</emphasis> <keycap>Tab</keycap> out of that split. If you use the
          <keycap function="enter">Enter</keycap> key, &app; will convert the split into shares of
          the commodity.
        </para>
      </note>

      <para>In the schemes of transaction splits presented below, the following symbols are used:

      <variablelist>
        <varlistentry>
            <term>NUM_SHARES</term>
        <listitem>
            <simpara>the number of shares you are selling</simpara>
        </listitem>
        </varlistentry>

        <varlistentry>
            <term>COMMISSION</term>
            <listitem>
                <simpara>brokerage commissions or fees</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>GROSS_SELL_PRICE</term>
            <listitem>
                <simpara>unit price for which you sold the shares, not reduced by COMMISSION</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>NET_SELL_PRICE</term>
            <listitem>
                <simpara>unit price for which you sold the shares, reduced by COMMISSION</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>GROSS_BUY_PRICE</term>
            <listitem>
                <simpara>unit price for which you bought the shares, not increased by COMMISSION</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>NET_BUY_PRICE</term>
            <listitem>
                <simpara>unit price for which you bought the shares, increased by COMMISSION</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>GROSS_BUY</term>
            <listitem>
                <simpara>total price for which you bought shares, excluding COMMISSION, equal to NUM_SHARES * GROSS_BUY_PRICE</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>NET_BUY</term>
            <listitem>
                <simpara>amount of money for which you bought shares including COMMISSION, equal to GROSS_BUY + COMMISSION</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>GROSS_SALE</term>
            <listitem>
                <simpara>total price for which you sold shares, equal to NUM_SHARES * GROSS_SELL_PRICE</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>NET_SALE</term>
            <listitem>
                <simpara>amount of money received from the sale, equal to GROSS_SALE &minus; COMMISSION</simpara>
        </listitem>
        </varlistentry>

        <varlistentry>
            <term>GROSS_PROFIT</term>
            <listitem>
                <simpara>amount of money you made on the sale, not reduced by COMMISSION</simpara>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>NET_PROFIT</term>
            <listitem>
                <simpara>amount of money you made on the sale, reduced by COMMISSION</simpara>
            </listitem>
        </varlistentry>
      </variablelist>
    </para>


      <para>There are 2 ways of manually recording the capital gain or loss. The capital gain/loss can be
        combined with the sale in one transaction or it can be entered in a separate transaction.
      </para>

      <sect3 id="invest-sell-man-comb">
        <title>Combine the Sale and Capital Gain/Loss in One Transaction</title>

        <para>This has the advantage that all parts of the sale event are kept together. This is
          <emphasis>not</emphasis> compatible with using <emphasis>scrubbing</emphasis> (see
          <xref linkend="invest-sellLots" />). If you may in future use scrubbing on a specific
          security, save some work later by entering the capital gain/loss splits in a separate
          transaction now.
        </para>

        <para>When the capital gain/loss splits are combined with the sale splits in one transaction, there are 2
          splits for the security account in the same transaction, so the transaction must be
          entered with the security register in <guilabel>Auto-Split Ledger</guilabel> or
          <guilabel>Transaction Journal</guilabel> view. One of the splits for the security account
          is for the sale and the other is for the capital gain or loss. The security account split
          for the capital gain or loss must be entered with 0 number of shares and 0 price per share
          to stop the automatic recalculation of these fields.
        </para>

        <para>Account for the profit or loss as coming from an <emphasis>Income:Capital Gains</emphasis> or
          <emphasis>Expenses:Capital Loss</emphasis> account.
        </para>

        <sect4 id="invest-sell-man-comb-gr">
          <title>Combined, Gross Pricing</title>

          <table>
            <title>Selling Shares Split Scheme, Sale and Capital Gain/Loss Are Combined, Gross Pricing</title>

            <tgroup cols="5">
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>

              <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>
                    Assets:Bank ABC
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    NET_SALE
                  </entry>

                  <entry></entry>
                </row>

                <row>
                  <entry>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    GROSS_PROFIT
                  </entry>

                  <entry>
                    (Loss)
                  </entry>
                </row>

                <row>
                  <entry>
                    Expenses:Commission
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    COMMISSION
                  </entry>

                  <entry></entry>
                </row>

                <row>
                  <entry>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    &minus;NUM_SHARES
                  </entry>

                  <entry>
                    GROSS_SELL_PRICE
                  </entry>

                  <entry></entry>

                  <entry>
                    GROSS_SALE
                  </entry>
                </row>

                <row>
                  <entry>
                    Income:Capital Gains
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    (Loss)
                  </entry>

                  <entry>
                    GROSS_PROFIT
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <example>
            <title>Sale of Shares with Profit, Manual Profit/Loss Calculation, Sale &amp; Profit Combined,
              Gross Pricing</title>

            <simpara>In this example, we will use the AMZN account created in <xref linkend="invest-setup-example2" />.</simpara>
            <para>You bought 100 shares of AMZN for $20 per share, then later sell them all for $36
              per share with a commission of $75. The split transaction scheme is as follows:
              <itemizedlist>
                <listitem><simpara>GROSS_BUY_PRICE is $20 (the original buying price),</simpara></listitem>
                <listitem><simpara>NUM_SHARES is 100,</simpara></listitem>
                <listitem><simpara>GROSS_BUY is $2,000 (the original buying cost),</simpara></listitem>
                <listitem><simpara>GROSS_SALE is $3,600,</simpara></listitem>
                <listitem><simpara>and finally GROSS_PROFIT is $1,600 (GROSS_SALE &minus; GROSS_BUY).</simpara></listitem>
              </itemizedlist>
            </para>
            <para><!-- Hack to get a figure inside of an example -->
              <table>
                <title>Selling Shares Split Scheme, Sale &amp; Gain Combined, Gross Pricing</title>
                <?dbfo table-width="70%" ?>
                <tgroup cols="5">
                  <colspec colnum="1" colwidth="4*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="1*"/>
                  <colspec colnum="1" colwidth="1*"/>

                  <tbody>
                    <row>
                      <entry>
                        <emphasis>Account</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Shares</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Price</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Buy</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Sell</emphasis>
                      </entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Bank ABC
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        3525.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Brokerage Account:Stock:AMZN
                      </entry>

                      <entry>
                        0
                      </entry>

                      <entry>
                        0
                      </entry>

                      <entry>
                        1600.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Expenses:Commission
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        75.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Brokerage Account:Stock:AMZN
                      </entry>

                      <entry>
                        &minus;100
                      </entry>

                      <entry>
                        36.00
                      </entry>

                      <entry></entry>

                      <entry>
                        3600.00
                      </entry>
                    </row>

                    <row>
                      <entry>
                        Income:Capital Gain (Long Term):AMZN
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        1600.00
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <figure pgwide="1">
                <title>Selling Shares, Gain Combined, Gross Pricing</title>
                <screenshot id="invest-sellstockManProfComb">
                  <mediaobject>
                    <imageobject role="html">
                      <imagedata fileref="figures/invest_sellstock.png"
                                 srccredit="Chris Good" width="&img-w;"/>
                    </imageobject>
                    <imageobject role="fo">
                      <imagedata fileref="figures/invest_sellstock.png"
                                 srccredit="Chris Good"/>
                    </imageobject>
                  </mediaobject>
                </screenshot>
              </figure>
              <note>
                <para>In the above screenshot, it appears there are 2 transactions for Mar. 21, 2006. This is because the
                  register is in <guilabel> Auto-Split Ledger</guilabel> view and there are 2 splits for
                  the register account in the 1 transaction. <guilabel>Transaction Journal</guilabel>
                  view may be clearer. Refer to <xref linkend="txns-registers-txntypes" />. As there are 2
                  splits for the register account in the sale transaction, this transaction must be
                  entered in <guilabel>Auto-Split Ledger</guilabel> or <guilabel>Transaction
                  Journal</guilabel> view. It cannot be entered in <guilabel>Basic Ledger</guilabel> view.
                </para>
              </note>
              <figure pgwide="1">
                <title>The Account Tree after the Example of Selling Shares for a Gain</title>
                <screenshot id="invest-sellstockManProfComb2">
                  <mediaobject>
                    <imageobject role="html">
                      <imagedata fileref="figures/invest_sellstock2.png"
                                 srccredit="Chris Good" width="&img-w;"/>
                    </imageobject>
                    <imageobject role="fo">
                      <imagedata fileref="figures/invest_sellstock2.png"
                                 srccredit="Chris Good"/>
                    </imageobject>
                  </mediaobject>
                </screenshot>
              </figure>
            </para>
          </example>
        </sect4>

        <sect4 id="invest-sell-man-comb-net">
          <title>Combined, Net Pricing</title>

          <table>
            <title>Selling Shares Split Scheme, Sale and Capital Gain/Loss Are Combined, Net Pricing</title>

            <tgroup cols="5">
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>

              <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>
                    Assets:Bank ABC
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    NET_SALE
                  </entry>

                  <entry></entry>
                </row>

                <row>
                  <entry>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    NET_PROFIT
                  </entry>

                  <entry>
                    (Loss)
                  </entry>
                </row>

                <row>
                  <entry>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    &minus;NUM_SHARES
                  </entry>

                  <entry>
                    NET_SELL_PRICE
                  </entry>

                  <entry></entry>

                  <entry>
                    NET_SALE
                  </entry>
                </row>

                <row>
                  <entry>
                    Income:Capital Gains
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    (Loss)
                  </entry>

                  <entry>
                    NET_PROFIT
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <example>
            <title>Sale of Shares with Profit, Manual Profit/Loss Calculation, Sale &amp; Profit Combined, Net Pricing</title>
            <simpara>In this example, we will use the AMZN account created in <xref linkend="invest-setup-example2" />.</simpara>
            <para>You bought 100 shares of AMZN for $20 per share (including commissions), then later
              sell them all for $36 per share with a commission of $75. The split transaction scheme
              is as follows:
              <itemizedlist>
                <listitem><simpara>NUM_SHARES is 100,</simpara></listitem>
                <listitem><simpara>NET_BUY_PRICE is $20 (the original buying price),</simpara></listitem>
                <listitem><simpara>NET_BUY is $2,000 (the original buying cost),</simpara></listitem>
                <listitem><simpara>NET_SELL_PRICE is $35.25 (($3600 &minus; $75) / 100)),</simpara></listitem>
                <listitem><simpara>GROSS_SALE is $3,600, NET_SALE is $3,525,</simpara></listitem>
                <listitem><simpara>and finally NET_PROFIT is $1,525 (NET_SALE &minus; NET_BUY).</simpara></listitem>
              </itemizedlist>
            </para>

            <para><!-- Hack to get a figures and tables inside of an example -->
              <table>
                <title>Selling Shares Split Scheme, Sale &amp; Gain Combined, Net Pricing</title>
                <?dbfo table-width="70%" ?>
                <tgroup cols="5">
                  <colspec colnum="1" colwidth="4*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="1*"/>
                  <colspec colnum="1" colwidth="1*"/>

                  <tbody>
                    <row>
                      <entry>
                        <emphasis>Account</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Shares</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Price</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Buy</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Sell</emphasis>
                      </entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Bank ABC
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        3525.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Brokerage Account:Stock:AMZN
                      </entry>

                      <entry>
                        0
                      </entry>

                      <entry>
                        0
                      </entry>

                      <entry>
                        1525.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Brokerage Account:Stock:AMZN
                      </entry>

                      <entry>
                        &minus;100
                      </entry>

                      <entry>
                        35.25
                      </entry>

                      <entry></entry>

                      <entry>
                        3525.00
                      </entry>
                    </row>

                    <row>
                      <entry>
                        Income:Capital Gain (Long Term):AMZN
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        1525.00
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>

              <figure pgwide="1">
                <title>Selling Shares for Gain using Net Pricing in Transaction Journal View</title>
                <screenshot id="invest-sellstockManProfCombNet">
                  <mediaobject>
                    <imageobject role="html">
                      <imagedata fileref="figures/invest_sellstockManProfCombNet.png"
                                 srccredit="Chris Good" width="&img-w;"/>
                    </imageobject>
                    <imageobject role="fo">
                      <imagedata fileref="figures/invest_sellstockManProfCombNet.png"
                                 srccredit="Chris Good"/>
                    </imageobject>
                  </mediaobject>
                </screenshot>
              </figure>
            </para>
          </example>

        </sect4>
      </sect3>

      <sect3 id="invest-sell-man-sep">
        <title>Separate the Capital Gain/Loss Transaction from the Sale Transaction</title>

        <para>This is <emphasis>required</emphasis> if using <emphasis>scrubbing</emphasis> to
          calculate and create capital gain/loss transactions automatically. Otherwise scrubbing will not detect
          them and will create an incorrectly valued capital gain/loss transaction.
        </para>

        <sect4 id="invest-sell-man-sep-gr">
          <title>Separated, Gross Pricing</title>

          <table>
            <title>Selling Shares Split Scheme, Sale and Capital Gain/Loss Are Separate Transactions, Sale Transaction</title>

            <tgroup cols="5">
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>

              <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>
                    Assets:Bank ABC
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    NET_SALE
                  </entry>

                  <entry></entry>
                </row>

                <row>
                  <entry>
                    Expenses:Commission
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    COMMISSION
                  </entry>

                  <entry></entry>
                </row>

                <row>
                  <entry>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    &minus;NUM_SHARES
                  </entry>

                  <entry>
                    GROSS_SELL_PRICE
                  </entry>

                  <entry></entry>

                  <entry>
                    GROSS_SALE
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <table>
            <title>Selling Shares Split Scheme, Sale and Capital Gain/Loss Are Separate Transactions, Capital Gain/Loss
              Transaction</title>

            <tgroup cols="5">
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>

              <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>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    GROSS_PROFIT
                  </entry>

                  <entry>
                    (Loss)
                  </entry>
                </row>

                <row>
                  <entry>
                    Income:Capital Gains
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    (Loss)
                  </entry>

                  <entry>
                    GROSS_PROFIT
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
          <example>
            <title>Sale of Shares with Profit, Manual Profit/Loss Calculation, Sale &amp; Profit Separated, Gross Pricing</title>
            <simpara>In this example, we will use the AMZN account created in <xref linkend="invest-setup-example2" />.</simpara>

            <para>You bought 100 shares of AMZN for $20 per share and commissions $20, then later sell them all for
              $36 per share with a commission of $75. The split transaction scheme is as follows:
              <itemizedlist>
                <listitem><simpara>GROSS_BUY_PRICE is $20 (the original buying price),</simpara></listitem>
                <listitem><simpara>NUM_SHARES is 100,</simpara></listitem>
                <listitem><simpara>GROSS_BUY is $2,000 (the original buying cost),</simpara></listitem>
                <listitem><simpara>GROSS_SALE is $3,600,</simpara></listitem>
                <listitem><simpara>finally GROSS_PROFIT is $1,600 (GROSS_SALE &minus; GROSS_BUY).</simpara></listitem>
              </itemizedlist>
            </para>

            <para>
              <table>
                <title>Selling Shares Split Scheme, Sale Transaction, Gross Pricing</title>
                <?dbfo table-width="70%" ?>
                <tgroup cols="5">
                  <colspec colnum="1" colwidth="4*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="1*"/>
                  <colspec colnum="1" colwidth="1*"/>

                  <tbody>
                    <row>
                      <entry>
                        <emphasis>Account</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Shares</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Price</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Buy</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Sell</emphasis>
                      </entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Bank ABC
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        3525.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Expenses:Commission
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        75.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Brokerage Account:Stock:AMZN
                      </entry>

                      <entry>
                        &minus;100
                      </entry>

                      <entry>
                        36.00
                      </entry>

                      <entry></entry>

                      <entry>
                        3600.00
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <table>
                <title>Selling Shares Split Scheme, Gain Transaction, Gross Pricing</title>
      <?dbfo table-width="70%" ?>
                <tgroup cols="5">
                  <colspec colnum="1" colwidth="4*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="2*"/>
                  <colspec colnum="1" colwidth="1*"/>
                  <colspec colnum="1" colwidth="1*"/>

                  <tbody>
                    <row>
                      <entry>
                        <emphasis>Account</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Shares</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Price</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Buy</emphasis>
                      </entry>

                      <entry>
                        <emphasis>Sell</emphasis>
                      </entry>
                    </row>

                    <row>
                      <entry>
                        Assets:Brokerage Account:Stock:AMZN
                      </entry>

                      <entry>
                        0
                      </entry>

                      <entry>
                        0
                      </entry>

                      <entry>
                        1600.00
                      </entry>

                      <entry></entry>
                    </row>

                    <row>
                      <entry>
                        Income:Capital Gain (Long Term):AMZN
                      </entry>

                      <entry></entry>

                      <entry></entry>

                      <entry></entry>

                      <entry>
                        1600.00
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
              <figure pgwide="1">
                <title>Selling Shares for Gain Where the Sale and Gain are Recorded in Separate Transactions,
                        in <guilabel>Transaction Journal</guilabel> View</title>
                <screenshot id="invest-sellstockManProfSep">
                  <mediaobject>
                    <imageobject role="html">
                      <imagedata fileref="figures/invest_sellstockManProfSep.png"
                                 srccredit="Chris Good" width="&img-w;"/>
                    </imageobject>
                     <imageobject role="fo">
                      <imagedata fileref="figures/invest_sellstockManProfSep.png"
                                 srccredit="Chris Good"/>
                    </imageobject>
                  </mediaobject>
                </screenshot>
              </figure>
            </para>
          </example>
        </sect4>

        <sect4 id="invest-sell-man-sep-net">
          <title>Separated, Net Pricing</title>

          <table>
            <title>Selling Shares Split Scheme, Sale and Capital Gain/Loss Are Separate Transactions, Sale Transaction</title>

            <tgroup cols="5">
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>

              <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>
                    Assets:Bank ABC
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    NET_SALE
                  </entry>

                  <entry></entry>
                </row>

                <row>
                  <entry>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    &minus;NUM_SHARES
                  </entry>

                  <entry>
                    NET_SELL_PRICE
                  </entry>

                  <entry></entry>

                  <entry>
                    NET_SALE
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <table>
            <title>Selling Shares Split Scheme, Sale and Capital Gain/Loss Are Separate Transactions, Capital Gain/Loss
              Transaction</title>

            <tgroup cols="5">
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>
              <colspec colnum="1" colwidth="2*"/>

              <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>
                    Assets:Stock:SYMBOL
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    0
                  </entry>

                  <entry>
                    NET_PROFIT
                  </entry>

                  <entry>
                    (Loss)
                  </entry>
                </row>

                <row>
                  <entry>
                    Income:Capital Gains
                  </entry>

                  <entry></entry>

                  <entry></entry>

                  <entry>
                    (Loss)
                  </entry>

                  <entry>
                    NET_PROFIT
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

      <example id="invest-sell-man-prof-sep-net">
        <title>Sale of Shares with Profit, Manual Profit/Loss Calculation, Sale &amp; Profit Separated, Net Pricing</title>
        <simpara>In this example, we will use the AMZN account created in <xref linkend="invest-setup-example2" />.</simpara>

        <para>You bought 100 shares of AMZN for $20 per share (including commissions), then later sell them all
          for $36 per share with a commission of $75. In the split transaction scheme is as follows:
          <itemizedlist>
            <listitem><simpara>NUM_SHARES is 100,</simpara></listitem>
            <listitem><simpara>NET_BUY_PRICE is $20 (the original buying price),</simpara></listitem>
            <listitem><simpara>NET_BUY is $2,000 (the original buying cost),</simpara></listitem>
            <listitem><simpara>NET_SELL_PRICE is $35.25 (($3600 &minus; $75) / 100)),</simpara></listitem>
            <listitem><simpara>GROSS_SALE is $3,600, NET_SALE is $3,525,</simpara></listitem>
            <listitem><simpara>and finally NET_PROFIT is $1,525 (NET_SALE &minus; NET_BUY).</simpara></listitem>
          </itemizedlist>
        </para>

        <para>
        <table>
          <title>Selling Shares Split Scheme, Sale Transaction, Net Pricing</title>
<?dbfo table-width="70%" ?>
          <tgroup cols="5">
            <colspec colnum="1" colwidth="4*"/>
            <colspec colnum="1" colwidth="2*"/>
            <colspec colnum="1" colwidth="2*"/>
            <colspec colnum="1" colwidth="1*"/>
            <colspec colnum="1" colwidth="1*"/>

            <tbody>
              <row>
                <entry>
                  <emphasis>Account</emphasis>
                </entry>

                <entry>
                  <emphasis>Shares</emphasis>
                </entry>

                <entry>
                  <emphasis>Price</emphasis>
                </entry>

                <entry>
                  <emphasis>Buy</emphasis>
                </entry>

                <entry>
                  <emphasis>Sell</emphasis>
                </entry>
              </row>

              <row>
                <entry>
                  Assets:Bank ABC
                </entry>

                <entry></entry>

                <entry></entry>

                <entry>
                  3525.00
                </entry>

                <entry></entry>
              </row>

              <row>
                <entry>
                  Assets:Brokerage Account:Stock:AMZN
                </entry>

                <entry>
                  &minus;100
                </entry>

                <entry>
                  35.25
                </entry>

                <entry></entry>

                <entry>
                  3525.00
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        </para>

        <para>
        <table>
          <title>Selling Shares Split Scheme, Gain Transaction, Net Pricing</title>
<?dbfo table-width="70%" ?>
          <tgroup cols="5">
            <colspec colnum="1" colwidth="4*"/>
            <colspec colnum="1" colwidth="2*"/>
            <colspec colnum="1" colwidth="2*"/>
            <colspec colnum="1" colwidth="1*"/>
            <colspec colnum="1" colwidth="1*"/>

            <tbody>
              <row>
                <entry>
                  <emphasis>Account</emphasis>
                </entry>

                <entry>
                  <emphasis>Shares</emphasis>
                </entry>

                <entry>
                  <emphasis>Price</emphasis>
                </entry>

                <entry>
                  <emphasis>Buy</emphasis>
                </entry>

                <entry>
                  <emphasis>Sell</emphasis>
                </entry>
              </row>

              <row>
                <entry>
                  Assets:Brokerage Account:Stock:AMZN
                </entry>

                <entry>
                  0
                </entry>

                <entry>
                  0
                </entry>

                <entry>
                  1525.00
                </entry>

                <entry></entry>
              </row>

              <row>
                <entry>
                  Income:Capital Gain (Long Term):AMZN
                </entry>

                <entry></entry>

                <entry></entry>

                <entry></entry>

                <entry>
                  1525.00
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <figure pgwide="1">
          <title>Selling Shares for Gain Where the Sale and Gain are Recorded in Separate Transactions,
                    in <guilabel>Transaction Journal</guilabel> View</title>
            <screenshot id="invest-sellstockManProfSepNet">
              <mediaobject>
                <imageobject role="html">
                  <imagedata fileref="figures/invest_sellstockManProfSepNet.png"
                             srccredit="Chris Good" width="&img-w;"/>
                </imageobject>
                <imageobject role="fo">
                  <imagedata fileref="figures/invest_sellstockManProfSep.png"
                             srccredit="Chris Good"/>
                </imageobject>
              </mediaobject>
            </screenshot>
        </figure>
        </para>
      </example>


        </sect4>
      </sect3>
    </sect2>

    <sect2 id="invest-sellLots">
      <title>Selling Shares with Automatic Calculation of Capital Gain or Loss Using Lots</title>

      <sect3 id="invest-sellLotsIntro">
        <title>Introduction</title>

        <para><ulink url="&url-wp-en;Lot">Wikipedia</ulink> includes the following definition of a lot:
          <blockquote>
            <simpara>a set of goods for sale together in an auction; or a quantity of a financial instrument</simpara>
          </blockquote>
        </para>

        <para>&app; has a built-in lot management facility that can be used to keep track of capital gains or
          losses resulting from security sales. Buy and sell transactions are put into lots for the
          purpose of calculating the cost of the sale. More specifically, a lot is used to link
          particular buy and sell transaction splits. Lots can be automatically or manually created
          and linked. Capital gain or loss can be automatically calculated and transaction(s)
          created for the difference between the sale value and the cost of the securities sold.
          &app; refers to this process as <emphasis>scrubbing</emphasis>.
        </para>

        <para>The term <emphasis>scrub</emphasis> is used because security accounts need to be cleaned after sales
          to ensure the difference between the cost paid for securities, and value received from
          selling them, is accounted for as capital gain or loss. If the capital gain/loss is not
          correct, the <guimenuitem>Trial Balance</guimenuitem> bottom line total debits will not balance to total credits.
          To see the <guimenuitem>Trial Balance</guimenuitem>, select <menuchoice>
            <guimenu>Reports</guimenu> <guisubmenu>Income &amp; Expense</guisubmenu>
            <guimenuitem>Trial Balance</guimenuitem>
          </menuchoice>.        </para>

        <note>
          <para>If you make an error, you can delete the lot(s) and capital gain/loss transaction(s) and retry.
            Ensure you delete the lot, or at least unlink sale transactions from the lot, before you
            delete a capital gain/loss transaction. Otherwise, the <guilabel>Lots in
            Account</guilabel> screen will recreate the capital gain/loss transaction when you
            select the lot.
          </para>
        </note>

        <para>If you are not familiar with <acronym>FIFO</acronym>, <acronym>LIFO</acronym> or Average costing, please see Wikipedia
          <ulink
            url="&url-wp-en;FIFO_and_LIFO_accounting">FIFO and LIFO
          accounting</ulink> and <ulink
            url="&url-wp-en;Average_cost_method">Average
          cost method</ulink>.
        </para>

        <para>If you are not familiar with the difference between &app; transactions and splits, please see
          <xref linkend="txns-registers-txntypes" />.
        </para>

        <para>The &app; lot management facility can be a useful feature, reducing manual calculation, especially
          if dividends have been reinvested over years and there are many different costs involved.
          It can automatically link buy transactions to sell transactions using <acronym>FIFO</acronym> cost method and
          one can manually link specific buy transactions to sell transactions in order to use <acronym>LIFO</acronym>.
          Advanced Portfolio Report basis costs and gains/losses will agree with the costs and
          gain/loss transactions created by scrubbing if either the <acronym>FIFO</acronym> or <acronym>LIFO</acronym> cost methods are
          used.
        </para>
      </sect3>

      <sect3 id="invest-sellLotsWin">
        <title>Lots in Account Window</title>

        <para>The <guilabel>Lots in Account SSSS</guilabel> window, where SSSS is a security account, is used to
          manually or automatically link security transaction splits to lots and create capital
          gain/loss transactions to account for the difference between the costs of buying a
          security and the value received by selling it.
        </para>

        <para>To open the <guilabel>Lots in Account</guilabel> window, open the security account register, then
          select
          <menuchoice>
            <guimenu>Actions</guimenu><guimenuitem>View Lots</guimenuitem>
          </menuchoice>.
        </para>

        <figure pgwide="1">
          <title>Selling Shares - Capital Gains - Lots in Account window</title><screenshot id="tool-lotsInAcct">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/investLots2_BeforeScrub1Lot.png"
                srccredit="Chris Good" width="&img-w;"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="figures/investLots2_BeforeScrub1Lot.png"
                           srccredit="Chris Good"/>
              </imageobject>
              <caption>
                <para>An image of the <emphasis>Lots in Account</emphasis> window.
                </para>
              </caption>
            </mediaobject>
          </screenshot>
        </figure>

        <para>Refer to the Help Manual, Chapter 8 Tools &amp; Assistants,
          <ulink url="&url-docs-C;help/tool-lots.html">Lots in Account</ulink>
          for details of the Lots in Account screen elements.
        </para>
      </sect3>

      <sect3 id="invest-sellProcedure">
        <title>Procedure Summary</title>

        <para>Using the lot management facility for the automatic calculation of capital gain or loss typically
          follows these steps:

        <orderedlist>
          <listitem>
            <simpara>Record the sale transaction using Net Pricing (but stop short of entering the Capital Gain
              transaction as it will be created by scrubbing). See
              <xref linkend="invest-sell-man-prof-sep-net" />.
            </simpara>
          </listitem>
<!-- Manual Lot Creation and Linking -->
          <listitem>
            <simpara><xref linkend="invest-sellManual" /> (Optional depending on cost method)</simpara>
          </listitem>

          <listitem>
<!-- Automatic Creation of Capital Gain Or Loss Transactions -->
            <simpara><xref linkend="invest-sellAuto" /></simpara>
          </listitem>

          <listitem>
<!-- Change Orphaned Gains-CCC to Gain/Loss Account -->
            <simpara><xref linkend="invest-sellChgCapGainsAcct" /></simpara>
          </listitem>

          <listitem>
<!-- Run a Trial Balance  -->
            <simpara><xref linkend="invest-sellTrialBal" /> report to ensure total debits balance to total credits.</simpara>
          </listitem>
        </orderedlist>
        </para>
      </sect3>

      <sect3 id="invest-sellManual">
        <title>Manual Lot Creation and Linking</title>

        <para>Before using this feature, ensure you have read <xref linkend="invest-sellConsiderations" />.
        </para>

        <para>This functionality allows the manual linking of specific buy and sell transactions. It may be used in
          the case where a user wishes to use a different cost method than the automatic linking
          method (<acronym>FIFO</acronym>). Effectively, if one wishes the cost basis and capital gains in the Advanced
          Portfolio Report to be consistent with the capital gains transactions created by
          scrubbing, manual lot creation only needs to be used when using <acronym>LIFO</acronym> or <quote>sale of
          designated lots</quote> (the same thing for securities as far as US personal tax law is
          concerned). This is because the scrub function can automatically do <acronym>FIFO</acronym> linking so there
          is no need to do it manually and scrubbing cannot be used for average costing.

          See <xref linkend="invest-sellManualExample" />.
        </para>
      </sect3>

      <sect3 id="invest-sellAuto">
        <title>Automatic Creation of Capital Gain Or Loss Transactions</title>

        <note>
          <para>Do <emphasis>not</emphasis> do this unless you are using <acronym>FIFO</acronym> or <acronym>LIFO</acronym> to cost sales. See
            <xref linkend="invest-sellConsiderations" />.
          </para>
        </note>

        <para>&app; can automatically calculate and create security sale capital gain/loss transactions. Lots are
          used to link buy transaction splits with sell transaction splits so the correct cost of
          the securities sold can be determined. &app; will use any existing lots, and create new
          lots for any buy transaction splits not already linked to a lot. Buy and sell transaction
          splits are linked to lots using <acronym>FIFO</acronym> method.
        </para>

        <para>See:
          <itemizedlist>
            <listitem><simpara><xref linkend="invest-sellAutoExample" />,</simpara></listitem>
            <listitem><simpara><xref linkend="invest-sellAutoExample2" />,</simpara></listitem>
            <listitem><simpara><xref linkend="invest-sellFifoSplit" />.</simpara></listitem>
          </itemizedlist>
        </para>

      </sect3>

      <sect3 id="invest-sellChgCapGainsAcct">
        <title>Change Orphaned Gains-CCC to Gain/Loss Account</title>

        <para>The capital gain/loss transaction(s) created by scrubbing uses an automatically created generic
          <emphasis>Orphaned Gains-CCC</emphasis> account (where CCC is the security currency)
          because &app; doesn't know which capital gain or loss account should be used. After
          scrubbing, the user should edit the <emphasis> Orphaned Gains-CCC</emphasis> transaction
          split to re-assign the income account to a more meaningful income (or expense) gain or
          loss account (for example, <emphasis>Income:Capital Gain (Long Term):IBM</emphasis>).
        </para>

        <para>See <xref linkend="invest-sellChgCapGainsAcctExample" />.
        </para>
      </sect3>

      <sect3 id="invest-sellTrialBal">
        <title>Run a Trial Balance</title>

        <para>Running a Trial Balance report (
          <menuchoice>
            <guimenu>Reports</guimenu><guisubmenu>Income &amp; Expense</guisubmenu>
            <guimenuitem>Trial Balance</guimenuitem>
          </menuchoice>
          ) after creating capital gain/loss transactions, is a basic check that capital
          gains/losses are correctly accounting for the difference between the cost paid for
          securities, and value received from selling them. At the end of the report, total debits
          should equal total credits.
        </para>

        <tip>
          <para>A Trial Balance may not balance due to some other problem. To determine if the cause of an imbalance
            is from incorrectly accounting for capital gain/loss:
            <orderedlist>
              <listitem>
                <para>If necessary, temporarily change the date of the sell transaction and the capital gain/loss
                  transaction, so they are the only transactions for a particular date, then run the Trial
                  Balance as at the day before. If the Trial Balance is still out by the same amount, it
                  is not the capital gain/loss that is causing the problem.
                </para>
              </listitem>
              <listitem>
                <para>If you find a prior <emphasis>out of balance</emphasis> Trial Balance, keep running the Trial
                  Balance report with different dates until you find the date it starts being out of
                  balance. Temporarily change the transaction dates for each transaction on the problem
                  date to the following day, then change the dates back to the correct date 1 at a time,
                  running the Trial Balance each time, until you identify the problem transaction. When
                  you change the date of a security sell transaction, you also need to change the date of
                  the corresponding capital gain transaction as it is only the sum of these that will
                  balance in the Trial Balance.
                </para>
              </listitem>
            </orderedlist>
          </para>
        </tip>
      </sect3>

      <sect3 id="invest-sellConsiderations">
        <title>Considerations</title>

        <para>There are some points that should be considered before using the lot management facility.
        </para>

        <orderedlist>
          <listitem>
            <para>&app; implements only the First In/ First Out (<acronym>FIFO</acronym>) cost method when automatically linking buy
              transactions to sell transactions. That means the oldest securities are always sold first.
              The Last In First Out (<acronym>LIFO</acronym>) cost method may be used by manually linking the most
              recent buy security splits to the sell split before scrubbing.
            </para>
          </listitem>

          <listitem>
            <para>The Advanced Portfolio Report does not use lot information when calculating costs, just the security
              transaction splits. It calculates the cost basis and gains or losses using the
              selected <emphasis>Basis calculation method</emphasis> report option (Average, <acronym>FIFO</acronym> or
              <acronym>LIFO</acronym>). If one wishes the Advanced Portfolio Report costs and gains/losses to be
              consistent with the capital gain/loss transactions created by scrubbing, the same cost
              model must be used in both places.
            </para>
          </listitem>

          <listitem>
            <para>Scrubbing does not recognize commissions or fees so makes no allowance for them in the calculation
              of gain or loss. Therefore you must use <emphasis>Net Pricing</emphasis> rather than
              <emphasis>Gross Pricing</emphasis> if you wish to use scrubbing. See
              <xref linkend="invest-buy-com" />.
            </para>
          </listitem>

          <listitem>
            <para>Scrubbing does not recognize capital gain/loss transaction splits if they have been manually entered
              as part of the sale transaction. Therefore ensure previous sales are recorded as 2
              transactions:
            </para>

            <table>
              <title>Transaction 1 dealing with value received and the reduction of the number of shares</title>

              <tgroup cols="5">
                <tbody>
                  <row>
                    <entry>
                      <emphasis>Account</emphasis>
                    </entry>

                    <entry>
                      <emphasis>Tot Shares</emphasis>
                    </entry>

                    <entry>
                      <emphasis>(Unit) Price</emphasis>
                    </entry>

                    <entry>
                      <emphasis>Buy (Debit)</emphasis>
                    </entry>

                    <entry>
                      <emphasis>Sell (Credit)</emphasis>
                    </entry>
                  </row>

                  <row>
                    <entry>
                      Brokerage or Bank
                    </entry>

                    <entry></entry>

                    <entry></entry>

                    <entry>
                      Debit
                    </entry>

                    <entry></entry>
                  </row>

                  <row>
                    <entry>
                      Security
                    </entry>

                    <entry>
                      &minus;NumSold
                    </entry>

                    <entry>
                      SaleUnitPrice
                    </entry>

                    <entry></entry>

                    <entry>
                      SaleValue
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <table>
              <title>Transaction 2 capital gain/loss (loss in this example)</title>

              <tgroup cols="5">
                <tbody>
                  <row>
                    <entry>
                      <emphasis>Account</emphasis>
                    </entry>

                    <entry>
                      <emphasis>Tot Shares</emphasis>
                    </entry>

                    <entry>
                      <emphasis>(Unit) Price</emphasis>
                    </entry>

                    <entry>
                      <emphasis>Buy (Debit)</emphasis>
                    </entry>

                    <entry>
                      <emphasis>Sell (Credit)</emphasis>
                    </entry>
                  </row>

                  <row>
                    <entry>
                      Capital Loss
                    </entry>

                    <entry></entry>

                    <entry></entry>

                    <entry>
                      Debit
                    </entry>

                    <entry></entry>
                  </row>

                  <row>
                    <entry>
                      Security
                    </entry>

                    <entry>
                      0
                    </entry>

                    <entry>
                      0
                    </entry>

                    <entry></entry>

                    <entry>
                      Credit
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
          </listitem>

          <listitem>
            <para>The automatic capital gains calculations can handle straightforward buy, sell, and return of capital
              transactions but any transaction that affect the number of shares, even simple splits,
              will cause it to produce wrong answers so those cases must be handled manually.
            </para>
          </listitem>
        </orderedlist>
      </sect3>

      <sect3>
      <title>Examples</title>
      <example id="invest-sellManualExample">
        <title>Manual Lot Creation and Linking</title>

        <para>Here is an example of selling part of a security holding using the <acronym>LIFO</acronym> method. In this example, the
          most recent buy transaction (dated Jul. 1, 2016, a reinvested dividend), is linked to a lot,
          along with the sell transaction, and the &app; scrub function is used to calculate capital
          gain or loss and create the capital gain/loss transaction.
        </para>

        <procedure>
          <step>
            <simpara>Open the security account's register.</simpara>

            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Security register before scrubbing a single lot</title><screenshot id="invest-lots0reg">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/investLots0_RegB4Scrub.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/investLots0_RegB4Scrub.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <simpara>An image of the Security Account register in transaction journal view, before lot scrubbing.</simpara>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>
          </step>
          <step>
            <simpara>Ensure all previous capital gain/loss transactions are separate transactions to the sell
              transactions which record the reduction in the number of shares and the value
              received.</simpara>
          </step>
          <step><simpara>Select
              <menuchoice>
                <guimenu>Actions</guimenu><guimenuitem>View Lots</guimenuitem>
              </menuchoice>
              to open the <guilabel>Lots in Account SSSS</guilabel> window where SSSS is the
              security account.
            </simpara>

            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Lots before scrubbing a single lot</title><screenshot id="invest-lots1B4CreateLot">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/investLots1_BeforeCreateLot.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/investLots1_BeforeCreateLot.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <para>An image of the <emphasis>Lots in Account</emphasis> window before lot scrubbing.
                    </para>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>
          </step>

          <step><simpara>Create a new lot using the <guibutton>New Lot</guibutton> button. Initially this lot is not linked to
              any buy or sell split.</simpara>
          </step>

          <step>
            <simpara>Highlight the new lot in the <guilabel>Lots in This Account</guilabel> panel.</simpara>
          </step>

          <step><simpara>Highlight the buy split (dated Jul. 1, 2016) of the security to be sold in the <guilabel>Splits
              free</guilabel> panel.</simpara>
          </step>

          <step><simpara>Click the <guilabel>&gt;&gt;</guilabel> button to link the buy split with the highlighted lot. The
              split moves from the <guilabel>Splits free</guilabel> panel to the <guilabel>Splits
              in Lot</guilabel> panel.
            </simpara>
          </step>

          <step><simpara>Repeat the previous 2 steps for any other buy splits that should be included in the lot (in this
              example, there is only 1 buy split in the sale).
            </simpara>
          </step>

          <step>
            <simpara>Highlight the sell split in the <guilabel>Splits free</guilabel> panel.</simpara>
          </step>

          <step>
            <simpara>Click the <guilabel>&gt;&gt;</guilabel> button to link the sell split with the highlighted lot.</simpara>
          </step>

          <step>
            <simpara>Check the lot <guilabel>Balance</guilabel> is as expected. In this example the lot balance
              should be zero as the number of securities sold in the lot, is matched with the same
              number of security buys.
            </simpara>

            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Lots before scrubbing a single lot, after manual linking</title>
              <screenshot id="invest-lots2B4Scrub1Lot">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/investLots2_BeforeScrub1Lot.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/investLots2_BeforeScrub1Lot.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <simpara>An image of the <emphasis>Lots in Account</emphasis> window before scrubbing a single lot.</simpara>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>
          </step>

          <step>
            <simpara>Click the <guibutton>Scrub</guibutton> button (<emphasis>not</emphasis> the <guibutton>Scrub Account</guibutton> button.)
            </simpara>
            <para>The <guilabel>Lots in Account</guilabel> window has not changed after using the
              <guilabel>Scrub</guilabel> button so no example screen image is supplied.
            </para>
          </step>

          <step>
            <simpara>Close the <guilabel>Lots in Account SSSS</guilabel> window and return to the security account
              register.
            </simpara>

            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Register after manual linking and scrubbing a single lot</title>
              <screenshot id="invest-lots2RegAftScrub1Lot">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/investLots2_RegAfterScrub1Lot.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/investLots2_RegAfterScrub1Lot.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <simpara>An image of the Register after scrubbing a single lot.</simpara>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>
          </step>

          <step>
            <simpara>Continue to <xref linkend="invest-sellChgCapGainsAcct" />.</simpara>
          </step>

        </procedure>
      </example>


      <example id="invest-sellAutoExample">
        <title>Automatic Creation of Capital Gain Or Loss Transactions</title>

        <simpara>Create the capital gains transaction by following these steps:</simpara>

        <procedure>
          <step>
            <simpara>Open the security account's register.</simpara>
          </step>

          <step>
            <simpara>Ensure any previous manually entered capital gain/loss transaction splits have been entered in
            separate transactions to the the sell transactions.</simpara>
          </step>

          <step>
            <simpara>Select
              <menuchoice>
                <guimenu>Actions</guimenu><guimenuitem>View Lots</guimenuitem>
              </menuchoice>
              to open the <guilabel>Lots in Account SSSS</guilabel> window where SSSS is the
              security account.</simpara>
          </step>

          <step>
            <simpara>If using <acronym>LIFO</acronym>, use the above procedure <xref linkend="invest-sellManual" /> to create a lot for each
              sell transaction, link the lot with the sell transaction and each of the buy
              transactions that make up the sale.</simpara>
          </step>

          <step>
            <simpara>Click the <guilabel>Scrub Account</guilabel> button which:</simpara>

            <itemizedlist>
              <listitem>
                <para>Creates lots for any buy transactions that are not already linked to a lot and links them to sell
                  transactions splits using the <acronym>FIFO</acronym> method. As a transaction split can only be
                  linked to 1 lot, if a sell transaction needs to be linked to multiple lots, the
                  sell transaction split is itself split into multiple subsplits. In the case of
                  multiple subsplits, it is possible to have different splits from the same
                  transaction in both the <guilabel>Splits free</guilabel> and <guilabel>Splits in
                  lot</guilabel> panels.
                </para>
              </listitem>

              <listitem>
                <simpara>Creates a separate transaction per lot for capital gain/loss.</simpara>
              </listitem>
            </itemizedlist>
          </step>

          <step>
            <simpara>Continue to <xref linkend="invest-sellChgCapGainsAcct" />.</simpara>
          </step>
        </procedure>
      </example>


      <example id="invest-sellAutoExample2">
        <title>Automatic Creation of Capital Gain Or Loss Transactions, 2 Sales at Once</title>

        <para>Here is an example of <acronym>FIFO</acronym> scrubbing without manual lot creation. In this example, the transactions
          for 2 sales are scrubbed at once but usually scrubbing would be performed after each sale.
          One reason for scrubbing 2 sales at once, could be because there were multiple sales on
          the same day.
          <figure pgwide="1">
            <title>Selling Shares - Capital Gains - Register before Scrub Account</title>
            <screenshot id="invest2-lots0reg">
              <mediaobject>
                <imageobject role="html">
                  <imagedata fileref="figures/invest2Lots0RegB4Scrub.png"
                             srccredit="Chris Good" width="&img-w;"/>
                </imageobject>
                <imageobject role="fo">
                  <imagedata fileref="figures/invest2Lots0RegB4Scrub.png"
                             srccredit="Chris Good"/>
                </imageobject>
                <caption>
                  <simpara>An image of the Security Account register in transaction journal view, before Scrub Account is used.</simpara>
                </caption>
              </mediaobject>
            </screenshot>
          </figure>
        </para>

        <procedure>
          <step><simpara>Select
              <menuchoice>
                <guimenu>Actions</guimenu><guimenuitem>View Lots</guimenuitem>
              </menuchoice>
              to open the <guilabel>Lots in Account SSSS</guilabel> window where SSSS is the
              security account.</simpara>
            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Lots before Scrub Account</title>
              <screenshot id="invest2-lots1B4ScrubAcct">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/invest2Lots1B4Scrub.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/invest2Lots1B4Scrub.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <simpara>An image of the <emphasis>Lots in Account</emphasis> window before Scrub Account is used.</simpara>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>
          </step>

          <step>
            <simpara>Click the <guilabel>Scrub Account</guilabel> button.</simpara>
            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Lots after Scrub Account</title>
              <screenshot id="invest2-lots2AftScrubAcct">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/invest2Lots2LotsAftScrubAcct.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/invest2Lots2LotsAftScrubAcct.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <para>An image of the <emphasis>Lots in Account </emphasis> window after using Scrub Account.
                    </para>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>

            <note>
              <para>After using the <guilabel>Scrub Account</guilabel> button only the last lot is shown, so the above
                image is after the <guilabel>Lots in Account</guilabel> window has been closed and
                reopened so all the lots show.
              </para>
            </note>
          </step>

          <step>
            <simpara>Close the <guilabel>Lots in Account SSSS</guilabel> window and return to the security account register.</simpara>
            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Register after Scrub Account</title>
              <screenshot id="invest2-lots3AftScrubAcct">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/invest2Lots3RegAftScrubAcct.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/invest2Lots3RegAftScrubAcct.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <para>An image of the <emphasis>security register</emphasis> after using Scrub Account.
                    </para>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>

            <note>
              <para>The security splits in the sell transactions have been split into subsplits, one subsplit per lot,
                and a capital gain transaction has been created for each security subsplit of each
                sell transaction.
              </para>
            </note>
          </step>

          <step>
            <simpara>Continue to <xref linkend="invest-sellChgCapGainsAcct" />.</simpara>
          </step>
        </procedure>
      </example>

      <example id="invest-sellFifoSplit">
        <title>Automatic Creation of Capital Gain Or Loss Transactions - After a Simple Stock Split</title>

        <para>Here is an example of <acronym>FIFO</acronym> scrubbing without manual lot creation/linking, where the Stock Split
          Assistant has been used for a simple stock split. In this example, 100 shares of security
          XYZ were bought for $10.00 each, there was a simple 2 for 1 stock split for zero cost (so
          the holding was then 200 shares @ $5.00 each), then all 200 shares were sold for $6.00
          each.
        </para>
        <para>
        <figure pgwide="1">
          <title>Selling Shares - Capital Gains - Register after Scrub Account</title><screenshot id="investLotsSplitReg">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/investLotsSplitReg.png"
                           srccredit="Chris Good" width="&img-w;"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="figures/investLotsSplitReg.png"
                           srccredit="Chris Good"/>
              </imageobject>
              <caption>
                <para>An image of the Security Account register in transaction journal view, after Scrub Account is used.
                </para>
              </caption>
            </mediaobject>
          </screenshot>
        </figure>

        <figure pgwide="1">
          <title>Selling Shares - Capital Gains - Lot 0 after Scrub Account</title><screenshot id="investLotsSplitLot0">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/investLotsSplitLot0.png"
                           srccredit="Chris Good" width="&img-w;"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="figures/investLotsSplitLot0.png"
                           srccredit="Chris Good"/>
              </imageobject>
              <caption>
                <para>An image of the Security Account register in transaction journal view, after Scrub Account is used.
                </para>
              </caption>
            </mediaobject>
          </screenshot>
        </figure>

        <figure pgwide="1">
          <title>Selling Shares - Capital Gains - Lot 1 after Scrub Account</title><screenshot id="investLotsSplitLot1">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/investLotsSplitLot1.png"
                           srccredit="Chris Good" width="&img-w;"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="figures/investLotsSplitLot1.png"
                           srccredit="Chris Good"/>
              </imageobject>
              <caption>
                <para>An image of the Security Account register in transaction journal view, after Scrub Account is used.
                </para>
              </caption>
            </mediaobject>
          </screenshot>
        </figure>
        </para>
        <para>The above screenshots show that scrubbing created:
          <itemizedlist>
            <listitem>
              <simpara>2 lots. A separate lot for each buy (it essentially treats the stock split as a buy of 100 for no cost.)</simpara>
            </listitem>
            <listitem>
              <simpara>2 capital gain transactions (one for each lot) on the date of the sale:</simpara>
              <itemizedlist>
                <listitem>
                  <simpara>Lot 0: Jul. 1, 2009 loss $400 (sale $600 &minus; cost $1,000.)</simpara>
                </listitem>
                <listitem>
                  <simpara>Lot 1: Jul. 1, 2009 gain $600 (sale $600 &minus; cost $0.)</simpara>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </para>

        <para>Total gain $200 is correct. Whether the gain is a single long-term one or one each of long-term and
          short-term or whether there's even a distinction depends on the user's tax jurisdiction
          and the way the split is structured. If the user needs help figuring it out they should
          consult a professional.
        </para>

      </example>

      <example id="invest-sellChgCapGainsAcctExample">
        <title>Changing the Orphaned Gains-CCC to Gain/Loss Account</title>
        <procedure>
          <step>
            <simpara>Close the <guilabel>Lots in Account SSSS</guilabel> window if open and return to the security
              account register.</simpara>
            <figure pgwide="1">
              <title>Selling Shares - Capital Gains - Register after scrubbing a single lot</title><screenshot id="invest-lots4AftScrub1LotReg">
                <mediaobject>
                  <imageobject role="html">
                    <imagedata fileref="figures/investLots2_RegAfterScrub1Lot.png"
                               srccredit="Chris Good" width="&img-w;"/>
                  </imageobject>
                  <imageobject role="fo">
                    <imagedata fileref="figures/investLots2_RegAfterScrub1Lot.png"
                               srccredit="Chris Good"/>
                  </imageobject>
                  <caption>
                    <para>An image of the <emphasis>security register</emphasis> after scrubbing a single lot.
                    </para>
                  </caption>
                </mediaobject>
              </screenshot>
            </figure>
          </step>

          <step>
            <simpara>Find each new <emphasis>Realized Gain/Loss</emphasis> transaction in the security account register
              (they will have the same date as the sell transactions).
            </simpara>
          </step>

          <step>
            <simpara>Edit the <emphasis>Orphaned Gains-CCC</emphasis> transaction split to re-assign the income account to a more
              meaningful income (or expense) gain or loss account (for example, <emphasis>Income:Capital Gain (Long Term):IBM</emphasis>).</simpara>
            <tip>
              <simpara>You may like to split the capital gain/loss into taxable and non taxable parts if that is in accord
                with your tax laws.
              </simpara>
            </tip>
          </step>
        </procedure>
      </example>
      </sect3>
    </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>

    <sect2 id="invest-dividendcash">
      <title>Dividends in Cash</title>

      <para>If the dividend is presented as cash, you should record the transaction in the asset account that
        received the money, as income from <emphasis>Income:Dividends</emphasis>. Additionally if
        you want to tie the cash dividend to a particular stock holding then add a dummy transaction
        split to the stock account with quantity 0 price 1 value 0.
      </para>

      <para>As an example consider the following; the dividends deposited as cash into the
        <emphasis>Broker</emphasis> Account with a tie to the stock account.
      </para>

<!-- ToDo: unshrink -->
      <figure>
        <title>Example Of Cash Dividend Transactions</title>
        <screenshot id="invest-dividendcash1">
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/invest_dividendcash.png"
                       srccredit="Daniel Dodson"/>
          </imageobject>
          <caption>
            <para>An image of the <emphasis>Brokerage</emphasis> Account register after a series of cash dividends.
            </para>
          </caption>
        </mediaobject>
      </screenshot>
      </figure>

      <note>
        <para>If you want to track dividends on a per-stock basis, you would need to create an
          <emphasis>Income:Dividends:STOCKSYMBOL</emphasis> account for each stock you own that pays
          dividends.
        </para>
      </note>
    </sect2>

    <sect2 id="invest-dividendreinvest">
      <title>Dividends Re-Invested</title>

      <para>If you receive the dividend in the form of an automatic reinvestment, the transaction for this
        should be handled within the stock or mutual fund account as income from
        <emphasis>Income:Dividends</emphasis> for the appropriate number of reinvested shares. This type of
        reinvest account is often referred to as a <acronym>DRIP</acronym> (Dividend Re-Investment Program).
      </para>

      <para>As an example consider the following purchase of NSTAR (NST) stock with the dividends reinvested
        into a DRIP Account. Mutual fund re-investments would be the same.
      </para>

      <para>Starting with the purchase of 100 shares on Jan. 3, 2005, all dividends will be reinvested and an
        account is created to track the dividend to the specific stock. &app; simplifies the entry
        by allowing calculations within the cells of the transaction. If the first dividend is
        $0.29/share, enter <userinput>53.28</userinput> (purchase price + dividend) in the share <guilabel>Price</guilabel>
        cell and <userinput>100*0.29</userinput> in the <guilabel>Buy</guilabel> cell. &app; will calculate for you the
        corresponding number of <guilabel>Shares</guilabel>.
      </para>

      <figure>
        <title>Example Of Dividend Reinvestment Transactions</title>
        <screenshot id="invest-dividendreinvest1">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/invest_dividendreinvest1.png"
                          srccredit="Cristian Marchi" width="&img-w;"/>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/invest_dividendreinvest1.png"
                          srccredit="Cristian Marchi"/>
            </imageobject>
            <caption>
              <para>An image of the NST Stock Account register after a dividend reinvestment.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>
  </sect1>

  <sect1 id="invest-retofcap">
    <title>Return of Capital</title>

    <para>This refers to a transaction where an investment returns capital to the investor and doesn't have
      any accounting implications other than reducing the cost basis. The number of shares held is
      not changed.
    </para>

    <para>A Return of Capital transaction can be entered in the stock register by entering the stock split
      with:
    </para>

    <informaltable>
      <tgroup cols="2">
        <tbody>
          <row>
            <entry>
              Shares
            </entry>

            <entry>
              0
            </entry>
          </row>

          <row>
            <entry>
              Price
            </entry>

            <entry>
              0
            </entry>
          </row>

          <row>
            <entry>
              Sell
            </entry>

            <entry>
              Return of Capital value
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The other side of the double entry would usually be a debit to the brokerage bank account.
    </para>

    <figure>
      <title>Example Of Return Of Capital Transactions</title>
      <screenshot id="invest-ret-of-cap">
        <mediaobject>
          <imageobject role="html">
            <imagedata fileref="figures/invest_ret_of_cap.png"
                        srccredit="Chris Good" width="&img-w;"/>
          </imageobject>
          <imageobject role="fo">
            <imagedata fileref="figures/invest_ret_of_cap.png"
                        srccredit="Chris Good"/>
          </imageobject>
          <caption>
            <para>An image of the Stock Account register after a return of capital.
            </para>
          </caption>
        </mediaobject>
      </screenshot>
    </figure>

    <note>
      <para>It is not possible to use the Stock Split Assistant to do this type of transaction.
      </para>
    </note>

    <tip>
      <para>If you accidentally entered a non-zero price in the stock split, &app; may have created an unwanted
        price database entry which could cause reports to be wrong. Check for and remove such an
        unwanted entry from the price database using
        <menuchoice>
          <guimenu>Tools</guimenu><guimenuitem>Price Database</guimenuitem>
        </menuchoice>.
      </para>
    </tip>
  </sect1>

  <sect1 id="invest-splitsnmergers1">
    <title>Splits and Mergers</title>

    <para>Companies may split their stock for many reasons but the most common is that the price has risen
      higher than management thinks is a reasonable price for many investors. Some of these splits
      are simple exchanges (for example, 2 for 1 or 3 for 2) and some are complex exchanges with cash
      distributions. Splits may also result in fewer shares if the exchange rate is a reverse split
      (1 for 3 or 0.75 for 1).
    </para>

    <sect2 id="invest-simplesplit">
      <title>Simple Stock Split</title>

      <para>As an example, our holding of NST stock declared a 2 for 1 stock split effective June 6, 2005. The
        process for entering this transaction is; select
        <menuchoice>
          <guimenu>Actions</guimenu><guimenuitem>Stock Split</guimenuitem>
        </menuchoice>
        to start the assistant.
      </para>

 <!-- ToDo: unshrink -->
      <figure>
        <title>Activation Of The <quote>Stock Split</quote> Assistant</title>
        <screenshot id="invest-split1">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_split1.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the selection of the stock split assistant.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>The first screen is an Introduction, select <guibutton>Forward</guibutton> to display the selection
        of the account and stock for the split. You will need to create an entry for each
        <emphasis>Account:Stock</emphasis> combination you hold.
      </para>

      <figure>
        <title>Selection Of A Stock Account In The <quote>Stock Split</quote> Assistant</title>
        <screenshot id="invest-split2">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_split2.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the stock split assistant at step 2 - Selection of Account/Stock.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>Select the <emphasis>Assets:Investments:DRIPs:NST</emphasis> and click on
        <guibutton>Forward</guibutton>.
      </para>

      <para>The next screen presents 5 fields in the Stock Splits Details window:
      </para>

      <variablelist>
      <varlistentry>
        <term>Date</term>
        <listitem><simpara>Enter the date of the split.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>Shares</term>
        <listitem><para>The number of shares increased (or decreased) in the transaction.
          In this example, it is a 2 for 1 split so the number of additional shares is the number of shares
          currently in the register.
          </para></listitem>
      </varlistentry>

      <varlistentry>
        <term>Description</term>
        <listitem><simpara>The Description should give a brief explanation of the transaction.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>New Price</term>
        <listitem><simpara>If desired the new price of the stock, after the split, may be entered.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>Currency</term>
        <listitem><simpara>The currency of the transaction is required. This should be the same as the stock purchase currency.</simpara></listitem>
      </varlistentry>

      </variablelist>

      <para>Click on the <guibutton>Forward</guibutton> button.
      </para>

      <figure>
        <title>Split Details In The <quote>Stock Split</quote> Assistant</title>
        <screenshot id="invest-split3">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_split3.png"
                         srccredit="Dave Herman"/>
             </imageobject>
            <caption>
              <para>An image of the stock split assistant at step 3 - Split Details.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>The next screen will be skipped in this example as there was no <quote>Cash in Lieu</quote>.
      </para>

       <figure>
        <title><quote>Cash In Lieu</quote> In The <quote>Stock Split</quote> Assistant</title>
        <screenshot id="invest-split4">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_split4.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the stock split assistant at step 4 - Cash in Lieu.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>A final <guilabel>Finish</guilabel> screen will give a last option to;
        <guibutton>Cancel</guibutton>, <guibutton>Back</guibutton> to modify any data entered or
        <guibutton>Apply</guibutton> to complete the stock split with the data entered.
      </para>

<!-- ToDo: unshrink -->
       <figure>
        <title>The NST Account After A Simple Stock Split</title>
        <screenshot id="invest-simplesplit1">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_simplesplit1.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the <emphasis>Assets:Investments:DRIPs:NST</emphasis> register after a simple stock
                split transaction.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>

    <sect2 id="invest-merger1">
      <title>Moderately Complex Stock Merger</title>

      <para>As an example, assume you held AT&amp;T stock during the Nov. 18, 2005 merger of SBC with AT&amp;T.
        For this example you will have purchased AT&amp;T on April 1, 2005, any dividends will have
        been paid in cash, therefore not entered into the AT&amp;T stock register.
      </para>

      <para>The conditions of the merger were 0.77942 share of SBC stock were exchanged for each share of
        AT&amp;T stock. The merged company continued to use the symbol <quote>T</quote> from
        AT&amp;T.
      </para>

      <para>AT&amp;T paid a <quote>dividend</quote> of $1.20/share on the transaction date, however this will
        not appear in the stock account as it was a cash distribution.
      </para>

      <para>The process for entering this transaction is identical to the simple split until the
        <quote>Details</quote> screen. You will need to create an split entry in each
        <emphasis>Investment Account:Stock</emphasis> account combination that has shares splitting.
      </para>

      <figure>
        <title>Selection Of A Stock Account In The <quote>Stock Split</quote> Assistant—Moderate</title>
        <screenshot id="invest-merge2">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_merge2.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the stock split assistant at step 2 - Selection of Account/Stock (<emphasis>Investment
                Account:T</emphasis>).
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>Select the <emphasis>Assets:Investments:Brokerage Account:Stock:T</emphasis> and click on
        <guibutton>Forward</guibutton>.
      </para>

      <para>The next screen presents 5 fields in the Stock Splits Details window:
      </para>

      <variablelist>
      <varlistentry>
        <term>Date</term>
        <listitem><simpara>Enter the date of the split. Here we&rsquo;ll enter November 18, 2005.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>Shares</term>
        <listitem><para>The number of shares increased (or decreased) in the transaction.
          In this example it is a 0.77942 for 1 split so the number of shares will decrease from the number of
          shares currently in the register. You may use &app;&rsquo;s ability to perform
          calculations on an entry form by entering data directly (
          <userinput>0.77942*100 &minus; 100</userinput>) to calculate the decrease in shares from the
          split.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term>Description</term>
        <listitem><simpara>The Description should give a brief explanation of the transaction.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>New Price</term>
        <listitem><simpara>If desired the new price of the stock, after the split, may be entered.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>Currency</term>
        <listitem><simpara>The currency of the transaction is required. This should be the same as the stock purchase currency.</simpara></listitem>
      </varlistentry>

      </variablelist>

      <para>Click on the <guibutton>Forward</guibutton> button.
      </para>

      <figure>
        <title>Split Details In The <quote>Stock Split</quote> Assistant—Moderate</title>
        <screenshot id="invest-merge3">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_merge3.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the stock split assistant at step 3 - Split Details.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>The next screen will be skipped in this example as there was no <quote>Cash in Lieu</quote>.
      </para>

      <para>A final <quote>Finish</quote> screen will give a last option to <guibutton>Back</guibutton> to modify
        any data entered or <guibutton>Apply</guibutton> to complete the stock split with the data
        entered.
      </para>

<!-- ToDo: unshrink -->
       <figure>
        <title>The T Account After A Moderate Stock Split</title>
        <screenshot id="invest-stockmerge1">
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/invest_stockmerge1.png"
                         srccredit="Dave Herman"/>
            </imageobject>
            <caption>
              <para>An image of the <emphasis>Investment Account:T</emphasis> register after a stock split transaction
                that decreases the shares.
              </para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>
  </sect1>
<!--  Working Location  !!!!!!!!!!!!
  <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>Reconciling with the Brokerage Statement (How-To)</para>
      </listitem>

      <listitem>
        <para>Recording Employee Stock Plans (Discussion)</para>
      </listitem>

      <listitem>
        <para>Stock Options (How-To)</para>
      </listitem>

    </itemizedlist>
  </sect1>
-->
</chapter>
