<?xml version="1.0" encoding="ISO-8859-1" ?>
<chapter id="firsttime">

<chapterinfo>
<authorgroup>
<author>
	<firstname>Michael</firstname>
	<othername>T.</othername>
	<surname>Edwardes</surname>
	<affiliation>
		<address><email>mte@users.sourceforge.net</email></address>
	</affiliation>
</author>
</authorgroup>
<date>2005-07-09</date>
<releaseinfo>0.8</releaseinfo>
</chapterinfo>

<title>Using &kappname; for the first time</title>

<sect1 id="firstime-1">
<title>Running &kappname; for the first time</title>

<para>
	After starting &kappname; and the application has fully loaded two windows will be opened.  The top most window, 'Tip of the Day' presents a method for the application to let you know about important or useful pieces of information.
	<screenshot>
	<screeninfo>Tip of the Day</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="tipofday.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Tip of the Day</phrase>
	</textobject>
	</mediaobject>
	</screenshot>
</para>

<para>
It is highly recommended to quickly read through these tips by pressing on the <guibutton>Previous</guibutton> and <guibutton>Next</guibutton> buttons at the bottom of the window.
</para>

<para>
Once you have read the tips the window can be closed and will re-open each time &kappname; is started.  To stop this default behavior uncheck the appropriate option on the Tip of the Day window.
</para>

<note><para>
	Tips can be read at anytime by selecting <guimenuitem>Show tip of the day</guimenuitem> from the <guimenu>Help</guimenu> menu within &kappname;.
</para></note>

<para>
All tips have been extracted from the Frequency Asked Questions list (FAQ) that provides more detailed help and can be found on the project <ulink url="http://kmymoney2.sourceforge.net/faq.html">website</ulink> and in this manual.
</para>

<para>
	Please click on <guibutton>Close</guibutton> to close the Tip of the Day dialog.
</para>
</sect1>

<sect1 id="firsttime.mainwindow">
<title>The main window</title>

<para>
	<screenshot>
	<screeninfo>The Main Window</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="mainwindow_numbered.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>The Main Window</phrase>
	</textobject>
	</mediaobject>
	</screenshot>
</para>

<para>
The &kappname; main window consists of four major parts
</para>
<itemizedlist>
	<listitem><para>A. The menu bar</para></listitem>
	<listitem><para>B. The toolbar</para></listitem>
	<listitem><para>C. The View selector</para></listitem>
	<listitem><para>D. The view</para></listitem>
</itemizedlist>



<para>	
The menu and toolbars provide access to the features of &kappname; and allow you to <link linkend="firsttime-3">Create</link> files or configure how &kappname; operates.
</para>

<para>
The view selector consists of up to ten icons in the left side of the main window, depending upon the software provided by your system.  By clicking on an icon, the view window on the right hand side is loaded with the appropriate view of your financial data.  Each view provides a unique representation of your financial situation and allows you to view or edit the information shown.
</para>

<para>
	The view selector contains the following icons
</para>
	
<itemizedlist>
	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="home_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Home View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			A configurable overview of your current financial situtation (or an introduction page when no data exists).
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="institutions_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Accounts View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			All of your institutions and accounts displayed in a hierarchy.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="accounts_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Accounts View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			All of your accounts displayed in a hierarchy.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="schedule_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Schedule View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			Your recurring bills and deposits.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="categories_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Categories View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			Special accounts that provide a means for you to group associated transactions.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="payees_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Payees View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			All Payees used by &kappname;.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="ledgers_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Ledgers View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			Your account transactions.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="investments_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Investments View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			Your portfolio summary.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="reports_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Reports View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			A collection of useful reports, providing alternate views of your financial data.
		</para>
	</listitem>

	<listitem>
		<para>
			<guiicon>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="outbox_view.png" format="PNG"></imagedata>
					</imageobject>
					<textobject>
						<phrase>Outbox View</phrase>
					</textobject>
				</inlinemediaobject>
			</guiicon>
			Used by the online banking module to provide feedback on running processes.
		</para>
	</listitem>
