Added kmymoney

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kmymoney@1239792 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 623 insertions, 0 deletions

diff --git a/doc/en/details-investments.docbook b/doc/en/details-investments.docbook
new file mode 100644
index 0000000..e9cae48
--- /dev/null
+++ b/doc/en/details-investments.docbook
@@ -0,0 +1,623 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="details.investments">
+<chapterinfo>
+  <authorgroup>
+    <author>
+      <firstname>Ace</firstname>
+      <surname>Jones</surname>
+      <affiliation>
+        <address><email>acejones@users.sourceforge.net</email></address>
+      </affiliation>
+    </author>
+  </authorgroup>
+  <date>2009-06-14</date>
+  <releaseinfo>1.0</releaseinfo>
+</chapterinfo>
+
+<title>Investments</title>
+
+<sect1 id="details.investments.overview">
+<title>Investments in &kappname;</title>
+
+<sect2>
+<title>Investments</title>
+
+<para>
+  Investments are instruments for investing money that are traded on a market.
+  Stocks, bonds, and mutual funds are the most common investments; so they are
+  the ones supported most directly.  Futures, commodities, options, and more
+  complex derivatives are also sometimes used, but &kappname; has no special
+  functionality for them.  As long as they behave like a stock or a bond, they
+  can be tracked easily.
+</para>
+</sect2>
+
+<sect2>
+<title>Base Currency</title>
+<para>
+  Each investment has a Base Currency.  This is the currency in which it is
+  traded.  When a price quote is entered for an investment, the currency of the
+  value given is always its base currency.  A stock on the NYSE (New York Stock
+  Exchange) would be in US dollars, and one on an Australian market would be in
+  Australian dollars.
+</para>
+</sect2>
+
+<sect2>
+<title>Investment Accounts</title>
+<para>
+  Investment Accounts hold a collection of investments.  An Investment account
+  contains transactions, such as buys and sells, of those investments.  All
+  transactions in an Investment account must relate to a specific investment.
+  There is no separate <quote>cash balance</quote> in an investment account.  For
+  that, you need a Brokerage Account.
+</para>
+</sect2>
+
+<sect2>
+<title>Brokerage Accounts</title>
+<para>
+  An investment account often has an associated Brokerage Account.  This is also
+  sometimes referred to as a <quote>Cash Account</quote>.  Investment accounts
+  cannot contain cash transactions, like a transfer from your bank.  When a
+  stock is sold, the proceeds are typically placed in the Brokerage Account.
+</para>
+
+<para>
+  When you create an Investment Account, you have the option of creating an
+  associated Brokerage Account with it.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="details.investments.investment">
+<title>Creating an Investment Account</title>
+
+<para>
+  The first step on the path to working with investments is to create an account
+  to hold your investments. Choose <menuchoice><guimenu>Account</guimenu>
+  <guimenuitem>New account...</guimenuitem></menuchoice> to begin the process of
+  adding a new account.  Create an account as usual, making sure to choose
+  <quote>Investment</quote> as the type of account.
+</para>
+
+<para>
+  To work with the new investment account, navigate to the
+  <guibutton>Investments</guibutton> view, and choose the account you have just
+  created from the <guilabel>Select Account</guilabel> dropdown box.
+</para>
+</sect1>
+            
+<sect1 id="details.investments.securities">
+<title>Adding Investments to Your Account</title>
+
+<para>
+  To add individual Investments to your Investment Account, navigate to
+  the <guibutton>Investments</guibutton> view, and choose the account where the
+  investment is held from the <guilabel>Select Account</guilabel> drop-down box.
+</para>
+
+<para>
+  Right-click the mouse in the empty space in the view.  This brings up
+  the <guimenu>Investment Options</guimenu> context menu. Choose
+  <guimenuitem>New...</guimenuitem> from this menu.  This launches the
+  <guilabel>New Investment Wizard</guilabel> which you use to create your new
+  Investment.
+</para>
+
+<sect2 id="details.investments.newinvestmentwizard">
+<title>New Investment Wizard</title>
+
+<para>
+  The first thing you'll be asked to enter is the type of investment, whether
+  it's a stock, bond, etc.
+</para>
+
+<para>
+  Next, the investment details page is presented.  The following information is
+  entered on this page:
+</para>
+
+<itemizedlist>
+  <listitem><para> Trading Symbol.  The ticker symbol used to identify the
+    investment on whatever market it trades.  &kappname; requires a trading
+    symbol for all investments; however some investments do not have symbols.
+    In this case, you will need to make up a symbol for it.
+  </para></listitem>
+
+  <listitem><para> Full name.  The friendly, readable name of the investment
+    you're creating, e.g., <quote>Advanced Micro Devices, Inc.</quote> This name is
+    also referred to as the security.
+  </para></listitem>
+
+  <listitem><para> Fraction.  The degree of precision to which your holdings are
+    measured.  For example, in the US most mutual funds measure holdings to
+    three decimal places, so you would enter 1000 in this field.  Stocks are
+    often measured to only whole units, so you could enter 1 for a stock like
+    this.
+  </para></listitem>
+  
+  <listitem><para> Trading market.  Where the stock trades.  This is an optional
+    field which is provided for your convenience.  This information is not used
+    anywhere else in &kappname;.
+  </para></listitem>
+
+  <listitem><para>Identification.  An optional field to enter additional
+    identification information you might like to keep track of.  Again, this
+    information is not used anywhere else.
+  </para></listitem>
+
+  <listitem><para>Trading currency. The underlying currency in which this
+    investment trades on its market.
+  </para></listitem>
+
+  <listitem><para> Price entry. Choose whether the price will be entered as an
+    individual price, or as the total for all shares.
+  </para></listitem>
+</itemizedlist>
+
+<para>
+  If you are using Online Quotes, ensure that the symbol exactly matches the
+  symbol used by your quote source.  Yahoo covers most of the world's markets,
+  and requires a suffix on the end of symbols outside the US.  For example,
+  Rubicon Limited on the New Zealand market should be entered as
+  <quote>RBC.NZ</quote>.
+</para>
+
+<para>
+  Finally, you're presented with the Online Update screen.  This is where you
+  tell &kappname; how you would like to update the prices of your investment.
+  The following items are set here:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+      Use Finance::Quote.  This is an option for GnuCash users who are used to
+      this style of quotes.  Most users can leave this unchecked.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Online Source.  The online source you'd like to use for this particular
+      investment.  The most common choice is <quote>Yahoo</quote>.  Try that
+      first, and if the investment cannot be found using this source, then
+      experiment with the others.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Factor.  A multiplier that should be applied to quotes retrieved for this
+      investment.  This is most commonly needed for UK stocks where the price
+      quoted is in pence (1/100), and the stock is denominated in pounds.  In
+      this case, enter 0,01 for the Factor.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+<sect1 id="details.investments.edit">
+<title>Editing an Investment</title>
+
+<para>
+  The Investment view window lists your current holdings in this account, along
+  with their symbol, value, and price.  Right-click the mouse on any of the
+  investments to bring up the <guimenu>Investment Options</guimenu> context
+  menu, where you have the option to add, edit, or delete individual investments
+  from this account. Also, you can update the price of your investments here
+  either manually or via their online source. In addition, it is possible to
+  close an empty account, or to reopen a closed account.
+</para>
+</sect1>
+
+<sect1 id="details.investments.ledger">
+<title>Investment Transactions</title>
+
+<para>
+	<screenshot>
+	<screeninfo>Investment Transaction Form</screeninfo>
+	<mediaobject>
+	<imageobject>
+	<imagedata fileref="investment-transactionform.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	<phrase>Investment Transaction Form</phrase>
+	</textobject>
+	</mediaobject>
+	</screenshot>
+</para>
+
+<para>
+  Investment transactions are entered and edited in the
+  <link linkend="details.ledgers">ledger</link> view, as with other kinds of
+  accounts. However, the fields are different, and vary depending on the
+  investment transaction type or activity.  Investment transactions have some
+  additional elements:
+</para>
+
+<itemizedlist>
+	<listitem><para>Activity</para></listitem>
+	<listitem><para>Security</para></listitem>
+	<listitem><para>Account</para></listitem>
+	<listitem><para>Shares, Price, &amp; Total Amount</para></listitem>
+	<listitem><para>Fees</para></listitem>
+	<listitem><para>Interest category</para></listitem>
+</itemizedlist>
+
+<sect2>
+<title>Activity</title>
+<para>
+  The Activity for an investment transaction describes what action is happening
+  to the stock.  The following activities are supported:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+      Buy/Sell.  Use to record purchases or sales of individual investments.
+      This action requires an account to transfer the funds from/to.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Dividend/Yield.  Also known as a <quote>Cash Dividend</quote>, this action
+      is used for when you receive an interest or dividend disbursement from
+      your investment. This action requires an account to transfer the funds
+      from/to.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Reinvest Dividend.  This is a dividend where the proceeds are re-invested
+      back into the investment.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Add/Remove Shares.  A simple increase or decrease in your balance.  This
+      should be used very rarely, because it's uncommon for shares to just show
+      up in your account (or disappear) unless it's a purchase or a sale.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Split Shares.  Used when the stock is split.  Enter the ratio of the split
+      in the <quote>Split Ratio</quote> field.  For example, in a 3:2 split,
+      enter 1.5
+    </para>
+  </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2>
+<title>Security</title>
+<para>
+  Each investment transaction must be associated with an individual security,
+  which is here just another name for an investment.  Choose the investment name
+  when adding or editing a transaction.  The symbol will be displayed when
+  viewing it.
+</para>
+</sect2>
+
+<sect2>
+<title>Account</title>
+<para>
+  For any transactions which generate or require money, you must enter the
+  account where the money is transferred to/from.  If your investment account
+  has an associated brokerage account, it's usually best to transfer the funds
+  there.  This applies to funds for purchase or sale of the investment, as well
+  as for fees paid or interest or dividends earned.
+</para>
+</sect2>
+
+<sect2>
+<title>Shares, Price &amp; Total Amount</title>
+<para>
+  For buy, sell, and cash dividend transactions, the number of shares, the price
+  per share, and the total amount of the transaction must be established.  You
+  can enter any two of these, and &kappname; will calculate the third.  It's
+  usually best to enter just the total amount and the number of shares, because
+  these are the known facts of the transaction.  The price per share can be
+  calculated from these.
+</para>
+</sect2>
+
+<sect2>
+<title>Fees</title>
+<para>
+  With many investment transactions you can include the fees (or commission) you
+  paid the broker.  If you enter a category for the fee, then a field will be
+  shown to the right where you can enter the amount of the fee.  If you need to
+  enter more than one fee for the transaction, you can use
+  the <link linkend="details.ledgers.split">Split Transactions</link> feature.
+  In this case, when you complete entering all the splits, the total amount of
+  the fees will be shown to the right.
+</para>
+</sect2>
+
+<sect2>
+<title>Interest</title>
+<para>
+  This is how you enter an interest or dividend payment from an invenstment.  As
+  with fees, if  you enter a category, then  a field will be shown  to the right
+  where  you can  enter the  amount.   You can  also use  the split  transaction
+  feature, if required.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="details.investments.foreign">
+<title>Working With Foreign Investments</title>
+
+<para>
+  &kappname; supports multiple currencies and investments, and you may want to
+  combine the two.  However, doing so requires extra care.  As noted above, when
+  you added an investment, you had to specify its trading currency.  This might
+  not be the same as your base currency, and it also might not be the same as
+  the account in which you hold the stock or the account where you transfer your
+  funds to/from for buys/sells.
+</para>
+
+<para>
+  Consider a hypothetical case.  Your base currency is USD.  You have an
+  investment account in EUR, and a brokerage account also in EUR.  In that
+  account, you hold shares of TietoEnator, which is traded in SEK.
+</para>
+
+<para>
+  When you enter a buy transaction on this investment, use SEK as the currency.
+  So if you buy 100 shares at a price of SEK 248.00, for a total of SEK
+  24,800.00, enter these values in the transaction.
+</para>
+
+<para>
+	<screenshot>
+	<screeninfo>Currency Warning</screeninfo>
+	<mediaobject>
+	<imageobject>
+	<imagedata fileref="investment-currencywarning.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	<phrase>Currency Warning</phrase>
+	</textobject>
+	</mediaobject>
+	</screenshot>
+</para>
+
+<para>
+  When you choose the brokerage account to fund the transfer, you'll be warned
+  that it's in a different currency.
+</para>
+
+<para>
+	<screenshot>
+	<screeninfo>Exchange Rate Editor</screeninfo>
+	<mediaobject>
+	<imageobject>
+	<imagedata fileref="investment-exchangerateeditor.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	<phrase>Exchange Rate Editor</phrase>
+	</textobject>
+	</mediaobject>
+	</screenshot>
+</para>
+
+<para>
+  When you finish the transaction, you will be prompted for a price update to
+  the investment account's currency, in this case, SEK -> EUR.  Review the
+  documentation on <link linkend="details.currencies.prices">Entering Prices
+  Manually</link> for more information on the price dialog.
+</para>
+
+<para>
+  If you then switch over to the brokerage account, you will see the transaction
+  as EUR 2,254.54, assuming an exchange rate is 11.0000 SEK / EUR.
+</para>
+</sect1>
+
+<sect1 id="details.investments.prices">
+<title>Updating Prices</title>
+<para>
+  There are two ways of updating the prices for your investments.  You can
+  either enter the new price manually or have &kappname; fetch it from the web.
+
+</para>
+
+<sect2>
+<title>Manual Price Updates</title>
+<para>
+  You can enter prices for your investments using the same
+  <link linkend="details.currencies.prices">Price Editor</link> as used for
+  currencies.
+</para>
+</sect2>
+
+<sect2 id="details.investments.onlinequotes">
+<title>Online Price Quotes</title>
+<para>
+  &kappname; has the ability to download the latest prices for your investments
+  and currencies via the web.  
+</para>
+
+<sect3>
+<title>How Online Quotes Work</title>
+<para>
+  At your request, &kappname; will fetch a page from the web that contains the
+  latest price for each item.  By default, prices are fetched from
+  http://finance.yahoo.com, and are subject to the terms and conditions of that
+  site.
+</para>
+
+<para>
+  The online quote lookup uses the investment's trading symbol to find the
+  price.  Therefore, it's important to set the symbol correctly.  Yahoo supports
+  stocks from most major world markets, so it's usually just a matter of finding
+  the correct symbol.  For example, TietoEnator trades on the Stockholm Stock
+  Exchange market, and its Yahoo symbol is TIEN.ST.
+</para>
+
+<para>
+  To find the trading symbol for a security supported by Yahoo, use the
+  <quote>Symbol Lookup</quote> feature at http://finance.yahoo.com.
+</para>
+</sect3>
+
+<sect3>
+<title>Assigning a Quote Source</title>
+
+<para>
+  In order to get online price quotes, you first have to enable it for each
+  investment or currency you want updated, by setting a <quote>Online Quote
+  Source</quote>.  This is the name of the service from which the quote should
+  be fetched.  KMyMoney ships with several sources to choose from.  Yahoo is the
+  recommended default source, and should work for most investments and all
+  currencies.
+</para>
+
+<para>
+  To assign a quote source to an investment, navigate to the investment summary
+  view for the account in which the security is held.  Edit the security by
+  right-clicking it and selecting <guimenuitem>Edit Investment
+  ...</guimenuitem>.  In the Investment Detail Wizard,
+  click <guibutton>Next</guibutton> twice, for the Online Update section.  In
+  the Online source dropdown box, select the online source.
+</para>
+
+<para>
+  Versions of &kappname; starting with 0.9 contain support for the
+  Finance::Quote package for obtaining online quotes. This is intended primarily
+  as a convenience for those users converting from the GnuCash finance package,
+  which uses it as its native method. If you do select this option, you should
+  see a different list of sources, those supported by Finance::Quote. If the
+  list is empty, it suggests that the package is not properly installed.  See
+  their web site at
+  <ulink url="http://finance-quote.sourceforge.net">
+  http://finance-quote.sourceforge.net</ulink> for more information.
+</para>
+</sect3>
+
+<sect3>
+<title>Adjusting a quote</title>
+
+<para>
+  Some online sources do not report the price in a base quantity (e.g., EUR) but
+  in a fraction (e.g., Cent). Using this information as price will produce wrong
+  values for your investments.
+</para>
+
+<para>
+  If this is the case for your online source, you can use the
+  <guilabel>Factor</guilabel> field to enter an adjusting factor. For the above
+  mentioned example the factor would be 0.01.
+</para>
+
+<para>
+  The <guilabel>Factor</guilabel> field is only available if a
+  <guibutton>Quote Source</guibutton> has been selected.
+</para>
+</sect3>
+
+<sect3>
+<title>Fetching Quotes</title>
+
+<para>
+  Typically, you will update the prices for all your investments and currencies
+  at once.  Choose the <menuchoice><guimenu>Tools</guimenu><guimenuitem>Update
+  Stock and Currency Prices...</guimenuitem></menuchoice> menu option to bring
+  up the online price quotes dialog.  Press <guibutton>Update All</guibutton> to
+  fetch quotes for all investments and currencies in your &kappname; file.
+</para>
+
+<para>
+	<screenshot>
+	<screeninfo>Update Stock and Currency Prices</screeninfo>
+	<mediaobject>
+	<imageobject>
+	<imagedata fileref="investment-onlineupdate.png" format="PNG" />
+	</imageobject>
+	<textobject>
+	<phrase>Online Stock and Currency Price Update</phrase>
+	</textobject>
+	</mediaobject>
+	</screenshot>
+</para>
+</sect3>
+
+<sect3>
+<title>Adding or Editing Quote Sources</title>
+
+<para>
+  Adding or editing quote sources is not recommended for anyone but the most
+  technical user.  You should feel comfortable reading HTML and writing complex
+  regular expressions.  If this doesn't sound like you, we recommend writing to
+  the developer's list if none of the quote sources work for you.  Ideally,
+  please point us to a web page where these quotes can be obtained.
+</para>
+
+<para>
+  If you do feel up to the challenge, here's how it works.  The quote sources
+  are contained in the settings dialog.
+  Choose <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+  &kappname;</guimenuitem></menuchoice>.  From there, choose
+  the <guilabel>Online Quotes</guilabel> section.  You can choose an existing
+  source to edit, or create a new one.  When you are done with your changes, be
+  sure to press the <guibutton>Update</guibutton> button before exiting the
+  dialog.  Your changes are not saved by default.
+</para>
+
+<para>
+  The first thing to worry about in an online quote source is the URL.  This is
+  the page that is fetched from the web.  You will see a %1 in all sources, and
+  a %2 in currency sources.  For investments, %1 is replaced by the trading
+  symbol.  For currencies, %1 is replaced by the From currency, and %2 is
+  replaced by the To currency.  This URL is then fetched, all HTML tags are
+  removed, and that stripped file is then sent to the page parser.
+</para>
+
+<para>
+  Note that the URL can also be a file: URL, which the quote fetcher takes to
+  mean an executable script.  It will pass any command-line arguments to it that
+  you have specified, and feed the stdout to the page parser.  For example, you
+  might have a script called getquote.sh that contains custom quote logic,
+  taking the symbol as a single parameter.  Your URL would be
+  <quote>file:/path/to/getquote.sh %1</quote>.
+</para>
+
+<para>
+  The page parser looks for a symbol, a date, and a price.  Regular expressions
+  tell it how to extract those items from the page.  Please review the
+  documentation for the <ulink
+  url="http://qt.nokia.com/doc/3.3/qregexp.html#1">QRegExp class</ulink> at
+  http://qt.nokia.com/doc/3.3/qregexp.html#1 for the exact makeup of the
+  regular expressions.  There should be exactly one capture expression,
+  surrounded by parentheses, in each regexp.  The date format further tells the
+  date parser the order of year, month, and day.  This date format should always
+  be in the form "%x %x %x". where x is y, m, or d.  The date parser is very
+  smart.  <quote>%m %d %y</quote> will parse <quote>December 31st, 2005</quote>
+  as easily as <quote>12/31/05</quote>.  Two digit years are interpreted as
+  being in the range of 1950-2049.
+</para>
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="details.investments.unimplemented">
+<title>Unimplemented Features</title>
+<para>
+  Certain common features that are normally found with investments are not yet
+  implemented in &kappname;.  These include: Derivatives (options, futures,
+  etc), capital gains, and tax reporting for investments.
+</para>
+</sect1>
+</chapter>