ch_basics.xml

<?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"
      xmlns:xi="http://www.w3.org/2001/XInclude">
  <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 accounting. 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>