</itemizedlist>
</sect1>	

<sect1 id="firsttime-3">
<title>Creating a new file</title>

<para>
	To create a new file you can either select <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice> from the  menu or choose the <inlinemediaobject><imageobject><imagedata fileref="new.png"/></imageobject><textobject><phrase>New</phrase></textobject></inlinemediaobject> icon from the toolbar.
</para>

<para>
	&kappname; will then open the personal information dialog box asking for your name and address.
</para>
	
<para>
	<screenshot>
	<screeninfo>Personal Information Dialog</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="newfile.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Personal Information Dialog</phrase>
	</textobject>
	</mediaobject>
	</screenshot>
</para>

<para>
Because all fields are optional, you can use &kappname; without entering any information now.  Any information entered here is used only to personalize your file.  In the future, it may be used in some reports and for online banking. If &kappname; requires any personal information in future releases and finds none, you will be prompted to enter the relevant data then.
</para>

<para>
	Please enter your name and address or nothing and press <guibutton>OK</guibutton>.
</para>

<para>&kappname; supports multiple currencies.  To set your base currency, (the currency you use day to day), select the appropriate symbol from the list provided.</para>

<para>
	Because this is a new file &kappname; will now import a set of default accounts with your interaction.  A message box is first shown reminding you that this step involves selecting the correct file to import into &kappname;.
</para>
<para>
	<screenshot>
	<mediaobject>
	<imageobject>
	<imagedata fileref="default_prompt.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Prompt</phrase>
	</textobject>
	</mediaobject>
	</screenshot>
</para>

<para>
	Please read the message and click on <guibutton>OK</guibutton>.
</para>

<para>
	Next &kappname; shows the standard KDE File Open dialog box allowing you to select the appropriate file for your country/region.  This window should list various language dependant directories containing files ending with the file extension 'kmt'.  If no files are listed matching this criteria then please navigate to $KDEDIR/share/apps/kmymoney2.  On a Mandrake 10 System this relates to /usr/share/apps/kmymoney2.

	<screenshot>
	<mediaobject>
	<imageobject>
	<imagedata fileref="kmt.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Account Templates</phrase>
	</textobject>
	</mediaobject>
	</screenshot>

	Only one file needs to be selected and should match your country and or region.  If your country/region is not listed then please select the default_account_enC.dat file or Click on <guibutton>Cancel</guibutton> to not load any pre-defined accounts.  The enC file relates to the default country and region and is usually American.  Accounts can be renamed later if needed.
</para>

<para>
	Choose the appropriate accounts file and click on <guibutton>OK</guibutton> to create the file.
</para>

<para>
After &kappname; has finished loading the default accounts your financial summary will be displayed.  As you have defined no accounts to hold your transactions this is currently empty.
</para>
</sect1>


<sect1 id="firsttime-4">
<title>Creating accounts</title>

<para>
You can create an account in one of two ways both of which are described here:
</para>

<variablelist>
	<varlistentry><term>Using the menu</term><listitem><para>To create an account using the menu select <menuchoice><guimenu>Accounts</guimenu><guimenuitem>Add new account</guimenuitem></menuchoice>.</para></listitem></varlistentry>
		
	<varlistentry><term>Using the Accounts view</term><listitem><para>To create an account using the accounts view click on the Accounts icon in the view selector and then right click on the Asset tree icon in the right hand view and select <guimenuitem>New account</guimenuitem> from the popup menu.  The Asset tree holds all of your accounts that are an asset.  Assets, and all the other account types, are discussed in more detail later in this manual.</para></listitem></varlistentry>
</variablelist>

<tip>
	<para>
		Note that &kappname; uses the context menus a lot throughout the whole application.  If you find yourself stuck trying to figure out how to do something, try right-clicking where you would expect to see a feature.
	</para>
</tip>

