Warning, /office/kmymoney/doc/details-investments.docbook is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" encoding="UTF-8"?>
0002 <chapter id="details.investments">
0003 <chapterinfo>
0004   <authorgroup>
0005     <author> &Ace.Jones; &Ace.Jones.mail; </author>
0006     <author>
0007       <personname><firstname>Michael</firstname><surname>Carpino</surname></personname>
0008       <email>mfcarpino@gmail.com</email>
0009     </author>
0010     <author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
0011   </authorgroup>
0012   <date>2019-12-30</date>
0013   <releaseinfo>5.0.7</releaseinfo>
0014 </chapterinfo>
0016 <title>Investments</title>
0018 <sect1 id="details.investments.overview">
0019 <title>Investments in &kmymoney;</title>
0021 <sect2>
0022 <title>Investments</title>
0024 <para>
0025   In very general terms, an investment is any allocation of money with the
0026   expectation of a future benefit.  &kmymoney;'s Investment accounts are designed for
0027   one particular type of investment: securities.  A security investment (or just a
0028   security) is an instrument for investing money that is traded on a market with the
0029   intention of a profitable return in the form of either appreciation in value, or
0030   income such as interest or dividends.  Stocks and mutual funds are the most common
0031   securities; and they are the ones specifically supported within &kmymoney;.  Bonds
0032   have a different financial structure, but can usually be handled by &kmymoney;.
0033   Futures, commodities, options, and more complex investment instruments like
0034   derivatives are other types of investments, but &kmymoney; has no special
0035   functionality for them.  As long an investment has similar characteristics to a
0036   stock or mutual fund, it can be tracked.
0037 </para>
0038 </sect2>
0040 <sect2>
0041 <title>Base Currency</title>
0042 <para>
0043   Each security has a Base Currency.  This is the currency in which it is traded.
0044   When a price quote is entered for an investment, the currency of the value given is
0045   always its base currency.  A stock on the NYSE (New York Stock Exchange) would be
0046   in US dollars (USD), and one on an Australian market would be in Australian dollars
0047   (AUD).  The Base currency for a security does not need to be the same as the
0048   default currency for the Investment account holding that security.
0049 </para>
0050 </sect2>
0052 <sect2>
0053 <title>Investment Accounts</title>
0054 <para>
0055   An Investment Account holds a collection of Securities, also referred to as
0056   Equities.  An Investment account contains transactions, recording activities such
0057   as buys, sells, dividends, reinvestments, yields, splits and income of those
0058   investments.  Each transaction in an Investment account must relate to a specific
0059   security.
0060 </para>
0062 <para>
0063   It is common for an account at a Brokerage Institution to contain both securities
0064   and cash.  In &kmymoney;, an Investment account holds <emphasis>only</emphasis>
0065   securities.  It cannot contain any cash balance.  This was a design decision made
0066   when Investment accounts were first included in &kmymoney;, and it might be changed
0067   in a future version.  For now, any cash needed to purchase a security or gained
0068   from a sell or dividend transaction requires the use of a Brokerage Account.
0069 </para>
0070 </sect2>
0072 <sect2 id="details.investments.brokerage">
0073 <title>Brokerage Accounts</title>
0074 <para>
0075   When an investment transaction uses (to buy a security) or produces (from a sell or
0076   dividend) cash, that transaction must refer to another account which can hold the
0077   money, most commonly a checking account.  You can specify any suitable account for
0078   any investment transaction which requires one.  However, &kmymoney; has the concept
0079   of a <emphasis>Brokerage Account</emphasis>, also sometimes referred to as
0080   a <quote>Cash Account</quote>, which is the default account for such transactions.
0081 </para>
0083 <para>
0084   When you create an Investment Account, you have the option of creating an
0085   associated Brokerage Account with it.  The default name of the Brokerage account
0086   will be the name of the investment account with " (Brokerage)" appended.
0087 </para>
0088 </sect2>
0089 </sect1>
0091 <sect1 id="details.investments.investment">
0092 <title>Creating an Investment Account</title>
0094 <para>
0095   The first step on the path to working with investments is to create an account
0096   to hold your defined securities. Choose the <menuchoice><guimenu>Account</guimenu>
0097   <guimenuitem>New account...</guimenuitem></menuchoice> menu item to begin the process.
0098   Create an account as previously defined in the adding <guilabel>Account</guilabel>
0099   section, making sure to choose <quote>Investment</quote> as the type of account.
0100 </para>
0102 <para>
0103   To work with the new investment account, navigate to the
0104   <guibutton>Investments</guibutton> view, and choose the account you have just
0105   created from the <guilabel>Select Account</guilabel> dropdown box.
0106 </para>
0107 </sect1>
0109 <sect1 id="details.investments.securities">
0110 <title>Adding Investments to Your Account</title>
0112 <para>
0113   To add individual securities to your Investment Account, navigate to the
0114   <guibutton>Investments</guibutton> view, select the
0115   <guibutton>Equities</guibutton> tab, and choose the Investment account where the
0116   investment is held from the <guilabel>Select Account</guilabel> drop-down box.
0118   <screenshot>
0119   <screeninfo>Investment View, Equities Tab</screeninfo>
0120   <mediaobject>
0121   <imageobject>
0122   <imagedata fileref="investments_summarytab.png" format="PNG" />
0123   </imageobject>
0124   <textobject>
0125   <phrase>Investment View, Equities Tab</phrase>
0126   </textobject>
0127   </mediaobject>
0128   </screenshot>
0129 </para>
0131 <para>
0132   Right-click the mouse in the empty space in the view.  This brings up
0133   the <guimenu>Investment Options</guimenu> context menu.  Choose
0134   <guimenuitem>New investment...</guimenuitem> from this menu.  This launches the
0135   <guilabel>New Investment Wizard</guilabel> which you use to create your new
0136   Investment.
0137 </para>
0139 <sect2 id="details.investments.newinvestmentwizard">
0140 <title>New Investment Wizard</title>
0142 <para>
0143   The first thing you'll be asked to enter is the type of investment, whether
0144   it's a stock, bond, &etc;
0145 </para>
0147 <para>
0148   Next, the investment details page is presented.  The following information is
0149   entered on this page:
0150 </para>
0152 <itemizedlist>
0153   <listitem><para> Trading Symbol.  A trading or ticker symbol is an abbreviation
0154       used to identify a publicly traded security of a particular instrument on a
0155       particular stock market exchange.  &kmymoney; requires a trading symbol for all
0156       securities; however some investments do not have symbols.  In this case, you
0157       will need to make up a symbol for it.
0158   </para></listitem>
0160   <listitem><para> Full name.  The friendly, readable name of the investment you're
0161     creating, &eg;, <quote>Advanced Micro Devices, Inc.</quote> This name is also
0162     referred to as the security.
0163   </para></listitem>
0165   <listitem><para> Fraction.  This indicates the degree of precision to which your
0166     holdings are measured.  For example, in the US most mutual funds measure holdings
0167     to three decimal places, so you would enter 1000 in this field.  Stocks are often
0168     measured to only whole units, so you could enter 1 for a stock like this.  You'll
0169     want to mirror the same decimal places that your brokerage uses to record your
0170     securities so the transactions amounts match within &kmymoney;.  Using extra
0171     precision will not cause a problem, but using too little precision can cause
0172     rounding errors which can make &kmymoney; unable to exactly match the information
0173     shown by your brokerage institution.
0174   </para></listitem>
0176   <listitem><para> Trading market.  Where the stock trades.  This is an optional
0177     field which is provided for your convenience.  This information is not used
0178     anywhere else within &kmymoney;.
0179   </para></listitem>
0181   <listitem><para>Identification.  An optional field to enter additional
0182     identification information you might like to keep track of.  Again, this
0183     information is not used anywhere else.
0184   </para></listitem>
0186   <listitem><para>Trading currency. The market exchange currency in which this
0187       investment trades.  This is typically the country that the security trades
0188       within.  It is usually, but not necessarily, the same as the default currency
0189       for the Investment account holding that security.
0190   </para></listitem>
0192   <listitem><para> Price entry.  Choose whether the price will be entered as the
0193       price per share or as the total for all shares when entering a transaction.
0194   </para></listitem>
0195 </itemizedlist>
0197 <para>
0198   If you are using Online Quotes, ensure that the symbol exactly matches the symbol
0199   used by your quote source.  Yahoo covers most of the world's markets, and requires
0200   a suffix on the end of symbols outside the US, to specify the country or market.
0201   For example, Rubicon Limited on the New Zealand market should be entered as
0202   <quote>RBC.NZ</quote>.
0203 </para>
0205 <para>
0206   Finally, you're presented with the Online Update screen.  This is where you
0207   tell &kmymoney; how you would like to update the prices of your investment.
0208   The following items are set here:
0209 </para>
0211 <itemizedlist>
0212   <listitem>
0213     <para>
0214       Use Finance::Quote.  This is an option for &gnucash; users who are used to
0215       this style of quotes.  Most users can leave this unchecked.
0216     </para>
0217   </listitem>
0219   <listitem>
0220     <para>
0221       Online Source.  The online source you'd like to use for this particular
0222       investment.  The most common choice is <quote>Yahoo</quote>.  Try that first,
0223       and if the investment cannot be found using this source, then experiment with
0224       the others.
0225     </para>
0226   </listitem>
0228   <listitem>
0229     <para>
0230       Factor.  A multiplier that should be applied to quotes retrieved for this
0231       investment.  This is most commonly needed for UK stocks where the price
0232       quoted is in pence (1/100), and the stock is denominated in pounds.  In
0233       this case, enter 0,01 for the Factor.
0234     </para>
0235   </listitem>
0236 </itemizedlist>
0237 </sect2>
0239 <sect2 id="details.investments.reuse">
0240   <title>Using a Security in more than one Investment Account</title>
0242 <note>
0243   <para>
0244     This section has been added just in time for the release of Version 5.0.8.  The
0245     author felt it was important to include at least the basic information now, since
0246     this topic has been a source of difficulty for some time.  The discussion will be
0247     expanded and screenshots of the New Security Wizard will be added as soon as
0248     possible.
0249   </para>
0250 </note>
0252 <para>
0253   It is possible to own shares of the same security in different investment accounts,
0254   such as a regular investment account and also a retirement account.  If you follow the
0255   instructions above, you will have that security show up in both accounts, but
0256   &kmymoney; will actually treat them as if each of the securities is a different
0257   underlying equity.  This results in duplicate storage, such as having two copies of
0258   the entire price history of the equity.  Therefore, you may prefer to have both
0259   securities refer to the same underlying equity.
0260 </para>
0262 <para>
0263   When you add a security to an investment account, and that security already exists in
0264   another investment account, you need to be careful if you want to reuse it rather than
0265   creating a new, duplicate security.  When you see the <guilabel>New Investment
0266   Wizard</guilabel>, after selecting the type of investment and clicking
0267   <guibutton>Next</guibutton>, you need to be sure the <guilabel>Full Name</guilabel>
0268   field is empty before entering the <guilabel>Trading Symbol</guilabel>.  When you hit
0269   <keycap>Tab</keycap>, if &kmymoney; already has a security using that symbol, it will
0270   ask if you wish to reuse it.  If you click <guibutton>Yes</guibutton>, it will fill in
0271   the rest of that dialog, and you can then just click <guibutton>Next</guibutton>.
0272 </para>
0274 </sect2>
0275 </sect1>
0277 <sect1 id="details.investments.edit">
0278 <title>Editing an Investment</title>
0280 <para>
0281   The <guilabel>Equities</guilabel> tab of the Investments view window lists your
0282   current holdings in this account, along with their symbol, value, quantity, and
0283   price.  Right-click the mouse on any of the investments to bring up the
0284   <guimenu>Investment Options</guimenu> context menu, where you have the option
0285   to add, edit, or delete individual investments from this account. Also, you
0286   can update the price of your investments here either manually or via their
0287   online source.  In addition, it is possible to close an empty account, or to
0288   reopen a closed account.  The order for value, quantity and price can be changed
0289   on the screen by selecting any of them by left clicking on the item in the top bar and
0290   dragging it to the left or right.
0291 </para>
0292 <para>
0293   If you choose to Edit an Investment, you will use the <guilabel>Investment detail
0294   wizard</guilabel>, which looks and functions just like the <guilabel>New Investment
0295   Wizard</guilabel>, as described in the previous section.
0296 </para>
0297 </sect1>
0299 <sect1 id="details.investments.ledger">
0300 <title>Investment Transactions</title>
0302 <para>
0303         <screenshot>
0304         <screeninfo>Investment Transaction Form</screeninfo>
0305         <mediaobject>
0306         <imageobject>
0307         <imagedata fileref="investment-transactionform.png" format="PNG" />
0308         </imageobject>
0309         <textobject>
0310         <phrase>Investment Transaction Form</phrase>
0311         </textobject>
0312         </mediaobject>
0313         </screenshot>
0314 </para>
0316 <para>
0317   Investment transactions are entered and edited in the
0318   <link linkend="details.ledgers">Ledger</link> view, as with other kinds of
0319   accounts.  However, the fields will appear different, and vary depending on the
0320   transaction type or activity.  Investment transactions have some additional
0321   elements:
0322 </para>
0324 <itemizedlist>
0325         <listitem><para>Activity</para></listitem>
0326         <listitem><para>Security</para></listitem>
0327         <listitem><para>Account</para></listitem>
0328         <listitem><para>Shares, Price, &amp; Total Amount</para></listitem>
0329         <listitem><para>Fees</para></listitem>
0330         <listitem><para>Interest category</para></listitem>
0331 </itemizedlist>
0333 <sect2>
0334 <title>Activity</title>
0335 <para>
0336   The Activity for an investment transaction describes what action is happening
0337   to the security.  The following activities are supported:
0338 </para>
0340 <variablelist>
0341   <varlistentry>
0342   <term>Buy/Sell</term>
0343   <listitem>
0344     <para>
0345       Use to record purchases or sales of individual securities.  This action
0346       requires an account to transfer the funds from/to, which defaults to the
0347       Brokerage account, if one has been created.
0348     </para>
0349   </listitem>
0350   </varlistentry>
0352   <varlistentry>
0353   <term>Dividend/Yield</term>
0354   <listitem>
0355     <para>
0356       Also known as a <quote>Cash Dividend</quote>, this action is used when you
0357       receive an interest or dividend disbursement from your security.  This action
0358       also requires an account to transfer the funds to.
0359     </para>
0360   </listitem>
0361   </varlistentry>
0363   <varlistentry>
0364   <term>Reinvest Dividend</term>
0365   <listitem>
0366     <para>
0367       Reinvest Dividend.  This is a dividend where the proceeds are used to purchase
0368       additional shares of the security.
0369     </para>
0370   </listitem>
0371   </varlistentry>
0373   <varlistentry>
0374   <term>Add/Remove Shares</term>
0375   <listitem>
0376     <para>
0377       A simple increase or decrease in the number of shares you own.  This should be
0378       used very rarely, because it's uncommon for shares to just show up in your
0379       account (or disappear) unless it's a purchase or a sale.  One use of these
0380       activities is for some situations &kmymoney; does not natively handle, such as
0381       the exchange of some number of shares of a security for a different number of
0382       shares of a different class of the same security.
0383     </para>
0384   </listitem>
0385   </varlistentry>
0387   <varlistentry>
0388   <term>Split Shares</term>
0389   <listitem>
0390     <para>
0391       This is used when the stock is split.  Enter the ratio of the split in
0392       the <quote>Split Ratio</quote> field.  For example, in a 3:2 split, enter 1.5.
0393       Reverse splits, where the ration is less than one, such as 2:3, although
0394       uncommon, are also allowed.
0395     </para>
0396   </listitem>
0397   </varlistentry>
0398 </variablelist>
0399 </sect2>
0401 <sect2>
0402 <title>Security</title>
0403 <para>
0404   Each investment transaction must be associated with an individual security.  Choose
0405   the security name when adding or editing a transaction.  The symbol will be
0406   displayed when viewing it.
0407 </para>
0408 </sect2>
0410 <sect2>
0411 <title>Account</title>
0412 <para>
0413   For any transaction which generates or requires money, you must enter the account
0414   where the money is transferred to/from.  If your investment account has an
0415   associated Brokerage account, it is usually best to transfer the funds there.  This
0416   applies to funds for purchase or sale of the security, as well as for fees paid or
0417   interest or dividends earned.
0418 </para>
0419 </sect2>
0421 <sect2>
0422 <title>Shares, Price &amp; Total Amount</title>
0423 <para>
0424   For buy, sell, and reinvestment transactions, the number of shares, the price per
0425   share, and the total amount of the transaction must be established.  You can enter
0426   any two of these, and &kmymoney; will calculate the third.  It's usually best to
0427   enter just the total amount and the number of shares, because these are the known
0428   facts of the transaction.  &kmymoney; will automatically calculate the price per
0429   share.  Note that there is only one entry field for the price, and it will be
0430   labeled
0431   <quote>Transaction amount</quote> or <quote>Price/share</quote> depending on the
0432   setting of the <guilabel>Price entry</guilabel> option when the account
0433   was <link linkend="details.investments.newinvestmentwizard">set up</link>.
0434 </para>
0435 </sect2>
0437 <sect2>
0438 <title>Fees</title>
0439 <para>
0440   With many investment transactions you can include the fees (or commission) you
0441   paid the broker.  If you enter a category for the fee, then a field will be
0442   shown to the right where you can enter the amount of the fee.  If you need to
0443   enter more than one fee for the transaction, you can use
0444   the <link linkend="details.ledgers.split">Split Transactions</link> feature.
0445   In this case, when you complete entering all the splits, the total amount of
0446   the fees will be shown to the right.
0447 </para>
0448 </sect2>
0450 <sect2>
0451 <title>Interest</title>
0452 <para>
0453   This is how you enter an interest or dividend payment from a security.  As
0454   with fees, if you enter a category, then  a field will be shown to the right
0455   where you can enter the amount.  You can also use the split transaction
0456   feature, if required.
0457 </para>
0458 </sect2>
0459 </sect1>
0461 <sect1 id="details.investments.foreign">
0462 <title>Working With Foreign Investments</title>
0464 <para>
0465   &kmymoney; supports multiple currencies and securities, and you may want to combine
0466   the two.  However, doing so requires extra care to assure accurate records.  As
0467   noted above, when you add a security, you must specify its trading currency.  This
0468   might not be the same as the base currency for your &kmymoney; file, and it also
0469   might not be the same as the default currency for the investment account in which
0470   you hold the stock or the account where you transfer your funds to/from for
0471   buys/sells.
0472 </para>
0474 <para>
0475   Consider a hypothetical case, where your base currency is USD.  You have an
0476   investment account in EUR, and a brokerage account also in EUR.  In that investment
0477   account, you hold shares of TietoEnator, which is traded in SEK.
0478 </para>
0480 <para>
0481   When you enter a buy transaction for this investment, use SEK as the currency.  So
0482   if you buy 100 shares at a price of SEK 248.00, for a total of SEK 24,800.00, enter
0483   these values in the transaction.
0484 </para>
0486 <para>
0487         <screenshot>
0488         <screeninfo>Currency Warning</screeninfo>
0489         <mediaobject>
0490         <imageobject>
0491         <imagedata fileref="investment-currencywarning.png" format="PNG" />
0492         </imageobject>
0493         <textobject>
0494         <phrase>Currency Warning</phrase>
0495         </textobject>
0496         </mediaobject>
0497         </screenshot>
0498 </para>
0500 <para>
0501   When you choose the brokerage account to fund the transfer, you'll be warned
0502   that it's in a different currency.
0503 </para>
0505 <para>
0506         <screenshot>
0507         <screeninfo>Exchange Rate Editor</screeninfo>
0508         <mediaobject>
0509         <imageobject>
0510         <imagedata fileref="investment-exchangerateeditor.png" format="PNG" />
0511         </imageobject>
0512         <textobject>
0513         <phrase>Exchange Rate Editor</phrase>
0514         </textobject>
0515         </mediaobject>
0516         </screenshot>
0517 </para>
0519 <para>
0520   When you finish entering the transaction, you will be prompted for a price update
0521   to the investment account's currency, in this case, SEK -> EUR.  Review the
0522   documentation on <link linkend="details.currencies.prices">Entering Prices
0523   Manually</link> for more information on the price dialog.
0524 </para>
0526 <para>
0527   If you then switch over to the brokerage account, you will see the transaction as
0528   EUR 2,254.54, assuming an exchange rate is 11.0000 SEK/EUR.
0529 </para>
0530 </sect1>
0532 <sect1 id="details.investments.prices">
0533 <title>Updating Prices</title>
0535 <para>
0536   There are two ways of updating the prices for your investments.  You can
0537   either enter the price manually or have &kmymoney; fetch it from the web.
0538 </para>
0540 <sect2>
0541 <title>Manual Price Updates</title>
0543 <para>
0544   You can enter prices for your investments using the same
0545   <link linkend="details.currencies.prices">Price Editor</link> as used for
0546   currencies.
0547 </para>
0548 </sect2>
0550 <sect2 id="details.investments.onlinequotes">
0551 <title>Online Price Quotes</title>
0552 <para>
0553   &kmymoney; has the ability to download the latest prices for your securities
0554   and currencies via the web.
0555 </para>
0557 <sect3>
0558 <title>How Online Quotes Work</title>
0559 <para>
0560   At your request, &kmymoney; will fetch a page from the web that contains the
0561   latest price for each security.  By default, prices are fetched from
0562   <ulink url="https://finance.yahoo.com">finance.yahoo.com</ulink>, and are
0563   subject to the terms and conditions of that site.
0564 </para>
0566 <para>
0567   The online quote lookup uses the security's trading symbol to find the price.
0568   Therefore, it is important to set the symbol correctly.  Yahoo supports stocks from
0569   most major world markets, so it's usually just a matter of finding the correct
0570   symbol.  For example, TietoEnator trades on the Stockholm Stock Exchange market,
0571   and its Yahoo symbol is TIEN.ST.
0572 </para>
0574 <para>
0575   To find the trading symbol for a security supported by Yahoo, use the
0576   <quote>Symbol Lookup</quote> feature
0577   at <ulink url="https://finance.yahoo.com">finance.yahoo.com</ulink>.
0578 </para>
0579 </sect3>
0581 <sect3>
0582 <title>Assigning a Quote Source</title>
0584 <para>
0585   In order to get online price quotes, you first have to enable it for each
0586   security or currency you want updated, by setting a <quote>Online Quote
0587   Source</quote>.  This is the name of the service from which the quote should
0588   be fetched.  &kmymoney; ships with several sources to choose from.  Yahoo is the
0589   recommended default source, and should work for most investments and all
0590   currencies.
0591 </para>
0593 <para>
0594   To assign a quote source for an investment, navigate to the investment summary view
0595   for the account in which the security is held.  Edit the security by right-clicking
0596   it and selecting <guimenuitem>Edit Investment ...</guimenuitem>.  In the Investment
0597   Detail Wizard, click <guibutton>Next</guibutton> twice, for the Online Update
0598   section.  In the Online source dropdown box, select the online source for your
0599   needs.
0600 </para>
0602 <para>
0603   Versions of &kmymoney; starting with 0.9 contain support for the Finance::Quote
0604   package for obtaining online quotes.  This is intended primarily as a convenience
0605   for those users converting from the &gnucash; finance package, which uses it as its
0606   native method.  If you do select this option, you should see a different list of
0607   sources, those supported by Finance::Quote. If the list is empty, it suggests that
0608   the package is not properly installed.  See their web site at
0609   <ulink url="http://finance-quote.sourceforge.net">
0610   http://finance-quote.sourceforge.net</ulink> for more information.
0611 </para>
0612 </sect3>
0614 <sect3>
0615 <title>Adjusting a quote</title>
0617 <para>
0618   Some online sources do not report the price in a base quantity (&eg;, EUR) but
0619   in a fraction (&eg;, Cent). Using this information as price will produce wrong
0620   values for your investments.
0621 </para>
0623 <para>
0624   If this is the case for your online source, you can use the
0625   <guilabel>Factor</guilabel> field to enter an adjusting factor. For the above
0626   mentioned example the factor would be 0.01.
0627 </para>
0629 <para>
0630   The <guilabel>Factor</guilabel> field is only available if a
0631   <guibutton>Quote Source</guibutton> has been selected.
0632 </para>
0633 </sect3>
0635 <sect3>
0636 <title>Fetching Quotes</title>
0638 <para>
0639   Typically, you will update the prices for all your securities and currencies as a
0640   single operation.  Choose the
0641   <menuchoice><guimenu>Tools</guimenu><guimenuitem>Update Stock and Currency
0642   Prices...</guimenuitem></menuchoice> menu item to bring up the online price
0643   quotes dialog.  Press <guibutton>Update All</guibutton> to fetch quotes for all
0644   securities and currencies in your &kmymoney; file.
0645 </para>
0647 <para>
0648         <screenshot>
0649         <screeninfo>Update Stock and Currency Prices</screeninfo>
0650         <mediaobject>
0651         <imageobject>
0652         <imagedata fileref="investment-onlineupdate.png" format="PNG" />
0653         </imageobject>
0654         <textobject>
0655         <phrase>Online Stock and Currency Price Update</phrase>
0656         </textobject>
0657         </mediaobject>
0658         </screenshot>
0659 </para>
0660 </sect3>
0662 <sect3>
0663 <title>Adding or Editing Quote Sources</title>
0665 <para>
0666   Adding or editing quote sources is not recommended for anyone but the most
0667   technical user.  You should feel comfortable reading HTML and writing complex
0668   regular expressions.  If this doesn't sound like you, we recommend writing to the
0669   developer's list if none of the quote sources work for you.  Ideally, please point
0670   us to a web page where these quotes can be obtained.  Additionally you can consult
0671   with members of the KDE Community Forum for &kmymoney; as they may already have a
0672   solution available for your needs.
0673 </para>
0675 <para>
0676   If you do feel up to the challenge, here's how it works.  The quote sources are
0677   contained in the settings dialog. Choose the
0678   <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
0679   &kmymoney;</guimenuitem></menuchoice> menu item. From there, choose the <guilabel>Online
0680   Quotes</guilabel> section.  You can choose an existing source to edit, or create a
0681   new one.  When you are done with your changes, be sure to press
0682   the <guibutton>Update</guibutton> button before exiting the dialog.  Your changes
0683   are not saved by default.
0684 </para>
0686 <para>
0687   The first thing to consider in an online quote source is the URL.  This is the page
0688   that is fetched from the web.  You will see a %1 in all sources, and a %2 in
0689   currency sources.  For investments, %1 is replaced by the trading symbol.  For
0690   currencies, %1 is replaced by the From currency, and %2 is replaced by the To
0691   currency.  This URL is then fetched, all HTML tags are (optionally) removed, and
0692   that stripped file is then sent to the page parser.
0693 </para>
0695 <para>
0696   Note that the URL can also be a file: URL, which the quote fetcher takes to be the
0697   path to an executable script.  It will pass any command-line arguments to it that
0698   you have specified, and feed the stdout to the page parser.  For example, you might
0699   have a script called getquote.sh that contains custom quote logic, taking the
0700   symbol as a single parameter.  Your URL would be
0701   <quote>file:/path/to/getquote.sh %1</quote>.
0702 </para>
0704 <para>
0705   The page parser looks for a symbol, a date, and a price.  Regular expressions tell
0706   it how to extract those items from the page.  Please review the documentation for
0707   the <ulink url="https://doc.qt.io/qt-5/qregularexpression.html">QRegularExpression
0708   class</ulink> for the exact syntax regular expressions used by &kmymoney;.  There
0709   should be exactly one capture expression, surrounded by parentheses, in each regexp
0710   field.  The date format further tells the date parser the order of year, month, and
0711   day.  This date format should always be in the form "%x %x %x". where x is y, m, or
0712   d.  The date parser is very smart.  <quote>%m %d %y</quote> will
0713   parse <quote>December 31st, 2005</quote> as easily as <quote>12/31/05</quote>.  Two
0714   digit years are interpreted as being in the range of 1950-2049.
0715 </para>
0716 </sect3>
0717 </sect2>
0718 </sect1>
0720 <sect1 id="details.investments.unimplemented">
0721 <title>Unimplemented Features</title>
0723 <para>
0724   There are some features that are normally associated with investments which are not
0725   yet implemented in &kmymoney;.  These include, but are not limited to derivatives,
0726   options, and futures.  In addition, when you sell a security, &kmymoney; does not
0727   know which specific shares you are selling, &ie;, the oldest or the most recently
0728   purchased, so it cannot calculate return on investment.  Finally, it has no direct
0729   knowledge about any country's specific tax reporting requirements, but these can
0730   usually be handled by marking as Tax related all the categories you use for
0731   transactions which might have tax consequences.
0732 </para>
0733 </sect1>
0734 </chapter>