<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "gnc-docbookx.dtd">

<!--
      (Do not remove this comment block.)
  Version: 2.0.0
  Last modified: 2014-08-28 (fell)
       modified: October 25th 2010
       modified: January 12th 2007
       modified: July 9th 2006
  Maintainers:
               Cristian Marchi <cri.penta@gmail.com>
               Chris Lyttle <chris@wilddev.net>
  Author:
  		Jon Lapham <lapham@extracta.com.br>
  	Updated	Bengt Thuree <bengt@thuree.com>
  Originally written by Carol Champagne.
  Translators:
               (translators put your name and email here)
-->
<chapter id="chapter_basics">
  <title>The Basics</title>

  <para>This chapter will introduce some of the basics of using &app;. It is
  recommended that you read through this chapter, before starting to do any
  real work with &app;. Next chapters will begin to show
  you hands on examples.</para>

  <sect1 id="basics-accounting1">
    <title>Accounting Concepts</title>

    <para>&app; is easy enough to use that you do not need to have a
    complete understanding of accounting principles to find it useful.
    However, you will find that some basic accounting knowledge will prove to
    be invaluable as &app; was designed using these principles as a
    template. It is highly recommended that you understand this section of the
    guide before proceeding.</para>

    <sect2 id="basics-accounting52">
      <title>The 5 Basic Accounts</title>

      <para>Basic accounting rules group all finance related things into 5
      fundamental types of <quote>accounts</quote>. That is, everything that
      accounting deals with can be placed into one of these 5 accounts:</para>

      <variablelist>
      <title>Account types</title>
        <varlistentry>
          <term><emphasis>Assets</emphasis></term>
          <listitem>
            <para>Things you own</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>Liabilities</emphasis></term>
          <listitem>
            <para>Things you owe</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>Equity</emphasis></term>
          <listitem>
            <para>Overall net worth</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>Income</emphasis></term>
          <listitem>
            <para>Increases the value of your
            accounts</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>Expenses</emphasis></term>
          <listitem>
            <para>Decreases the value of your
            accounts</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>It is clear that it is possible to categorize your financial world
      into these 5 groups. For example, the cash in your bank account is an
      asset, your mortgage is a liability, your paycheck is income, and the
      cost of dinner last night is an expense.</para>
    </sect2>

    <sect2 id="basics-accountingequation2">
      <title>The Accounting Equation</title>

      <para>With the 5 basic accounts defined, what is the relationship
      between them? How does one type of account affect the others? Firstly,
      equity is defined by assets and liability. That is, your net worth is
      calculated by subtracting your liabilities from your assets:</para>

      <equation id="accounting_equation_static">
        <title>The static accounting equation</title>
        <mathphrase>Assets - Liabilities = Equity</mathphrase>
      </equation>

      <para>Furthermore, you can increase your equity through income, and
      decrease equity through expenses. This makes sense of course, when you
      receive a paycheck you become <quote>richer</quote> and when you pay for dinner you
      become <quote>poorer</quote>. This is expressed mathematically in what is known as
      the Accounting Equation:</para>

      <equation id="accounting_equation_dynamic">
        <title>The (dynamic) accounting equation</title>
        <mathphrase>Assets - Liabilities = Equity + (Income - Expenses)</mathphrase>
      </equation>

      <para>This equation must always be balanced, a condition that can only
      be satisfied if you enter values to multiple accounts. For example: if
      you receive money in the form of income you must see an equal increase
      in your assets. As another example, you could have an increase in assets
      if you have a parallel increase in liabilities.</para>

      <figure pgwide="1">
        <title>The basic accounts relationships</title>
        <screenshot id="basics-AccountRelationships">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_AccountRelationships.png"
                         format="PNG" srccredit="Geert Janssens" ></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_AccountRelationships.svg"
                         format="SVG" srccredit="Geert Janssens"
                         contentwidth="4in"></imagedata>
            </imageobject>

            <textobject>
              <phrase>The basic accounts relationships</phrase>
            </textobject>

            <caption>
              <para>A graphical view of the relationship between the 5 basic
              accounts. Net worth (equity) increases through income and
              decreases through expenses. The arrows represent the movement of
              value.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </sect2>
    
    <sect2 id="basics-debits-credits">
      <title>Debits and Credits</title>
      
      <para>The use of debits and credits in accounting and their effect on accounts of different types
       is often confusing when first encountered in acccounting. The accounting equation introduced above
       is the key to understanding which accounts types are debited or credited and when. First of all we need
       to rearrange the expanded form a little bit with Assets on the left hand side of the equal sign and 
       transposing any account type with a negative sign to the other side to obtain:
      </para>
      
      <equation id="accounting_equation_rearranged">
        <title>The rearranged accounting equation</title>
        <mathphrase> Assets + Expenses = Liabilities + Equity + Income</mathphrase>
      </equation>
      
      <para>With the accounting equation in this form, the accounts on the left hand side of the equal sign 
      are known as <emphasis>debit balance accounts</emphasis> in accounting practice,
      that is the normal positive balance for these accounts is increased by <emphasis>debit</emphasis> entries to accounts of these types. 
      Conversely credit entries to accounts of these types will decrease the balance of accounts of these types.
      </para>
      
      <para>Similarly, the account types on the right hand side of the equal sign are known as <emphasis>credit balance
      accounts</emphasis>, that is the normal positive balance for these account types is increased by <emphasis>credit</emphasis> entries to
      the accounts of these types. Again debit entries to accounts of these types will reduce the balance in the account.
      </para>
      
      <table frame='all' id="basics-debits-credits-effect-tbl">
        <title>Summary of effect of debits (Dr) and credits (Cr) on the balance of accounts of the 5 account types</title>
        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
        <colspec colname='c1'/><colspec colname='c2'/><colspec colname='c3'/>
          <thead>
          <row><entry>Account Type</entry><entry namest="c2" nameend="c3" align ="center">Effect on Account Balance</entry></row>
          <row><entry> </entry><entry>Debit (Dr)</entry><entry>Credit (Cr)</entry></row>
          </thead>
          <tbody>
          <row><entry>Assets</entry><entry morerows='1' valign='middle'>Increase</entry><entry morerows='1' valign='middle'>Decrease</entry></row>
          <row><entry>Expenses</entry></row>
          <row><entry>Liabilities</entry><entry morerows='2' valign='middle'>Decrease</entry><entry morerows='2' valign='middle'>Increase</entry></row>
          <row><entry>Equity</entry></row>
          <row><entry>Income</entry></row>
          </tbody>      
        </tgroup>
      </table>    
    </sect2>
    
    <sect2 id="basics-accountingdouble2">
      <title>Double Entry</title>

      <para>The accounting equation is the very heart of a <firstterm>double entry
      accounting system</firstterm>. For every change in value of one account in the
      Accounting Equation, there must be a balancing change in another. This
      concept is known as the <firstterm>Principle of Balance</firstterm>, and
      is of fundamental importance for understanding &app; and other double
      entry accounting systems. When you work with &app;, you will always be
      concerned with at least 2 accounts, to keep the accounting equation
      balanced.</para>

      <para>Balancing changes (or transfers of money) among accounts are
      done by debiting one account and simultaneously crediting another.
      Accounting <firstterm>debits</firstterm> and
      <firstterm>credits</firstterm> do not mean <quote>decrease</quote>
      and <quote>increase</quote>. Debits and credits each increase certain
      types of accounts and decrease others as described in the previous section. In asset and expense accounts,
      debits increase the balance and credits decrease the balance. In
      liability, equity and income accounts, credits increase the balance
      and debits decrease the balance.</para>

      <para>In traditional double-entry accounting, the left column in the
      register is used for debits, while the right column is used for credits.
      Accountants record increases in asset and expense accounts on the
      debit (left) side, and they record increases in liability, revenue, and equity
      accounts on the credit (right) side. &app;
      follows this convention in the register.</para>

      <note>
        <para>This accounting terminology can be confusing to new users,
        which is why &app; allows you to use the
        common terms <guilabel>Deposit</guilabel> and
        <guilabel>Withdrawal</guilabel>. If you prefer the formal accounting
        terms, you can change the account register column headings to use
        them in the <guilabel>Accounts</guilabel> tab under
        <guilabel>Preferences</guilabel> (see the
        &app; Help Manual for more information on
        setting preferences).</para>
      </note>

      <warning>
        <para>Common use of the words <emphasis>debit</emphasis> and <emphasis>credit</emphasis>
        does not match how accountants use these words. In common use,
        <emphasis>credit</emphasis> generally has positive associations; in accounting,
        <emphasis>credit</emphasis> means
        <emphasis>affecting the right column</emphasis> of the ledger sheet of an account.
        This is associated with a <emphasis>decrease</emphasis> in asset and expense,
        but an <emphasis>increase</emphasis> of income, liability and equity accounts.</para>
        <para>For more details see <ulink url="&url-wp-en;Debits_and_credits"></ulink>.</para>
      </warning>

    </sect2>
  </sect1>

  <sect1 id="basics-entry1">
    <title>Data Entry Concepts</title>

    <para>When entering data in &app;, you should be aware of the 3 levels
    of organization in which &app; divides your data: files, accounts and
    transactions. These levels are presented in their order of complexity, one
    file contains many accounts and one account contains many transactions.
    This division is fundamental to understanding how to use &app;.</para>

    <sect2 id="basics-files2">
      <title>Files</title>

      <para>&app; stores information at the
      highest level in files. A file can be stored on your computer either
      as a single <acronym>XML</acronym> file (in all versions of
      &app;), or in a <acronym>SQL</acronym>
      database (in &app; version 2.4 and higher).</para>

      <note>
        <para><acronym>SQL</acronym> is pronounced <quote>sequel</quote>,
        so in spoken and written language we would say <quote>a SQL
        database</quote>.</para>
      </note>

      <para>With the <acronym>XML</acronym> file format,
      &app; stores your data in an
      <acronym>XML</acronym> data file, usually in compressed format
      (although this can be changed in the <guilabel>General</guilabel>
      tab of the &app; <guilabel>Preferences</guilabel>).</para>

      <para>With <acronym>SQL</acronym> storage,
      &app; stores your data in a
      <acronym>SQL</acronym> database under the database application you
      select (SQLite3, MySQL or PostgreSQL).</para>

      <para>You will need one main file or database for each set of
      accounts you are maintaining. To learn how to create and manage
      &app; files, see <xref
      linkend="basics-files1"/>.</para>

      <note>
        <para>If you think you might need more than one set of accounts,
        you might want to consult a professional accountant or bookkeeper
        before proceeding. Most users will probably have only one data
        file.</para>
      </note>

      <para>Backup files and log files are automatically generated by
      &app; when appropriate. Backup and log
      files are described in <xref linkend="basics-backup1"/>.</para>
    </sect2> <!-- basics-files2 -->
    <sect2 id="basics-accounts2">
      <title>Accounts</title>

      <para>An <glossterm linkend="gnc-gl_account">account</glossterm> keeps track of what you own,
      owe, spend or receive. Each &app; file can
      contain any number of accounts, and each account can contain many
      sub-accounts up to an arbitrary number of levels. This simple feature
      gives &app; much of its power in managing
      your finances, as you will see in later chapters.</para>

      <para>Examples of accounts include: checking accounts, savings
      accounts, credit card accounts, mortgages, and loans. Each
      &app; account tracks the activity for that
      <quote>real</quote> account, and can inform you of its status.</para>

      <para>In addition, accounts are also used to categorize the money you
      receive or spend. For example, you can create expense accounts to
      track the money you pay on utilities or groceries. Even though these
      are not accounts that receive statements, they allow you to determine
      how much money is being spent in each of these areas.</para>

      <para>Accounts will be covered in more detail in <xref
      linkend="chapter_accts"/>.</para>
    </sect2> <!-- basics-accounts2 -->
    <sect2 id="basics-transactions2">
      <title>Transactions</title>

      <para>A <firstterm>transaction</firstterm> represents the movement of
      money among accounts. Whenever you spend or receive money, or
      transfer money between accounts, that is a transaction.</para>

      <para>Examples of transactions are: paying a phone bill, transferring
      money from savings to checking, buying a pizza, withdrawing money,
      and depositing a paycheck. <xref linkend="chapter_txns"/> goes more
      in depth on how to enter transactions.</para>

      <para>In <link linkend="basics-accountingdouble2">double entry accounting</link>,
      transactions always involve at least two accounts&ndash;a source
      account and a destination account.
      &app; manages this by inserting a line
      into the transaction for every account that is affected, and
      recording the amounts involved in each line. A line within a
      transaction that records the account and amount of money involved is
      called a <firstterm>split</firstterm>. A transaction can contain an
      arbitrary number of splits.</para>
      <note>
        <para>Splits in transactions will be covered in <xref
        linkend="txns-registers-multiaccount2"/></para>
      </note>
    </sect2> <!-- basics-transactions2 -->
  </sect1> <!-- basics-entry1 -->

  <sect1 id="basics-running-gnucash">
    <title>Running &app;</title>
    <para>&app; can be run from your desktop main menu by selecting the associated menu entry.</para>
    <para>Alternatively it can be run from a command line prompt with the command <command>gnucash</command>.</para>

    <para>During start up, &app; will display the
    Splash Screen, where some information about the program (version number, build, etc.)
    and the loading process are displayed.</para>

    <sect2 id="basics-welcome-to-gnucash">
    <title><guilabel>Welcome to &appname;</guilabel> dialog</title>
    <para>The very first time you open &app;, you will see the
    <guilabel>Welcome to &appname;!</guilabel> screen. This dialog includes three choices:</para>
    <!-- Recommend screen shot here of Welcome to GnuCash! dialog -->

      <itemizedlist id="welcome-screen-options">
        <listitem>
          <para><guilabel>Create a new set of accounts</guilabel> - Runs the
          <guilabel>New Account Hierarchy Setup</guilabel> assistant (see <xref linkend="basics-acct-hierarchy"/>). Select
          this option if you want to be assisted in creating a set of accounts.</para>
        </listitem>

        <listitem>
          <para><guilabel>Import my QIF files</guilabel> - Runs the
          <guilabel>Import QIF Files</guilabel> assistant (see <xref linkend="importing-qif"/>). Select this option
          if you already have Quicken files (<filename>.qif</filename> files) and wish
          to import them into &app;.</para>
        </listitem>

        <listitem>
            <para><guilabel>Open the new user tutorial</guilabel> -
            Opens the &app; Tutorial and Concepts Guide. Select this
            option if you are completely new to &app; and
            accounting concepts.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>It is possible to access each of these items after you have left this screen,
        but the <guilabel>Welcome to &appname;!</guilabel> screen will not reappear.
        To create a new set of accounts, see <xref linkend="basics-acct-hierarchy" />. To import
        QIF files, see <xref linkend="importing-qif" />.</para>
      </note>
    </sect2>

    <sect2 id="basics-acct-hierarchy">
      <title>New Account Hierarchy Setup</title>

      <para>The <emphasis>New Account Hierarchy Setup</emphasis> assistant helps you
      to create a set of &app; accounts. It will
      appear if you choose <guibutton>Create a new set of accounts</guibutton>
      in the <guilabel>Welcome to &appname;!</guilabel> menu, or when you select
      <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>. You may also use it to add a section of accounts to an existing book from the <guilabel>Accounts</guilabel> page by selecting <guimenu>Action</guimenu>&gt;<guimenuitem>New Account Hierarchy...</guimenuitem>.</para>
      <para>This assistant will guide you through the creation of a <emphasis>Chart of Accounts</emphasis>. There are several
      steps in the assistant, which are outlined below.</para>

      <orderedlist>
          <listitem>
              <para>The first screen briefly describes what this assistant does. </para>
          </listitem>
          <listitem>
              <para><guilabel>New Book Options</guilabel> Appears only when creating a new book. Here you set various book attributes. This page has four tabs:
              Accounts, Budgeting, Business, and Counters. These items are explained elsewhere in
              the Guide, and can be changed at any time from <guimenu>File</guimenu>&gt;<guimenuitem>Properties</guimenuitem>.</para>
          </listitem>
          <listitem>
              <para><guilabel>Choose Currency</guilabel> sets the hidden root account currency and the default currency for new accounts. The offered default is  based on the computer locale settings. Choose this carefully: Not only does it set the default currency for creating new accounts, it is the "Home" currency for the book and becomes the default currency for all stock pricing and foriegn currency exchange rates. While it can be changed by rerunning the <guilabel>New Account Hierarchy Setup</guilabel> Assistant from the <guimenu>Action</guimenu> menu, doing so after you've created transactions is risky.</para>
          </listitem>
          <listitem>
            <para><guilabel>Choose accounts to create</guilabel> provides a variety of accounting categories that may be added to the book. There are two main panels: On the left the list of categories with a selection check box next to each one and on the right the accounts that will be added by the highlighted category.</para>
            <para> Above the <guilabel>Categories</guilabel> list you'll find two list-buttons, one for language code and the other for country code. The initial selection is again based on your computer's locale settings. You may select any language and country combination that suits your needs.</para>
            <note><para>The <guilabel>New Account Hierarchy Setup</guilabel> Assistant can't process selections from more than one locale at a time, so if you need to select segments from multiple locales&mdash;perhaps because the categories for your primary locale are intended to extend those of another country&mdash;you'll need to run the assistant more than once from the <guimenu>Action</guimenu> menu.</para></note>
          </listitem>
          <listitem>
              <para><guilabel>Setup selected accounts</guilabel> presents  the accounts from the categories you selected on <guilabel>Choose accounts to create</guilabel> in a non-collapsible tree view with four or five columns depending on whether or not you're creating a new book:
              <itemizedlist>
                <listitem><para><guilabel>Account Name</guilabel>. This is editable, just click in it or select the row and press <keycap>Enter</keycap>.</para></listitem>
                <listitem><para><guilabel>Type</guilabel> Not editable. This is the type of the account.</para></listitem>
                <listitem><para><guilabel>Placeholder</guilabel> accounts (accounts that are intended only to collect sub-accounts and not to have transactions themselves). You may change this by checking to make an account a placeholder or unchecking to make it a regular account.</para></listitem>
                <listitem><para><guilabel>Opening Balances</guilabel>can accept a value for new non-placeholder accounts that are not of type <emphasis>Equity</emphasis>, as existing accounts already have balances, placeholder accounts can't have transactions, and Equity can't have an opening balance.<note><para><guilabel>Opening Balance</guilabel>entry isn't obvious until you click in it. You must move out of the entry by clicking somewhere or by pressing <keycap>Tab</keycap> or <keycap>Enter</keycap> before clicking <guilabel>Next</guilabel> or your entry will be discarded.</para></note></para></listitem>
                <listitem><para><guilabel>Use Existing</guilabel> appears only when you've started the <guilabel>New Account Hierarchy Setup</guilabel> Assistant from the <guimenu>Action</guimenu> menu. It indicates whether an account already exists. It's not editable.</para></listitem>
              </itemizedlist></para>
          </listitem>
          <listitem>
              <para><guilabel>Finish account setup</guilabel> is the last screen and gives you a final option to cancel the process, back up to change something, or apply to confirm your choices. If you're creating a new book, gnucash will present a dialog to select a backend and either a file to save it or database server, database name, and credentials to create a MySQL or Postgresql database if GnuCash was built with those features and you have the necesaary dependencies installed.</para>
              <warning>
                  <para>If you choose to cancel, any selections you have made up to
                  this point will be lost.</para>
              </warning>
          </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="basics-tip2">
      <title>Tip of the Day</title>

      <para>&app; provides a <guilabel>Tip of the Day</guilabel> screen to
      give helpful hints for using the program:</para>

      <screenshot id="basics-TipOfDay">
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/basics_TipOfDay.png" format="PNG"
                       srccredit="Cristian Marchi" ></imagedata>
          </imageobject>

          <textobject>
            <phrase>The Tip of the Day</phrase>
          </textobject>

          <caption>
            <para>This image shows the <guilabel>Tip of the
            Day</guilabel>.</para>
          </caption>
        </mediaobject>
      </screenshot>

      <para>These tips provide useful information for beginning users. To view
      more of the tips, click <guibutton>Forward</guibutton> to continue. If you
      do not wish to see this screen box on start-up, deselect the box next to
      <guilabel>Show tips at startup</guilabel>. When you have
      finished viewing the helpful tips, click <guibutton>Close</guibutton> to
      close the <guilabel>Tip of the Day</guilabel> screen.</para>
    </sect2>

    <sect2 id="basics-main2">
      <title>Account Tree Window</title>

      <para>You should now see the <guilabel>Accounts</guilabel> window, which
      appears as shown below. The exact layout of the account tree will depend
      on which default accounts you selected during the New Account Hierarchy
      Setup. In this example, the <guilabel>Common Accounts</guilabel> are shown.</para>

      <screenshot id="basics-Accounts">
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/basics_Accounts.png" format="PNG"
                       srccredit="Cristian Marchi" ></imagedata>
          </imageobject>

          <textobject>
            <phrase>The Account Tree Window</phrase>
          </textobject>

          <caption>
            <para>This image shows the <guilabel>Accounts</guilabel>
            window.</para>
          </caption>
        </mediaobject>
      </screenshot>

      <para>The Account Tree window (also known as a Chart of Accounts, or CoA) provides an overview of the data contained
      in the current file. It contains a list of account names and their
      current balances.</para>
      <para>From this window, you can open the register of any
      account either by double-clicking the account name, right clicking the account name and selecting <guilabel>Open Account</guilabel> from the
      menu, or by using the <guibutton>Open</guibutton> button on the toolbar. &app; allows you to have as many account registers open as you wish. For more information on using account registers, see <xref linkend="basics-register2" />.</para>

      <tip>
        <para>Clicking the small triangle to the left of an account that has children will expand the tree view showing child accounts.</para>
      </tip>

      <para>At the top of this window is the <emphasis>Titlebar</emphasis>, which displays the
      file name for this set of accounts (once you have saved the file.) Below that is the <emphasis>Menubar</emphasis>.
      You can access the menu options by either clicking on these menu
      headings or by using shortcuts and access keys (see <xref linkend="basics-shortcut2" />).
      Next is the <emphasis>Toolbar</emphasis>, which contains buttons
      for the most common functions.</para>

      <para>The account tree appears below the <emphasis>Toolbar</emphasis>. Once you have
      started creating accounts, the account names will appear in the account
      tree. You can customize which headings show up by using the
      small <guiicon>down-arrow</guiicon> at the far right just above the account tree.</para>

      <para>At the bottom is the <emphasis>Statusbar</emphasis>, which tells you
      information about what you own (Net Assets) and how much money you have
      made (Profits).</para>


    </sect2>

    <sect2 id="basics-register2">
      <title>Account Register Window</title>

      <para>Account Register windows are used to enter and edit your
      account data. As the name suggests, they look similar to a checkbook
      register.</para>

      <screenshot id="basics-CheckAccount">
        <mediaobject>
          <imageobject role="html">
            <imagedata fileref="figures/basics_CheckAccount.png" format="PNG"
                       srccredit="Bengt Thuree" width="510"></imagedata>
          </imageobject>

          <imageobject role="fo">
            <imagedata fileref="figures/basics_CheckAccount.png" format="PNG"
                       srccredit="Bengt Thuree" ></imagedata>
          </imageobject>

          <textobject>
            <phrase>The Checking Account Register</phrase>
          </textobject>

          <caption>
            <para>This image shows the <guilabel>Checking Account - Register
            </guilabel> with several transactions.</para>
          </caption>
        </mediaobject>
      </screenshot>

      <para><xref linkend="chapter_txns"></xref> explains more about account
      register windows and how to
      enter data into them. For now, note that the parts of an account
      register window are similar to the parts of the account tree window
      described earlier. The <emphasis>Titlebar</emphasis> at the top contains the account name.
      Below that, the <emphasis>Menubar</emphasis> contains menu options related to the account
      register. <emphasis>Toolbar</emphasis> buttons simplify common data entry functions. The
      <emphasis>Statusbar</emphasis> at the bottom of the window, displays some account balances
      covered in <xref linkend="chapter_txns"></xref>. At the bottom of the
      account register window,
      information appears about the current location of the cursor.</para>

      <note>
      <para>In the register windows, you can resize the various columns that
        &app; displays, <emphasis>but keep in mind that
        the Description and Balance columns behave differently from other columns</emphasis>.</para>
      <para>The <guilabel>Description</guilabel> column is designed to expand
          automatically to fill all unused horizontal screen space.
          Therefore you should set the widths of all your other columns before
         setting the Description column width.</para>
      <para>The <guilabel>Balance</guilabel> column must be resized by
          double-clicking on the column heading.</para>
      </note>

    </sect2>

    <sect2 id="basics-toolbar2">
      <title>Toolbar Buttons</title>

      <para>Both the account tree window and the account register window
      contain <emphasis>Toolbar</emphasis> buttons. These buttons provide quick access to common
      functions such as <guibutton>Save</guibutton> and
      <guibutton>Open</guibutton> in the account tree window and
      <guibutton>Record</guibutton> and <guibutton>Delete</guibutton> in the
      account register window. If you are not sure what a button does, move
      the mouse pointer over that button, and you should see a description of
      the function appear.</para>

      <para>Here is a summary of the account tree window buttons:</para>

      <variablelist>
      <title>Account tree window buttons</title>
        <varlistentry>
        <term><guibutton>Save</guibutton></term>
        <listitem>
          <para>Save the current file to disk</para>
        </listitem>
        </varlistentry>

        <varlistentry>
        <term><guibutton>Close</guibutton></term>
        <listitem>
          <para>Close the current notebook page</para>
        </listitem>
        </varlistentry>

        <varlistentry>
        <term><guibutton>Open</guibutton>, <guibutton>Edit</guibutton>,
          <guibutton>New</guibutton> and <guibutton>Delete</guibutton></term>
        <listitem>
          <para>These are functions related to accounts. They are discussed in
          <xref linkend="chapter_accts"></xref>.</para>
        </listitem>
        </varlistentry>
      </variablelist>

      <para>Register-specific buttons are discussed in <xref linkend="chapter_txns"></xref>.
      </para>
    </sect2>

    <sect2 id="basics-tabbar">
      <title>Tab Bar</title>

      <para>&app; uses a tabbed model that allows you to open multiple account registers and reports simultaneously. Each open window (which can include account registers, reports, or Scheduled Transactions windows) is given a tab on this bar that you can click to view that window. Tabs can be configured in Preferences to appear along any side of the &app; window.</para>

    <para>To see the full name for a tab, hover the mouse pointer over an account window tab.</para>

    <para>If more screens are open than can be displayed across the screen, some tabs
        will not display.  You can move through all tabs by clicking the arrows on
        either end of the tab bar. A complete list of tabs can be viewed by
        right-clicking the Tab Bar and any tab can be selected by clicking it.</para>
    </sect2>

    <sect2 id="basics-options2">
      <title>Menu Items</title>

      <para>The account tree window and the account register window both
      contain menu headings in a <emphasis>Menubar</emphasis>. Clicking on a menu heading brings
      up the menu items for that heading.</para>

      <para>You can click on the account tree menu headings and then move the
      mouse pointer over the menu items to see what they do. As the pointer
      moves over a menu item, a description of the item appears in the lower
      left-hand corner of the window (inside the <emphasis>Statusbar</emphasis>). To select a menu item, click on
      it.</para>

      <para>You can also access the most common menu items in a window by
      right-clicking the mouse anywhere in that window. In the account tree
      window, this will bring up a list of account items. In the account
      register window, this will bring up a list of transaction items.</para>

      <para>Other ways of accessing menu items are through keyboard shortcuts
      and access keys, described next.</para> </sect2>

    <sect2 id="basics-shortcut2">
      <title>Menu Shortcuts</title>

      <para>All of the menu items have access keys which are
      marked by underlined characters in the menu names. Pressing the
      <keycap>Alt</keycap> key with the underlined character in the menu
      heading will bring up the menu items for that heading. Once the menu
      items are displayed, type the underlined character in the menu item to
      activate it. For example, typing <keycombo><keycap>Alt</keycap>
      <keycap>F</keycap></keycombo> in the main window brings up the <guimenu>File</guimenu>
      menu, then typing <keycap>S</keycap> will save the file.  Access keys
      are fixed and cannot be changed by users.</para>

      <para>Some of the more commonly used menu items also have shortcut keys
      that directly activate the command without having to traverse the menu
      structure.  These shortcuts typically use the <keycap>Ctrl</keycap>
      key, although they can use any key combination.  Menu shortcuts are
      displayed at the end of each menu item.</para>
    </sect2>
  </sect1>

  <sect1 id="basics-files1">
    <title>Storing your financial data</title>
	<sect2 id="basics-files1-overview">
		<title>Overview</title>
		
		<para>&app; offers several formats for storing 
		your financial data. The default file storage format is <acronym>XML</acronym>, 
		while <acronym>SQL</acronym> storage is available in SQLite, MySQL, and PostgreSQL 
		formats. Users can choose a file format for new files from <menuchoice><guimenu>File</guimenu> 
		<guimenuitem>Save </guimenuitem></menuchoice> and for existing files from <menuchoice><guimenu>File</guimenu> 
		<guimenuitem>Save As...</guimenuitem></menuchoice> dialogs.</para>
		
		<para>The <acronym>XML</acronym> storage format is a text file that by default is compressed, 
		which is a preference that is set at <menuchoice><guimenu>Edit</guimenu> 
		<guimenuitem>Preferences</guimenuitem></menuchoice> <guilabel>General</guilabel> 
		<guilabel>Compress files</guilabel>. SQLite storage is also available, and stores 
		your data in a single file on your system, like the <acronym>XML</acronym> format. However,
		internally, an SQLite file is managed as a database. The MySQL and PostgreSQL storage options 
		require access to a MySQL or PostgreSQL database server and the installation of 
		additional database drivers on your machine.</para>
		
		<tip>
		<para>Users can change the format at any time by using <menuchoice><guimenu>File</guimenu> 
		<guimenuitem>Save As...</guimenuitem></menuchoice>. This will create a copy of 
		the data file in the selected format.</para>
		</tip>
	</sect2>

	<sect2 id="basics-files-storage-comparison">
		<title>Storage Comparison and Recommendations</title>
		<para>Each storage format has benefits and shortcomings that users should 
		consider for their needs and abilities. See the 
		<link linkend='basics-storage-comparison-table' endterm="basics-storage-comparison-tbltitle"/> below
		for further details.</para>
		
		<para>The <acronym>XML</acronym> format is the most stable and established, 
		and for this reason, it is recommended for most users. <acronym>SQL</acronym>
		storage was added for the 2.4 release and has become an increasingly popular 
		choice for users. The SQLite format allows users to realize the benefits of 
		<acronym>SQL</acronym> storage without the overhead of installing or managing 
		a full <acronym>DBMS</acronym>. MySQL and PostgreSQL require the installation 
		of MySQL and PostgreSQL <acronym>DBMS</acronym>, respectively, and are best 
		maintained only by experienced database administrators.</para>
			
		<note>
			<para>Use of a <acronym>SQL</acronym> back end for storage implies to many 
			that &app; has fully implemented <acronym>DBMS</acronym> 
			features, including multi-user and incremental data manipulation.  However, 
			&app; does not currently implement these features, 
			although it is a long term goal of the development team. </para>
		</note>
	</sect2>
	<sect2 id="basics-storage-comparison-tblsect">
		<title>Storage Comparison Table</title>
		<table frame="topbot" id="basics-storage-comparison-table">
			<title id="basics-storage-comparison-tbltitle">Storage Comparison</title>

			<tgroup align="left" cols="5">
				<colspec colname="c1item" ></colspec>
				<colspec colname="c2xml" ></colspec>
				<colspec colname="c3sqlite" ></colspec>
				<colspec colname="c4mysql" ></colspec>
				<colspec colname="c5pgsql" ></colspec>

            <thead>
              <row>
                <entry> </entry>
                <entry align="center">XML</entry>
                <entry align="center">SQLite</entry>
                <entry align="center">MySQL</entry>
                <entry align="center">PostgreSQL</entry>
              </row>
            </thead>

            <tbody>
            <row>
				<entry namest="c1item"                      >Availability</entry>
  				<entry align="center" namest="c2xml"        > Built-in </entry>
  				<entry align="center" namest="c3sqlite" nameend="c5pgsql" > Depends on packaging<footnote>
					<para>SQLite relies on an additional package and driver (called libdbi 
						and libdbd-sqlite3, respectively), which are installed by 
						default on Mac OS and Windows. Linux users may need to manually 
						install these for SQLite.</para>
					<para>MySQL and PostgreSQL may require the installation of additional software drivers 
						(libdbd-mysql and libdbd-pgsql).</para>
					</footnote>
				</entry>
			</row>

			<row>
				<entry namest="c1item"                      >File extension</entry>
  				<entry align="center" namest="c2xml" nameend="c3sqlite"       > gnucash </entry>
  				<entry align="center" namest="c4mysql" nameend="c5pgsql" > N/A<footnote>
					<para>MySQL and PostgreSQL place data within their own storage system.</para></footnote></entry>
			</row>

			<row>
                <entry namest="c1item"                      >Additional software</entry>
  				<entry align="center" namest="c2xml" nameend="c3sqlite" > None </entry>
  				<entry align="center" namest="c4mysql"      > MySQL </entry>
  				<entry align="center" namest="c5pgsql" > PostgreSQL </entry>
			</row>

			<row>
                <entry namest="c1item"                      >Additional expertise</entry>
  				<entry align="center" namest="c2xml" nameend="c3sqlite"  > None </entry>
  				<entry align="center" namest="c4mysql" nameend="c5pgsql" > Database Administrator </entry>
			</row>

			<row>
                <entry namest="c1item"                      >Compression</entry>
  				<entry align="center" namest="c2xml"        > gzip </entry>
  				<entry align="center" namest="c3sqlite" nameend="c5pgsql" > N/A </entry>
			</row>

			<row>
                <entry namest="c1item"                      >File Save</entry>
  				<entry align="center" namest="c2xml"        > On command </entry>
  				<entry align="center" namest="c3sqlite" nameend="c5pgsql" > On commit </entry>
			</row>

			<row>
                <entry namest="c1item"                      >Multi-user</entry>
  				<entry align="center" namest="c2xml"        > No </entry>
  				<entry align="center" namest="c3sqlite"     > No </entry>
  				<entry align="center" namest="c4mysql"      > No </entry>
  				<entry align="center" namest="c5pgsql" > No </entry>
			</row>
			</tbody>
		</tgroup>
		</table>
	</sect2>

    <sect2 id="basics-create-data">
    <title>Creating a file</title>
    <para>To create a new &app; file do the following:</para>

    <orderedlist>
      <listitem>
        <para>From the &app; <emphasis>Menubar</emphasis>, choose <menuchoice><guimenu>File</guimenu>
        <guimenuitem>New File</guimenuitem></menuchoice>. The <guilabel>New Account Hierarchy setup</guilabel>
        assistant will start.</para>
        <note>
          <para>If you are running &app; for the first time, you will be presented
          with the <guilabel>Welcome to &appname;!</guilabel> screen. This screen is described in detail in the
          &app; manual.</para>
        </note>
      </listitem>

      <listitem>
        <para>Set your preferences in the assistant and move through the screens with the
        <guibutton>Forward</guibutton>, <guibutton>Cancel</guibutton> and <guibutton>Previous</guibutton>
        buttons.</para>
      </listitem>
    </orderedlist>

    </sect2>

    <sect2 id="basics-store-data">
    <title>Saving data</title>
    <para>Follow these steps to save the file under your preferred name:</para>

    <orderedlist>
      <listitem>
        <para>Choose <menuchoice><guimenu>File</guimenu> <guimenuitem>Save
        As...</guimenuitem></menuchoice> from the <emphasis>Menubar</emphasis> or select the
        <guibutton>Save</guibutton> <emphasis>Toolbar</emphasis> button. &app; will bring
        up the save window.</para>
      </listitem>

      <listitem>
        <para>Select the <guilabel>Data Format</guilabel> of the file you are saving from the
        drop down list. The default selection is <acronym>XML</acronym> but if you have set up a
        database back end you can change to that format.</para>
        <para>Depending on the selected <guilabel>Data Format</guilabel> the window can change as
        described in the following.</para>
      </listitem>

      <listitem>
      <para></para>
        <itemizedlist>
          <listitem>
            <para>If you selected <acronym>XML</acronym> or <acronym>sqlite3</acronym> you will see a screen like this:</para>

        <figure>
        <title>Save screen when <acronym>XML</acronym> or <acronym>sqlite3</acronym> is selected.</title>
        <screenshot id="basics-SaveXML">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_SaveXML.png" format="PNG"
                         srccredit="Cristian Marchi" width="510px"></imagedata>
            </imageobject>

            <imageobject role="fo">
              <imagedata fileref="figures/basics_SaveXML.png" format="PNG"
                         srccredit="Cristian Marchi"></imagedata>
            </imageobject>

            <textobject>
              <phrase>The Save screen</phrase>
            </textobject>

            <caption>
              <para>This image shows the <guilabel>Save</guilabel> screen when the selected
              <guilabel>Data Format</guilabel> is <acronym>XML</acronym> or <acronym>sqlite3</acronym>.</para>
            </caption>
          </mediaobject>
        </screenshot>
        </figure>

            <para>Type your chosen filename in the <guilabel>Name</guilabel> field. It is not necessary to specify an
            extension when you write the file name. &app; will automatically add the extension
            <filename>.gnucash</filename> to the file.</para>
            <note>
              <para>The <filename>.gnucash</filename> extension was introduced in the 2.3 series of &app;.
              For already existing files, the extension will never be changed. So if you open an existing file named
              <filename>Myoldfile</filename>, that name won&rsquo;t be changed if the file is saved. You might use the
              <guimenuitem>Save As...</guimenuitem> command and give the file a new name in order to have it saved with the
              extension <filename>.gnucash</filename>.</para>
            </note>
            <para>Select the path where the file will be saved by browsing the tree in the lower panes.</para>
            <tip>
              <para>Click on the <guibutton>Create Folder</guibutton> button to create a new folder with a
              custom name in the selected path.</para>
            </tip>
          </listitem>

          <listitem>
            <para>If you selected <acronym>mysql</acronym> or <acronym>postgres</acronym>
            <guilabel>Data Format</guilabel> you will see a screen like this:</para>

            <figure>
            <title>Save screen when <acronym>mysql</acronym> or <acronym>postgres</acronym> is selected.</title>
            <screenshot id="basics-SaveSQL">
              <mediaobject>
                <imageobject role="html">
                  <imagedata fileref="figures/basics_SaveSQL.png" format="PNG"
                             srccredit="Marchi Cristian" width="510px"></imagedata>
                </imageobject>

                <imageobject role="fo">
                  <imagedata fileref="figures/basics_SaveSQL.png" format="PNG"
                             srccredit="Cristian Marchi"></imagedata>
                </imageobject>

                <textobject>
                  <phrase>The Save screen</phrase>
                </textobject>

                <caption>
                  <para>This image shows the <guilabel>Save</guilabel> screen when the selected
                  <guilabel>Data Format</guilabel> is <acronym>mysql</acronym> or <acronym>postgres</acronym>.</para>
                </caption>
              </mediaobject>
            </screenshot>
            </figure>

            <para>Enter in this window the <guilabel>Database Connection</guilabel> information:
            <guilabel>Host</guilabel>, <guilabel>Database</guilabel>, <guilabel>Username</guilabel>
            and <guilabel>Password</guilabel>.</para>
            <warning>
              <para>Saving to <acronym>mysql</acronym> or <acronym>postgres</acronym> requires the proper permissions in that
              database, that is you need to have the permissions to create a new database with the given database name, or
              you need to have write access to an existing database with the given database name.</para>
            </warning>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>Click the <guibutton>Save As</guibutton> button to save the
        file.</para>
      </listitem>
    </orderedlist>

    <para>If you are keeping track of finances for a single household, you
    need only one file. But if you are also tracking business finances or want
    to keep data separate for some reason, then you will need more than one
    file.</para>

    <para>Before ending each &app; session, be sure to save your data
    changes using <menuchoice><guimenu>File</guimenu>
    <guimenuitem>Save</guimenuitem></menuchoice> or the <guibutton>Save</guibutton> <emphasis>Toolbar</emphasis>
    button.
    <note>
        <para>As it is very important to save your data frequently to avoid losing them for whatever reason,
        &app; is able to automatically save the opened file every a certain amount of time.
        This interval can be set in the <guilabel>General</guilabel> tab under
        <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>
        (<menuchoice><guimenu>GnuCash</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> on MacOS).
        Keep in mind that this option is relevant only if you are saving in <acronym>XML</acronym> format.
        If you are working with a database, the <guibutton>Save</guibutton> button and the <guimenuitem>Save</guimenuitem>
        menu entry will be grayed out because changes are stored right away.</para>
    </note>
    </para>
    </sect2>

    <sect2 id="basics-open-data">
    <title>Opening data</title>
    <para>To open an existing file or database, select <menuchoice><guimenu>File</guimenu>
    <guimenuitem>Open</guimenuitem></menuchoice> from the menu. In the window that will open,
    select the <guilabel>Data Format</guilabel>. If you selected <guilabel>File</guilabel> choose the file you want to open
    by browsing the folders in the lower panes. Else, enter the required <guilabel>Database Connection</guilabel>
    information.</para>
    <tip>
      <para>&app; keeps a list of the recently opened files. Open the <guilabel>File</guilabel>
      menu and you will see listed the names of recently opened files. Click on the one you want to load to open it.</para>
    </tip>
    </sect2>

    <sect2 id="basics-expt-acct">
    <title>Duplicating an Account Hierarchy</title>
    <para>In some cases, it might be useful to duplicate the structure of an existing data file in a new file.
    For example, you might want to try out new accounting techniques without corrupting your actual
    accounting data, or you might need to follow accounting guidelines that require you to close your books at the end
    of the year and begin each year with a fresh set of books.</para>

    <para>&app; allows you to create an empty copy of your Chart of Accounts simply by selecting
    <menuchoice><guimenu>File</guimenu><guisubmenu>Export</guisubmenu><guimenuitem>Export Accounts</guimenuitem></menuchoice>.
    When you select this command, you are asked to provide the name for the new empty file, and &app;
    creates a new data file that contains only your account hierarchy (that is, there is no transaction data).
    Once saved, the new file can be opened like any other &app; data file as described above.</para>
    </sect2>

  </sect1>

  <sect1 id="basics-backup1">
    <title>Backing Up and Recovering Data</title>

    <para>&app; creates several types of files to help ensure that your data
    is not lost. If you look in the folder where your saved file resides, you may see other
    files generated by &app; with the following extensions: <filename>.gnucash</filename>,
    <filename>.log</filename>, <filename>.LCK</filename>, <filename>.LNK</filename> in the same directory
    as your primary data file. What each of these files does is presented below.</para>

    <note>
    <para>The following sections are relevant only if you are saving your financial data in the <acronym>XML</acronym> format</para>
    </note>

    <programlisting>
      $ ls
      myfile.gnucash
      myfile.gnucash.20100414185747.gnucash
      myfile.gnucash.20100414223248.log
      myfile.gnucash.20100415114340.gnucash
      myfile.gnucash.20100415154508.log
      myfile.gnucash.20100415173322.gnucash
      myfile.gnucash.20100415194251.log
      myfile.gnucash.7f0982.12093.LNK
      myfile.gnucash.LCK
    </programlisting>

    <sect2 id="basics-backupxac2">
      <title>Backup file (.gnucash)</title>

      <para>Each time you save your data file, a backup copy will also be
      saved with the extension <filename>.YYYYMMDDHHMMSS.gnucash</filename>. This backup file is a complete copy of
      your previous data file, and the filename format refers to the data
      file, year, month, day and time of the backup. For example, the filename
      <filename>myfile.gnucash.20100414185747.gnucash</filename> indicates this is a
      backup copy of the file <filename>myfile</filename> saved in the year
      2010, April 14, at 6:57:47 p.m.</para>

      <para>To restore an old backup file, simply open the <filename>.YYYYMMDDHHMMSS.gnucash</filename> file with the
      date to which you wish to return. Be sure to save this file under a
      different name.</para>

      <note>
       <para>
         <filename>.YYYYMMDDHHMMSS.xac</filename> instead of the actual extension <filename>.YYYYMMDDHHMMSS.gnucash</filename>.
         So if you upgrade from the 2.2 series to the 2.4 series, you may end up with both <filename>.YYYYMMDDHHMMSS.xac</filename>
         and <filename>.YYYYMMDDHHMMSS.gnucash</filename> backup files in your directory.</para>
      </note>
    </sect2>

    <sect2 id="basics-backuplog2">
      <title>Log file (.log)</title>

      <para>Each time you open and edit a file in &app;,
      &app; creates a log file of changes you have made to your data file.
      The log file uses a similar naming format as the backup files:
      <filename>.YYYYMMDDHHMMSS.log</filename>. Log files
      are not a full backup of your data file - they simply record changes you
      have made to the data file in the current &app; session.</para>

      <para>In case you exit &app; inadvertently, possibly due to a power
      outage or a system wide crash, it is possible to recover most of your
      work since the last time you saved your &app; file using this log
      file. This is the procedure:</para>

      <orderedlist>
        <listitem>
          <para>Open the last saved &app; file.</para>
        </listitem>

        <listitem>
          <para>Go to <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
          <guimenuitem>Replay &appname; .log file</guimenuitem></menuchoice>
          and select the one .log file with the same date as the saved file
          you just opened. Make sure that you picked the right .log file, or
          you will possibly wreak havoc in your accounts.</para>
        </listitem>
      </orderedlist>

      <para>Log replaying will recover any transaction affecting the balance
      entered since the last save, including those created from scheduled
      transactions and business features (invoices, bills, etc.).</para>

      <warning>
        <para>Changes to the scheduled transactions, invoices or
        bills themselves are NOT recovered, and their transactions that were
        recovered may not be properly associated with them, and should thus be
        double-checked. Especially for business transactions, you may have to
        delete and re-create some of them. If you do not, although the balance
        will be correct, some reports may not.</para>
      </warning>
    </sect2>

    <sect2 id="basics-backuplock2">
      <title>Lock files (.LNK and .LCK)</title>

      <para>You may occasionally see <filename>.LNK</filename> and <filename>.LCK</filename> files appear. These do not
      store any data, but they are created to prevent more than one user from
      opening the same file at the same time. These files are automatically
      created when you open the file, to lock it so no one else can access it.
      When you close your &app; session or open another file, &app;
      unlocks the first data file by deleting the <filename>.LCK</filename> and <filename>.LNK</filename> files.</para>

      <para>If &app; crashes while you have a data file open, the <filename>.LCK</filename> and
      <filename>.LNK</filename> files are not deleted. The next time you try to open &app;, you
      will get a warning message that the file is locked. The warning message
      appears because the <filename>.LNK</filename> and <filename>.LCK</filename> files are still in your directory. It is
      safe to choose <guibutton>Yes</guibutton> to open the file, but you should delete the <filename>.LNK</filename> and
      <filename>.LCK</filename> files (using a terminal window or your file manager). Once those
      files are deleted, you will not get the warning message again unless
      &app; crashes.</para>
    </sect2>

    <sect2 id="basics-backupmanage2">
      <title>File Management</title>

      <para>So which files should you keep around? Keep your main data file,
      of course. It&rsquo;s a
      good idea to keep some of the more recent <filename>.YYYYMMDDHHMMSS.gnucash</filename> backup files, but you can safely
      delete the <filename>.log</filename> files since they are not complete copies of your data.</para>

      <note>
        <para>If you upgraded from a &app; version prior to 2.4, you may also have backup files
        in the old <filename>.xac</filename> format. For these files you can apply the same principle described above for
        <filename>.YYYYMMDDHHMMSS.gnucash</filename> backup files.</para>
      </note>

      <para>You should also delete any <filename>.LCK</filename> and <filename>.LNK</filename> files that you see after
      closing &app;. If you decide to back up your data file to another
      disk manually, it&rsquo;s enough to back up the main data file - not the <filename>.YYYYMMDDHHMMSS.gnucash</filename>
      backup files.</para>

      <note>
        <para>By default &app; will automatically delete any <filename>.log</filename> and <filename>.YYYYMMDDHHMMSS.gnucash</filename>
        backup files that are older than 30 days. You can change this behavior in the &app;
        preferences in the <guilabel>General</guilabel> tab under <menuchoice><guimenu>Edit</guimenu>
        <guimenuitem>Preferences</guimenuitem></menuchoice>
        (<menuchoice><guimenu>GnuCash</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> on MacOS).</para>
      </note>

    </sect2>
  </sect1>

  <sect1 id="basics-migrate-settings">
    <title>Migrating &app; data</title>
      <para>Sometimes you may need to move your financial data and &app; settings to another machine.
      Typical use cases are when you buy a new computer or if you want to use the same settings over two different operating
      systems in a dual boot configuration.</para>

   <sect2 id="migrate-financial">
     <title>Migrating financial data</title>
     <para>Migrating &app; financial data is a as simple as copying  <filename>.gnucash</filename>
     files with a file manager if you know where they are saved. If you can&rsquo;t remember where a file is stored
     but you can open it directly within &app;, save it in the desired path from within
     &app;.</para>

     <para>All other files in the folder are either backups or log files. It won&rsquo;t do any harm to copy them too, but it&rsquo;s not likely
     to do any good, either.</para>
   </sect2>

   <sect2 id="migrate-prefs">
     <title>Migrating preferences data</title>
     <para>Preferences are stored in three different locations: one for &app; preferences,
     one for reports, and one for online banking settings. Preferences are managed by
     <application>gsettings</application>, reports are managed by &app;
     itself, and online banking is managed by <application>aqbanking</application>. If you do not use online banking,
     then you will not have this folder on your machine.</para>
     <para>Where the &app; preferences are stored varies
     depending on your operating system (see <xref linkend="App-sett-loc" />, <xref linkend="Report-loc" />, and
     <xref linkend="OB-sett-loc" />). To back up and transfer your entire installation, you must copy
     these preferences as well.</para>


	<table id="App-sett-loc"><title>Application Settings Locations</title>
	<tgroup cols="2" align="left">
  	  <thead>
	    <row>
  		<entry>Operating system</entry>
		<entry>folder</entry>
	    </row>
	  </thead>
	  <tbody>
            <row>
     	      <entry>Unix</entry>
     	      <entry>&app; preferences are stored in <application>dconf</application>.
                  You can use the commands <command>dconf dump /org/gnucash/</command> on the old machine
                  and <command>dconf load /org/gnucash/</command> on the new machine to migrate your preferences.</entry>
            </row>
            <row>
              <entry>Mac OSX</entry>
              <entry><filename class="directory">~/Library/Preferences/gnucash.plist</filename></entry>
            </row>
            <row>
              <entry>Windows</entry>
              <entry>The preferences are stored in the Windows registry <filename class="directory">HKEY_CURRENT_USER/software/GSettings</filename></entry>
            </row>
	  </tbody>
	</tgroup>
	</table>

        <table id="Report-loc"><title>Saved Reports Locations</title>
	<tgroup cols="2" align="left">
  	  <thead>
	    <row>
  		<entry>Operating system</entry>
		<entry>folder</entry>
	    </row>
	  </thead>
	  <tbody>
            <row>
     	      <entry>Unix</entry>
              <entry><filename class="directory">&dir-data;</filename>
                <footnote><para>Up to &app; 2.6.21 it was <filename class="directory">&dir-old;</filename></para></footnote>
              </entry>
            </row>
            <row>
              <entry>Mac OSX</entry>
              <entry><filename class="directory">~/Library/Application Support/gnucash</filename></entry>
            </row>
            <row>
              <entry>Windows</entry>
              <entry><filename class="directory">Documents and Settings/Username/.gnucash</filename> or
                     <filename class="directory">Users/Username/.gnucash</filename></entry>
            </row>
	  </tbody>
	</tgroup>
	</table>


	<table id="OB-sett-loc"><title>Online Banking Settings Locations</title>
	<tgroup cols="2" align="left">
  	  <thead>
	    <row>
  		<entry>Operating system</entry>
		<entry>folder</entry>
	    </row>
	  </thead>
	  <tbody>
            <row>
     	      <entry>Unix</entry>
              <entry><filename class="directory">~/.aqbanking</filename></entry>
            </row>
            <row>
              <entry>Mac OSX</entry>
              <entry><filename class="directory">~/.aqbanking</filename></entry>
            </row>
            <row>
              <entry>Windows</entry>
              <entry><filename class="directory">Documents and Settings/Username/.aqbanking</filename></entry>
            </row>
	  </tbody>
	</tgroup>
	</table>

     <note>
       <para>On Unix and Mac OSX, these folders will generally not
       display in the file manager. You must set the file manager to show hidden files
       and folders to see them.</para>
     </note>

     <tip>
       <para>On Unix and Mac OSX, the <keycap>~</keycap> symbol means the
       <filename class="directory">home</filename> folder.</para>
     </tip>

   </sect2>

  </sect1>

  <sect1 id="basics-together1">
    <title>Putting It All Together</title>

    <note>
      <para>This section begins a tutorial that will continue throughout this
      book. At the end of each chapter, you will see a <guilabel>Putting It
      All Together</guilabel> section that walks you through examples to
      illustrate concepts discussed in that section. Each <guilabel>Putting It
      All Together</guilabel> section builds on the previous one, so be sure
      to save your file for easy access.</para>
    </note>

    <para>Let&rsquo;s get started!</para>

    <orderedlist>
      <listitem>
        <para>First, let&rsquo;s create a file to store your real data. Open &app;
        and select <menuchoice><guimenu>File</guimenu><guimenuitem>New File</guimenuitem></menuchoice>
        from the <emphasis>Menubar</emphasis>. This will start the <guilabel>New Account Hierarchy Setup</guilabel> assistant that allows
        you to create several accounts at once.</para>
        <note>
          <para>If you are running &app; for the first time, you will be presented with the
          <guilabel>Cannot find default values</guilabel> screen which is described in details in the
          &app; manual.</para>
        </note>

      <figure pgwide="1">
        <title>New Account Hierarchy Setup: Introduction</title>
        <screenshot id="basics-NewAccountHierarchySetup">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup.png"
                         format="PNG" srccredit="John Ralls" width="510"></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup.png"
                         format="PNG" srccredit="John Ralls" ></imagedata>
            </imageobject>
            <caption>
              <para>This image shows the first screen of the <guilabel>New
              Account Hierarchy Setup</guilabel> assistant.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>

      <para>The first screen of the assistant gives you a description of what the assistant does.
      Click the <guibutton>Forward</guibutton> button to proceed to the next screen.</para>
    </listitem>

    <listitem>
      <para>In the second screen, set the <guilabel>New Book Options</guilabel> on
        the different tabs, then press the <guibutton>Forward</guibutton> button.
        You can also update these options later using <menuchoice><guimenu>File
        </guimenu><guimenuitem>Properties</guimenuitem></menuchoice>.
        For details of these options, see the &app;
        Help manual, chapter Customizing GnuCash, Book Options.
      </para>

      <figure pgwide="1">
        <title>New Account Hierarchy Setup: Book Options</title>
        <screenshot id="basics-NewBookOptions">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_NewBookOpts.png"
                         format="PNG" srccredit="Frank H. Ellenberger" width="510"></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_NewBookOpts.png"
                         format="PNG" srccredit="Frank H. Ellenberger" ></imagedata>
            </imageobject>
            <caption>
              <para>This image shows the second screen of the <guilabel>New
              Account Hierarchy Setup</guilabel> assistant where you select the
              <guilabel>Book Options</guilabel>.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </listitem>

    <listitem>
      <para>In the third screen, select the currency to use for the new accounts from the dropdown list.
      Then press the <guibutton>Forward</guibutton> button.</para>
      <note>
        <para>The currency you select here, will be assigned to all the
        <guilabel>accounts</guilabel> created in this assistant.</para>
      </note>

      <figure pgwide="1">
        <title>New Account Hierarchy Setup: Currency Selection</title>
        <screenshot id="basics-NewAccountHierarchySetup-currency">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_currency.png"
                         format="PNG" srccredit="John Ralls" width="510"></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_currency.png"
                         format="PNG" srccredit="John Ralls" ></imagedata>
            </imageobject>
            <caption>
              <para>This image shows the third screen of the <guilabel>New
              Account Hierarchy Setup</guilabel> assistant where you select the
              <guilabel>Currency</guilabel>.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </listitem>

    <listitem>
      <para>In the fourth screen select the <guilabel>Common Accounts</guilabel> group in the
      <guilabel>Categories</guilabel> pane. Then press the <guibutton>Forward</guibutton> button to
      proceed.</para>
      <note>
        <para>If you want, you can select one or more of the predefined account-groups here. For more
        information on account types, see <xref linkend="accts-types1"></xref>.</para>
      </note>

      <figure pgwide="1">
        <title>New Account Hierarchy Setup: Account Selection</title>
        <screenshot id="basics-NewAccountHierarchySetup-Accounts">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_Accounts.png"
                         format="PNG" srccredit="John Ralls" width="510"></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_Accounts.png"
                         format="PNG" srccredit="John Ralls" ></imagedata>
            </imageobject>
            <caption>
              <para>This image shows the fourth screen of the <guilabel>New
              Account Hierarchy Setup</guilabel> assistant where you choose the
              various <guilabel>Accounts</guilabel>.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </listitem>

    <listitem>
      <para>In the fifth screen you will be able to set an <guilabel>Opening
      Balance</guilabel> on each of the accounts, as well as indicate if
      the account should be a <guilabel>Placeholder</guilabel>. As these features will be
      described in next chapters, leave all as configured by &app;
      and click <guibutton>Forward</guibutton> to open the last screen of the assistant.</para>

      <figure pgwide="1">
        <title>New Account Hierarchy Setup: Account Setup</title>
        <screenshot id="basics-NewAccountHierarchySetup-Setup.png">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_Setup.png"
                         format="PNG" srccredit="John Ralls" width="510"></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_Setup.png"
                         format="PNG" srccredit="John Ralls" ></imagedata>
            </imageobject>
            <caption>
              <para>This image shows the fifth screen of the <guilabel>New
              Account Hierarchy Setup</guilabel> assistant where you can set
              <guilabel>Opening Balance</guilabel>.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </listitem>

    <listitem>
      <para>In the last screen of the assistant, click <guibutton>Apply</guibutton> to create all the accounts and
      leave the assistant.</para>

      <figure pgwide="1">
        <title>New Account Hierarchy Setup: Finish</title>
        <screenshot id="basics-NewAccountHierarchySetup-Finish">
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_Finish.png"
                         format="PNG" srccredit="John Ralls" width="510"></imagedata>
            </imageobject>
            <imageobject role="fo">
              <imagedata fileref="figures/basics_NewAccountHierarchySetup_Finish.png"
                         format="PNG" srccredit="John Ralls" ></imagedata>
            </imageobject>
            <caption>
              <para>This image shows the last screen of the <guilabel>New
              Account Hierarchy Setup</guilabel> assistant.</para>
            </caption>
          </mediaobject>
        </screenshot>
      </figure>
    </listitem>

    <listitem>
      <para>After pressing <guibutton>Apply</guibutton> in the previous window, you will be
      presented with the save dialog. Select the <acronym>XML</acronym> <guilabel>Data Format</guilabel>,
      <guilabel>Name</guilabel> the file as <filename>gcashdata_1</filename>, select the folder where to
      save the file (remember it as the data file will be used in the tutorials throughout this manual),
      and finally press the <guibutton>Save as</guibutton> button.</para>

        <para>Your main window should now look something like this:</para>

      <figure pgwide="1">
        <title>Tutorial: Starting Account View of the Test File</title>
          <screenshot id="basics-EmptyAccounts">
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="figures/basics_EmptyAccounts.png"
                           format="PNG" srccredit="Frank H. Ellenberger" width="510"></imagedata>
              </imageobject>

              <imageobject role="fo">
                <imagedata fileref="figures/basics_EmptyAccounts.png"
                           format="PNG" srccredit="Frank H. Ellenberger" ></imagedata>
              </imageobject>
            </mediaobject>
          </screenshot>
      </figure>
    </listitem>
  </orderedlist>
</sect1>
<xi:include href="ch_accts.xml" />
<xi:include href="ch_txns.xml" />
</chapter>