<para>
	Creating a new account by either method opens the <emphasis>New Account Wizard</emphasis>.  This wizard will take you step by step through the process of creating an account, gathering the required information at each step.  To navigate through the pages click on the <guibutton>Previous</guibutton> and <guibutton>Next</guibutton> buttons.
</para>

<para>
Create an account using either of the two previously mentioned methods to continue.
A full description of creating accounts can be found in the <link linkend="details.accounts">Accounts</link> section.
</para>

<para>
	Now that one or more accounts exist in &kappname; your account summary is shown in the Home view.  You can create transactions manually in the <link linkend="details.ledgers">Ledger</link> view, or set up automatic transactions through the <link linkend="details.schedules">Schedule</link> view.
</para>

</sect1>

<sect1 id="firsttime.schedules">
<title>Schedules</title>
<para>
	A <link linkend="details.schedules">Schedule</link> is a transaction that occurs one or more times over a certain period of time.  Sometimes called recurring transactions a typical example is your pay check that you receive every month or week.  Rather than have to enter the transaction details each time you get paid, you can instruct &kappname; to create a schedule that will enter a transaction for you when you get paid.
</para>
</sect1>

<sect1 id="firsttime.categories">
<title>Categories</title>
<para>	
	To maintain <link linkend="details.categories">categories</link> click on the <guiicon><inlinemediaobject><imageobject><imagedata fileref="categories_view.png"/></imageobject></inlinemediaobject>Categories</guiicon> icon in the view selector.
</para>
</sect1>

<sect1 id="firsttime.payees">
<title>Payees</title>
<para>
	To maintain your list of payees click on the <guiicon><inlinemediaobject><imageobject><imagedata fileref="payees_view.png"/></imageobject></inlinemediaobject>Payees</guiicon> icon in the view selector.
</para>

<para>
A full description of this topic can be found in the <link linkend="details.payees">Payees</link> section.
</para>
</sect1>

<sect1 id="firsttime-import">
<title>Quicken Interchange Format (QIF) Import</title>
<para>
If you currently use a financial manager application &kappname; can then import an account's transactions as long as they are in the Quicken Interchange Format (QIF).  Most financial programs can export this format and the different applications methods of exporting QIF is not discussed here for brevity.
</para>

<para>
A full description of this topic can be found in the <link linkend="details.impexp.qifimp">QIF Import</link> section.
</para>
</sect1>

<sect1 id="firsttime-find">
<title>Searching for transactions</title>

<para>
	&kappname; provides a useful and powerful transaction search facility in the form of the search dialog.
</para>

<para>
	The search dialog can be opened from the toolbar using the <guiicon><inlinemediaobject><imageobject><imagedata fileref="transaction_find.png"/></imageobject></inlinemediaobject>Find</guiicon> icon or by selecting <guimenuitem>Find Transaction</guimenuitem> from the <guimenu>Account</guimenu> menu.
</para>

<para>
A full description of this topic can be found in the <link linkend="details.search">Search</link> section.
</para>

</sect1>

<sect1 id="firsttime-reconcile">
<title>Reconciliation</title>

<para>
At some point you will want to reconcile the transactions you have entered with the transactions listed in a statement, be it a bank statement, credit card statement, loan statement or any other statement.  Reconciliation involves matching what you have entered with what the statement lists.  If any discrepancies are found then either you or the person who created the statement have made a mistake.
</para>

<para>
To reconcile an account click on the <guiicon><inlinemediaobject><imageobject><imagedata fileref="reconcile.png"/></imageobject></inlinemediaobject> Reconcile Ledgers</guiicon> icon in the account selector, choose your account from the drop down list and then click on the <guibutton>Reconcile</guibutton> button.
</para>

<para>
A full description of this topic can be found in the <link linkend="details.reconcile">Reconciliation</link> section.
</para>

</sect1>

<sect1 id="firsttime-backup">
<title>Backing up</title>
<para>
Now that you have created some accounts and entered transactions its a good idea to perform a backup.  Because the file used by &kappname; is a standard Unix file you can just copy the file to another location to back it up or use the dialog provided by &kappname;.  Using the dialog is the preferred method because if &kappname; ever starts using other file formats, such as SQL, then it would be much harder to copy the file manually.
</para>

<para>
	To backup your file through &kappname; Select <guimenuitem>Backup</guimenuitem> from the <guimenu>File</guimenu> menu and enter the directory where you wish the file to be copied to.  If the directory needs mounting first and you have the sufficient privileges then check the tick box labelled <guilabel>Mount this directory before backing up</guilabel> and click on <guibutton>OK</guibutton>.
</para>

<para>
The file will be coped to the directory specified with the current date appended to the filename so it is easy to see the date the file was backed up.
</para>
</sect1>

<sect1 id="firsttime-contact">
<title>Contacting the developers / Reporting Bugs</title>
<sect2><title>Contacting the developers</title>
<para>
	You can contact the developers through their mailing list &devlist;.
</para>
<para>
We're happy to hear about your experiences using &kappname;.
</para>
</sect2>
<sect2><title>Reporting bugs</title>
<para>
	To report a bug please use the interface provided by &kappname; by selecting <menuchoice><guimenu>Help</guimenu><guimenuitem>Report Bug</guimenuitem></menuchoice> and filling in the required information.
</para>
<sect3 id="firsttime.bugs.quality"><title>Writing High Quality Bug Reports</title>
<para>
	We encourage users to take extra time to write high-quality bug reports when submitting them.
	This reduces wasted effort on all sides, as the reporter and the developer who will fix it trade e-mails until this information is really in place.
</para>
<para>
Eli Goldberg wrote the canonical Bug-Writing Guideline, available at <ulink url="http://issues.apache.org/bugwritinghelp.html">http://issues.apache.org/bugwritinghelp.html</ulink>.  Generally, you'll be well-served by following these guidelines:
</para>

<formalpara><title>Include your system information</title>
<para>
The  <menuchoice><guimenu>Help</guimenu><guimenuitem>Report Bug</guimenuitem></menuchoice> menu choice will fill this in automatically.  But if you would prefer not to use this interface, we will need to know the version of &kappname; you're running, the version of KDE, the name and version of your distribution, and the version of your kernel.
</para>
</formalpara>


<formalpara><title>Include a backtrace for crashes</title>
<para>
The backtrace is often the single most useful piece of information in solving crashes.
</para>
</formalpara>

<formalpara><title>Try to reproduce it</title><para>Let us know if you were able to do so.  It's useful to know whether the bug only happened once and you couldn't get it to happen again; or whether it happens every time; or whether it happens sometimes but not others.</para>
</formalpara>

<formalpara><title>Include specific steps</title><para>This is a bad bug: &quot;I entered a transaction, and &kappname; crashed.&quot;  A much better bug is: &quot;Using the transaction form, I entered a new transaction in my Credit Card account.  I selected the Transfer tab, entered in an amount, then changed to the Deposit tab, and back to the Transfer tab.  When I returned to the Transfer tab, &kappname; crashed.  This bug is fully reproducable for me.&quot;</para>
</formalpara>

<formalpara><title>Tell us what you expected to happen</title><para>In crashes this is obvious, but in more subtle bugs, sometimes you'll see a bug report that is not obvious what the reporter expected to happen.  Always tell us what you think should have happened.</para>
</formalpara>

<formalpara><title>Consider running with debugging enabled</title><para>By compiling a version configured with --enable-debug=full you can ensure that the best possible backtraces are generated.  If you encounter a crash, run &kappname; again from within gdb, and reproduce the crash.  When it crashes, type &quot;bt&quot; to generate a backtrace.</para>
</formalpara>

<para>Running this way is a bit more difficult, so we don't expect all users to do this.  However, if you're interested in helping &kappname; become as stable as possible, this is the best way to do it short of finding the bug in the code and sending in a patch.</para>
</sect3>
</sect2>
</sect1>

</chapter>