gramps/gramps2/help/C/gramps-manual.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!--
	  User Manual for Gramps - a GTK+/GNOME based genealogy program

	  Copyright (C) 2003-2005  Alexander Roitman

	  This document is free software; you can redistribute it and/or modify
	  it under the terms of the GNU General Public License as published by
	  the Free Software Foundation; either version 2 of the License, or
	  (at your option) any later version.

	  This document is distributed in the hope that it will be useful,
	  but WITHOUT ANY WARRANTY; without even the implied warranty of
	  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	  GNU General Public License for more details.

	  You should have received a copy of the GNU General Public License
	  along with this program; if not, write to the Free Software
	  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-->
<book id="index" lang="en">
  <!-- please do not change the id; for translations, change lang to -->

  <!-- appropriate code -->

  <bookinfo>
    <title>GRAMPS Manual V3.0</title>

    <copyright>
      <year>2001</year>

      <holder>Donald N. Allingham</holder>
    </copyright>

    <copyright>
      <year>2003-2005</year>

      <holder>Alex Roitman</holder>
    </copyright>

    <!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

-->

    <!-- 
  An address can be added to the publisher information.  If a role is 
  not specified, the publisher/author is the same for all versions of the 
  document. 
 -->

    <publisher>
      <publishername>GRAMPS Project</publishername>
    </publisher>

    <legalnotice id="legalnotice">
      <para>This manual is free software; you can redistribute it and/or
      modify it under the terms of the GNU General Public License as published
      by the Free Software Foundation; either version 2 of the License, or (at
      your option) any later version.</para>

      <para>This manual is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
      Public License for more details.</para>

      <para>You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software Foundation,
      Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</para>
    </legalnotice>

    <!-- 
   This file  contains link to license for the documentation (GNU GPL), and 
   other legal stuff such as "NO WARRANTY" statement.  
-->

    <authorgroup>
      <author>
        <firstname>Alex</firstname>

        <surname>Roitman</surname>

        <affiliation>
          <orgname>GRAMPS Project</orgname>

          <address><email>shura@gramps-project.org</email></address>
        </affiliation>
      </author>

      <author>
        <firstname>Donald N.</firstname>

        <surname>Allingham</surname>

        <affiliation>
          <orgname>GRAMPS Project</orgname>

          <address><email>don@gramps-project.org</email></address>
        </affiliation>
      </author>

      <!-- This is appropriate place for other contributors: translators,
     maintainers,  etc. Commented out by default.
     
      <othercredit role="translator">
	<firstname>Latin</firstname> 
	<surname>Translator 1</surname> 
	<affiliation> 
	  <orgname>Latin Translation Team</orgname> 
	  <address> <email>translator@gnome.org</email> </address> 
	</affiliation>
	<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>

    <!-- According to GNU GPL, revision history is mandatory if you are -->

    <!-- modifying/reusing someone else's document.  If not, you can omit it. -->

    <!-- Remember to remove the &manrevision; entity from the revision entries other
-->

    <!-- than the current revision. -->

    <!-- The revision numbering system for GNOME manuals is as follows: -->

    <!-- * the revision number consists of two components -->

    <!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->

    <!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->

    <!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->

    <!-- is written in that desktop time frame is V2.0, the second version of the manual is V2.1, etc. -->

    <!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->

    <!-- to V3.0, and so on. -->

    <revhistory>
      <revision>
        <revnumber>GRAMPS Manual V3.0</revnumber>

        <date>July 2006</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS Manual V2.5</revnumber>

        <date>February 2004</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS Manual V2.4</revnumber>

        <date>December 2003</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS Manual V2.3</revnumber>

        <date>September 2003</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS Manual V2.2</revnumber>

        <date>July 2003</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="author">Donald A. Peterson
          <email>dpeterson@sigmaxi.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS Manual V2.1</revnumber>

        <date>May 2003</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS Manual V2.0</revnumber>

        <date>April 2003</date>

        <revdescription>
          <para role="author">Alex Roitman
          <email>shura@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>GRAMPS User Manual V1.1</revnumber>

        <date>2001</date>

        <revdescription>
          <para role="author">Donald N. Allingham
          <email>don@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>gramps User Manual V1.0</revnumber>

        <date>2001</date>

        <revdescription>
          <para role="author">Donald N. Allingham
          <email>don@gramps-project.org</email></para>

          <para role="publisher">GRAMPS Project</para>
        </revdescription>
      </revision>
    </revhistory>

    <releaseinfo>This manual describes version 2.2.0 of GRAMPS.</releaseinfo>
  </bookinfo>

  <preface id="gramps-preface">
    <title>Preface</title>

    <para>GRAMPS is a software package designed for genealogical research.
    Although similar to other genealogical programs, GRAMPS offers some unique
    and powerful features, which we'll discuss below.</para>

    <para>GRAMPS is a Open Source Software package, which means you are free
    to make copies and distribute it to anyone you like. It's developed and
    maintained by a worldwide team of volunteers whose goal is to make GRAMPS
    powerful, yet easy to use.</para>

    <sect1 id="why-gramps">
      <title>Why use GRAMPS?</title>

      <para>Most genealogy programs allow you to enter information about your
      ancestors and descendants. Typically, they can display family
      relationships through charts, graphs, or reports. Some allow you to
      include pictures or other media. Most let you include information about
      people even if those people are not related to the primary family you
      happen to be researching. And they may include features that let you
      exchange data with other programs and print different types of
      reports.</para>

      <para>GRAMPS has all these capabilities and more. Notably, it allows you
      to integrate bits and pieces of data as they arise from your research
      and to put them in one place -- your computer. You can then use your
      computer to manipulate, correlate, and analyze your data, rather than
      messing with reams of paper.</para>
    </sect1>

    <sect1 id="typography">
      <title>Typographical conventions</title>

      <para>In this book, some words are marked with special typography:
      <itemizedlist>
          <listitem>
            <simpara><application>Applications</application></simpara>
          </listitem>

          <listitem>
            <simpara><command>Commands</command> you type at the command
            line</simpara>
          </listitem>

          <listitem>
            <simpara><filename>Filenames</filename></simpara>
          </listitem>

          <listitem>
            <simpara><replaceable>Replaceable text</replaceable></simpara>
          </listitem>

          <listitem>
            <simpara><guilabel>Labels</guilabel> for buttons and other
            portions of the graphical interface</simpara>
          </listitem>

          <listitem>
            <simpara>Menu selections look like this: <menuchoice>
                <guimenu>Menu</guimenu>

                <guisubmenu>Submenu</guisubmenu>

                <guimenuitem>Menu Item</guimenuitem>
              </menuchoice></simpara>
          </listitem>

          <listitem>
            <simpara><guibutton>Buttons</guibutton> you can click</simpara>
          </listitem>

          <listitem>
            <simpara><userinput>Anything you type in</userinput></simpara>
          </listitem>
        </itemizedlist></para>

      <para>The manual also provides assorted bits of additional information
      in tips and notes, as follows. <tip id="example-tip">
          <title>Example Tip</title>

          <para>Tips and bits of extra information will look like this.</para>
        </tip> <note id="example-note">
          <title>Example Note</title>

          <para>Notes will look like this.</para>
        </note></para>

      <para>Finally, there are warnings, notifying you where you should be
      careful: <warning id="example-warning">
          <title>Example Warning</title>

          <para>This is what a warning looks like. If there's a chance you'll
          run into trouble, you will be warned beforehand.</para>
        </warning></para>
    </sect1>
  </preface>

  <chapter id="gramps-getting-started">
    <title>Getting Started</title>

    <para>In this chapter, we'll begin with the basics. We'll show you how to
    start GRAMPS and how to get help when you need it.</para>

    <sect1 id="gramps-start">
      <title>To Start GRAMPS</title>

      <para>You can start GRAMPS in the following ways:</para>

      <variablelist>
        <varlistentry>
          <term>From the <guimenu>Applications</guimenu> menu</term>

          <listitem>
            <para>Select GRAMPS from the list of programs displayed in your
            computer's Applications menu. (The location and appearance of this
            menu vary slightly from one distribution of Linux to another. On
            the default GNOME desktop, you'll find GRAMPS in the <menuchoice>
                <guimenu>Applications</guimenu>

                <guisubmenu>Other</guisubmenu>
              </menuchoice> menu.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>From the command line</term>

          <listitem>
            <para>If you're adept with Linux and like to work from the command
            line, you can start GRAMPS by calling up a terminal window, typing
            <command>gramps</command>, and then pressing
            <keycap>Enter</keycap>.</para>

            <para>If you would like GRAMPS to open a specific database or to
            import a specific file on startup, you can supply the filename as
            a command line argument:</para>

            <para><filename>gramps filename.grdb</filename></para>

            <para>where <filename>filename.grdb</filename> is the name of the
            file you want to open. The command line provides many more ways to
            start GRAMPS and perform different tasks.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <sect1 id="run-1st-time">
      <title>Running GRAMPS for the first time</title>

      <para>The first time you run the program, GRAMPS will display the
      "Getting Started" dialogs. Follow the directions that guide you through
      <guilabel>Researcher information</guilabel> and <guilabel>the LDS
      extensions</guilabel> sections. You should find them to be
      self-explanatory.</para>

      <note id="note-dialog">
        <title>Dialog boxes</title>

        <para>We'll make frequent reference in this manual to dialogs. A
        dialog is simply a pop-up window into which you can enter
        information.</para>
      </note>

      <para>We recommend you enter your personal information when GRAMPS
      prompts you for it. GRAMPS uses this information strictly so it can
      create valid GEDCOM output files (which require information about the
      files' creator). If you wish, you can choose not to supply this
      information, but be aware that unless and until you do, any GEDCOM files
      you export will not be valid.</para>

      <figure id="druid-fig">
        <title>GRAMPS Getting Started Window: Researcher Information</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/researcher.png" format="PNG" />
            </imageobject>

            <textobject>
              <phrase>Shows Researcher Information Window.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

      <tip id="preferences-tip">
        <title>Entering personal information</title>

        <para>This information can be entered at any time in the Preferences
        dialog, under the Database/Researcher Information category.</para>
      </tip>
    </sect1>

    <!---->

    <sect1 id="choose-db-start">
      <title>Choosing a database</title>

      <para>If GRAMPS is started without a database selected, the initial
      screen will have little functionality. Most operations will not be
      available. To load a database, select either <guibutton>New</guibutton>
      to create a new database, or <guibutton>Open</guibutton> to open an
      existing database. GRAMPS keeps track of your recently opened databases,
      and these can be selected by clicking on the arrow next to the
      <guibutton>Open</guibutton> button and choosing from the drop down
      menu.</para>

      <figure id="first-open">
        <title>Initial Window</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/first-open.png" format="PNG" />
            </imageobject>

            <textobject>
              <phrase>Initial Window.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

      <!---->
    </sect1>

    <sect1 id="get-help">
      <title>Obtaining Help</title>

      <para>GRAMPS has a <menuchoice>
          <guimenu>Help</guimenu>
        </menuchoice> menu that you can consult at any time. It includes the
      following items:</para>

      <variablelist>
        <varlistentry>
          <term>User manual</term>

          <listitem>
            <para>An electronic version of the manual that you can access
            while you work in GRAMPS.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>FAQ</term>

          <listitem>
            <para>A list of Frequently Asked Questions about GRAMPS.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>GRAMPS home page</term>

          <listitem>
            <para>A link to the GRAMPS' project web site.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>GRAMPS mailing lists</term>

          <listitem>
            <para>Gives you direct access to GRAMPS' mailing list
            archives.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Report a bug</term>

          <listitem>
            <para>Choose this item to file a bug report in our bug tracking
            system. (Remember, GRAMPS is a living project. We want to know
            about any problems you encounter so we can work to solve them for
            everyone's benefit.)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Show plugin status</term>

          <listitem>
            <para>Use this item to display the status of any plugins you may
            have added.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Open example database</term>

          <listitem>
            <para>Select this item to load the example database that is
            included in your GRAMPS package. This database is composed of
            fictitious people and serves as a useful example for learning how
            to work with GRAMPS.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>
  </chapter>

  <chapter id="gramps-mainwin">
    <title>Main Window</title>

    <para>When you open a database (either existing or new), the following
    window is displayed:</para>

    <!-- ==== Figure: Main Window  ==== -->

    <figure id="mainwin-fig" pgwide="1">
      <title>GRAMPS Main Window</title>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata depth="" fileref="figures/mainwin.png" format="PNG"
                       scale="100" width="" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>

    <!-- ==== End of Figure ==== -->

    <para>The main GRAMPS window contains the following elements:</para>

    <variablelist>
      <varlistentry>
        <term>Menubar</term>

        <listitem>
          <para>The menubar is located at the very top of the window (right
          below the window title) and provides access to all the features of
          GRAMPS.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Toolbar</term>

        <listitem>
          <para>The toolbar is located right below the menubar. It gives you
          access to the most frequently used functions of GRAMPS. You can set
          options that control how it appears by going to <menuchoice>
              <guimenu>Edit</guimenu>

              <guisubmenu>Preferences</guisubmenu>
            </menuchoice>. You can also hide it entirely by going to
          <menuchoice>
              <guimenu>View</guimenu>

              <guisubmenu>Toolbar</guisubmenu>
            </menuchoice>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Progress Bar</term>

        <listitem>
          <para>The Progress Bar is located in the lower left corner of the
          GRAMPS window. It displays the progress of time consuming
          operations, such as opening and saving large data bases, importing
          and exporting to other formats, generating web sites, etc. When you
          are not doing these types of operations, the Progress Bar is
          blank.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Status Bar</term>

        <listitem>
          <para>The Status Bar is located to the right of the Progress Bar, on
          the very bottom of the GRAMPS window. It displays information about
          current GRAMPS activity and contextual information about the
          selected items. The behavior of the Status Bar can be adjusted in
          the Preferences dialog, which can be found by selecting <menuchoice>
              <guimenu>Edit</guimenu>

              <guisubmenu>Preferences</guisubmenu>
            </menuchoice>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Display area</term>

        <listitem>
          <para>The largest area in the center of the GRAMPS window is the
          display area. What it displays depends on the currently selected
          View. We'll discuss Views in detail below.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <!-- ================ Main Window Subsection  -->

    <sect1 id="gramps-views">
      <title>Views</title>

      <para>Genealogical information is very broad and can be extremely
      detailed. Displaying it poses a challenge that GRAMPS takes on by
      dividing and organizing the information into a series of Views. Each
      View displays a portion of the total information, selected according to
      a particular category. This will become clearer as we explore the nine
      different Views, listed below:</para>

      <itemizedlist>
        <listitem>
          <para>People</para>

          <para>Displays the list of all people in the database</para>
        </listitem>

        <listitem>
          <para>Relationships</para>

          <para>Shows the relationships between the selected person and other
          people. This includes parents, spouses, and children</para>
        </listitem>

        <listitem>
          <para>Family List</para>

          <para>Shows the list of all families in the database</para>
        </listitem>

        <listitem>
          <para>Pedigree View</para>

          <para>Displays a graphical ancestor tree for the selected
          person</para>
        </listitem>

        <listitem>
          <para>Events</para>

          <para>Displays the list of all events in the database</para>
        </listitem>

        <listitem>
          <para>Sources View</para>

          <para>Displays the list of all sources in the database</para>
        </listitem>

        <listitem>
          <para>Places View</para>

          <para>Displays the list of all places in the database</para>
        </listitem>

        <listitem>
          <para>Media View</para>

          <para>Displays the list of all media objects in the database</para>
        </listitem>

        <listitem>
          <para>Repositories</para>

          <para>Displays the list of all repositories in the database.</para>
        </listitem>
      </itemizedlist>

      <para>Before we launch into a description of each View, let's first
      explain how to switch between Views.</para>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="view-modes">
        <title>Switching Views and Viewing Modes</title>

        <para>As mentioned above there are six different Views. In addition,
        there are two different Viewing Modes. You can tell at a glance which
        Viewing Mode you are in: If you see icons listed vertically in a
        sidebar at the left of the window, you are in the Sidebar Viewing
        Mode. If instead you see a series of "notebook tabs" (labeled People,
        Family, Pedigree, Sources, Places, Media) that run horizontally across
        the window, then you are in the Tabbed Viewing Mode. You can switch
        from one Viewing Mode to another by selecting <menuchoice>
            <guimenu>View</guimenu>

            <guimenuitem>Sidebar</guimenuitem>
          </menuchoice> from the Sidebar menu item.</para>

        <para>If you're in the Sidebar Viewing Mode, you can select the View
        you want by clicking one of the sidebar icons.</para>

        <!-- ==== Figure: Sidebar Mode ==== -->

        <figure id="side-nofilt-fig">
          <title>Sidebar Viewing Mode</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/mainwin.png" format="PNG"
                           scale="100" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows sidebar viewing mode.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>If you're in the Tabbed Viewing Mode, you can select the View
        you want by clicking the corresponding notebook tab.</para>

        <!-- ==== Figure: Tabbed Notebook Mode ==== -->

        <figure id="noside-nofilt-fig">
          <title>Tabbed Viewing Mode</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/noside-nofilt.png"
                           format="PNG" scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows tabbed viewing mode.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->
      </sect2>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="people-view">
        <title>People View</title>

        <para>When GRAMPS first opens a database, it displays the People View
        (<xref linkend="side-nofilt-fig" /> and <xref
        linkend="noside-nofilt-fig" />). This view lists all the people stored
        in the database.</para>

        <para>You'll note that people are grouped according to their family
        names. To the left of each family name is an arrow. Clicking it once
        will reveal the entire list of people sharing that name. Clicking the
        arrow again will "roll up" the list and show only the family
        name.</para>

        <para>By default, the People View, displays the following columns:
        <guilabel>Names</guilabel>, GRAMPS <guilabel>ID</guilabel> numbers,
        <guilabel>Gender</guilabel>, and their <guilabel>Birth</guilabel> and
        <guilabel>Death dates</guilabel>. You can add or remove columns to and
        from the display by calling up the <guilabel>Column Editor</guilabel>
        dialog (<menuchoice>
            <guimenu>Edit</guimenu>

            <guimenuitem>Column Editor</guimenuitem>
          </menuchoice>) and checking or unchecking the boxes listed. You can
        also change the position of a column in People View by clicking and
        dragging it to a new position in the Editor. Once you have made the
        changes you want, click <guibutton>OK</guibutton> to exit the Editor
        and see your changes in the People View.</para>

        <note id="columns-tip">
          <title>Column Editor</title>

          <para>The Column Editor is available in all Views and works the same
          way in each.</para>
        </note>

        <!-- ==== Figure: Enabled Filter ==== -->

        <figure id="column-editor-fig">
          <title>Column Editor Dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/column-editor.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows column editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ================ Main Window Sub-sub-subsection  -->

        <sect3 id="filters">
          <title>Filters</title>

          <para>Genealogical databases can contain information on many people,
          families, places, and objects. It's therefore possible for a View to
          contain a long list of data that's difficult to work with. GRAMPS
          gives you two different means for controlling this condition by
          allowing you to filter a list to a more manageable size. These
          methods are Search and Filtering.</para>

          <para>Search is a simple but fast method of searching the columns
          displayed on the screen. Typing the characters into the Search box
          and clicking the Find button will display only lines that match the
          text.</para>

          <para>Alternatively, you can enable the Filter sidebar, which will
          be displayed on the right hand side of the display. When the filter
          sidebar is displayed, the Search bar is not displayed. The Filter
          side bar allows you to interactive build a set of filter rules that
          can be applied to the display. The filter is applied based on the
          rules and the data, not on the screen display.</para>

          <!-- ==== Figure: Enabled Filter ==== -->

          <figure id="side-filt-fig">
            <title>Filter Controls Displayed</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata depth="" fileref="figures/side-filt.png"
                             format="PNG" scale="" width="" />
                </imageobject>

                <textobject>
                  <phrase>Shows filter controls.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>

          <!-- ==== End of Figure ==== -->

          <para>When GRAMPS opens a database, no filtering is in effect. In
          People View, for example, all people in the database are listed by
          default.</para>
        </sect3>
      </sect2>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="relationships-view">
        <title>Relationships View</title>

        <para>The Relationships View displays the family relationships of a
        selected person that we call the Active person. Specifically, it shows
        his or her parents, spouses, and children.</para>

        <para>The Relationships View is designed to allow for quick
        navigation. You can quickly change the selected person simply by
        clicking the name of any person listed on the page. Each name is
        actually a hypertext link, similar to a web page.</para>

        <!-- ==== Figure: Family View ==== -->

        <figure id="family-fig">
          <title>Relationsihps View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/family.png" format="PNG"
                           scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Relationships View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The Relationships View displays the following sections:</para>

        <variablelist>
          <varlistentry>
            <term>Active person</term>

            <listitem>
              <para>At the top of the screen, name, ID, birth, and death
              information of the active person is displayed. If a photo of the
              person is available, it is show on the right hand side. Next to
              the person's name is a symbol indicating gender, and an Edit
              button. Clicking the <guibutton>Edit</guibutton> button will
              allow you to edit all of the person's individual information in
              an Edit Person dialog.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Parents</term>

            <listitem>
              <para>The next sections display the person's parents and
              siblings. Since it is possible to have multiple sets of parents,
              it is possible to have several Parents sections. You can control
              how much information is displayed by using the
              <guimenu>View</guimenu> menu. The view menu allows you to show
              or hide details (the birth and death information) and to show or
              hide siblings. Next to each person listed is an
              <guibutton>Edit</guibutton> button, which will allow you to edit
              all the details of that particular person.</para>

              <para>You may add, edit, or delete family information using the
              buttons next to the Parents label. You can add a set of parents
              by either selecting the Add button (the first button) or the
              <guibutton>Select</guibutton> button (the second button). The
              <guibutton>Add</guibutton> button will create a new family with
              the active person listed as a child. The
              <guibutton>Select</guibutton> button will allow you to choose
              from a list of existing families, and then add the person as a
              child to that family.</para>

              <warning>
                <para>If you are not careful, it is possible to create
                multiple families with the same parents. This is rarely what
                the user wants to do. If you attempt to add a new family that
                has the same parents as an existing family, GRAMPS will issue
                a warning dialog. If you get this dialog, you should probably
                Cancel the edit, and then use the
                <guibutton>Select</guibutton> button to select the existing
                family.</para>
              </warning>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Family</term>

            <listitem>
              <para>Similar to the Parents section is the Family section,
              which displays families where the person is a parent. Because it
              is possible to have mulitple familes, it is possible to have
              multiple Family sections. Each family section displays the
              spouse and any children.</para>

              <note>
                <para>We use the term <emphasis>spouse</emphasis> for sake of
                simplicity. However, please note that
                <emphasis>spouse</emphasis> may in fact be a domestic partner,
                a partner in a civil union, or various other similar
                relationships between two people. <emphasis>Spouse</emphasis>
                relationships are not required to be only between a male and
                female.</para>
              </note>

              <para>You may add, edit, or delete family information using the
              buttons next to the Family label. You can add a spouse by
              clicking the Add button (the first button), which will create a
              new family with the active person listed as a father or mother.
              Selecting the Edit button will allow you to edit the displayed
              family. Clicking the Delete button will remove the person from
              the displayed family.</para>

              <warning>
                <para>Removing a person from a family does not delete the
                family. The person is removed as the father or mother, and any
                other relationships in the family continue to exist.</para>
              </warning>

              <note>
                <para>We use the terms <emphasis>father</emphasis> and
                <emphasis>mother</emphasis> for the sake of simplicity. Even
                if there are no children in a family, the
                <emphasis>father</emphasis> and <emphasis>mother</emphasis>
                terminology is still used. In the case of male/male or
                female/female relationships, one of the
                <emphasis>father</emphasis> and <emphasis>mother</emphasis>
                labels should be considered to be convience labels, and should
                be considered as interchangable.</para>
              </note>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="family-list-view">
        <title>Family List View</title>

        <para>The Family List View displays a list of all families in the
        database. From this view, you may add, edit, or delete families. The
        default display lists the ID, Father, Mother, and Relationship.
        Children cannot be displayed on the screen in this view.</para>

        <!-- ==== Figure: Family View ==== -->

        <figure id="family-list">
          <title>Family List View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/family-list.png"
                           format="PNG" scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Family List View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <warning>
          <para>Unlike the Relationships View, clicking the Remove button in
          this view will remove the family from the database. All people will
          remain, but all relationships between the people in the family will
          be removed.</para>
        </warning>

        <!-- ==== End of Figure ==== -->
      </sect2>

      <sect2 id="pedigree-view">
        <title>Pedigree View</title>

        <para>The Pedigree View displays a family tree of the Active person's
        ancestors. The Pedigree View shows up to four generations, depending
        on the size of the window. Each person is indicated by a box labeled
        with his or her name, birth and death information, and optionally an
        image if available. Two lines branch from each box. The top one shows
        the person's father and the bottom one the mother. Solid lines
        represent birth relations, while dashed lines represent non-birth
        relations such as adoption, step-parenthood, guardianship, etc.</para>

        <!-- ==== Figure: Pedigree View ==== -->

        <figure id="pedigree-fig">
          <title>Pedigree View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/pedigree.png"
                           format="PNG" scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Pedigree View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>To the left of the Active person is a left arrow button. If the
        Active person has children, clicking this button expands a list of the
        Active person's children. Selecting one of the children makes that
        child the active Person.</para>

        <para>The appearance of the children's names in the menu
        differentiates the <emphasis>dead ends</emphasis> of the tree from the
        continuing branches. Children who have children themselves appear in
        the menu in the boldface and italic type, while children without
        children (<emphasis>dead ends</emphasis>) appear in a regular font. If
        the Active person has only one child, no menu will be displayed (since
        there is only one choice) and the child will become the Active person
        when the arrow button is clicked.</para>

        <!-- ==== Figure: Pedigree View ==== -->

        <figure id="pedigree-child-cut-fig">
          <title>Children Menu</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/pedigree-child-cut.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Children Menu in Pedigree View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The right-hand side of the window shows two right arrow buttons.
        When the top button is clicked, the Father of the Active person
        becomes the Active person. Clicking the bottom button makes the Mother
        of the Active person the Active person.</para>

        <!-- ==== Figure: Pedigree View ==== -->

        <figure id="pedigree-siblings-cut-fig">
          <title>Personal Context Menu</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth=""
                           fileref="figures/pedigree-siblings-cut.png"
                           format="PNG" scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Context Menu in Pedigree View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>Right-clicking on any person's box in the Pedigree View will
        bring up the "context menu". Among other useful items, the context
        menu has sub-menus listing <guilabel>Spouses</guilabel>,
        <guilabel>Siblings</guilabel>, <guilabel>Children</guilabel>, and
        <guilabel>Parents</guilabel> of that person. "Greyed-out" sub-menus
        indicate the absence of the data in the appropriate category.
        Similarly to the children menu above, Childrens' and Parents' menus
        distinguish continuing lines from dead ends.</para>
      </sect2>

      <sect2>
        <title>Events View</title>

        <para>New in version 2.2 is the inclusion of an Events View. Events
        can be shared between between multiple people and multiple families.
        The Events View lists the all the events recorded in the database. The
        default view displays the <guilabel>Description</guilabel>,
        <guilabel>ID</guilabel>, <guilabel>Type</guilabel>,
        <guilabel>Date</guilabel>, <guilabel>Place</guilabel> and
        <guilabel>Cause</guilabel> of the event.</para>

        <figure id="events-fig">
          <title>Events View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/events.png" format="PNG"
                           scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Events View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <warning>
          <para>Because events can be shared, you should take the extra time
          to give each event a unique and meaningful description. This will
          help you find the correct event if you decide to share
          events.</para>
        </warning>

        <para>The list of Events can be sorted in the usual manner, by
        clicking on the column heading. Clcking once sorts in ascending order,
        clicking again sorts in descending order. The <guilabel>Column
        Editor</guilabel> dialog can be used to add, remove and rearrange the
        displayed columns.</para>
      </sect2>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="sources-view">
        <title>Sources View</title>

        <para>Sources View lists the sources of certain information stored in
        the database. These can include various documents (birth, death, and
        marriage certificates, etc.), books, films, journals, private diaries,
        - nearly anything that can provide genealogical evidence. GRAMPS gives
        you the option to provide a source for each event you record (births,
        deaths, marriages, etc.). The Source View lists the
        <guilabel>Title</guilabel>, <guilabel>ID</guilabel>, and
        <guilabel>Author</guilabel> of the source, as well as any
        <guilabel>Publication</guilabel> information that may be associated
        with it.</para>

        <para>The list of Sources can be sorted in the usual manner, by
        clicking on a column heading. Clicking once sorts in ascending order,
        clicking again sorts in descending order. The <guilabel>Column
        Editor</guilabel> dialog can be used to add, remove and rearrange the
        displayed columns.</para>

        <!-- ==== Figure: Sources View ==== -->

        <figure id="sources-fig">
          <title>Sources View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/sources.png" format="PNG"
                           scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Sources View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->
      </sect2>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="places-view">
        <title>Places View</title>

        <para>The Places View lists the geographical places in which the
        events of the database took place. These could be places of birth,
        death, and marriages of people, as well as their home, employment,
        education addresses, or any other conceivable reference to the
        geographical location. The Places View lists the places'
        <guilabel>Name</guilabel>, <guilabel>ID</guilabel>, <guilabel>Church
        Parish</guilabel>, <guilabel>City</guilabel>,
        <guilabel>County</guilabel>, <guilabel>State</guilabel>, and
        <guilabel>Country</guilabel>. All of these columns can be used for
        sorting by the usual sorting rules. The <guilabel>Column
        Editor</guilabel> dialog may be used to add, remove and rearrange the
        displayed columns.</para>

        <para>If a place has been highlighted, you may select the
        <guibutton>Google Maps</guibutton> button to attempt to display the
        place in a web browser. Your default web browser should open,
        attempting to use either the longitude and lattitude coordinates or
        the place name to display the location using the Google Maps web site.
        This feature is limited, and may not always produce the results you
        desire.</para>

        <!-- ==== Figure: Places View ==== -->

        <figure id="places-fig">
          <title>Places View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/places.png" format="PNG"
                           scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Places View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->
      </sect2>

      <!-- ================ Main Window Sub-subsection  -->

      <sect2 id="media-view">
        <title>Media View</title>

        <para>The Media View is a list of Media Objects used in the database.
        Media Objects are any files that relate somehow to the stored
        genealogical data. Technically, any file can be stored as a Media
        Object. Most frequently, these are images, audio files, animation
        files, etc. The list box on the bottom lists the
        <guilabel>Name</guilabel>, <guilabel>ID</guilabel>,
        <guilabel>Type</guilabel>, and <guilabel>Path</guilabel> of the Media
        Object. The <guilabel>Column Editor</guilabel> dialog may be used to
        rearrange the displayed columns, which obey usual sorting rules. The
        top part of the GRAMPS window shows a preview (if available) and
        information about the Media Object.</para>

        <!-- ==== Figure: Media View ==== -->

        <figure id="media-fig">
          <title>Media View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/media.png" format="PNG"
                           scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Media View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->
      </sect2>

      <sect2>
        <title>Repositories View</title>

        <para>Version 2.2 adds support for Repositories. A repository can be
        thought of as a collection of sources. Each source in the database can
        reference a repository (such as a library) in which it belongs. The
        functionality of the Repositories View is similar to the other
        views.</para>

        <figure id="repository-fig">
          <title>Repositories View</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/repository.png"
                           format="PNG" scale="" width="" />
              </imageobject>

              <textobject>
                <phrase>Repositories View.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="gramps-usage">
    <title>Usage</title>

    <para>Now we turn to a detailed exploration of the day-to-day use of
    GRAMPS. First, we should point out that GRAMPS often offers more than one
    way to do the same task. We'll try to point out some of these alternatives
    where appropriate.</para>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="new-db">
      <title>Starting a New Database</title>

      <para>To start a new database, choose <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>New</guimenuitem>
        </menuchoice> or select the <guibutton>New</guibutton> button from the
      toolbar. You will then be asked to give the new database a name.</para>

      <note id="new-db-notdir-note">
        <title>GRAMPS databases</title>

        <para>GRAMPS stores your data in a Berkeley database, sometimes known
        as BSDDB. These files have ".grdb" as their default extension. The
        extension is automatically added to your filename.</para>
      </note>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="open-db">
      <title>Opening a Database</title>

      <para>To open a database, either choose <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Open</guimenuitem>
        </menuchoice> or click the <guibutton>Open</guibutton> button on the
      Toolbar. The <guilabel>Open database</guilabel> dialog will appear and
      you'll see a list of files. If you don't see the file you're looking
      for, make sure the All files filter is selected. (This dialog has a
      "filetype" filter, meaning it may only be showing files that have a
      certain extension.)</para>

      <para>To open a recently accessed database, choose either <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Open Recent</guimenuitem>
        </menuchoice> or the down arrow next to the
      <guibutton>Open</guibutton> button and select the filename from the
      list.</para>

      <para>If you do not have "write permissions" for the selected database,
      it will be opened in a Read Only mode. In this mode, the data may be
      viewed, but no changes will be made to the database. To indicate this
      mode, the title of the main window will be appended with <guilabel>(Read
      Only)</guilabel> text.</para>

      <para>GRAMPS allows you to open certain databases that have not been
      saved in GRAMPS' own file format. These include XML and GEDCOM
      databases. But you should be aware that if the XML or GEDCOM database is
      relatively large, you may encounter some performance problems. These can
      be avoided by creating a new GRAMPS database and importing your
      XML/GEDCOM data into it.</para>

      <note id="open-db-note2">
        <title>Opening XML and GEDCOM databases</title>

        <para>XML and GEDCOM databases require all data to be held in memory.
        GRAMPS' native grdb format does not. Thus, a database with a grdb
        format can access data quicker and more efficiently.</para>
      </note>

      <warning id="open-db-warn">
        <title>GEDCOM Editing</title>

        <para>Please keep in mind that some information in a GEDCOM file may
        be lost during import into GRAMPS. Simply opening and viewing the file
        will not change it. However, if any changes were made and they were
        not abandoned upon exit, exiting GRAMPS will save the data, with
        possible data loss.</para>
      </warning>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="save-db">
      <title>Saving Changes to Your Database</title>

      <para>GRAMPS saves your changes as soon as you apply them. This means,
      for example, that any time you click <guibutton>OK</guibutton> when
      using GRAMPS, your changes are immediately recorded and saved. There is
      no separate "save" command (although there is a "save as" command that
      we'll discuss later.)</para>

      <para>You can undo changes you've made by selecting <menuchoice>
          <guimenu>Edit</guimenu>

          <guimenuitem>Undo</guimenuitem>
        </menuchoice>. If you select this command repeatedly, your most recent
      changes will be undone one at a time. To roll back multple commands at a
      time, you can using the <guilabel>Undo History</guilabel> dialog
      available from the <guilabel>Edit</guilabel> menu.</para>

      <para>If you want to return your database to the way it was when you
      opened it, select <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Abandon changes and quit</guimenuitem>
        </menuchoice>. (This is just like quitting without saving in other
      programs.)</para>

      <para>If you would like to save your database under a different name,
      you can do so by choosing <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Save as...</guimenuitem>
        </menuchoice> and specifying the name (and, optionally, the format) of
      your new database. Note that "Save as" will allow you to continue
      editing the newly saved database. If this is not what you want to do,
      you may wish to use the "Export" command instead.</para>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="import-data">
      <title>Importing Data</title>

      <para>Importing allows you to bring data from other genealogy programs
      into a GRAMPS database. Currently, GRAMPS can import data from the
      following formats:</para>

      <itemizedlist>
        <listitem>
          <para>Another GRAMPS database (having the "grdb" file
          extension),</para>
        </listitem>

        <listitem>
          <para>GEDCOM</para>
        </listitem>

        <listitem>
          <para>GRAMPS XML</para>
        </listitem>

        <listitem>
          <para>GRAMPS package</para>
        </listitem>

        <listitem>
          <para>GeneWeb</para>
        </listitem>
      </itemizedlist>

      <note id="import-note">
        <title>Importing vs. opening</title>

        <para>Please recognize that importing a database is different from
        opening a database. When you import, you are actually bringing data
        from one database into a GRAMPS database. When you open a file, you
        are editing your original file.</para>
      </note>

      <para>To import data, select <menuchoice>
          <guimenu>File</guimenu>

          <guisubmenu>Import</guisubmenu>
        </menuchoice>. The <guilabel>Import database</guilabel> dialog will
      open, asking you to specify the file you wish to import.</para>

      <warning id="import-dataloss">
        <title>Data loss with some formats</title>

        <para>It is important to note that the importing process is not
        perfect for GEDCOM and GeneWeb databases. There is a chance that some
        of the data in these databases will not be imported into
        GRAMPS.</para>
      </warning>

      <para>The GRAMPS database (grdb), GRAMPS XML, and GRAMPS package are all
      native GRAMPS formats. There is no risk of information loss when import
      or exporting to these formats.</para>

      <variablelist>
        <varlistentry>
          <term>GRAMPS database (grdb)</term>

          <listitem>
            <para>The native GRAMPS database format is a specific form of
            Berkeley database (BSDDB) with a special structure of data tables.
            This format is binary and architecture-dependent. It is very quick
            and efficient, but not generally portable across computers with
            different binary architecture (e.g. i386 vs alpha).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>GRAMPS XML</term>

          <listitem>
            <para>The GRAMPS XML file was the default format for older
            versions of GRAMPS. Unlike the grdb format, it is architecture
            independent and human-readable. The database may also have
            references to non-local (external) media objects, therefore it is
            not guaranteed to be completely portable. The GRAMPS XML database
            is created by saving ( <menuchoice>
                <guimenu>File</guimenu>

                <guimenuitem>Save As...</guimenuitem>
              </menuchoice> ) or exporting ( <menuchoice>
                <guimenu>File</guimenu>

                <guimenuitem>Export...</guimenuitem>
              </menuchoice> ) data in that format</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>GRAMPS package</term>

          <listitem>
            <para>The GRAMPS package is a compressed archive containing the
            GRAMPS XML file and all media objects (images, sound files, etc.)
            to which the database refers. Because it contains all the media
            objects, this format is completely portable. The GRAMPS package is
            created by exporting ( <menuchoice>
                <guimenu>File</guimenu>

                <guimenuitem>Export...</guimenuitem>
              </menuchoice> ) data in that format.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>If you import information from another GRAMPS database or GRAMPS
      XML database, you will see the progress of the operation in the progress
      bar of GRAMPS' main window.</para>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="export-data">
      <title>Exporting Data</title>

      <para>Exporting allows you to share any portion of your GRAMPS database
      with other researchers as well as to enable you to transfer your data to
      another computer. Currently, GRAMPS can export data to the following
      formats: GRAMPS database (grdb), GRAMPS XML, GEDCOM, GRAMPS package, Web
      Family Tree, and GeneWeb.</para>

      <note id="export-note">
        <title>Export is saving a copy</title>

        <para>When you export, you are saving a copy of the currently opened
        database. Exporting creates another file with a copy of your data.
        Note that the database that remains opened in your GRAMPS window is
        NOT the file saved by your export. Additional editing of the currently
        opened database will not alter the copy produced by the export.</para>
      </note>

      <para>To export data, choose <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Export</guimenuitem>
        </menuchoice>. This will bring up the <guilabel>Export</guilabel>
      assistant. Its pages will guide you through the format selection (see
      <xref linkend="export-druid-fig" />), file selection, and format
      specific export options (see <xref linkend="gedcom-export-fig" />).
      After a final confirmation page, the export will be performed according
      to the choices you have made. At any time, you can click the
      <guibutton>Back</guibutton> and revise any selection, and then go
      forward to redo the export.</para>

      <!-- ==== Figure: GEDCOM Export ==== -->

      <figure id="export-druid-fig">
        <title>Export assistant: format selection</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata depth="" fileref="figures/export-druid.png"
                         format="PNG" width="" />
            </imageobject>

            <textobject>
              <phrase>Shows format selection page of an Export
              assistant</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

      <sect2 id="export-gedcom">
        <title>Exporting into the GEDCOM format</title>

        <para>GRAMPS allows you to export a database into the common GEDCOM
        format. It provides options that allow you to fine tune your export
        (see <xref linkend="gedcom-export-fig" />).</para>

        <variablelist>
          <varlistentry>
            <term>Encoding</term>

            <listitem>
              <para>Since different languages use different characters, it is
              important to tell a GEDCOM file what character set is used. The
              two formats traditionally accepted are ASCII and ANSEL. Since
              all ASCII characters are valid ANSEL characters, GRAMPS does not
              provide an option for ASCII.</para>

              <para>Because ANSEL is not commonly used, some genealogy
              programs will accept ANSI (more commonly know as ISO-8859-1) and
              Unicode character sets. Only select ANSI or Unicode if you know
              any program that attempts to read the GEDCOM file will
              understand these character sets.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Filter</term>

            <listitem>
              <para>The filter allows you to export a limited amount of data,
              based on the criteria you select.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Target</term>

            <listitem>
              <para>While GEDCOM is a standard, not every program implements
              it in the same way. This can lead to data loss. GRAMPS can
              reduce the data loss in some cases. You can tell GRAMPS what
              program is the target, and GRAMPS will customize the exported
              file for that program. If your program is not listed, choose the
              "GEDCOM 5.5 Standard".</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Copyright</term>

            <listitem>
              <para>Allows you to select a statement to describe your
              Copyright claim.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>No not include records marked private</term>

            <listitem>
              <para>Check this box to prevent private records from being
              included in the exported file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Restrict data on living people</term>

            <listitem>
              <para>Check this box to limit the information exported for
              living people. This means that all information concerning their
              birth, death, addresses, significant events, etc., will be
              omitted in the exported GEDCOM file. If you choose this option,
              you will be given additional options to limit further the data
              on living people. For example, you can choose to substitute the
              word "Living" for the first name; you can exclude notes; and you
              can exclude sources for living people.</para>

              <para>Sometimes, it is not always obvious from the data if
              someone is actually alive. GRAMPS uses an advanced algorithm to
              try to determine if a person could still be alive. Remember,
              GRAMPS is making its best guess, and it may not always be able
              to guess correctly all the time. Please double check your
              data.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Reference images from path</term>

            <listitem>
              <para>Check this box to tell GRAMPS to use the specific path for
              your images when writing image references in GEDCOM.</para>

              <para>This option allows specify where your image files are
              located. This is useful when you are transfering your GEDCOM
              file from one computer to another. It tells the program that is
              importing the data where your images are.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <!-- ==== Figure: GEDCOM Export ==== -->

        <figure id="gedcom-export-fig">
          <title>Export assistant: GEDCOM options</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/gedcom-export.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows GEDCOM options page of an Export druid</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Export ==== -->
      </sect2>

      <sect2 id="export-gramps-formats">
        <title>Export into GRAMPS formats</title>

        <variablelist>
          <varlistentry>
            <term>GRAMPS database (grdb) export</term>

            <listitem>
              <para>Exporting to the GRAMPS native format will simply make a
              copy of your data under another name. Exporting to this format
              can also be useful if you have directly opened an XML or GEDCOM
              file and would like to save it as the grdb file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GRAMPS XML database export</term>

            <listitem>
              <para>Exporting into GRAMPS XML format will produce a database
              compatible with the previous versions of GRAMPS. As XML is a
              text-based human-readable format, you may also use it to take a
              look at your data.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GRAMPS package export</term>

            <listitem>
              <para>Exporting to the GRAMPS package format will create a
              compressed file that contains the database and copies of all
              associated media files. This is useful if you want to move your
              database to another computer or to share it with someone.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Export to CD</term>

            <listitem>
              <para>Exporting to CD will prepare your database and copies of
              all media object files for recording onto a CD. To actually burn
              the CD, you will need to go to the GNOME
              <guilabel>burn:///</guilabel> location, which can be accessed by
              navigating through Nautilus: After exporting to CD, select
              <menuchoice>
                  <guimenu>Go</guimenu>

                  <guisubmenu>CD Creator</guisubmenu>
                </menuchoice> in the Nautilus menu. Your database directory
              will show up. To burn it to the CD, click the CD icon on the
              Nautilus toolbar, or select <menuchoice>
                  <guimenu>File</guimenu>

                  <guisubmenu>Write to CD</guisubmenu>
                </menuchoice> in the Nautilus menu.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>If a media file is not found during export, you will see the
        same <guilabel>Missing Media</guilabel> dialog you encounter with
        GEDCOM export.</para>
      </sect2>

      <sect2 id="export-other-formats">
        <title>Export into other formats</title>

        <variablelist>
          <varlistentry>
            <term>Web Family Tree</term>

            <listitem>
              <para>Exporting to Web Family Tree will create a text file that
              can be used by the Web Family Tree program. Export options
              include filter selection and the ability to limit data on living
              people to that of their family ties.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>GeneWeb</term>

            <listitem>
              <para>Exporting to GeneWeb will save a copy of your data into a
              popular web genealogy format. To find out more about GeneWeb and
              its format, visit <ulink type="http"
              url="http://cristal.inria.fr/~ddr/GeneWeb/en/">http://cristal.inria.fr/~ddr/GeneWeb/en/</ulink>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>vCalendar and vCard</term>

            <listitem>
              <para>Exporting to vCalendar or vCard will save information in a
              format used in many calendaring and addressbook applications,
              sometimes called PIM for Personal Information Manager.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="gramps-edit-quick">
      <title>Entering and Editing Data: Quick Start Overview</title>

      <para>This section is designed to give you the basic knowledge necessary
      to start putting your genealogical information into GRAMPS. It will
      explain how to enter people into the database and how to specify their
      family relationships. (A more detailed explanation will follow in the
      section entitled <xref linkend="gramps-edit-complete" />.)</para>

      <para>First, let's identify the types of information you can enter into
      your GRAMPS database. These include:</para>

      <itemizedlist>
        <listitem>
          <para>Personal information about an individual (names, addresses,
          birth and death dates, etc.)</para>
        </listitem>

        <listitem>
          <para>Information about an individual's relationships (marriages,
          divorces, civil unions, etc.)</para>
        </listitem>

        <listitem>
          <para>Information about an individual's parents and children</para>
        </listitem>

        <listitem>
          <para>Sources that document your research</para>
        </listitem>
      </itemizedlist>

      <note id="keybind">
        <title>Keybindings</title>

        <para>In addition to interacting with GRAMPS through menu items and
        buttons, you can use its extensive set of "keybindings." For more
        information, see <xref linkend="append-keybind" />.</para>
      </note>

      <para>Now let's take a quick look at how you can enter and edit these
      various types of information.</para>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-add-pers">
        <title>To Add or Edit a Person</title>

        <para>There are multiple ways to add a person to the database. We will
        cover some of them as we proceed. The simplest way to enter a person
        to add them from the People View. While you are in the People View
        (<xref linkend="side-nofilt-fig" />), click the
        <guibutton>Add</guibutton> on the toolbar. Enter any data you know
        about this person into the <guilabel>Edit Person</guilabel> dialog
        (see <xref linkend="edit-pers-fig" /> for details).</para>

        <para>To edit information about a person already present in the
        database, select the person from the People View and click the
        <guibutton>Edit</guibutton> button on the toolbar.</para>

        <note id="person-menu">
          <title>Alternate ways of adding or editing a person from the People
          View</title>

          <para>You can also use <guilabel>Add...</guilabel> and
          <guilabel>Edit...</guilabel> menu items available under
          <guimenu>Edit</guimenu>. Or you can right-click on the person and
          select <guilabel>Add...</guilabel> or <guilabel>Edit...</guilabel>
          from the context menu that pops up.</para>
        </note>

        <para>People can also be added to the database in the Relationships
        View, Edit Family dialog, and other places where it makes
        sense.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-spec-rel">
        <title>To Specify a Relationship</title>

        <para>There are two primary ways to specify relationships between
        people - using the Relationships View and using the Edit Family dialog
        from the Family List View. The Family List is usually used to build
        all the relationships within a single family at a time. The
        Relationships View is usually used to build multiple relationships to
        a single person.</para>

        <para>To specify a new relationship to the selected person, switch to
        the Relationships View (<xref linkend="family-fig" />) and you'll see
        this individual indicated as the "Active person". Next to the
        <guilabel>Family</guilabel> label is a <guibutton>Add</guibutton>
        button (typically represented by a <guibutton>+</guibutton> sign).
        Clicking the <guibutton>Add</guibutton> button will display the Edit
        Family dialog with the selected person set as either the father or the
        mother.</para>

        <figure id="edit-family">
          <title>Editing a family</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/edit-family.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Editing a family.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <para>Now a question: Does the person who will form the relationship
        with the Active person already exist in the database? If yes, click
        the <guibutton>Select</guibutton> button to the other person. You'll
        then be able to browse through the list of people in the database to
        select the one you want. If not, click the <guibutton>Add</guibutton>
        button. This will allow you to add a new person to the database and to
        specify the relationship this person has to the Active person.</para>

        <figure id="select-person">
          <title>Selecting a person</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/select-person.png" format="PNG" />
              </imageobject>

              <textobject>
                <phrase>Selecting a person.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <note id="spouse-filter">
          <title>Filtering</title>

          <para>By default, GRAMPS filters the displayed list to show only
          those people who could theoretically have a relationship with the
          Active Person. That is, GRAMPS only shows those people whose birth
          dates and death dates fit within the lifetime of the Active Person.
          If you wish, you can add a person to the list by clicking the
          <guibutton>+</guibutton> button. To completely override the filter
          and display all people from the database, check the <guilabel>Show
          all</guilabel> box.</para>
        </note>

        <para>To edit an existing relationship from the Relationships View,
        click on the <guibutton>Edit</guibutton> button next to corresponding
        Family entry. If there is more than one relationship in the list, you
        can select the spouse or partner you want by clicking the
        corresponding <guibutton>Edit</guibutton> button next to the
        relationship.</para>

        <para>To specify a new relationship in the Family List View, click on
        the <guibutton>Add</guibutton> button on the toolbar, and an empty
        Edit Family dialog will open. At this point, you can add people to the
        family.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-spec-par">
        <title>To Specify Parents</title>

        <para>You can specify Active person's parents in the Relationship
        View(<xref linkend="family-fig" />). A little care is required to
        prevent the creation of duplicate families. If you wish to add the
        active person to an already existing family, you should click the
        <guibutton>Select</guibutton> button. If the family including the
        parents does not already exist, you should click the
        <guibutton>Add</guibutton> button.</para>

        <para>If you click on the <guibutton>Select</guibutton> button, you
        are presented with the Select Family dialog. This will allow you to
        select the existing family, and then the Active person will be added
        as a child to the family.</para>

        <figure id="select-family">
          <title>Selecting a family</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/select-family.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Selecting a family.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <para>If you click on the <guibutton>Add</guibutton> button, a new
        Edit Family dialog is presented with the Active person listed a child
        of the new family. You can add the parents to the family by either
        adding new people as the parents or selecting existing people as the
        parents.</para>

        <warning>
          <para>If you create a new family and select parents that are already
          in an existing family, GRAMPS will issue a warning message. If you
          proceed by saving the new famiy, you will have a duplicate
          family.</para>

          <figure id="family-warn">
            <title>Duplicate family warning</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="figures/family-warn.png" format="PNG"
                             width="" />
                </imageobject>

                <textobject>
                  <phrase>Duplicate family warning.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>
        </warning>

        <para>You can also specify the parents of a person in the Family List
        View. If the family already exists, click on the
        <guibutton>Edit</guibutton> button on the tool bar and add the person
        as a child when the Edit Family dialog is displayed. If the family
        does not already exist, click the <guibutton>Add</guibutton> button to
        create a new family, and add the appropriate parents and
        children.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-spec-ch">
        <title>To Specify Children</title>

        <para>Adding children to a relationship is done through a similar
        proceedure. From the Relationships View or the Family List View,
        select the existing family or create a new family. Children can be
        added by selecting the Add button or Select button to the right of the
        child list.</para>

        <para>Clicking the <guibutton>Add</guibutton> button will display the
        Edit Person dialog, allowing you to enter a new person. Clicking on
        the <guibutton>Select</guibutton> button, will allow you to select an
        existing person from a list. By default, the child is added with a the
        relationship type of birth to both parents.</para>

        <para>If you wish to change the parent/child relationship from the
        default setting of birth, select the child and click on the Edit
        button. This will display the Edit Child Reference dialog.</para>

        <figure id="child-ref">
          <title>Child Reference Editor</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/child-ref.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Child Reference Editor.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-add-img">
        <title>Adding Photos and Other Media Objects</title>

        <para>You can add photos and other media objects to individual people,
        events, sources, and places. You can also add images that might not be
        limited to a single person or event (for example, group family
        photos).</para>

        <para>If you want to add an image to a single person, switch to the
        People View (<xref linkend="side-nofilt-fig" />), select a person, and
        then click the <guibutton>Edit</guibutton> icon on the toolbar. This
        will bring up the <guilabel>Edit Person</guilabel> dialog (<xref
        linkend="edit-pers-fig" />). Next, select the
        <guilabel>Gallery</guilabel> tab, and click the
        <guibutton>+</guibutton> button to call up the <guilabel>Select a
        media object</guilabel> dialog. Type a filename or browse to find the
        image file you want and then provide a title for that image. Keep
        adding images until you are done.</para>

        <para>To add images related to a relationship (for example, a
        marriage), switch to the Family View (<xref linkend="family-fig" />)
        and double-click on the Spouse box. This calls up the
        <guilabel>Marriage/Relationship editor</guilabel> dialog. Select the
        <guilabel>Gallery</guilabel> tab and click the
        <guibutton>+</guibutton> button to add an image.</para>

        <para>To add images related to a source or a place, first switch to
        the Source View (<xref linkend="sources-fig" />) or Place View (<xref
        linkend="places-fig" />). Select the source or place you want and then
        either double-click on it or click the <guibutton>Edit</guibutton>
        icon on the toolbar. Select the <guilabel>Gallery</guilabel> tab and
        click the <guibutton>+</guibutton> button to add an image.</para>

        <para>Finally, to add images that you want to include in the database,
        but hare are not limited to any particular person, relationship,
        source or place, switch to the Media View (<xref
        linkend="media-fig" />). Then click the <guibutton>Add</guibutton>
        icon on the toolbar to add an image. If you have already added any
        images to any individual galleries, you will also find them listed in
        the Media View.</para>

        <note id="alt-add-image">
          <title>Alternate way of adding images to galleries</title>

          <para>An image can always be added to any gallery by using
          drag-and-drop. Items can be dragged from the Media View, any
          gallery, the desktop, the file manager or a web browser and dropped
          on the target gallery, adding the image to the gallery.</para>
        </note>

        <para>In any gallery, you can also use the <guibutton>Edit</guibutton>
        to edit image information and the <guibutton>-</guibutton> button and
        to remove the image reference from that gallery.</para>

        <note id="remove-image-from-gallery">
          <title>Removing an image from a gallery</title>

          <para>Removing a media object from a gallery does not remove the
          image from the database. To completely remove the image from the
          database, delete it from Media View by first selecting it and then
          clicking the <guibutton>Remove</guibutton> icon on the
          toolbar.</para>
        </note>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-edit-src-plc">
        <title>To Edit Sources and Places</title>

        <para>To add a source or a place to the database, switch to the
        appropriate Source View (<xref linkend="sources-fig" />) or Place View
        (<xref linkend="places-fig" />). Then click the
        <guibutton>Add</guibutton> icon on the toolbar to add a source/place.
        Enter the information into the <guilabel>Source Editor</guilabel> (or
        <guilabel>Place Editor</guilabel>) dialog.</para>

        <para>To edit information about sources and places already present in
        the database, switch to the appropriate view, select an entry you
        would like to view/modify, and then click the
        <guibutton>Edit</guibutton> icon on the toolbar. Alternatively, you
        may double-click on the entry to edit it.</para>
      </sect2>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="gramps-edit-complete">
      <title>Entering and Editing Data: Complete Description</title>

      <para>The previous section offered you a quick overview of how to enter
      and edit data in GRAMPS. This section continues that discussion in much
      greater detail.</para>

      <para>As we have seen above, GRAMPS offers you a series of Views. Each
      of these Views gives you opportunities to enter and edit information. In
      fact, you can often get to the same information from different
      Views.</para>

      <para>In GRAMPS, information is entered and edited through what we call
      dialogs. Since we use that term frequently, we should define what we
      mean by it:</para>

      <para>A dialog is a pop-up window that provides one or more forms for
      entering and editing data that fits a certain category. Examples in
      GRAMPS include the Edit Person dialog and the Marriage/Relationship
      dialog, among many others.</para>

      <para>A dialog often includes a series of "notebook tabs" that group the
      information into subcategories. For example, the Edit Person dialog has
      notebook tabs for subcategories such as Events, Attributes, Addresses,
      and Notes, among others.</para>

      <note id="edit-button-note">
        <title>Add, Remove, and Edit buttons</title>

        <para>In most cases, GRAMPS uses a <guibutton>+</guibutton> to
        correspond to <guibutton>Add</guibutton>, a <guibutton>-</guibutton>
        correspond to <guibutton>Remove</guibutton>, and an icon of a pen on a
        sheet of paper to denote <guibutton>Edit</guibutton>. We will continue
        referring to the latter as the <guibutton>Edit</guibutton> button,
        while using <guibutton>+</guibutton> and <guibutton>-</guibutton> to
        denote the two former buttons.</para>
      </note>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-pers">
        <title>Editing Information About People</title>

        <para>Information about people is entered and edited through the
        <guilabel>Edit Person</guilabel> dialog. This dialog can be invoked
        from different Views in the following ways:</para>

        <variablelist>
          <varlistentry>
            <term>From the People View:</term>

            <listitem>
              <itemizedlist>
                <listitem>
                  <para>Double-click the name of the person whose data you
                  would like to edit</para>
                </listitem>

                <listitem>
                  <para>Select the name by single click and then click the
                  <guibutton>Edit</guibutton> button on the toolbar.</para>
                </listitem>

                <listitem>
                  <para>Select the name and then press
                  <keycap>Enter</keycap>.</para>
                </listitem>

                <listitem>
                  <para>Select <guimenuitem>Edit...</guimenuitem> from the
                  <guisubmenu>Edit</guisubmenu> menu of GRAMPS</para>
                </listitem>

                <listitem>
                  <para>Select <guimenuitem>Edit</guimenuitem> from the
                  context menu that appears upon right-click on the
                  name.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>From the Relationships View:</term>

            <listitem>
              <para>To edit the active person's data, click on the Edit button
              next to the active person's name.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>From the Pedigree View:</term>

            <listitem>
              <para>Double-click in the box having the name of the person
              whose data you want to edit.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>In each of the above cases, the <guilabel>Edit Person</guilabel>
        dialog will appear:</para>

        <!-- ==== Figure: Edit Person dialog ==== -->

        <figure id="edit-pers-fig">
          <title>Edit Person dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-person.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Edit Person dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The top of the window shows the basic information about the
        person whose data is being edited. Below are several "notebook tabs"
        containing different categories of available information. Click any
        tab to view and edit its contents. Clicking the
        <guibutton>OK</guibutton> button at the bottom will apply all the
        changes made in all tabs and close the dialog window. Clicking the
        <guibutton>Cancel</guibutton> button will close the window without
        applying any changes. If any data in any tabs were modified, an alert
        window will appear, prompting you to choose from the following
        options: close the dialog without saving changes, cancel the initial
        cancel request, or save the changes.</para>

        <note>
          <para>Clicking <guibutton>OK</guibutton> will immediately save
          changes to the database. There is no need for a Save operation,
          since all changes are immediate.</para>
        </note>

        <tip>
          <para>If a tab label is in boldface type, this means it contains
          data. If not, it has no data.</para>
        </tip>

        <para>The general information is at the top of the window. This
        includes the primary name and general information.:</para>

        <variablelist>
          <varlistentry>
            <term>Primary Name</term>

            <listitem>
              <para>includes <guilabel>Given name</guilabel>, <guilabel>Family
              name</guilabel>, <guilabel>Family prefix</guilabel> (such as
              "de" or "van"), <guilabel>Suffix</guilabel> (e.g. Jr. or III),
              <guilabel>Title</guilabel> (e.g. Dr. or Rev.),
              <guilabel>Nickname</guilabel> (Bob for Robert),
              <guilabel>Type</guilabel> of the name (birth name, married name,
              etc.). Some of these <guilabel>Family name</guilabel> and
              <guilabel>Type</guilabel> fields provide "autocompletion"
              feature: as you type in these fields, a menu appears below the
              field containing database entries that match your partial input.
              This gives you a shortcut by letting you select an entry that
              already exists in the database rather than having to type it all
              out. You can select the entry using your mouse or using your
              arrow and <keycap>Enter</keycap> keys.</para>

              <para>The <guilabel>Edit</guilabel> (that is, the "pen and
              paper" icon) next to the <guilabel>Prefix</guilabel> entry field
              invokes the <guilabel>Name Editor</guilabel> dialog. This dialog
              allows editing the preferred name in full detail (see <xref
              linkend="adv-an" />).</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>General</term>

            <listitem>
              <para>The <guilabel>Gender</guilabel> menu offers the choice of
              person's gender : <guilabel>male</guilabel>,
              <guilabel>female</guilabel>, and
              <guilabel>unknown</guilabel>.</para>

              <para>The field <guilabel>ID</guilabel> displays the GRAMPS ID
              number which identifies the user in the database. This value
              helps you distiguish between people who have the same name. You
              may enter any unique value you want. If you do not provide a
              value, GRAMPS will automatically select a value for you.</para>

              <para>The <guilabel>Marker</guilabel> allows you to specify som
              basic information on the status of your research.</para>

              <para>The <guilabel>Privacy</guilabel> button lets you mark
              whether or not the person's record is considered private.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Image</term>

            <listitem>
              <para>The <guilabel>Image</guilabel> area shows the first image
              available in the <guilabel>Gallery</guilabel> of this person (if
              any exist).</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>The tabs reflect the following categories of personal
        data:</para>

        <variablelist>
          <varlistentry>
            <term>Events</term>

            <listitem>
              <para>The <guilabel>Events</guilabel> tab lets you view and edit
              any events relevant to the person. The bottom part of the window
              lists all such events stored in the database. The top part shows
              the details of the currently selected event in the list (if
              any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> allow
              you to add, modify, and remove an event record from the
              database. Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when an
              event is selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Names</term>

            <!-- ==== Figure: Edit Person dialog - Names ==== -->

            <listitem>
              <para>The <guilabel>Names</guilabel> tab lets you view and edit
              any alternate names the person may have. The bottom part of the
              window lists all alternate names for the person stored in the
              database. The top part shows the details of the currently
              selected name in the list (if any). The buttons
              <guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> allow the addition, modification, and
              removal of an alternate name from the database. Note that the
              Edit and - buttons become available only when an alternate name
              is selected from the list.</para>

              <figure id="edit-pers-names-fig">
                <title>Edit Person dialog - Names</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=" "
                                 fileref="figures/edit-person-names.png"
                                 format="PNG" width=" " />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Names Tab of Edit Person dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <para>When you add a new name or edit an existing name, the
              <guilabel>Name Editor</guilabel> dialog is invoked. This dialog
              is described in the section below (see <xref
              linkend="adv-an" />).</para>

              <!-- ==== End of Figure ==== -->
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Attributes</term>

            <listitem>
              <para>The <guilabel>Attributes</guilabel> tab lets you view and
              assign attributes to the person. You have complete freedom to
              define and use attributes. For example, attributes might be
              assigned to describe the person's physical characteristics or
              personality traits.</para>

              <para>Note that each attribute listed in the
              <guilabel>Attribute</guilabel> dialog consists of two parts: the
              Attribute itself and a Value associated with that Attribute.
              This so-called "Parameter-Value" pairing can help you organize
              and systematize your research. For example, if you define "Hair
              color" as an Attribute for a person, "Hair Color" will become a
              selectable Attribute for all other people. The Value of Hair
              Color for person A might be red, and brown for person B. In
              similar fashion, you might define an Attribute like "Generosity"
              and use the Value of "Enormous" to describe a particularly
              generous person.</para>

              <para>The bottom part of the dialog window displays the list of
              all Attributes stored in the database. The top part shows the
              details of the currently selected attribute in the list (if
              any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, and remove an attribute record from the
              database. Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when an
              attribute is selected from the list.</para>

              <!-- ==== Figure: Edit Person dialog - Attributes ==== -->

              <figure id="edit-pers-attributes-fig">
                <title>Edit Person dialog - Attributes</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=""
                                 fileref="figures/edit-person-attributes.png"
                                 format="PNG" width="" />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Attributes Tab of Edit Person
                      dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Addresses</term>

            <listitem>
              <para>The <guilabel>Addresses</guilabel> tab lets you view and
              record the various addresses of the person. The bottom part of
              the window lists all addresses stored in the database. The top
              part shows the details of the currently selected address in the
              list (if any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> allow
              you to correspondingly add, modify, and remove an address record
              from the database. Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when an
              address is selected from the list.</para>

              <para>Some reports allow you to restrict data on living people.
              In particular, that option will omit their addresses.</para>

              <!-- ==== Figure: Edit Person dialog - Addresses ==== -->

              <figure id="edit-pers-addresses-fig">
                <title>Edit Person dialog - Addresses</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=" "
                                 fileref="figures/edit-person-addresses.png"
                                 format="PNG" width=" " />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Addresses Tab of Edit Person
                      dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Notes</term>

            <listitem>
              <!-- ==== Figure: Edit Person dialog - Notes ==== -->

              <figure id="edit-pers-notes-fig">
                <title>Edit Person dialog - Notes</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=" "
                                 fileref="figures/edit-person-notes.png"
                                 format="PNG" width=" " />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Notes Tab of Edit Person dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->

              <para>The <guilabel>Notes</guilabel> tab provides a place to
              record various items about the person that do not fit neatly
              into other categories. To add a note or modify existing notes
              simply edit the text in the text entry field.</para>

              <para>The <guilabel>Format</guilabel> option lets you set the
              way the note will appear in reports and web pages. If you select
              "Flowed," the text generated will have single spaces put in
              place of all multiple spaces, tabs, and single end-of-line
              characters. A blank line inserted between two blocks of text
              will signal a new paragraph; additional inserted lines will be
              ignored.</para>

              <para>If you select the Preformatted option, the text in reports
              and web pages will appear exactly as you enter it in the Notes
              dialog.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Sources</term>

            <listitem>
              <!-- ==== Figure: Edit Person dialog - Sources ==== -->

              <figure id="edit-pers-sources-fig">
                <title>Edit Person dialog - Sources</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=" "
                                 fileref="figures/edit-person-sources.png"
                                 format="PNG" width=" " />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Sources Tab of Edit Person
                      dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->

              <para>The <guilabel>Sources</guilabel> tab allows you to view
              and document the sources for the information you collect. These
              might be general sources that do not describe a specific event,
              but which nevertheless yield information about the person. For
              example, if Aunt Martha's memoirs mention her great-grandson
              Paul, the researcher may assume that this Paul actually existed
              and cite Aunt Martha's memoirs as the source that justifies this
              assumption.</para>

              <tip>
                <para>Sources which document specific events are best recorded
                as sources of the event (under the <guilabel>Events</guilabel>
                tab) instead of as a source of the person. The person's
                <guilabel>Sources</guilabel> tab is best used for any sources
                not specificly connected to any other data.</para>
              </tip>

              <para>The central part displays the list of all source
              references stored in the database in relation to the person. The
              buttons <guibutton>+</guibutton>, <guibutton>Edit</guibutton>,
              and <guibutton>-</guibutton> allow you to correspondingly add,
              modify, and remove a source reference to this person. Note that
              the <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
              buttons become available only when a source reference is
              selected from the list.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Gallery</term>

            <listitem>
              <para>The <guilabel>Gallery</guilabel> tab lets you view and
              store photos, videos, and other media objects that are
              associated with the person. The central part of the window lists
              all such media objects. Any object in the form of a valid image
              file will result in the display of a thumbnail view of the
              image. For other objects such as audio files, movie files, etc.,
              a corresponding file type icon is displayed instead.</para>

              <tip>
                <para>The first available image in the gallery will be also
                displayed in the <guilabel>Image</guilabel> area in the
                <guilabel>General</guilabel> tab.</para>
              </tip>

              <para>The buttons <guibutton>+</guibutton>,
              <guibutton>Select</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> let you add a new image to the
              database, link to an image already stored in the database,
              modify an image, and remove a given media object from the
              person's gallery. Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when a
              media object is selected from the list.</para>

              <!-- ==== Figure: Edit Person dialog - Gallery ==== -->

              <figure id="edit-pers-gallery-fig">
                <title>Edit Person dialog - Gallery</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=""
                                 fileref="figures/edit-person-gallery.png"
                                 format="PNG" width="" />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Gallery Tab of Edit Person
                      dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->

              <note>
                <para>Removing a media object from a person's gallery does not
                remove it from the database. It only removes the reference to
                that object from this person's record.</para>
              </note>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Internet</term>

            <listitem>
              <para>The <guilabel>Internet</guilabel> tab displays Internet
              addresses relevant to the person. The bottom part lists all such
              Internet addresses and accompanying descriptions. The top part
              shows the details of the currently selected addresses in the
              list (if any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, and remove an Internet address. The "Go" button
              (represented by an icon having a green arrow and yellow circle)
              opens your web browser and takes you directly to the highlighted
              page. Note that the <guibutton>Edit</guibutton>,
              <guibutton>-</guibutton>, and <guibutton>Go</guibutton> buttons
              become available only when an address is selected from the
              list.</para>

              <!-- ==== Figure: Edit Person dialog - Internet ==== -->

              <figure id="edit-pers-internet-fig">
                <title>Edit Person dialog - Internet</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=""
                                 fileref="figures/edit-person-internet.png"
                                 format="PNG" width="" />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Internet Tab of Edit Person
                      dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
	    <term>Associations</term>
	    <listitem>
	      <para>The <guilabel>Associations</guilabel> tab lets you
	      view and edit information about the associations between
	      people in the database. The associations may include Godparents,
	      family friends, or any other types of associations you may 
	      wish to record.</para>
              <!-- ==== Figure: Edit Person dialog - LDS ==== -->

              <figure id="edit-pers-as-fig">
                <title>Edit Person dialog - Associations</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=""
                                 fileref="figures/edit-person-assoc.png"
                                 format="PNG" width="" />
                    </imageobject>

                    <textobject>
                      <phrase>Shows Associations Tab of Edit Person dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>
	    </listitem>
	  </varlistentry>
	</variablelist>

        <variablelist>
          <varlistentry>
            <term>LDS</term>

            <listitem>
              <para>The <guilabel>LDS</guilabel> (Latter Days Saints) tab lets
              you view and edit information about LDS ordinances of the
              person. These are LDS Baptism, Endowment, and Sealed to Parents
              ordinances, as labeled inside the tab. Each ordinance is
              described by its date, LDS temple, and Place where it happened.
              An additional pop-up menu, "Parents," is available for the
              Sealed to Parents ordinance. Each ordinance can be further
              described through the selections available in the Status pop-up
              menu. It can also be include notes and references to sources
              through the corresponding <guibutton>Sources...</guibutton> and
              <guibutton>Note</guibutton> buttons.</para>

              <!-- ==== Figure: Edit Person dialog - LDS ==== -->

              <figure id="edit-pers-lds-fig">
                <title>Edit Person dialog - LDS</title>

                <screenshot>
                  <mediaobject>
                    <imageobject>
                      <imagedata depth=""
                                 fileref="figures/edit-person-lds.png"
                                 format="PNG" width="" />
                    </imageobject>

                    <textobject>
                      <phrase>Shows LDS Tab of Edit Person dialog.</phrase>
                    </textobject>
                  </mediaobject>
                </screenshot>
              </figure>

              <!-- ==== End of Figure ==== -->
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-dates">
        <title>Editing Dates</title>

        <para>This section describes how to enter and modify dates. Since
        dates are so important in genealogical research, GRAMPS takes special
        care to preserve and use any date information available.</para>

        <para>Information can be entered into a date field by directly typing
        it or by invoking the Date selection dialog. Both methods will be
        discussed below, but first, we will cover some important features of
        dates as they are used in GRAMPS.</para>

        <sect3 id="adv-dates-types">
          <title>Date types</title>

          <para>Dates in GRAMPS are classified according to the following
          types:</para>

          <variablelist>
            <varlistentry>
              <term>Regular</term>

              <listitem>
                <para>A "regular" date is one which includes a specific day,
                date, or month. It can be complete (e.g., June 6, 1990) or
                partial (e.g., July 1977).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Before</term>

              <listitem>
                <para>A "before" date is one that can only be identified as
                occurring before a certain day, month, or year.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>After</term>

              <listitem>
                <para>An "after" date is one that occurs after a certain day,
                month, or year.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Range</term>

              <listitem>
                <para>A "range" describes a time period during which the event
                occurred. For example, "between January 1932 and March
                1932."</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Span</term>

              <listitem>
                <para>A "span" describes a time period during which a
                condition existed. For example, "from May 12, 2000 to February
                2, 2002."</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3 id="adv-dates-parsing">
          <title>Date formats and parsing rules</title>

          <para>GRAMPS recognizes dates entered in a variety of formats. The
          default numeric format is that which is conventional for the
          environment is which GRAMPS is operating; that is, DD.MM.YYYY for
          most European countries, MM/DD/YYYY for the U.S., and so on.</para>

          <para>Besides exact dates, GRAMPS recognizes many dates that are not
          regular: before, after, about, ranges and spans. It also understands
          the quality: estimated or calculated. Finally, it supports partial
          dates and many alternative calendars. Below is the list of date
          entry rules to allow precise date parsing.</para>

          <note>
            <title>Date parsing rules</title>

            <para>The list only applys to the English version of GRAMPS. If
            you are using localized version of GRAMPS, your version may or may
            not provide a localized date parser. At the time of this writing,
            localized parsers exist for French, German, Russian, Finnish,
            Dutch and Spanish languages.</para>

            <para>If the localized parser is available for your version,
            chances are that other rules are in effect. If there is no manual
            in your language yet, you may try following your instinct and go
            with the common ways of denoting dates in your language. If all
            else fails, use the <guilabel>Date selection</guilabel> dialog
            described below.</para>
          </note>

          <itemizedlist>
            <listitem>
              <para>Regular single dates can be entered just as you would
              write them. Examples: May 24, 1961 or January 1, 2004.</para>
            </listitem>

            <listitem>
              <para>Dates that are not regular should start with the quality:
              <guilabel>estimated</guilabel> or
              <guilabel>calculated</guilabel>, if applicable. Example: est.
              1961, or calc 2005. (Note that a quality does not need to be
              specified for regular dates.)</para>
            </listitem>

            <listitem>
              <para>After the quality should appear the type. If the type is
              <guilabel>before</guilabel>, <guilabel>after</guilabel>, or
              <guilabel>about</guilabel>, you scan specify the type by writing
              "before", "after" or "about". If the type is a range, write
              "between DATE and DATE", and if the type is a span, write "from
              DATE to DATE". patterns, where DATE is a single date.</para>

              <para>Examples: est from 2001 to 2003, before June 1975, est
              about 2000, calc between May 1900 and January 1, 1990.</para>
            </listitem>

            <listitem>
              <para>Partial dates are entered simply by omitting unknown
              information. Examples: May 1961 and 2004.</para>
            </listitem>

            <listitem>
              <para>Alternate calendars are calendars other than the Gregorian
              calendar. Currently, GRAMPS supports Hebrew, French Republican,
              Julian, Islamic, and Persian alternate calendars. To specify the
              calendar other than the default Gregorian, append the name of
              the calendar to the date string, e.g. "January 9, 1905
              (julian)".</para>
            </listitem>
          </itemizedlist>
        </sect3>

        <sect3 id="adv-dates-led">
          <title>Date Validity Indicators</title>

          <para>GRAMPS uses color circles to indicate the validity of the
          entered date.</para>

          <tip>
            <title>Date LED buttons</title>

            <para>The color circles are also referred to as the LED buttons.
            Clicking on an LED button will invoke the <guilabel>Date
            selection</guilabel> dialog described in detail below, see <xref
            linkend="adv-dates-gui" /></para>
          </tip>

          <itemizedlist>
            <listitem>
              <para>A green circle means that the date is valid and complete
              regular date (e.g. May 24, 1961). In simple terms, green means
              that the date corresponds to a unique date.</para>
            </listitem>

            <listitem>
              <para>Yellow circle means that the date is valid but is not a
              regular date. This could be the date of a different type: a
              before date (before May 25, 1962), an after date (after May,
              1960), an about date (about May 23, 1961), a range (between May
              1, 1961 and May 31, 1961), or a span (from May 1, 1961 to May
              31, 1961). It can also be a complete single date, but with
              quality of Estimated or Calculated. Finally, it could be a
              partial date, i.e. a regular quality single date missing some
              portion, e.g. May 1961 or 1961.</para>

              <para>While partial dates do not uniquely define the day, they
              allow at least for some type of comparisons between the
              dates.</para>
            </listitem>

            <listitem>
              <para>Red circle means that the date is not recognized as a
              valid date (e.g. "Christmas week of 61", or "the summer when I
              had surgery"). In such a case the date will be stored as a text
              string and therefore cannot be compared other dates. As you can
              see, it is best to avoid such date entries. It would be better,
              for example, to enter a date of "December 1961" and then to add
              the note "Christmas week of '61."</para>
            </listitem>
          </itemizedlist>
        </sect3>

        <sect3 id="adv-dates-gui">
          <title>Graphical User Interface for Entering Dates</title>

          <para>While the above parsing rules provide a guide for you to type
          in most common dates, you can also use <guilabel>Date
          selection</guilabel> dialog. The dialog is particularly useful for
          building a complex date or for simply insuring that your information
          is entered in a way GRAMPS will understand. The <guilabel>Date
          selection</guilabel> dialog can be invoked by clicking the colored
          circle button next to the date entry field.</para>

          <!-- ==== Figure: Date selection dialog ==== -->

          <para><figure id="adv-dates-gui-fig">
              <title>Date selection dialog</title>

              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata depth="" fileref="figures/date-selection.png"
                               format="PNG" width="" />
                  </imageobject>

                  <textobject>
                    <phrase>Shows Date selection dialog.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure></para>

          <!-- ==== End of Figure ==== -->

          <para>The <guilabel>Calendar</guilabel> menu lets you choose a
          calendar other than the default Gregorian. The
          <guilabel>Quality</guilabel> menu gives you the choices of Regular,
          Estimated, or Calculated. The <guilabel>Type</guilabel> menu allows
          you establish the exact date type: Regular, Before, After, About,
          Range, Span, and Text only. You can set the
          <guilabel>Date</guilabel> by setting the day, the month, and the
          year. In the event that your date type is Range or Span, the
          <guilabel>Second date</guilabel> will be activated. Finally, the
          <guilabel>Text comment</guilabel> text entry field allows storing an
          arbitrary text string along with the date.</para>

          <note>
            <para>If you have an important comment to make about a date, you
            are better off doing so in a Note that corresponds to the event
            than in the Text comment field of the Date selection dialog. We
            recommend this for the following reason: If you enter a date by
            typing it directly into the date field (that is, not via the Date
            selector dialog), your entry will be copied and stored as the text
            comment string when GRAMPS parses the entered text. Thus, any
            comment that may have been there prior to the parsing will be
            overwritten.</para>
          </note>
        </sect3>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-rel">
        <title>Editing Information About Relationships</title>

        <para>Information about relationships is entered and edited through
        the <guilabel>Marriage/Relationship Editor</guilabel> dialog. This
        dialog is invoked from Family View by double-clicking the Spouse
        box</para>

        <note>
          <para>You can also invoke this dialog by right-clicking inside the
          Spouse box and selecting "Edit relationship" item from the context
          menu that pops up.</para>
        </note>

        <!-- ==== Figure: Edit Relationship dialog ==== -->

        <figure id="edit-rel-fig">
          <title>Marriage/Relationship Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-rel.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Marriage/Relationship Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The top of the window shows the names of the people whose
        relationship is being edited. The main part of the window displays
        seven notebook tabs representing different categories of information
        about the relationship. Click any tab to view or edit the information
        it contains. The bottom part has <guibutton>OK</guibutton> and
        <guibutton>Cancel</guibutton> buttons. Clicking the
        <guibutton>OK</guibutton> button at any time will apply all the
        changes made in all tabs and close the dialog window. Clicking the
        <guibutton>Cancel</guibutton> button at any time will close the window
        without applying any changes. If any of the data in any tab is
        modified, an alert window will appear that will prompt you choose
        between closing the dialog without saving changes, canceling the
        initial cancel request, or saving the changes.</para>

        <note>
          <para>Clicking <guibutton>OK</guibutton> will immediately save
          changes to the database. This version of GRAMPS does not have a
          separate saving function, all changes are immediate.</para>
        </note>

        <tip>
          <para>If a tab label is in boldface type, this means it contains
          data. If not, it has no data.</para>
        </tip>

        <para>The tabs provide the following information categories of
        relationship data:</para>

        <variablelist>
          <varlistentry>
            <term>General</term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab lets you edit the
              Relationship type. The available types (such as Married,
              Unmarried, etc.) can be chosen from the drop-down
              <guilabel>Relationship type</guilabel> menu. The
              <guilabel>GRAMPS ID</guilabel> field displays the ID number
              which labels this relationship in the database. The
              <guilabel>Last changed</guilabel> label shows the last time the
              relationship was modified. Finally, the Information is complete
              check button indicates whether the record of this relationship
              is complete or not.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Events</term>

            <listitem>
              <para>The <guilabel>Events</guilabel> tab lets you view and edit
              events relevant to the relationship. The bottom part displays
              the list of all such events stored in the database. The top part
              shows the details of the currently selected event in the list
              (if any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, or remove an event record from the database.
              Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when an
              event is selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Attributes</term>

            <listitem>
              <para>The <guilabel>Attributes</guilabel> tab lets you view and
              edit particular information about the relationship that can be
              expressed as attributes. The bottom part displays the list of
              all such attributes stored in the database. The top part shows
              the details of the currently selected attribute in the list (if
              any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, or remove an attribute. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
              become available only when an attribute is selected from the
              list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Notes</term>

            <listitem>
              <para>The <guilabel>Notes</guilabel> tab lets you view and edit
              notes associated with the relationship. These could be any
              comments which do not naturally fit into the "Parameter-Value"
              pairs available to Attributes. To add a note or modify existing
              notes simply edit the text in the text entry field.</para>

              <para>The <guilabel>Format</guilabel> option lets you set the
              way the note will appear in reports and web pages. If you select
              Flowed, the text generated will have single spaces put in place
              of all multiple spaces, tabs, and single end-of-line characters.
              A blank line inserted between two blocks of text will signal a
              new paragraph; additional inserted lines will be ignored.</para>

              <para>If you select the Preformatted option, the text in reports
              and web pages will appear exactly as you enter it in the Notes
              dialog.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Sources</term>

            <listitem>
              <para>The <guilabel>Sources</guilabel> tab lets you view and
              edit the sources which provide evidence for the relationship.
              These might be documents that refer to the relationship, but
              which do not necessarily document it officially. For example, if
              Aunt Martha's memoirs mention that her great-grandson Paul was
              married, the researcher may take this as evidence of the
              relationship between Paul and his wife existed and cite the
              memoirs as the source for this assumption.</para>

              <note>
                <para>Sources that document specific events such as marriages
                or divorces are better filed in relation to those events,
                under the Events tab.</para>
              </note>

              <para>The central part of the Sources window displays the list
              of all source references associated with the relationship. The
              buttons <guibutton>+</guibutton>, <guibutton>Edit</guibutton>,
              and <guibutton>-</guibutton> allow let you add, modify, and
              remove a source reference to this relationship. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
              become available only when a source reference is selected from
              the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Gallery</term>

            <listitem>
              <para>The <guilabel>Gallery</guilabel> tab lets you store and
              display photos and other media objects associated with the
              relationship. The central part of the window lists all such
              objects and gives you a thumbnail preview of image files. Other
              objects such as audio files, movie files, etc., are represented
              by a generic GRAMPS icon. The buttons <guilabel>+</guilabel>,
              <guilabel>Select</guilabel>, <guilabel>Edit</guilabel>, and
              <guilabel>-</guilabel> let you add a new image, add a reference
              to an existing image, modify an existing image, and remove a
              media object's link to the relationship. Note that the
              <guilabel>Edit</guilabel> and <guilabel>-</guilabel> buttons
              become available only when a media object is selected from the
              list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>LDS</term>

            <listitem>
              <para>The <guilabel>LDS</guilabel> (Latter Days Saints) tab
              displays information about the LDS <guilabel>Sealed to
              Spouse</guilabel> ordinance. The data can include date, LDS
              temple, and Place. The status of the ordinance can be described
              through the selections available in the
              <guilabel>Status</guilabel> pop-up menu and can also be
              referenced in the corresponding
              <guibutton>Sources...</guibutton> and
              <guibutton>Note</guibutton> buttons.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-src">
        <title>Editing Information About Sources</title>

        <para>To edit source data, switch to the Sources View and select the
        desired entry in the list of sources. Double-click that entry or click
        the <guibutton>Edit</guibutton> icon on the toolbar to invoke the
        following <guilabel>Source Editor</guilabel> dialog:</para>

        <!-- ==== Figure: Source Editor dialog ==== -->

        <figure id="edit-src-fig">
          <title>Source Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-src.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Source Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The main part of the window displays four notebook tabs
        containing different categories of information. Click a tab to view or
        edit its contents. The bottom part of the window has
        <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> buttons.
        Clicking <guibutton>OK</guibutton> will apply all the changes made in
        all tabs and close the dialog window. Clicking the
        <guibutton>Cancel</guibutton> button will close the window without
        applying any changes.</para>

        <note>
          <para>Clicking <guibutton>OK</guibutton> will immediately save
          changes to the database (write on disk). All changes are
          immediate.</para>
        </note>

        <tip>
          <para>If a tab label is in boldface type, this means it contains
          data. If not, it has no data.</para>
        </tip>

        <para>The tabs provide the following information categories of source
        data:</para>

        <variablelist>
          <varlistentry>
            <term>General</term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab lets you define basic
              information about the source: its <guilabel>Title</guilabel>,
              <guilabel>Author</guilabel>, <guilabel>Abbreviation</guilabel>,
              and <guilabel>Publication information</guilabel>. You can type
              this information directly into the adjacent fields.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Note</term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab provides a place to
              record various information about the source that does not fit
              neatly into other categories. To add a note or modify existing
              notes simply edit the text in the text entry field.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Data</term>

            <listitem>
              <para>The <guilabel>Data</guilabel> tab displays "Key/Value"
              pairs that may be associated with the source. These are similar
              to the "Attributes" used for other types of GRAMPS records. The
              difference between these Key/Value pairs and Attributes is that
              Attributes may have source references and notes, while Key/Value
              data may not.</para>

              <para>The central part of the window lists all existing
              Key/Value pairs. The buttons <guibutton>+</guibutton> and
              <guibutton>-</guibutton> let you add and remove pairs. To modify
              the text of Key or Value, first select the desired entry. Then
              click in either the Key or Value cell of that entry and type
              your text. When you are done, click outside the cell to exit
              editing mode.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Gallery</term>

            <listitem>
              <para>The <guilabel>Gallery</guilabel> tab lets you store and
              display photos and other media objects associated with a given
              source (for example, a photo of a birth certificate). The
              central part of the window lists all such media objects and
              gives you a thumbnail preview of image files. Other objects such
              as audio files, movie files, etc., are represented by a generic
              GRAMPS icon. The buttons <guibutton>+</guibutton>,
              <guibutton>Select</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> let you add a new image, add a
              reference to an existing image, modify an existing image, and
              remove a media object's link to the source. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
              become available only when a media object is selected from the
              list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>References</term>

            <listitem>
              <para>The <guilabel>References</guilabel> tab lists all the
              database records that refer to this source, if any. The list can
              be ordered by any of its column headings:
              <guilabel>Type</guilabel>, <guilabel>ID</guilabel>, or
              <guilabel>Name</guilabel>. Double-clicking an entry allows you
              to view and edit the record.</para>

              <note>
                <para>Only primary objects can be shown in the
                <guilabel>References</guilabel> tab: Person, Family, Event,
                Place, or Media object. Secondary objects such as Names and
                Attributes can only be accessed through the primary objects to
                which they belong.</para>
              </note>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-plc">
        <title>Editing Information About Places</title>

        <para>To edit information about places, switch to the Places View and
        select the desired entry from the list of places. Double-click that
        entry or click the <guibutton>Edit</guibutton> button on the toolbar
        to bring up the following <guilabel>Place Editor</guilabel>
        dialog:</para>

        <!-- ==== Figure: Place Editor dialog ==== -->

        <figure id="edit-plc-fig">
          <title>Place Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-plc.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Place Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The main part of the window displays seven notebook tabs
        containing different categories of information. Click a tab to view or
        edit its contents. The bottom part of the window has
        <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> buttons.
        Clicking <guibutton>OK</guibutton> will apply all the changes made in
        all tabs and close the dialog window. Clicking the
        <guibutton>Cancel</guibutton> button will close the window without
        applying any changes.</para>

        <note>
          <para>Clicking <guibutton>OK</guibutton> will immediately save
          changes to the database). All changes are immediate.</para>
        </note>

        <tip>
          <para>If a tab label is in boldface type, this means it contains
          data. If not, it has no data.</para>
        </tip>

        <para>The tabs represent following categories of place data:</para>

        <variablelist>
          <varlistentry>
            <term>General</term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab you view and edit the
              basic information about the place: the
              <guilabel>Title</guilabel> which labels it in the database,
              <guilabel>City</guilabel>, <guilabel>Church parish</guilabel>,
              <guilabel>County</guilabel>, <guilabel>State</guilabel>,
              <guilabel>Country</guilabel>, <guilabel>Longitude</guilabel>,
              and <guilabel>Latitude</guilabel>. You can type this information
              directly into the adjacent fields.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Other names</term>

            <listitem>
              <para>The <guilabel>Other names</guilabel> tab lets you view and
              edit other names by which the place might be known. The bottom
              part of the window lists all other names of the place stored in
              the database. The top part of the window shows the details of
              the currently selected name in the list (if any). The buttons
              <guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> let you add, modify, and remove a name
              record. Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when a
              name is selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Note</term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab displays any comments or
              notes concerning the place. To add a note or modify existing
              notes simply edit the text in the text entry field.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Sources</guilabel></term>

            <listitem>
              <para>The <guilabel>Sources</guilabel> tab lets you view and
              edit sources relevant to a place. The central part of the window
              lists all such source references stored in the database. The
              buttons <guibutton>+</guibutton>, <guibutton>Edit</guibutton>,
              and <guibutton>-</guibutton> let you add, modify, and remove a
              source reference associated with a place. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
              become available only when a source reference is selected from
              the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Gallery</term>

            <listitem>
              <para>The <guilabel>Gallery</guilabel> tab lets you store and
              display photos and other media objects associated with a given
              place. The central part of the window lists all such media
              objects and gives you a thumbnail preview of image files. Other
              objects such as audio files, movie files, etc., are represented
              by a generic GRAMPS icon. The buttons <guibutton>+</guibutton>,
              <guibutton>Select</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> let you add a new image, add a
              reference to an existing image, modify an existing image, and
              remove a media object's link to the place. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
              become available only when a media object is selected from the
              list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Internet</term>

            <listitem>
              <para>The <guilabel>Internet</guilabel> tab contains Internet
              addresses relevant to the place. The bottom part of the window
              lists all such Internet addresses stored in the database. The
              top part shows the details of the currently selected address in
              the list (if any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, and remove an Internet address. The
              <guibutton>Go</guibutton> button (represented by an icon with a
              green arrow and yellow circle) opens your browser and takes you
              to the web page corresponding to the highlighted Internet
              address. Note that the <guibutton>Edit</guibutton>,
              <guibutton>-</guibutton>, and <guibutton>Go</guibutton> buttons
              become available only when an address is selected from the
              list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>References</term>

            <listitem>
              <para>The <guilabel>References</guilabel> tab indicates any
              database records (events or LDS ordinances) that refer to a
              place. This information cannot be modified from the Place Editor
              dialog. Instead, the corresponding database record (e.g., a
              birth event) has to be brought up and its place reference
              edited.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-media">
        <title>Editing Information About Media Objects</title>

        <para>To edit media data, switch to the Media View and select the
        desired entry in the list of sources. Double-click on that entry or
        click <guibutton>Edit</guibutton> on the toolbar to invoke the
        following <guilabel>Media Properties Editor</guilabel> dialog:</para>

        <!-- ==== Figure: Edit Media Properties dialog ==== -->

        <figure id="edit-media-fig">
          <title>Media Properties Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-media.png"
                           format="PNG" width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Media Properties Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>A thumbnail preview of the object is presented, along with a
        summary of its properties (ID, path, and object type). The central
        part of the window displays five notebook tabs containing different
        categories of information. Click a tab to view or edit its contents.
        The bottom part of the window has <guibutton>OK</guibutton> and
        <guibutton>Cancel</guibutton> buttons. Clicking
        <guibutton>OK</guibutton> will apply all the changes made in all tabs
        and close the dialog window. Clicking the
        <guibutton>Cancel</guibutton> button will close the window without
        applying any changes.</para>

        <note>
          <para>Clicking <guibutton>OK</guibutton> will immediately save
          changes to the database (write on disk). All changes are
          immediate.</para>
        </note>

        <tip>
          <para>If a tab label is in boldface type, this means it contains
          data. If not, it has no data.</para>
        </tip>

        <para>The tabs represent the following categories of media
        data:</para>

        <variablelist>
          <varlistentry>
            <term>General</term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab lets you view and
              edit the object's Title and Date. You can type this information
              directly into the corresponding fields. For the Date, you can
              also enter information by clicking the LED button and invoking
              the <guilabel>Date selection</guilabel> dialog.</para>

              <note>
                <para>Every media object is referred to by its Path. The user
                is responsible for keeping track of the object files. GRAMPS
                will only reference and display the contents, not manage the
                files themselves.</para>
              </note>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Attributes</term>

            <listitem>
              <para>The <guilabel>Attributes</guilabel> tab lets you view and
              edit particular information about the media object that can be
              expressed as Attributes. The bottom part displays the list of
              all such attributes stored in the database. The top part shows
              the details of the currently selected attribute in the list (if
              any). The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, or remove an attribute. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
              become available only when an attribute is selected from the
              list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Notes</term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab provides a place to
              record various information about the source that does not fit
              neatly into other categories. This area is particularly useful
              for recording information that does not naturally fit into the
              "Parameter/Value" pairs available to Attributes. To add a note
              or modify existing notes simply edit the text in the text entry
              field.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>References</term>

            <listitem>
              <para>The <guilabel>References</guilabel> tab indicates any
              database records that refer to a given media object. The list
              can be ordered according to any of its column headings:
              <guilabel>Type</guilabel>, <guilabel>ID</guilabel>, or
              <guilabel>Name</guilabel>. Double-clicking an entry allows you
              to view and edit the corresponding record.</para>

              <note>
                <para>Only primary objects can be shown in the
                <guilabel>References</guilabel> tab: Person, Family, Event,
                Source, or Place. The secondary objects such as Names and
                Attributes, although able to refer the media object, will only
                show up through their primary objects to which they
                belong.</para>
              </note>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-ev">
        <title>Editing Information About Events</title>

        <para>Events are edited through the <guilabel>Event Editor</guilabel>
        dialog. This dialog can be accessed from either the <guilabel>Edit
        Person</guilabel> dialog or the
        <guilabel>Marriage/Relationship</guilabel> dialog.</para>

        <!-- ==== Figure: Event Editor dialog ==== -->

        <figure id="edit-ev-fig">
          <title>Event Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-ev.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Event Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The central part of the window displays five notebook tabs
        containing different categories of information. Click a tab to view or
        edit its contents. The bottom part of the window has
        <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> buttons.
        Clicking <guibutton>OK</guibutton> will apply all the changes made in
        all tabs and close the dialog window. Clicking the
        <guibutton>Cancel</guibutton> button will close the window without
        applying any changes.</para>

        <tip>
          <para>If a tab label is in boldface type, this means it contains
          data. If not, it has no data.</para>
        </tip>

        <para>The tabs provide the following information categories of the
        event data:</para>

        <variablelist>
          <varlistentry>
            <term>General</term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab lets you view and
              edit basic information about the event: its
              <guilabel>Type</guilabel>, <guilabel>Date</guilabel>,
              <guilabel>Place</guilabel>, <guilabel>Cause</guilabel>, and
              <guilabel>Description</guilabel>. You can type this information
              directly into the adjacent fields. The type can be selected from
              available types listed in the Event type drop-down menu. The
              rest of the information can be typed in the appropriate text
              entry fields. Checking the Private record box marks the event
              record as private and allows it to be omitted from
              reports.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Sources</term>

            <listitem>
              <para>The <guilabel>Sources</guilabel> tab lets you view and
              edit sources relevant to an event. The central part of the
              window lists all such source references stored in the database.
              The buttons <guibutton>+</guibutton>,
              <guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
              you add, modify, and remove a source reference associated with a
              place. Note that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when a
              source reference is selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term>Note</term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab provides a place to
              record notes or comments about the event. To add a note or
              modify existing notes simply edit the text in the text entry
              field.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <!-- END OF EDIT -->

      <sect2 id="adv-si">
        <title>Editing Source References</title>

        <para>Source references connect a Source to another object and allow
        you to provide additional information about the source. When adding
        source references to events, places, etc., the following dialog
        appears:</para>

        <!-- ==== Figure: Source Information dialog ==== -->

        <figure id="edit-si-fig">
          <title>Source Information dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-si.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Source Information dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The dialog includes two main headings, <guilabel>Source
        selection</guilabel> and <guilabel>Source details</guilabel>.
        <guilabel>Source selection</guilabel> displays the
        <guilabel>Title</guilabel> of the Source, its
        <guilabel>Author</guilabel>, and <guilabel>Publication
        information</guilabel>. The <guilabel>Title</guilabel> can be selected
        from the available sources listed in the drop-down menu. If the source
        you are referencing is not already in the database, you can enter it
        by clicking <guibutton>New...</guibutton> and filling out the invoked
        <guilabel>Source Editor</guilabel> dialog.</para>

        <para>The <guilabel>Source details</guilabel> section indicates the
        details associated with the particular reference to this Source:
        <guilabel>Confidence</guilabel>,
        <guilabel>Volume/Film/Page</guilabel>, <guilabel>Date</guilabel>,
        <guilabel>Text</guilabel>, and <guilabel>Comments</guilabel>. You can
        choose the Confidence level from the <guilabel>Confidence</guilabel>
        drop-down menu. The remaining details can be typed in the
        corresponding text entry fields.</para>

        <tip>
          <para>Information in this dialog is specific to the particular
          reference. A single source can be referenced many times, and all
          such references will have in common the overall source information.
          This dialog lets you provide reference-specific data, such as
          relevant quotes, comments, confidence, page numbers, etc., to
          further specify and document the reference.</para>
        </tip>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-an">
        <title>Names</title>

        <para>Names are edited through the following <guilabel>Name
        Editor</guilabel> dialog:</para>

        <!-- ==== Figure: Names Editor dialog ==== -->

        <figure id="edit-an-fig">
          <title>Name Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-an.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Name Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The top of the window shows the dialog title including the name
        of the person whose name is being edited. The central part of the
        window displays three notebook tabs containing different categories of
        available information. You can bring any tab to the top for viewing or
        editing by clicking on the appropriate tab heading. The bottom part
        has <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton>
        buttons. Clicking the <guibutton>OK</guibutton> button at any time
        will apply all the changes made in all tabs and close the dialog
        window. Clicking the <guibutton>Cancel</guibutton> button at any time
        will close the window without applying any changes.</para>

        <tip>
          <para>The tab labels reflect the presence of corresponding
          information: if the tab contains any data, its label appears
          boldface; if the tab has no data then its label appears regular (not
          bold).</para>
        </tip>

        <para>The tabs provide the following information categories of the
        name data:</para>

        <variablelist>
          <varlistentry>
            <term><guilabel>General</guilabel></term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab allows editing of
              general information about the name: given name, family name,
              patronymic (a form of father's name used in some languages, e.g.
              Russian), family prefix, suffix, title, and type of the name.
              The information can be typed in the appropriate text entry
              fields. The family name and the type can be also selected from
              available choices listed in the appropriate drop-down
              menus.</para>

              <para><guilabel>Options</guilabel> allow you to adjust specific
              grouping, sorting, and displaying properties of this name, as
              well as to provide the date corresponding to the name. The
              <guilabel>Grouping</guilabel> field provides an alternative
              grouping node for a given name, overriding the default grouping
              based on the family name. This may be necessary with similar
              family names that need to be grouped together -- for example
              Russian names Ivanov and Ivanova are considered the same, but
              difference in gender is reflected in different spelling. To
              enable typing into this field, check the
              <guilabel>Override</guilabel> check button. The <guilabel>Sort
              as</guilabel> and <guilabel>Display as</guilabel> determine the
              manner in which the name appears in the People View and in the
              reports. The <guilabel>Date</guilabel> can provide information
              on the validity of this name -- use spans as necessary. Check
              the <guilabel>Private record</guilabel> box to mark this name
              record as private. This will give you a chance to omit this name
              from being included in reports, if you choose so among the
              report generation options.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Sources</guilabel></term>

            <listitem>
              <para>The <guilabel>Sources</guilabel> tab displays information
              about sources relevant to this name and controls allowing its
              modification. The central part displays the list of all such
              sources' references stored in the database. The buttons
              <guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> allow you to correspondingly add,
              modify, and remove a source reference to this name. Note that
              the <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
              buttons become available only when a source reference is
              selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Note</guilabel></term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab displays any notes
              concerning the name. To add a note or modify existing notes
              simply edit the text in the text entry field.</para>

              <para>The <guilabel>Format</guilabel> option allows you to set
              the appearance of the note in the output (i.e. in reports and
              web pages). Selecting <guilabel>Flowed</guilabel> will replace
              all multiple spaces, tabs, and single end-of-line characters
              with single space in the output. The two consecutive new lines
              (i.e. an empty line) denote a new paragraph. Selecting
              <guilabel>Preformatted</guilabel> will honor all multiple spaces
              tabs, and new lines, so that the output will appear as it is
              entered into the text entry field.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-at">
        <title>Attributes</title>

        <para>Attributes are edited through the following <guilabel>Attribute
        Editor</guilabel> dialog:</para>

        <!-- ==== Figure: Attribute Editor dialog ==== -->

        <figure id="edit-at-fig">
          <title>Attribute Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-at.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Attribute Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The top of the window shows the dialog title including the name
        of the person whose attribute is being edited. The central part of the
        window displays three notebook tabs containing different categories of
        available information. You can bring any tab to the top for viewing or
        editing by clicking on the appropriate tab heading. The bottom part
        has <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton>
        buttons. Clicking the <guibutton>OK</guibutton> button at any time
        will apply all the changes made in all tabs and close the dialog
        window. Clicking the <guibutton>Cancel</guibutton> button at any time
        will close the window without applying any changes.</para>

        <tip>
          <para>The tab labels reflect the presence of corresponding
          information: if the tab contains any data, its label appears
          boldface; if the tab has no data then its label appears regular (not
          bold).</para>
        </tip>

        <para>The tabs provide the following information categories of the
        attribute data:</para>

        <variablelist>
          <varlistentry>
            <term><guilabel>General</guilabel></term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab allows editing of the
              most general information about the attribute: name of the
              attribute and its value. The information can be typed in the
              appropriate text entry fields. The attribute name can also be
              selected from available choices (if any) listed in the
              <guilabel>Attribute </guilabel> drop-down menu. Check the
              <guilabel>Private record</guilabel> box to mark this attribute
              record as private. This will give you a chance to omit this
              attribute from being included in the reports, if you choose so
              among the report generation options.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Sources</guilabel></term>

            <listitem>
              <para>The <guilabel>Sources</guilabel> tab displays information
              about sources relevant to this attribute and controls allowing
              its modification. The central part displays the list of all such
              sources references stored in the database. The buttons
              <guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> allow you to correspondingly add,
              modify, and remove a source reference to this attribute. Note
              that the <guibutton>Edit</guibutton> and
              <guibutton>-</guibutton> buttons become available only when a
              source reference is selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Note</guilabel></term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab displays any notes
              concerning the attribute. To add a note or modify existing notes
              simply edit the text in the text entry field.</para>

              <para>The <guilabel>Format</guilabel> option allows you to set
              the appearance of the note in the output (i.e. in reports and
              web pages). Selecting <guilabel>Flowed</guilabel> will replace
              all multiple spaces, tabs, and single end-of-line characters
              with single space in the output. The two consecutive new lines
              (i.e. an empty line) denote a new paragraph. Selecting
              <guilabel>Preformatted</guilabel> will honor all multiple spaces
              tabs, and new lines, so that the output will appear as it is
              entered into the text entry field.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-ad">
        <title>Addresses</title>

        <para>Addresses are edited through the following <guilabel>Address
        Editor</guilabel> dialog:</para>

        <!-- ==== Figure: Address Editor dialog ==== -->

        <figure id="edit-ad-fig">
          <title>Address Editor dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="" fileref="figures/edit-ad.png" format="PNG"
                           width="" />
              </imageobject>

              <textobject>
                <phrase>Shows Address Editor dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The top of the window shows the dialog title including the name
        of the person whose address is being edited. The central part of the
        window displays three notebook tabs containing different categories of
        available information. You can bring any tab to the top for viewing or
        editing by clicking on the appropriate tab heading. The bottom part
        has <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton>
        buttons. Clicking the <guibutton>OK</guibutton> button at any time
        will apply all the changes made in all tabs and close the dialog
        window. Clicking the <guibutton>Cancel</guibutton> button at any time
        will close the window without applying any changes.</para>

        <tip>
          <para>The tab labels reflect the presence of corresponding
          information: if the tab contains any data, its label appears
          boldface; if the tab has no data then its label appears regular (not
          bold).</para>
        </tip>

        <para>The tabs provide the following information categories of the
        address data:</para>

        <variablelist>
          <varlistentry>
            <term><guilabel>General</guilabel></term>

            <listitem>
              <para>The <guilabel>General</guilabel> tab allows editing of the
              most general information about the address: date, street
              address, city or county, state or province, country, the postal
              code, and the phone number. The information can be typed in the
              appropriate text entry fields. Check the <guilabel>Private
              record</guilabel> box to mark this address record as private.
              This will give you a chance to omit this address from being
              included in reports, if you choose so among the report
              generation options.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Sources</guilabel></term>

            <listitem>
              <para>The <guilabel>Sources</guilabel> tab displays information
              about sources relevant to this address and controls allowing its
              modification. The central part displays the list of all such
              sources references stored in the database. The buttons
              <guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
              <guibutton>-</guibutton> allow you to correspondingly add,
              modify, and remove a source reference to this address. Note that
              the <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
              buttons become available only when a source reference is
              selected from the list.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
          <varlistentry>
            <term><guilabel>Note</guilabel></term>

            <listitem>
              <para>The <guilabel>Note</guilabel> tab displays any notes
              concerning the address. To add a note or modify existing notes
              simply edit the text in the text entry field.</para>

              <para>The <guilabel>Format</guilabel> option allows you to set
              the appearance of the note in the output (i.e. in reports and
              web pages). Selecting <guilabel>Flowed</guilabel> will replace
              all multiple spaces, tabs, and single end-of-line characters
              with single space in the output. The two consecutive new lines
              (i.e. an empty line) denote a new paragraph. Selecting
              <guilabel>Preformatted</guilabel> will honor all multiple spaces
              tabs, and new lines, so that the output will appear as it is
              entered into the text entry field.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="adv-merge">
        <title>Merging records</title>

        <para>Sometime several records in the database turn out to be
        describing the same object: same person, same place, or same source.
        It could happen either when the data is entered twice by mistake, or
        when new information reveals that the two entries refer to the same
        person. It can also happen after importing GEDCOM obtained from a
        relative, whose database overlaps with your existing data.</para>

        <para>Whenever you detect duplicate records, merging them a useful way
        of correcting the situation.</para>

        <tip>
          <para>To make a merge, exactly two records have to be selected in
          the appropriate view (People View, Sources View, or Places View).
          This is accomplished by selecting one entry and then selecting
          another person while holding down <keycap>Ctrl</keycap> key.</para>
        </tip>

        <sect3 id="adv-merge-people">
          <title>Merge People</title>

          <para>There are two ways of merging personal records:
          <guilabel>Compare and Merge</guilabel> and <guilabel>Fast
          Merge</guilabel>, both available from the <guimenu>Edit</guimenu>
          menu.</para>

          <note>
            <para>Merging people does not discard any information with either
            method. The decisions you make during the merge only affect which
            data will become primary and which will become secondary for the
            resulting merged record.</para>
          </note>

          <variablelist>
            <varlistentry>
              <term><guilabel>Compare and Merge</guilabel></term>

              <listitem>
                <para>When exactly two people are selected, choose <menuchoice>
                    <guimenu>Edit</guimenu>

                    <guimenuitem>Compare and Merge...</guimenuitem>
                  </menuchoice> to invoke <guilabel>Compare People</guilabel>
                dialog.</para>

                <!-- ==== Figure: Compare People dialog ==== -->

                <figure id="comp-people-fig">
                  <title>Compare People dialog</title>

                  <screenshot>
                    <mediaobject>
                      <imageobject>
                        <imagedata depth="469"
                                   fileref="figures/comp-people.png"
                                   format="PNG" width="500" />
                      </imageobject>

                      <textobject>
                        <phrase>Shows Compare People dialog.</phrase>
                      </textobject>
                    </mediaobject>
                  </screenshot>
                </figure>

                <!-- ==== End of Figure ==== -->

                <para>The dialog allows you to make a decision on whether or
                not the selected records should be merged. If you decide that
                the records should not be merged, despite similar names, you
                may click <guibutton>Cancel</guibutton> to close the dialog
                without making any changes. If you decide to proceed with
                merging, select the appropriate <guilabel>Select</guilabel>
                radio button to specify the record to be used as the source of
                primary data, then click <guibutton>Merge and
                close</guibutton>.</para>

                <para>The data from the other record will be kept as alternate
                data. Specifically, all names from the other record will
                become alternate names of the merged record. Similarly,
                parents, spouses, and children of the other record will become
                alternate parents, spouses, and children of the merged record,
                and so on.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <variablelist>
            <varlistentry>
              <term><guilabel>Fast Merge</guilabel></term>

              <listitem>
                <para>When exactly two people are selected, choose <menuchoice>
                    <guimenu>Edit</guimenu>

                    <guimenuitem>Fast Merge</guimenuitem>
                  </menuchoice> to invoke <guilabel>Merge People</guilabel>
                dialog.</para>

                <!-- ==== Figure: Compare People dialog ==== -->

                <figure id="merge-people-fig">
                  <title>Merge People dialog</title>

                  <screenshot>
                    <mediaobject>
                      <imageobject>
                        <imagedata depth="245"
                                   fileref="figures/merge-people.png"
                                   format="PNG" width="382" />
                      </imageobject>

                      <textobject>
                        <phrase>Shows Merge People dialog.</phrase>
                      </textobject>
                    </mediaobject>
                  </screenshot>
                </figure>

                <!-- ==== End of Figure ==== -->

                <para>The dialog allows you to quickly merge two records,
                specifying the record to be used as the source of primary
                data. The data from the other record will be kept as alternate
                data. Specifically, all names from the other record will
                become alternate names of the merged record. Similarly,
                parents, spouses, and children of the other record will become
                alternate parents, spouses, and children of the merged record,
                and so on.</para>

                <tip>
                  <para>If you are not certain whether or not you need to
                  merge the records, or which record to specify as the source
                  of primary data, use <guilabel>Compare and Merge</guilabel>
                  method described above..</para>
                </tip>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <!-- ================ Usage Sub-subsection ================ -->

        <sect3 id="adv-merge-sources">
          <title>Merge Sources</title>

          <para>When exactly two sources are selected, choose <menuchoice>
              <guimenu>Edit</guimenu>

              <guimenuitem>Compare and Merge...</guimenuitem>
            </menuchoice> to invoke <guilabel>Merge Sources</guilabel>
          dialog.</para>

          <!-- ==== Figure: Merge Sources dialog ==== -->

          <figure id="merge-src-fig">
            <title>Merge Sources dialog</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata depth="224" fileref="figures/merge-src.png"
                             format="PNG" width="500" />
                </imageobject>

                <textobject>
                  <phrase>Shows Merge Sources dialog.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>

          <!-- ==== End of Figure ==== -->

          <para>The dialog allows you to make a decision on whether or not the
          selected records should be merged. If you decide that the records
          should not be merged, despite similar titles, you may click
          <guibutton>Cancel</guibutton> to close the dialog without making any
          changes. If you decide to proceed with merging, choose the
          appropriate radio button to specify the title, author, abbreviated
          title, publication information, and the ID to be used for the merged
          record, then click <guibutton>OK</guibutton>.</para>
        </sect3>

        <sect3 id="adv-merge-places">
          <title>Merge Places</title>

          <para>When exactly two places are selected, choose <menuchoice>
              <guimenu>Edit</guimenu>

              <guimenuitem>Compare and Merge...</guimenuitem>
            </menuchoice> to invoke <guilabel>Select title</guilabel>
          dialog.</para>

          <!-- ==== Figure: Select title dialog ==== -->

          <figure id="merge-plc-fig">
            <title>Merge Places dialog</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata depth="185" fileref="figures/merge-plc.png"
                             format="PNG" width="400" />
                </imageobject>

                <textobject>
                  <phrase>Shows Select title dialog.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>

          <!-- ==== End of Figure ==== -->

          <para>The dialog allows you to make a decision on whether or not the
          selected records should be merged. If you decide that the records
          should not be merged, despite similar titles, you may click
          <guibutton>Cancel</guibutton> to close the dialog without making any
          changes. If you decide to proceed with merging, choose the
          appropriate radio button to specify the title of the merged record,
          or specify <guilabel>Other</guilabel> and enter new text, then click
          <guibutton>OK</guibutton>.</para>
        </sect3>
      </sect2>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="gramps-nav">
      <title>Navigation</title>

      <para>As long as any database is open, GRAMPS is focused on a single
      person usually referred to as an Active person. This allows you to view
      or modify the data concerning this person, his or her immediate family,
      etc. Navigating in the database (i.e. moving from person to person) is
      in fact nothing else but changing the Active person. This section
      describes many alternative ways to navigate through the database using
      both the complex and the convenient interfaces GRAMPS provides. All
      these ways eventually accomplish the same thing, but some are more
      convenient than others, depending what you are doing in GRAMPS at the
      moment.</para>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-people">
        <title>Using the People View</title>

        <para>The most intuitive way to select an active person is to use the
        People View (see <xref linkend="people-view" />). When in the People
        View, just select the name of the desired person from the list by
        clicking that list entry. The person you have selected becomes active.
        The statusbar updates to reflect the change of the active
        person.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-family">
        <title>Using the Family View</title>

        <para>When in the Family View (see <xref
        linkend="relationships-view" />), you can easily navigate between the
        members of the displayed family as follows:</para>

        <itemizedlist>
          <listitem>
            <para>To make the currently selected spouse the active person,
            click the double-arrow button to the right of the active person
            box. Alternatively, right-click into the spouse box and select
            <guilabel>Make the selected spouse an active person</guilabel>
            item from the context menu.</para>
          </listitem>

          <listitem>
            <para>To make the currently selected parents the active family
            (thereby making father the active person and mother the selected
            spouse), click the right-arrow button to the right of the active
            person's parents box. Alternatively, right-click into the active
            person's parents box and select <guilabel>Make the selected
            parents the active family</guilabel> item from the context
            menu.</para>
          </listitem>

          <listitem>
            <para>To make the currently selected spouse's parents the active
            family (thereby making father the active person and mother the
            selected spouse), click the right-arrow button to the right of the
            spouse's parents box. Alternatively, right-click into the spouse's
            parents box and select <guilabel>Make the selected parents the
            active family</guilabel> item from the context menu.</para>
          </listitem>

          <listitem>
            <para>To make the currently selected child the active person,
            click the left-arrow button to the right of the children box.
            Alternatively, right-click into the children box and select
            <guilabel>Make the selected child an active person</guilabel> item
            from the context menu.</para>
          </listitem>
        </itemizedlist>

        <para>In addition to this, GRAMPS provides an extensive set of
        keyboard navigation options. The detailed reference to the key
        bindings is found in the <xref linkend="append-keybind" />.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-pedigree">
        <title>Using the Pedigree View</title>

        <para>The Pedigree View (see <xref linkend="pedigree-view" />) also
        allows you to move along the family tree. The benefit of this method
        is that you can see more than one generation of the family tree. Also,
        you can jump directly from a great-grandson to a great-grandfather
        without going through the intermediate generations.</para>

        <para>Note that after changing the active person in the Pedigree View,
        the display is re-adjusted to show four generations, starting from the
        newly selected Active person. When in the Pedigree View, you can
        easily navigate between the members of the displayed family tree as
        follows:</para>

        <itemizedlist>
          <listitem>
            <para>To make any displayed person the active person, double-click
            the line that connects to the left side of the corresponding
            box.</para>
          </listitem>

          <listitem>
            <para>To make a child of the currently active person (if any) the
            active person, click the left arrow button to the left of the
            corresponding box. If there is more than one child, the button
            expands to the menu listing the children to choose from.</para>
          </listitem>

          <listitem>
            <para>To move the whole family tree one generation back, click on
            the corresponding right arrow button on the right-hand side of the
            display area. Clicking the upper button will move the tree along
            the paternal line. Clicking the lower button will move the tree
            along the maternal line.</para>

            <para>Clicking either of these buttons is completely equivalent to
            double-clicking the lines connecting to the left of the
            corresponding boxes for father and mother.</para>
          </listitem>
        </itemizedlist>

        <para>You can also quickly access any of the spouses, siblings,
        children, or parents of any displayed person. To do this, move the
        mouse over the desired person's box and right-click to invoke a
        context menu. The appropriate menu items will contain submenus listing
        all spouses, siblings, children, and parents of the corresponding
        person.</para>

        <tip>
          <title>Advantages of using right-click menus</title>

          <itemizedlist>
            <listitem>
              <para>Direct access to spouse and siblings</para>
            </listitem>

            <listitem>
              <para>Complete lists of all member of all categories, not only
              the preferred members.</para>
            </listitem>
          </itemizedlist>
        </tip>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-default">
        <title>Setting the Home Person</title>

        <para>One and only one person in the database can be selected as the
        Home person. Once the Home person is selected, moving to that person
        becomes a matter of a single click, regardless of which view you are
        using at the moment.</para>

        <para>To set the Home person, first navigate to that person using any
        method you like. Then choose <menuchoice>
            <guimenu>Edit</guimenu>

            <guimenuitem>Set Home person</guimenuitem>
          </menuchoice>. Once this is done, you can move to the Home person
        from anywhere in the database by simply clicking the
        <guibutton>Home</guibutton> icon on the toolbar. You can also choose
        <menuchoice>
            <guimenu>Go</guimenu>

            <guimenuitem>Home</guimenuitem>
          </menuchoice> from the menu or select <guilabel>Home</guilabel> item
        from any context menu available on the right click.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-history">
        <title>Using history-based tools</title>

        <para>GRAMPS also features a powerful set of history-based navigation
        tools. These tools are similar to those commonly used in web browsers.
        They include <guilabel>Back</guilabel> and
        <guilabel>Forward</guilabel> items available from the <menuchoice>
            <guimenu>Go</guimenu>
          </menuchoice> menu, context menus (available in People, Family, and
        Pedigree views), and the toolbar buttons. They also include the list
        of the recent selections available under the <menuchoice>
            <guimenu>Go</guimenu>
          </menuchoice> menu that allows you to jump directly to any of the
        recent selections. Finally, right-clicking on the
        <guibutton>Back</guibutton> and <guibutton>Forward</guibutton> toolbar
        buttons invokes the popup menu with corresponding portion of the
        history. Select any item from the menu to jump directly to it.</para>
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-bookmk">
        <title>Bookmarking People</title>

        <para>Similar to setting the Home person, you can bookmark other
        people from the database to simplify further navigation. To bookmark a
        person, first navigate to that person, then choose <menuchoice>
            <guimenu>Bookmarks</guimenu>

            <guimenuitem>Add bookmark</guimenuitem>
          </menuchoice>. To move to that person from anywhere in the database,
        choose <menuchoice>
            <guimenu>Bookmarks</guimenu>

            <guisubmenu>Go to bookmark</guisubmenu>

            <guimenuitem><replaceable>Person's
            name</replaceable></guimenuitem>
          </menuchoice>.</para>

        <para>You can manage your bookmarks by choosing <menuchoice>
            <guimenu>Bookmarks</guimenu>

            <guimenuitem>Edit bookmarks...</guimenuitem>
          </menuchoice>. This opens the following <guilabel>Edit
        Bookmarks</guilabel> dialog with the list of bookmarks and the
        controls to modify this list.</para>

        <!-- ==== Figure: Edit Bookmarks dialog ==== -->

        <figure id="edit-bm-fig">
          <title>Edit Bookmarks dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="376" fileref="figures/edit-bm.png"
                           format="PNG" width="412" />
              </imageobject>

              <textobject>
                <phrase>Shows Edit Bookmarks dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->
      </sect2>

      <!-- ================ Usage Sub-subsection ================ -->

      <sect2 id="gramps-nav-find">
        <title>Finding records</title>

        <para>To find a record in a database, first switch to the appropriate
        View that provides the list of the desired records: People, Sources,
        Places, or Media. Then start typing the name of a person or the title
        of a Source, Place, or Media object that you are looking for,
        respectively. You may also press <keycap>Ctrl+F</keycap> to turn on
        the search mode, but simply staring to type is also enough.</para>

        <!-- ==== Figure: Type-ahead find ==== -->

        <figure id="find-people-fig">
          <title>Type-ahead find</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="352" fileref="figures/find-people.png"
                           format="PNG" width="500" />
              </imageobject>

              <textobject>
                <phrase>Shows type-ahead find.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>As you type, the first record in the list that is compatible
        with your input will be selected.</para>

        <tip>
          <title>Finding People</title>

          <para>For more complex people searches you may want to use filters.
          Enable filter controls by choosing <menuchoice>
              <guimenu>View</guimenu>

              <guimenuitem>Filter</guimenuitem>
            </menuchoice>, select the desired filter, and click
          <guibutton>Apply</guibutton>. For details, see <xref
          linkend="filters" /></para>
        </tip>
      </sect2>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="gen-reports">
      <title>Generating Reports</title>

      <para>Reports are the most common form of the output produced by
      genealogical research. The majority of genealogical software puts a lot
      of emphasis on developing nice looking reports. GRAMPS is no exception
      in this regard, offering a choice of a variety of reports. GRAMPS can
      generate reports in a multitude of open formats, both text based and
      graphical. GRAMPS can also produce screen based reports that are
      convenient for viewing a summary of your database. Finally, GRAMPS can
      generate a web site suitable for immediate posting on the Internet. All
      of these are almost infinitely flexible. If you wish to modify or extend
      the default format of GRAMPS report, you can design and choose the style
      for each of your reports.</para>

      <para>All reports can be accessed through the menu by choosing
      <menuchoice>
          <guimenu>Reports</guimenu>

          <guisubmenu><replaceable>Report Type</replaceable></guisubmenu>

          <guimenuitem><replaceable>Particular
          Report</replaceable></guimenuitem>
        </menuchoice>. Alternatively, you can browse the complete selection of
      available reports along with their brief descriptions in a
      <guilabel>Report Selection</guilabel> dialog invoked by clicking the
      <guibutton>Reports</guibutton> icon on the toolbar.</para>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="subst-values">
        <title>Substitution Values</title>

        <para>Many of the graphical reports allow you to customize the
        information on the display. Variable substituions are used to
        substitute date for a particular symbol. There are two styles of
        variables. The difference between the two styles is how empty data is
        handled.</para>

        <para>The first style of variables are preceeded by a '$'. If the
        variable evaluates to an empty string, the variable is replaced with
        the empty string. The second style of variables are preceeded by a
        '%'. If the variable evaluates to an empty string, the line that
        contains the variable is removed from the output.</para>

        <variablelist>
          <varlistentry>
            <term>$n/%n</term>

            <listitem>
              <para>Displays the person's name in the form of FirstName
              LastName</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$N/%N</term>

            <listitem>
              <para>Displays the person's name in the form of LastName,
              FirstName</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$i/%i</term>

            <listitem>
              <para>Displays the GRAMPS ID associated with the person.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$b/%b</term>

            <listitem>
              <para>Displays the person's date of birth</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$B/%B</term>

            <listitem>
              <para>Displays the person's place of birth</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$d/%d</term>

            <listitem>
              <para>Displays the person's date of death</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$D/%D</term>

            <listitem>
              <para>Displays the person's place of death</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$s/%s</term>

            <listitem>
              <para>Displays the name of the person's preferred spouse in the
              form of FirstName LastName</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$S/%S</term>

            <listitem>
              <para>Displays the name of the person's preferred spouse in the
              form of LastName, FirstName.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$m/%m</term>

            <listitem>
              <para>Displays the marriage date of the person and the preferred
              spouse.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$M/%M</term>

            <listitem>
              <para>Displays the place assocated with the marriage of the
              person and the preferred spouse.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <sect2 id="rep-books">
        <title>Books</title>

        <para>Currently, the only available report under this category is the
        Book Report.</para>

        <para>The Book Report creates a single document (i.e. a Book)
        containing a collection of graphical and textual reports.
        Consequently, this allows for a very rich set of documents that GRAMPS
        can produce.</para>

        <para>When Book Report is selected, the following book configuration
        dialog appears:</para>

        <!-- ==== Figure: Book Report dialog ==== -->

        <figure id="rep-book-fig">
          <title>Book Report dialog</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata depth="524" fileref="figures/bookreport.png"
                           format="PNG" width="510" />
              </imageobject>

              <textobject>
                <phrase>Shows Book Report dialog.</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
        </figure>

        <!-- ==== End of Figure ==== -->

        <para>The <guilabel>Book name</guilabel> text entry field is used to
        save the book (a set of configured selections) for future use. The top
        pane lists the items available for inclusion in the book. The bottom
        pane lists the currently selected items in the order they will appear
        in the book.</para>

        <para>The horizontal set of buttons by the <guilabel>Book
        name</guilabel> field operates on the whole book. Click the
        <guibutton>Clear</guibutton> button to clear all items from the
        current book. Click the <guibutton>Save</guibutton> button to save the
        current book (under the name typed in the <guilabel>Book
        name</guilabel> text entry field) for future use.</para>

        <tip>
          <para>Saving the book also saves the configuration for each
          item.</para>
        </tip>

        <para>Click the <guibutton>Open</guibutton> button to load the book
        from the list of previously saved books. Finally, click the
        <guibutton>Edit books</guibutton> button to invoke the editable list
        of available books.</para>

        <para>The vertical set of buttons to the right of the bottom pane
        operates on the selected book item. Click the
        <guibutton>Add</guibutton> button to add selected item from the
        available list to the current book. Click the
        <guibutton>Remove</guibutton> button to remove an item from the
        current book. Use <guibutton>Up</guibutton> and
        <guibutton>Down</guibutton> to change the items order in the current
        book. Click the <guibutton>Setup</guibutton> button to configure the
        options of the selected item of the current book.</para>

        <para>The configuration dialogs invoked by
        <guibutton>Setup</guibutton> are item-specific. If you choose not to
        configure the item, same defaults will be used for all needed options.
        The common option for almost all book items is the center person: the
        person on whom the item is centered. Thanks to this option, you can
        create a book with items centered on different people (e.g. your mom's
        and dad's ancestors as separate chapters). By default, the center
        person is set to the active person.</para>

        <para>Almost all items available for inclusion in the book are textual
        or graphical reports, and are therefore available in the form of
        standalone reports. The exception is the following items which are
        only available as book items:</para>

        <variablelist>
          <varlistentry>
            <term>Title Page</term>

            <listitem>
              <para>This item produces a customized Title page. You can
              configure the text of title, subtitle, and the footer of the
              page. An image can be optionally placed between the subtitle and
              the footer. Because of its configurability, this item can be
              used to create title pages for the whole book, its chapter, or
              even a single item.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Custom Text</term>

            <listitem>
              <para>This item produces a page with three paragraphs, each
              containing custom text. The appearance of the text can be
              adjusted by using custom styles. This item was meant to be used
              for epigraphs, dedications, explanations, notes, and so
              forth.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="rep-codegen">
        <title>Code Generators</title>

        <para>This category contains reports that produce code intended to be
        run through the computer, rather than the usual formatted output for
        human reading. The only code generator currently available in GRAMPS
        is the Relationship Graph producing the GraphViz description of the
        graph.</para>

        <para>The Relationship Graph creates a complex relationship graph in
        GraphViz format. The GraphViz <command>dot</command> tool can
        transform the graph into postscript, jpeg, png, vrml, svg, and other
        formats. GraphViz tools are freely available from the <ulink
        type="http" url="http://www.graphviz.org">GraphViz site</ulink>.
        Specific options for this report include filter and number of
        generations considered, as well as several GraphViz-specific options
        related to pagination, color, and details of the graph.</para>

        <tip>
          <para>If you are not interested in GraphViz code itself and just
          want to generate graphical output, GRAMPS can do it for you under
          the hood. Look for <guilabel>Relationship Graph</guilabel> in the
          Graphical Reports category, <xref linkend="rep-graph" /></para>
        </tip>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="rep-graph">
        <title>Graphical Reports</title>

        <para>Graphical reports represent information in forms of charts and
        graphs. Most of the options are common among graphical reports,
        therefore they will be described only once, at the end of this
        section. The few options which are specific to a given report will be
        described directly in that report's entry.</para>

        <para>The following graphical reports are currently available in
        GRAMPS:</para>

        <variablelist>
          <varlistentry>
            <term>Ancestor Chart</term>

            <listitem>
              <para>This report generates the chart of people who are
              ancestors of the Active person. Specific options include the
              number of generations considered and the format of the displayed
              entries.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Ancestor Chart (Wall Chart)</term>

            <listitem>
              <para>This report is similar to the Ancestor Chart report. It
              provides more options which make it useful for generating huge
              charts suitable for a poster or a wall chart. These options
              include the ability to compress the report (getting rid of an
              empty space) and the option to fit the whole chart on to a
              single page. In the latter case, the contents of the chart is
              scaled down appropriately.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Descendant Graph</term>

            <listitem>
              <para>This report generates a graph of people who are
              descendants of the Active person. Specific options include the
              format of the displayed entries.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Fan Chart</term>

            <listitem>
              <para>This report produces a chart resembling a fan, with Active
              person in the center, parents the the semicircle next to it,
              grandparents in the next semicircle, and so on, for a total of
              five generations.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Relationship Graph</term>

            <listitem>
              <para>This report creates a complex relationship graph in
              GraphViz format and then converts into graphical output running
              it through the the GraphViz <command>dot</command> tool behind
              the scene. Specific options for this report include filter,
              options for dates and places for the events, and whether to
              include URLs and IDs for individuals and families. There are
              also several GraphViz-specific options related to pagination,
              color, and details of the graph.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Statistics Chart</term>

            <listitem>
              <para>This report can collect and display a wealth of
              statistical data about your database. Specific options include
              filter, sorting methods, and additional birth- and gender-based
              limit for inclusion into statistics. You can also set the
              minimum number of items to qualify for the bar chart, so that
              the charts with fewer items will generate a pie chart instead.
              The <guilabel>Chart Selection</guilabel> tab allows you to check
              which charts you want to include in your report.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Timeline Graph</term>

            <listitem>
              <para>This report outputs the list of people with their
              lifetimes represented by intervals on a common chronological
              scale. Specific options include filter, sorting method, and the
              title of the report.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Common options for graphical reports are the filename of the
        output, the format of the output, selected style, page size and
        orientation. Optionally, the reports can be immediately opened with
        the default application.</para>

        <tip>
          <para>The options used in reports are persistent: each report
          remembers its options used last time.</para>
        </tip>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="rep-text">
        <title>Text Reports</title>

        <para>Text reports represent the desired information as formatted
        text. Most of the options are common among text reports, therefore
        they will be described only once, at the end of this section. The
        options which are specific to a given report will be described
        directly in that report's entry.</para>

        <para>The following text reports are currently available in
        GRAMPS:</para>

        <variablelist>
          <varlistentry>
            <term>Ahnentafel Report</term>

            <listitem>
              <para>This report lists the active person and his or her
              ancestors along with their vital data. The people are numbered
              in a special way which is an established standard called
              Ahnentafel. The active person is given number 1. His or her
              father and mother have numbers 2 and 3, respectively. This rule
              holds for every person while going back in generations: father's
              parents are numbered 4 and 5, and mother's parents are numbered
              6 and 7, fathers always numbered with even and mothers with odd
              numbers. Therefore, for any person having number N in this tree,
              the numbers of father and mother are 2N and 2N+1,
              respectively.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Complete Individual Report</term>

            <listitem>
              <para>This report provides individual summaries similar to that
              of the Individual Summary report. The advantage of this report
              is the specific filter option. Depending on the filter choice
              (active person only, his or her descendants, his or her
              ancestors, or entire database), the report may contain from one
              to many individual summaries. Another option for this report is
              the inclusion of source information when listing events.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Comprehensive Ancestors Report</term>

            <listitem>
              <para>This report produces a comprehensive description of
              ancestors of the active person. The highlights of this report
              include elaborate layout, images of children, present and former
              spouses, and source citations. Specific options: number of
              backward generations to consider, whether to cite sources, and
              whether to break pages between generations.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Descendant Report</term>

            <listitem>
              <para>This report produces a brief description of descendants of
              the active person. Specific options: number of forward
              generations to consider.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Detailed Ancestral Report</term>

            <listitem>
              <para>This report covers in detail the ancestors of the active
              person. It includes vital data (birth and death) as well as
              marriages. Specific options: number of backward generations to
              consider, as well as a variety of options regarding the exact
              contents to include.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Detailed Descendant Report</term>

            <listitem>
              <para>This report covers in detail the descendants of the active
              person. It includes vital (birth and death) information as well
              as marriages. Specific options: number of forward generations to
              consider.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>FTM Style Ancestral Report</term>

            <listitem>
              <para>This report creates an ancestral report similar to that
              produced by the Family Tree Maker (tm) program. It covers in
              detail the active person and his/her ancestors It includes vital
              information as well as marriages, children, and notes. Specific
              options: number of backward generations to consider.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>FTM Style Descendant Report</term>

            <listitem>
              <para>This report creates a descendant report similar to that
              produced by the Family Tree Maker (tm) program. It covers in
              detail the active person and his/her descendants. It includes
              vital information as well as marriages, children, and notes.
              Specific options: number of forward generations to
              consider.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Family Group Report</term>

            <listitem>
              <para>This creates a family group report, showing information on
              a set of parents and their children. Specific options: the
              spouse (available only if the active person has more than one
              spouse).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Individual Summary</term>

            <listitem>
              <para>This report produces a detailed summary on the active
              person. The report includes all the facts known to the database
              about that person.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Common options for text reports are the filename of the output,
        the format of the output, selected style, page size and orientation.
        For HTML reports, there is no page information. Instead, HTML options
        include the choice of the HTML template, either available in GRAMPS or
        a custom template defined by you. Optionally, the reports can be
        immediately opened with the default application.</para>

        <tip>
          <para>The options used in reports are persistent: each report
          remembers its options used last time.</para>
        </tip>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="rep-view">
        <title>View Reports</title>

        <para>View reports are representing overall summaries of the database
        information available immediately for on-screen viewing. The following
        view reports are currently available in GRAMPS:</para>

        <variablelist>
          <varlistentry>
            <term>Number of ancestors</term>

            <listitem>
              <para>This report displays the number of ancestors of the active
              person.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Summary of the database</term>

            <listitem>
              <para>This report displays the overall statistics concerning
              number of individuals of each gender, various incomplete entries
              statistics, as well as family and media statistics.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="rep-web">
        <title>Web Page</title>

        <para>The only available report in this category is the Narrative Web
        Site report. It generates a web site (that is, a set of linked web
        pages), for a set of selected individuals.</para>

        <sect3 id="rep-web-narr">
          <title>Narrative Web Site</title>

          <variablelist>
            <varlistentry>
              <term>Introduction</term>

              <listitem>
                <para>GRAMPS 2.0.6 introduced the Narrative Web generator. The
                new tool provides considerably more functionality than the
                older web generator. Instead of using HTML templates to
                customize the pages, CSS style sheets are used.</para>

                <para>More information is now displayed about each person,
                along with information about sources, places, and media
                objects. Introduction pages can be added to provide additional
                information, such as family history.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Selecting the output</term>

              <listitem>
                <para>Genealogy records can generate a lot of files. Many web
                servers have a difficult time with many files in a single
                directory. The Narrative Web Generator strives to keep the
                number of files per directory to a managable level. To do
                this, a hierarchy of directores is created. The generated
                files names are not intuitive, but are unique per person.
                Subsequent runs will geneate identical file names, making it
                easy to replace files.</para>

                <para>By default, the output files are written to the
                specified directory. Because of the number of files and
                directories that are created, it may be difficult to transfer
                the files to an external web host. To aid in this, you may
                directly create a gzip'd tar file to more easily upload the
                data. This is the format that should be used if you would like
                to take advantage of the free genealogy page hosting at the
                <ulink type="http"
                url="http://family.gramps-project.org">GRAMPS web hosting
                site</ulink>.</para>

                <para>To select the gzip'd tar file, select the
                <guilabel>Store web pages in .tar.gz archive</guilabel>
                option.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Applying a filter</term>

              <listitem>
                <para>Like the previous web page generator, and most of the
                other GRAMPS reports, you can control what is included in the
                output by choosing a filter. Several default filters are
                provided for you, but you are free to use the Custom Filter
                Editor tool to create your own.</para>

                <para>Any person matching this filter who is not excluded due
                to the privacy rules, will be included in the output. The
                default filter includes all people in the database.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Applying a style sheet</term>

              <listitem>
                <para>GRAMPS provides six built in style sheets for your web
                page. Each of these style sheets produces a unique look for
                your pages. The generated style sheet is named
                <filename>narrative.css</filename>. You may edit this file if
                you wish to further customize your site.</para>

                <para>If you make modifications to your style sheet, you need
                to be aware the regenerating the pages with the same output
                directory will overwrite your changes to this file. To prevent
                this from happening, make sure you choose <guilabel>No style
                sheet</guilabel> for subsequent runs.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Character set encoding</term>

              <listitem>
                <para>Because of GRAMPS internationalization ability, the
                default character set for the HTML pages is UTF-8. This
                provides support for virtually all characters.</para>

                <para>The Apache web server is sometimes misconfigured to
                override the character set specified in an HTML page. This
                causes problems with the UTF-8 character set generated by
                GRAMPS, distorting characters on the screen.</para>

                <para>If your web server is misconfigured and you do not have
                priveledge to fix the configururation, you may solve this
                problem by overriding the default character set to match what
                your web server may be expecting.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Copyright notice</term>

              <listitem>
                <para>International copyright law reserves all rights to your
                data. You own the data, and people must get your permission to
                use it. In genealogy, however, sharing data is a common ideal.
                It this case, you may wish to grant the user more
                rights.</para>

                <para>While the default for GRAMPS is to place a notice
                indicating that all rights are reserved, we give you the
                option to place your site under one of several of the Create
                Commons licenses. With a Creative Commons license, you grant
                user's certain permission to use your data without requiring
                them to contact you directly for permission.</para>

                <para>See the <ulink type="http"
                url="http://creativecommons.org/">Creative Commons</ulink> web
                site for more information.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Controlling page generation</term>

              <listitem>
                <para>Three additional pages can be generated by the web page
                generator. The Home page is a page that will display an image
                and a whatever text you wish. To enable this page, choose a
                Media Object from the <guilabel>Home Media/Note ID</guilabel>
                menu on the <guilabel>Page Generation</guilabel> tab. If the
                Media Object contains an image, the image is displayed at the
                top of the page. If the Media Object contains a Note, the
                Note's text is used for the text of the page. A second page,
                the Introduction page, works similarly. Just choose the Media
                Object in the <guilabel>Introduction Media/Note ID</guilabel>
                menu.</para>

                <para>If you choose to include a contact page, the researcher
                information stored in the database is displayed, along with
                the information specified in the <guilabel>Publisher
                contact/Note ID</guilabel> menu. Please use this page with
                caution, since you may consider your contact information to be
                private.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Privacy</term>

              <listitem>
                <para>Privacy of personal information is an important issue on
                the web today. GRAMPS tries to give you control over the
                information that is presented.</para>

                <para>GRAMPS provides two options to control the privacy of
                your information. If you select the <guilabel>Do not include
                records marked private</guilabel> option, any data that is
                marked as private will not be displayed on the generated site.
                If you select <guilabel>Restrict information on living
                people</guilabel>, GRAMPS will attempt to determine which
                people have the potential of still being alive, and will omit
                these people from the database. Some countries have laws that
                indicate that a certain number of years must pass after
                someone's death before information can be published. The
                <guilabel>Years to restrict from person's death</guilabel>
                option allows you to specifiy how many years a person must be
                deceased before the information is included.</para>

                <para>Please note that it is your responsibility to double
                check all information in the pages for any privacy
                information. GRAMPS cannot be held responsible for any privacy
                issues.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Adding custom code your pages</term>

              <listitem>
                <para>If you are not interested in customizing your pages, you
                may skip the section.</para>

                <para>The previous web generator allowed you to customize your
                pages using HTML templates. Your data would be substituted for
                certain markers in the code.</para>

                <para>This method proved to be too cumbersome for most users.
                The Narrative Web Page Generator introduces a simpler
                mechanism. On the <guilabel>Page Generation</guilabel> tab,
                you may specify text (including HTML code) that will be
                inserted into each page, separately for the header and the
                footer.</para>

                <para>To create this code, you need to create a Media Object
                marked as an internal note. To create this, add a new Media
                Object in the Media View, and select the internal note option.
                You may then enter your HTML code.</para>

                <para>To insert the code from the internal notes into the web
                pages, select the appropriate Media Objects from the
                <guilabel>HTML user header</guilabel> and <guilabel>HTML user
                footer</guilabel> menus. Two div sections will be added to the
                pages - userheader and userfooter. The corresponding HTML code
                is inserted into the HTML page surrounded by div markers. You
                can customize your style sheet to provide additional
                formatting and positioning information to control these
                sections.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>
      </sect2>
    </sect1>

    <!-- ================ Usage Subsection ================================ -->

    <sect1 id="gramps-tools">
      <title>Running Tools</title>

      <para>GRAMPS tools allow you to perform various types of analysis of
      your genealogical data. Typically, the tools do not produce output in
      form of printouts or files. Instead, they produce screen output
      immediately available for the researcher. However, when appropriate, you
      can save the results of running a tool into a file. Tools present one of
      the major strengths of GRAMPS compared to the most genealogical
      software.</para>

      <para>The tools can be accessed through the menu by choosing <menuchoice>
          <guimenu>Tools</guimenu>

          <guisubmenu><replaceable>Tool Section</replaceable></guisubmenu>

          <guimenuitem><replaceable>Particular
          Tool</replaceable></guimenuitem>
        </menuchoice>. Alternatively, you can browse the complete selection of
      available tools along with their brief descriptions in a <guilabel>Tool
      Selection</guilabel> dialog invoked by clicking the
      <guibutton>Tools</guibutton> icon on the toolbar.</para>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="tools-ae">
        <title>Analysis and Exploration</title>

        <para>This section contains tools which analyze and explore the
        database, but do not alter it. The following analysis and exploration
        tools are currently available in GRAMPS:</para>

        <variablelist>
          <varlistentry>
            <term>Compare individual events</term>

            <listitem>
              <para>This tool compares events across the selected group of
              people. The people for this comparison are chosen with the use
              of custom filters. The custom filters can be created in the
              Custom Filter Editor (see <xref linkend="tools-util-cfe" />)
              that can be invoked by clicking the <guilabel>Custom Filter
              Editor</guilabel> button. The resulting table produced by this
              tool can be saved as a spreadsheet.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Interactive descendant browser</term>

            <listitem>
              <para>This tool builds a tree with the active person being the
              root. Children branch from their parents in the usual manner.
              Use this tool for a quick glance of a person's
              descendants.</para>

              <tip>
                <para>Double-clicking on tree node will bring up the
                <guilabel>Edit Person</guilabel> dialog allowing to view or
                modify the personal data.</para>
              </tip>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="tools-db">
        <title>Database Processing</title>

        <para>This section contains tools which may modify your database. The
        tools from this section are used mostly for finding and correcting
        errors in the data. The following database processing tools are
        currently available in GRAMPS:</para>

        <note>
          <para>The modifications will only be performed upon your explicit
          consent, except for the automatic fixes performed by <guilabel>Check
          and repair database</guilabel> tool.</para>
        </note>

        <variablelist>
          <varlistentry>
            <term>Check and repair database</term>

            <listitem>
              <para>This tool checks the database for integrity problems,
              fixing the problems it can. Specifically, the tool is checking
              for:</para>

              <itemizedlist>
                <listitem>
                  <para>Broken family links. These are the cases when a
                  person's record refers to a family while the family's record
                  does not refer to that person, and vice versa.</para>
                </listitem>

                <listitem>
                  <para>Missing media objects. The missing media object is the
                  object whose file is referenced in the database but does not
                  exist. This can happen when the file is accidentally
                  deleted, renamed, or moved to another location.</para>
                </listitem>

                <listitem>
                  <para>Empty families. These are the family entries which
                  have no reference to any person as their member.</para>
                </listitem>

                <listitem>
                  <para>Parent relationship. This checks all families to
                  ensure that father and mother are not mixed up. The check is
                  also made that parents have different gender. If they have
                  common gender then their relationship is renamed to
                  "Partners".</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Extract information from names</term>

            <listitem>
              <para>This tool searches the entire database and attempts to
              extract titles and nicknames that may be embedded in a person's
              <guilabel>Given name</guilabel> field. If any information could
              be extracted, the candidates for fixing will be presented in the
              table. You may then decide which to repair as suggested and
              which not to.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Find possible duplicate people</term>

            <listitem>
              <para>This tool searches the entire database, looking for the
              entries that may represent the same person.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Fix capitalization of family names</term>

            <listitem>
              <para>This tool searches the entire database and attempts to fix
              the capitalization of family names. The aim is to have
              conventional capitalization: capital first letter and lower case
              for the rest of the family name. If deviations from this rule
              are detected, the candidates for fixing will be presented in the
              table. You may then decide which to repair as suggested and
              which not to.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Rename personal event types</term>

            <listitem>
              <para>This tool allows all the events of a certain name to be
              renamed to a new name.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Reorder GRAMPS IDs</term>

            <listitem>
              <para>This tool reorders the GRAMPS IDs according to the
              defaults of GRAMPS.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="tools-debug">
        <title>Debug</title>

        <para>This section contains debugging tools that are not of general
        interest for many of the users of GRAMPS. If you're not interested in
        debugging or developing GRAMPS you may safely skip this
        section.</para>

        <variablelist>
          <varlistentry>
            <term>Python evaluation window</term>

            <listitem>
              <para>Enter expression into the <guilabel>Evaluation
              Window</guilabel>, get the output in <guilabel>Output
              Window</guilabel>. Any errors should end up in the
              <guilabel>Error Window</guilabel>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Reload plugins</term>

            <listitem>
              <para>Makes an attempt to reload all plugins.</para>

              <note>
                <para>This tool is itself a plugin, but it will not reload
                itself!</para>
              </note>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Show uncollected objects</term>

            <listitem>
              <para>Provides the window listing all uncollected objects.
              Depending on the system settings, recently abandoned GUI objects
              may still be uncollected.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <!-- =============== Usage Sub-subsection ================ -->

      <sect2 id="tools-util">
        <title>Utilities</title>

        <para>This section contains tools allowing you to perform a simple
        operation on a portion of data. The results can be saved in your
        database, but they will not modify your existing data. The following
        utilities are currently available in GRAMPS:</para>

        <sect3 id="tools-util-cfe">
          <title>Custom Filter Editor</title>

          <para>The Custom Filter Editor builds custom filters that can be
          used to select people included in reports, exports, and other tools
          and utilities. This is in fact a very powerful tool in genealogical
          analysis.</para>

          <para>When you launch it, the <guilabel>User defined
          filters</guilabel> dialog appears that lists all the filters (if
          any) previously defined by you. Click the
          <guibutton>Add...</guibutton> button to define a new filter. Once
          you have designed your filters, you can edit, test, and delete
          selected filters using the <guibutton>Edit...</guibutton>,
          <guibutton>Test...</guibutton>, and <guibutton>Delete</guibutton>
          buttons, respectively. All the filters displayed in the list will be
          automatically saved along with your database and will be available
          with subsequent sessions of GRAMPS.</para>

          <note>
            <para>The changes made to the filters only take effect when you
            click the <guibutton>Apply and close</guibutton> button.</para>
          </note>

          <para>Clicking the <guibutton>Add...</guibutton> button invokes the
          following <guilabel>Define filter</guilabel> dialog:</para>

          <!-- ==== Figure: Define filter dialog ==== -->

          <figure id="cfe-df-fig">
            <title>Define filter dialog</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata depth="410" fileref="figures/cfe-df.png"
                             format="PNG" width="400" />
                </imageobject>

                <textobject>
                  <phrase>Shows Define filter dialog.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>

          <!-- ==== End of Figure ==== -->

          <para>Type the name for your new filter into the
          <guilabel>Name</guilabel> field. Enter any comment that would help
          you identify this filter in the future into the
          <guilabel>Comment</guilabel> field. Add as many rules to the
          <guilabel>Rule list</guilabel> as you would like to your filter
          using <guibutton>Add...</guibutton> button. If the filter has more
          than one rule, select one of the <guilabel>Rule
          operations</guilabel>. This allows you to choose whether all rules
          must apply, only one (either) rule must apply, or exactly one
          (either) rule must apply, in order for the filter to generate a
          match. If your filter has only one rule, this selection has no
          effect.</para>

          <para>Check <guilabel>Return values that do not match the filter
          rules</guilabel> to invert the filter rule. For example, inverting
          "has a common ancestor with I1" rule will match everyone who does
          not have a common ancestor with that person).</para>

          <para>Clicking the <guibutton>Add...</guibutton> button invokes the
          following <guilabel>Add Rule</guilabel> dialog:</para>

          <!-- ==== Figure: Add Rule dialog ==== -->

          <figure id="cfe-ar-fig">
            <title>Add Rule dialog</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata depth="297" fileref="figures/cfe-ar.png"
                             format="PNG" width="500" />
                </imageobject>

                <textobject>
                  <phrase>Shows Add Rule dialog.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>

          <!-- ==== End of Figure ==== -->

          <para>The pane on the left-hand side displays available filter rules
          arranged by their categories in an expandable tree. For detailed
          filter rule reference, see <xref linkend="append-filtref" />. Click
          on the arrows to fold/unfold the appropriate category. Select the
          rule from the tree by clicking on its name. The right-hand side
          displays the name, the description, and the values for the currently
          selected rule. Once you are satisfied with your rule selection and
          its values, click <guibutton>OK</guibutton> to add this rule to the
          rule list of the currently edited filter. Clicking
          <guibutton>Cancel</guibutton> will abort adding the rule to the
          filter.</para>

          <tip>
            <para>A filter you have already designed may be used as a rule for
            another filter. This gives you nearly infinite flexibility in
            custom-tailoring your selection criteria that can be later used in
            most of the exports, reports, and some of the tools (such as
            comparing individual events).</para>
          </tip>
        </sect3>

        <sect3 id="tools-util-scratch-pad">
          <title>Scratch Pad</title>

          <para>This tool provides a temporary note pad to store database
          records for easy reuse. In short, this is a sort of the
          copy-and-paste functionality extended from textual objects to other
          types of records used in GRAMPS.</para>

          <tip>
            <para>Scratch Pad makes extensive use of drag-and-drop
            technique.</para>
          </tip>

          <para>To invoke Scratch Pad, either choose <menuchoice>
              <guimenu>Tools</guimenu>

              <guisubmenu>Utilities</guisubmenu>

              <guimenuitem>Scratch Pad</guimenuitem>
            </menuchoice> or click the <guilabel>ScratchPad</guilabel> button
          on the toolbar. The following window will appear:</para>

          <!-- ==== Figure: Scratch Pad tool ==== -->

          <figure id="scratch-pad-fig">
            <title>Scratch Pad tool</title>

            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata depth="246" fileref="figures/scratch-pad.png"
                             format="PNG" width="500" />
                </imageobject>

                <textobject>
                  <phrase>Shows Add Scratch Pad tool.</phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>

          <!-- ==== End of Figure ==== -->

          <para>Scratch Pad supports addresses, attributes (both personal and
          family), events (both personal and family), names, media objects
          references, source references, URLs, and of course textual
          information of notes and comments. To store any type of these
          records, simply drag the existing record on to the Scratch Pad from
          the corresponding editor dialog. To reuse the record, drag it from
          the Scratch Pad on to the corresponding place in the editor, e.g.
          Address tab, Attribute tab, etc.</para>

          <tip>
            <para>Some objects are showing the link icon on the left. This
            indicates that dragging such selection will produce a reference to
            an existing object, not copy the object itself.</para>

            <para>For example, the media object file will not be duplicated.
            Instead, the reference will be made to an existing media object,
            which will result in the local gallery entry.</para>
          </tip>

          <tip>
            <para>Scratch Pad storage is persistent within a single GRAMPS
            session. Closing the window will not lose the stored records.
            However, exiting GRAMPS will.</para>
          </tip>
        </sect3>

        <sect3 id="tools-util-other">
          <title>Other tools</title>

          <variablelist>
            <varlistentry>
              <term>Generate SoundEx codes</term>

              <listitem>
                <para>This utility generates SoundEx codes for the names of
                people in the database. Please visit the <ulink type="http"
                url="http://www.archives.gov/research_room/genealogy/census/soundex.html">NARA
                Soundex Indexing page</ulink> to learn more about Soundex
                Indexing System.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Relationship calculator</term>

              <listitem>
                <para>This utility calculates and displays the relationship of
                any person to the active person.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Verify the database</term>

              <listitem>
                <para>This utility allows you to verify the database based on
                the set of criteria specified by you.</para>

                <tip>
                  <title>Difference between Verify tool and previously
                  described Check tool</title>

                  <para>The Check tool detects inconsistencies in the database
                  structure. The Verify tool, however, is detecting the
                  records that do not satisfy your particular criteria.</para>
                </tip>

                <para>For example, you may want to make sure that nobody in
                your database had children at the age of 98. Based on common
                sense, such a record would indicate an error. However, it is
                not a consistency error in the database. Besides, someone
                might have a child at the age of 98 (although this rarely
                happens). The Verify tool will display everything that
                violates your criteria so that you can check whether the
                record is erroneous or not. The ultimate decision is
                yours.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="gramps-settings">
    <!-- $Id$ -->

    <title>Settings</title>

    <sect1 id="gramps-prefs">
      <title>Preferences</title>

      <para>Most of the settings in GRAMPS, are configured in the
      <guilabel>Preferences</guilabel> dialog. To invoke it, choose
      <menuchoice>
          <guimenu>Edit</guimenu>

          <guimenuitem>Preferences...</guimenuitem>
        </menuchoice>.</para>

      <!-- ==== Figure: Type-ahead find ==== -->

      <figure id="prefs-fig">
        <title>Preferences dialog</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/prefs.png" format="PNG" />
            </imageobject>

            <textobject>
              <phrase>Shows Preferences dialog.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

      <!-- ==== End of Figure ==== -->

      <para>The pane on the left displays the tree of available option
      categories. Selecting a tree node will display the corresponding options
      in the right side of the dialog.</para>

      <sect2 id="gramps-prefs-db">
        <title>Database</title>

        <para>This category contains preferences relevant to the database
        itself. It has the following subcategories:</para>

        <variablelist>
          <varlistentry>
            <term><guilabel>General</guilabel></term>

            <listitem>
              <variablelist>
                <varlistentry>
                  <term><guilabel>Automatically load last
                  database</guilabel></term>

                  <listitem>
                    <para>Check this box to automatically load the last open
                    database on startup.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><guilabel>Family name guessing</guilabel></term>

                  <listitem>
                    <para>This option affects the initial family name of a
                    child when he/she is added to the database.</para>

                    <tip>
                      <para>This option only affects the initial family name
                      guessed by GRAMPS when the <guilabel>Edit
                      Person</guilabel> dialog is launched. You can modify
                      that name the way you see fit. Set this option to the
                      value that you will most frequently use, as it will save
                      you a lot of typing.</para>
                    </tip>

                    <para>If <guilabel>None</guilabel> is selected, no
                    guessing will be attempted. Selecting <guilabel>Father's
                    surname</guilabel> will use the family name of the father.
                    Selecting <guilabel>Combination of mother's and father's
                    surname</guilabel> will use the father's name followed by
                    the mother's name. Finally, <guilabel>Icelandic
                    style</guilabel> will use the father's given name followed
                    by the "sson" suffix (e.g. the son of Edwin will be
                    guessed as Edwinsson).</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><guilabel>GRAMPS IDs</guilabel></term>

            <listitem>
              <para>Enter ID prefixes for various kinds of database entries
              into the corresponding text entry fields.</para>

              <tip>
                <para>The ID prefixes use formatting conventions common for C,
                Python, and other programming languages. For example, the %04d
                expands to an integer, prepended with zeros to have the total
                width of four digits. If you would like IDs to be 1, 2, 3,
                etc, simply set the formatting parameter to %d.</para>
              </tip>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><guilabel>Researcher Information</guilabel></term>

            <listitem>
              <para>Enter your personal information in the corresponding text
              entry fields. Although GRAMPS requests information about you,
              this information is used only so that GRAMPS can create valid
              GEDCOM output files. A valid GEDCOM file requires information
              about the file's creator. If you choose, you may leave the
              information empty, however none of your exported GEDCOM files
              will be valid.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <sect2 id="gramps-prefs-display">
        <title>Display</title>

        <para>This category contains preferences relevant to displaying
        database records and controls in GRAMPS. It has the following
        subcategories:</para>

        <variablelist>
          <varlistentry>
            <term><guilabel>General</guilabel></term>

            <listitem>
              <variablelist>
                <varlistentry>
                  <term><guilabel>Default view</guilabel></term>

                  <listitem>
                    <para>This determines which view will appear when you
                    start GRAMPS. Choose between Person and Family
                    views.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><guilabel>Family view style</guilabel></term>

                  <listitem>
                    <para>This selects between the two available styles of the
                    Family view layout. The <guilabel>Left to right</guilabel>
                    style is similar to the Family Tree Maker (tm), while the
                    <guilabel>Top to bottom</guilabel> is similar to the
                    Reunion.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><guilabel>Always display the LDS ordinance
                  tabs</guilabel></term>

                  <listitem>
                    <para>Check this box to have LDS ordinance tabs displayed.
                    If you do not know what LDS is then you probably should
                    not check it.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><guilabel>Display Tip of the Day</guilabel></term>

                  <listitem>
                    <para>Check this box to have the <guilabel>Tip of the
                    Day</guilabel> dialog appear on every startup. The tips
                    are displayed randomly from the large collection of
                    information bits on GRAMPS.</para>

                    <tip>
                      <para>The <guilabel>Tip of the Day</guilabel> is likely
                      to be useful for new user of GRAMPS.</para>
                    </tip>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><guilabel>Dates</guilabel></term>

            <listitem>
              <para>Select the display format for the dates from the available
              formats listed in this menu.</para>

              <tip>
                <para>Available date display formats are language-specific.
                Depending on whether or not there is a GRAMPS date displayer
                available for your language, you may or may not have a lot of
                choices.</para>
              </tip>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><guilabel>Toolbar and Statusbar</guilabel></term>

            <listitem>
              <variablelist>
                <varlistentry>
                  <term><guilabel>Toolbar</guilabel></term>

                  <listitem>
                    <para>Select the desired appearance of the toolbar icons
                    from the menu. Selecting <guilabel>GNOME
                    Settings</guilabel> will use the overall settings selected
                    for your GNOME desktop.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><guilabel>Statusbar</guilabel></term>

                  <listitem>
                    <para>Select the desired contents displayed in the
                    statusbar using the radio buttons.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>
    </sect1>

    <sect1 id="gramps-prefs-other">
      <title>Other settings</title>

      <para>Besides <guilabel>Preferences</guilabel> dialog, there are other
      settings available in GRAMPS. For various reasons they have been made
      more readily accessible, as listed below.</para>

      <variablelist>
        <varlistentry>
          <term>Column Editor</term>

          <listitem>
            <para>The columns of the list views may be added, removed, or
            reordered in a <guilabel>Column Editor Dialog</guilabel>, see
            <xref linkend="column-editor-fig" />. Only checked columns will be
            shown in the view. To change their order, drag any column to its
            desired place inside the editor. Clicking
            <guibutton>OK</guibutton> will reflect the changes in the
            appropriate view. To invoke <guilabel>Column Editor
            Dialog</guilabel>, choose <menuchoice>
                <guimenu>Edit</guimenu>

                <guimenuitem>Column Editor...</guimenuitem>
              </menuchoice>.</para>

            <tip>
              <para>The <guilabel>Column Editor</guilabel> is available and
              works in the same way for all list views. Specifically, it is
              available for People View, Family View (children list). Sources
              View, Places View, and Media View.</para>
            </tip>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Setting Home person</term>

          <listitem>
            <para>The Home person is the person who becomes active when
            database opened, when <guibutton>Home</guibutton> button is
            clicked or the <guimenuitem>Home</guimenuitem> menu item is
            selected from either <guimenu>Go</guimenu> menu or the right-click
            context menu anywhere.</para>

            <para>To set Home person, make the desired person active and then
            choose <menuchoice>
                <guimenu>Edit</guimenu>

                <guimenuitem>Set Home person...</guimenuitem>
              </menuchoice>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Adjusting viewing controls</term>

          <listitem>
            <para>Whether the toolbar, the sidebar, or the filter (People View
            only) are displayed in the main window is adjusted through the
            <guimenu>View</guimenu> menu.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <sect1 id="gramps-prefs-adv">
      <title>Advanced manipulation of settings</title>

      <warning>
        <para>The contents of this section is outside the scope of interest of
        a general user of GRAMPS. If you proceed with tweaking the options on
        the low level you may damage your GRAMPS installation. Be careful. YOU
        HAVE BEEN WARNED!</para>
      </warning>

      <para>By default, GRAMPS stores its settings using gconf2 system. All
      the settings used in this version of GRAMPS are stored in subdirectories
      under <filename>/apps/gramps/</filename> in the gconf2 namespace.
      Accessing the keys can be done either using
      <command>gconftool-2</command> command line tool, or the
      <command>gconf-editor</command> GUI tool.</para>

      <para>All keys are documented, and the notification mechanisms are used
      as appropriate. Therefore, updating keys from outside of GRAMPS should
      lead to updating GRAMPS in real time, without necessarily restarting
      it.</para>
    </sect1>
  </chapter>

  <!-- $Id$ -->

  <appendix id="faq">
    <title>Frequently Asked Questions</title>

    <para>This appendix contains the list of questions that frequently come up
    in mailing list discussions and forums. This list is by no means complete.
    If you would like to add questions/answers to this list, please email your
    suggestions to <ulink type="mailto"
    url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink></para>

    <variablelist>
      <varlistentry>
        <term>What is GRAMPS?</term>

        <listitem>
          <para>GRAMPS is the Genealogical Research and Analysis Management
          Program System. In other words, it is a personal genealogy program
          letting you store, edit, and research genealogical data using the
          powers of your computer.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Where do I get it and how much does it cost?</term>

        <listitem>
          <para>GRAMPS can be downloaded from <ulink type="http"
          url="http://sf.net/projects/gramps">http://sf.net/projects/gramps</ulink>
          at no charge. GRAMPS is an Open Source project covered by the GNU
          General Public License. You have full access to the source code and
          are allowed to distribute the program and source code freely.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Does it work with Windows (tm)?</term>

        <listitem>
          <para>No. GRAMPS uses the GTK and GNOME libraries. While the GTK
          libraries have been ported to Windows, the GNOME libraries have not.
          This, however, may change in the future.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Does it work with the Mac?</term>

        <listitem>
          <para><ulink type="http" url="http://fink.sourceforge.net"> The Fink
          project</ulink> has ported <ulink type="http"
          url="http://fink.sourceforge.net/pdb/package.php/gramps"> some older
          versions</ulink> of GRAMPS to OSX (tm). The Mac OSX port is not
          directly supported by the GRAMPS project, primarily because none of
          the GRAMPS developers have access to Mac OSX and because OSX is not
          Free Software.</para>

          <para>This version of GRAMPS (2.2.0) does not appear to have been
          ported by the Fink project. Please contact the Fink project for more
          information.</para>

          <para>Some people have had success using the DarwinPorts instead of
          the Fink project.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Does it work with KDE?</term>

        <listitem>
          <para>Yes, as long as the required GNOME libraries are
          installed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Do I really have to have GNOME installed?</term>

        <listitem>
          <para>Yes, but you do not have to be running the GNOME
          desktop.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>What version of GNOME do I need?</term>

        <listitem>
          <para>This version of gramps requires GNOME 2.8.0 or higher.
          Previous versions in 1.0.x series required GNOME 2.0.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Is GRAMPS compatible with other genealogical software?</term>

        <listitem>
          <para>GRAMPS makes every effort to maintain compatibility with
          GEDCOM, the general standard of recording genealogical information.
          We have import and export filters that enable GRAMPS to read and
          write GEDCOM files.</para>

          <para>It is important to understand that the GEDCOM standard is
          poorly implemented -- virtually every genealogical software has its
          own "flavor" of GEDCOM. As we learn about new flavor, the
          import/export filters can be created very quickly. However, finding
          out about the unknown flavors requires user feedback. Please feel
          free to inform us about any GEDCOM flavor not supported by GRAMPS,
          and we will do our best to support it!</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Can GRAMPS read files created by other genealogy
        programs?</term>

        <listitem>
          <para>See above.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Can GRAMPS write files readable by other genealogy
        programs?</term>

        <listitem>
          <para>See above.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Can GRAMPS print a genealogical tree for my family?</term>

        <listitem>
          <para>Yes. Different people have different ideas of what a
          genealogical tree is. Some think of it as a chart going from the
          distant ancestor and listing all his/her descendants and their
          families. Others think it should be a chart going from the person
          back in time, listing the ancestors and their families. Yet other
          people think of a table, text report, etc.</para>

          <para>GRAMPS can produce any of the above, and many more different
          charts and reports. Moreover, the plugin architecture enables users
          (you) to create their own plugins which could be new reports,
          charts, or research tools.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>In what formats can GRAMPS output its reports?</term>

        <listitem>
          <para>Text reports are available in HTML, PDF, AbiWord, KWord,
          LaTeX, RTF, and OpenOffice formats. Graphical reports (charts and
          diagrams) are available in PostScript, PDF, SVG, OpenOffice, and
          GraphViz formats.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Is GRAMPS compatible with the Internet?</term>

        <listitem>
          <para>GRAMPS can store web addresses and direct your browser to
          them. It can import data that you download from the Internet. It can
          export data that you could send over the Internet. GRAMPS is
          familiar with the standard file formats widely used on the Internet
          (e.g. JPEG, PNG, and GIF images, MP3, OGG, and WAV sound files,
          QuickTime, MPEG, and AVI movie files, etc). Other than that, there
          is little that a genealogical program can do with the
          Internet.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Can I create custom reports/filters/whatever?</term>

        <listitem>
          <para>Yes. There are many levels of customization. One is creating
          or modifying the templates used for the reports. This gives you some
          control over the fonts, colors, and some layout of the reports. You
          can also use GRAMPS controls in the report dialogs to tell what
          contents should be used for a particular report. In addition to
          this, you have an ability to create your own filters -- this is
          useful in selecting people based on criteria set by you. You can
          combine these filters to create new, more complex filters. Finally,
          you have an option to create your own plugins. These may be new
          reports, research tools, import/export filters, etc. This assumes
          some knowledge of programming in Python.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>What standards does GRAMPS support?</term>

        <listitem>
          <para>The nice thing about standards is that there never is a
          shortage of them. GRAMPS is tested to support the following flavors
          of GEDCOM: GEDCOM5.5, Brother's Keeper, Family Origins, Family Tree
          Maker, Ftree, GeneWeb, Legacy, Personal Ancestral File, Pro-Gen,
          Reunion, and Visual Genealogie.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>What is the maximum database size (bytes) GRAMPS can
        handle?</term>

        <listitem>
          <para>GRAMPS has no hard limits on the size of a database that it
          can handle. Starting with this release, GRAMPS no longer loads all
          data into memory, which allows it to work with a much larger
          database than before. In reality, however, there are practical
          limits. The main limiting factors are the available memory on the
          system and the cache size used for BSDDB database access. With
          common memory sizes these days, GRAMPS should have no problem using
          databases with tens of thousands of people.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>How many people can GRAMPS database handle?</term>

        <listitem>
          <para>We have found that on a typical system, GRAMPS tends to bog
          down after the database has around 150,000 people. Again, this is
          dependent on how much memory you have.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Why is GRAMPS running so slowly?</term>

        <listitem>
          <para>It does not anymore! Just try out the current version,
          2.2.0.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>My database is really big. Is there a way around loading all the
        data into memory?</term>

        <listitem>
          <para>Starting with this release, GRAMPS no longer loads all data
          into memory, which allows it to work with a much larger database
          than before.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>I want to rerun the Startup dialog. How do I do this?</term>

        <listitem>
          <para>GRAMPS keeps a flag in the GNOME configuration database to
          indicate that the startup dialog has been run. To cause GRAMPS to
          rerun this, the flag needs to be reset. This can be done with the
          following command:</para>

          <para><command>gconftool-2 -u
          /apps/gramps/behavior/startup</command></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Why are non-latin characters displayed as garbage in PDF/PS
        reports?</term>

        <listitem>
          <para>This is a limitation of the builtin fonts of PS and PDF
          formats. To print non-latin text, use the Print... in the format
          selection menu of the report dialog. This will use the gnome-print
          backend, which supports PS and PDF creation, as well as direct
          printing.</para>

          <para>If you only have latin text, the PDF option will produce a
          smalled PDF compared to that created by gnome-print, simply because
          no font information will be embedded.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Why can I not add/remove/edit columns to the lists in People
        View and Family View?</term>

        <listitem>
          <para>Now you can! Just try out the current version, 2.2.0.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>I would like to contribute to GRAMPS by writing my favorite
        report. How do I do that?</term>

        <listitem>
          <para>The easiest way to contribute to reports, filters, tools, etc.
          is to copy an existing GRAMPS report, filter, or tool. If you can
          create what you want by modifying existing code -- great! If your
          idea does not fit into the logic of any existing GRAMPS tool, the
          <ulink type="http"
          url="http://gramps.sourceforge.net/phpwiki/index.php/GrampsDevelopersPage">following
          page</ulink> may provide some help in writing your own plugin from
          scratch.</para>

          <para>If you need more help or would like to discuss your idea with
          us, please do not hesitate to contact us at <ulink type="mailto"
          url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink></para>

          <para>To test your work in progress, you may save your plugin under
          <replaceable>$HOME/.gramps/plugins</replaceable> directory and it
          should be found and imported on startup. The correctly written
          plugin will register itself with GRAMPS, create menu item, and so
          on.</para>

          <para>If you are happy with your plugin and would like to contribute
          your code back to the GRAMPS project, you are very welcome to do so
          by contacting us at <ulink type="mailto"
          url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>I found a bug and I want it fixed right now! What do I
        do?</term>

        <listitem>
          <para>The best thing you can do is to fix the bug and send the patch
          to <ulink type="mailto"
          url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink>
          :-)</para>

          <para>A good bug report would include:</para>

          <itemizedlist>
            <listitem>
              <para>Version of gramps you were using when you encountered the
              bug (available through <menuchoice>
                  <guisubmenu>Help</guisubmenu>

                  <guimenuitem>About</guimenuitem>
                </menuchoice> menu item).</para>
            </listitem>

            <listitem>
              <para>Language under which gramps was run (available by
              executing</para>

              <para><command>echo $LANG</command></para>

              <para>in your terminal).</para>
            </listitem>

            <listitem>
              <para>Symptoms indicating that this is indeed a bug.</para>
            </listitem>

            <listitem>
              <para>Any Traceback messages, error messages, warnings, etc,
              that showed up in your terminal or a in separate traceback
              window.</para>
            </listitem>
          </itemizedlist>

          <para>Most problems can be fixed quickly provided there is enough
          information. To ensure this, please follow up on your bug reports.
          In particular, if you file a bug report with sf.net bug tracker,
          PLEASE log in to sf.net before filing (register your free account if
          you don't have one). Then we will have a way of contacting you
          should we need more information. If you choose to file your report
          anonymously, at least check every so often whether your report page
          has something new posted, as it probably would.</para>

          <para>If the above explanations seem vague, please follow <ulink
          type="http"
          url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">this
          link.</ulink></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>It is obvious that GRAMPS absolutely needs to become a
        (client-server/web-based/PHP/weblog/Javascript/C++/distributed/KDE/Motif/Tcl/Win32/C#/You-name-it)
        application. When is this going to happen?</term>

        <listitem>
          <para>The surest way to see it happen is to get it done by yourself.
          Since GRAMPS is free/open source, nobody prevents you from taking
          all of the code and continuing its development in whatever direction
          you see fit. In doing so, you may consider giving your new project
          another name to avoid confusion with the continuing GRAMPS
          development. If you would like the GRAMPS project to provide advice,
          expertise, filters, etc., we will gladly cooperate with your new
          project, to ensure compatibility or import/export options to your
          new format of a project.</para>

          <para>If, however, you would like the GRAMPS project to to adopt
          your strategy, you would need to convince GRAMPS developers that
          your strategy is good for GRAMPS and superior to the present
          development strategy.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </appendix>

  <appendix id="append-keybind">
    <!-- $Id$ -->

    <title>Keybindings reference</title>

    <para>Most of the standard menu items define equivalent keybindings. These
    are apparent because they are displayed on the right of the menu item.
    However, some keybindings are not associated with any items in the
    menu.</para>

    <para>This appendix contains the list of keybindings that are not
    displayed in menus of GRAMPS.</para>

    <sect1 id="keybind-lists">
      <title>List Views</title>

      <para>The following bindings are available in all list views: People
      View, Sources View, Places View, and Media View.</para>

      <informaltable frame="topbot">
        <tgroup cols="2">
          <colspec colname="col1" />

          <colspec colname="col2" />

          <thead>
            <row valign="top">
              <entry colname="col1" colsep="0"
              valign="top"><para>Key</para></entry>

              <entry colname="col2" valign="top"><para>Function</para></entry>
            </row>
          </thead>

          <tbody>
            <row valign="top">
              <entry><para><keycap>Enter</keycap></para></entry>

              <entry><para>Invoke <guilabel>Edit Person</guilabel> dialog with
              the selected person.</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect1>

    <sect1 id="keybind-family">
      <title>Family View</title>

      <para>The bindings available in the Family View depend on where the
      focus is. The following tables list the bindings for all focus
      targets.</para>

      <variablelist>
        <varlistentry>
          <term>Focus on the Active Person</term>

          <listitem>
            <informaltable frame="topbot">
              <tgroup cols="2">
                <colspec colname="col1" />

                <colspec colname="col2" />

                <thead>
                  <row valign="top">
                    <entry colname="col1" colsep="0"
                    valign="top"><para>Key</para></entry>

                    <entry colname="col2"
                    valign="top"><para>Function</para></entry>
                  </row>
                </thead>

                <tbody>
                  <row valign="top">
                    <entry><para><keycap>Enter</keycap></para></entry>

                    <entry><para>Invoke <guilabel>Edit Person</guilabel>
                    dialog with the active person.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Ctrl</keycap>+<keycap>Down</keycap>
                    or
                    <keycap>Ctrl</keycap>+<keycap>Right</keycap></para></entry>

                    <entry><para>Swap the Active Person and the selected
                    spouse. Use <keycap>Ctrl</keycap>+<keycap>Down</keycap> in
                    standard Family View and
                    <keycap>Ctrl</keycap>+<keycap>Right</keycap> in
                    alternative Family View.</para></entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Focus on the Spouse box</term>

          <listitem>
            <informaltable frame="topbot">
              <tgroup cols="2">
                <colspec colname="col1" />

                <colspec colname="col2" />

                <thead>
                  <row valign="top">
                    <entry colname="col1" colsep="0"
                    valign="top"><para>Key</para></entry>

                    <entry colname="col2"
                    valign="top"><para>Function</para></entry>
                  </row>
                </thead>

                <tbody>
                  <row valign="top">
                    <entry><para><keycap>Enter</keycap></para></entry>

                    <entry><para>Edit relationship between the Active Person
                    and the selected spouse.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Shift</keycap>+<keycap>Enter</keycap></para></entry>

                    <entry><para>Edit the personal information for the
                    selected spouse.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Insert</keycap></para></entry>

                    <entry><para>Add a person from the database to the spouse
                    list.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Shift</keycap>+<keycap>Insert</keycap></para></entry>

                    <entry><para>Add a new person to the database and to the
                    spouse list.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Delete</keycap></para></entry>

                    <entry><para>Delete the selected spouse from the spouse
                    list. The spouse is not deleted from the
                    database.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Ctrl</keycap>+<keycap>Up</keycap> or
                    <keycap>Ctrl</keycap>+<keycap>Left</keycap></para></entry>

                    <entry><para>Swap the selected spouse and the Active
                    Person. Use <keycap>Ctrl</keycap>+<keycap>Up</keycap> in
                    standard Family View and
                    <keycap>Ctrl</keycap>+<keycap>Left</keycap> in alternative
                    Family View.</para></entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Focus on the Parents box</term>

          <listitem>
            <informaltable frame="topbot">
              <tgroup cols="2">
                <colspec colname="col1" />

                <colspec colname="col2" />

                <thead>
                  <row valign="top">
                    <entry colname="col1" colsep="0"
                    valign="top"><para>Key</para></entry>

                    <entry colname="col2"
                    valign="top"><para>Function</para></entry>
                  </row>
                </thead>

                <tbody>
                  <row valign="top">
                    <entry><para><keycap>Enter</keycap></para></entry>

                    <entry><para>Edit relationship between the parents and
                    their child (either the Active Person or the selected
                    spouse, depending which parents box the focus is
                    in).</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Insert</keycap></para></entry>

                    <entry><para>Add a new set of parents from the database to
                    the list.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Shift</keycap>+<keycap>Insert</keycap></para></entry>

                    <entry><para>Add a new set of parents to the database and
                    to the list.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Delete</keycap></para></entry>

                    <entry><para>Delete the selected parents from the list.
                    The parents are not deleted from the
                    database.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Ctrl</keycap>+<keycap>Right</keycap>
                    or
                    <keycap>Ctrl</keycap>+<keycap>Down</keycap></para></entry>

                    <entry><para>Make the selected parents the active family.
                    Use <keycap>Ctrl</keycap>+<keycap>Right</keycap> in
                    standard Family View and
                    <keycap>Ctrl</keycap>+<keycap>Down</keycap> in alternative
                    Family View.</para></entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Focus on the Children box</term>

          <listitem>
            <informaltable frame="topbot">
              <tgroup cols="2">
                <colspec colname="col1" />

                <colspec colname="col2" />

                <thead>
                  <row valign="top">
                    <entry colname="col1" colsep="0"
                    valign="top"><para>Key</para></entry>

                    <entry colname="col2"
                    valign="top"><para>Function</para></entry>
                  </row>
                </thead>

                <tbody>
                  <row valign="top">
                    <entry><para><keycap>Enter</keycap></para></entry>

                    <entry><para>Edit relationship between the child and
                    his/her parents (the Active Person and the selected
                    spouse).</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Shift</keycap>+<keycap>Enter</keycap></para></entry>

                    <entry><para>Edit the personal information for the
                    selected child.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Insert</keycap></para></entry>

                    <entry><para>Add a new person from the database to the
                    children list.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Shift</keycap>+<keycap>Insert</keycap></para></entry>

                    <entry><para>Add a new person to the database and to the
                    children list.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Delete</keycap></para></entry>

                    <entry><para>Delete the selected child from the list. The
                    child is not deleted from the database.</para></entry>
                  </row>

                  <row valign="top">
                    <entry><para><keycap>Ctrl</keycap>+<keycap>Left</keycap>
                    or
                    <keycap>Ctrl</keycap>+<keycap>Up</keycap></para></entry>

                    <entry><para>Make the selected child the Active Person.
                    Use <keycap>Ctrl</keycap>+<keycap>Left</keycap> in
                    standard Family View and
                    <keycap>Ctrl</keycap>+<keycap>Up</keycap> in alternative
                    Family View.</para></entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>
  </appendix>

  <appendix id="append-filtref">
    <!-- $Id$ -->

    <title>Filter rules reference</title>

    <para>This appendix lists of all the filter rules currently defined in
    GRAMPS. Each of these rules is available for use when creating custom
    filters, see <xref linkend="tools-util-cfe" />. The rules are listed by
    their categories.</para>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-general">
      <title>General filters</title>

      <para>This category includes the following most general rules:</para>

      <variablelist>
        <varlistentry>
          <term>Has complete record</term>

          <listitem>
            <para>This rule matches all people whose records are marked as
            complete. Currently, the completeness of personal information is
            marked manually, in the <guilabel>Edit Person</guilabel>
            dialog.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People with incomplete names</term>

          <listitem>
            <para>This rule matches all people with either given name or
            family name missing.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is bookmarked person</term>

          <listitem>
            <para>This rule matches all people who are on the bookmark
            list.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has text matching substring of</term>

          <listitem>
            <para>This rule matches all people whose records contain specified
            substring. All textual records are searched. Optionally, the
            search can be made case sensitive, or a regular expression
            match.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Everyone</term>

          <listitem>
            <para>This rule matches any person in the database. As such it is
            not very useful on its own except for testing purposes. However,
            it may be useful in combinations with other rules.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People probably alive</term>

          <listitem>
            <para>This rule matches all people whose records do not indicate
            their death and who are not unreasonably old, judging by their
            available birth data and today's date.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has a name</term>

          <listitem>
            <para>This rule matches any person whose name matches the
            specified value in full or in part. For example, Marta Ericsdotter
            will be matched by the rule using the value "eric" for the family
            name.</para>

            <para>Separate values can be used for Given name, Family name,
            Suffix, and the Title. The rule returns a match if, and only if,
            all non-empty values are (partially) matched by a person's name.
            To use just one value, leave the other values empty.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has the Id</term>

          <listitem>
            <para>This rule matches any person with a specified GRAMPS ID. The
            rule returns a match only if the ID is matched exactly.</para>

            <para>You can either enter the ID into a text entry field, or
            select a person from the list by clicking
            <guibutton>Select...</guibutton> button. In the latter case, the
            ID will appear in the text field after the selection was
            made.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is default person</term>

          <listitem>
            <para>This rule matches the default (home) person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People marked private</term>

          <listitem>
            <para>This rule matches people whose records are marked as
            private.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a female</term>

          <listitem>
            <para>This rule matches any female person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People who have images</term>

          <listitem>
            <para>This rule matches people with images in their
            galleries.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People without a birth date</term>

          <listitem>
            <para>This rule matches people missing birth date.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a male</term>

          <listitem>
            <para>This rule matches any male person.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-event">
      <title>Event filters</title>

      <para>This category includes the following rules that match people based
      on their recorded events:</para>

      <variablelist>
        <varlistentry>
          <term>Has the birth</term>

          <listitem>
            <para>This rule matches people whose birth event matches specified
            values for Date, Place, and Description. The rule returns a match
            even if the person's birth event matches the value partially. The
            matching rules are case-insensitive. For example, anyone born in
            Sweden will be matched by the rule using the value "sw" for the
            Place.</para>

            <para>The rule returns a match if, and only if, all non-empty
            values are (partially) matched by a person's birth. To use just
            one value, leave the other values empty.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has the death</term>

          <listitem>
            <para>This rule matches people whose death event matches specified
            values for Date, Place, and Description. The rule returns a match
            even if the person's death event matches the value partially. The
            matching rules are case-insensitive. For example, anyone who died
            in Sweden will be matched by the rule using the value "sw" for the
            Place.</para>

            <para>The rule returns a match if, and only if, all non-empty
            values are (partially) matched by a person's death. To use just
            one value, leave the other values empty.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has source of</term>

          <listitem>
            <para>This rule matches people whose records refer to the
            specified source.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has the personal event</term>

          <listitem>
            <para>This rule matches people that have a personal event matching
            specified values for the Event type, Date, Place, and Description.
            The rule returns a match even if the person's event matches the
            value partially. The matching rules are case-insensitive. For
            example, anyone who graduated in Sweden will be matched by the
            rule using the Graduation event and the value "sw" for the
            Place.</para>

            <para>The personal events should be selected from a pull-down
            menu. The rule returns a match if, and only if, all non-empty
            values are (partially) matched by the personal event. To use just
            one value, leave the other values empty.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has the family event</term>

          <listitem>
            <para>This rule matches people that have a family event matching
            specified values for the Event type, Date, Place, and Description.
            The rule returns a match even if the person's event matches the
            value partially. The matching rules are case-insensitive. For
            example, anyone who was married in Sweden will be matched by the
            rule using the Marriage event and the value "sw" for the
            Place.</para>

            <para>The family events should be selected from a pull-down menu.
            The rule returns a match if, and only if, all non-empty values are
            (partially) matched by the personal event. To use just one value,
            leave the other values empty.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Witness</term>

          <listitem>
            <para>This rule matches people who are present as a witness in the
            event. If the personal or family event type is specified, only the
            events of this type will be searched.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People with incomplete events</term>

          <listitem>
            <para>This rule matches people missing date or place in any
            personal event.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Families with incomplete events</term>

          <listitem>
            <para>This rule matches people missing date or place in any family
            event of any of their families.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-family">
      <title>Family filters</title>

      <para>This category includes the following rules that match people based
      on their family relationships:</para>

      <variablelist>
        <varlistentry>
          <term>People with children</term>

          <listitem>
            <para>This rule matches people with children.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People with multiple marriage records</term>

          <listitem>
            <para>This rule matches people with more than one spouse.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People with no marriage records</term>

          <listitem>
            <para>This rule matches people with no spouses.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>People who were adopted</term>

          <listitem>
            <para>This rule matches adopted people.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has the relationships</term>

          <listitem>
            <para>This rule matches people with a particular relationship. The
            relationship must match the type selected from the menu.
            Optionally, the number of relationships and the number of children
            can be specified.</para>

            <para>The rule returns a match if, and only if, all non-empty
            values are (partially) matched by a person's relationship. To use
            just one value, leave the other values empty.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is spouse of filter match</term>

          <listitem>
            <para>This rule matches people married to someone who is matched
            by the specified filter. The specified filter name should be
            selected from the menu.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a child of filter match</term>

          <listitem>
            <para>This rule matches people for whom either parent is matched
            by the specified filter. The specified filter name should be
            selected from the menu.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a parent of filter match</term>

          <listitem>
            <para>This rule matches people whose child is matched by the
            specified filter. The specified filter name should be selected
            from the menu.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a sibling of filter match</term>

          <listitem>
            <para>This rule matches people whose sibling is matched by the
            specified filter. The specified filter name should be selected
            from the menu.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-ancestral">
      <title>Ancestral filters</title>

      <para>This category includes the following rules that match people based
      on their ancestral relations to other people:</para>

      <variablelist>
        <varlistentry>
          <term>Is an ancestor of</term>

          <listitem>
            <para>This rule matches people who are ancestors of the specified
            person. The Inclusive option determines whether the specified
            person should be considered his/her own ancestor (useful for
            building reports).</para>

            <para>You can either enter the ID into a text entry field, or
            select a person from the list by clicking
            <guibutton>Select...</guibutton> button. In the latter case, the
            ID will appear in the text field after the selection was
            made.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is an ancestor of person at least N generations away</term>

          <listitem>
            <para>This rule matches people who are ancestors of the specified
            person and are at least N generations away from that person in
            their lineage. For example, using this rule with the value of 2
            for the number of generations will match grandparents,
            great-grandparents, etc., but not the parents of the specified
            person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is an ancestor of person not more than N generations
          away</term>

          <listitem>
            <para>This rule matches people who are ancestors of the specified
            person and are no more than N generations away from that person in
            their lineage. For example, using this rule with the value of 2
            for the number of generations will match parents and grandparents,
            but not great-grandparents, etc., of the specified person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has a common ancestor with</term>

          <listitem>
            <para>This rule matches people who have common ancestors with the
            specified person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has a common ancestor with filter match</term>

          <listitem>
            <para>This rule matches people who have common ancestors with
            someone who is matched by the specified filter. The specified
            filter name should be selected from the menu.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is an ancestor of filter match</term>

          <listitem>
            <para>This rule matches people who are ancestors of someone who is
            matched by the specified filter. The specified filter name should
            be selected from the menu.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-descendant">
      <title>Descendant filters</title>

      <para>This category includes the following rules that match people based
      on their descendant relations to other people:</para>

      <variablelist>
        <varlistentry>
          <term>Is a descendant of</term>

          <listitem>
            <para>This rule matches people who are descendants of the
            specified person. The Inclusive option determines whether the
            specified person should be considered his/her own descendant
            (useful for building reports).</para>

            <para>You can either enter the ID into a text entry field, or
            select a person from the list by clicking
            <guibutton>Select...</guibutton> button. In the latter case, the
            ID will appear in the text field after the selection was
            made.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a descendant of person at least N generations away</term>

          <listitem>
            <para>This rule matches people who are descendants of the
            specified person and are at least N generations away from that
            person in their lineage. For example, using this rule with the
            value of 2 for the number of generations will match grandchildren,
            great-grandchildren, etc., but not the children of the specified
            person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a descendant of person not more than N generations
          away</term>

          <listitem>
            <para>This rule matches people who are descendants of the
            specified person and are no more than N generations away from that
            person in their lineage. For example, using this rule with the
            value of 2 for the number of generations will match children and
            grandchildren, but not great-grandchildren, etc., of the specified
            person.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a descendant of filter match</term>

          <listitem>
            <para>This rule matches people who are descendants of someone who
            is matched by the specified filter. The specified filter name
            should be selected from the menu.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Is a descendant family member of</term>

          <listitem>
            <para>This rule not only matches people who are descendants of the
            specified person, but also those descendants' spouses.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-relat">
      <title>Relationship filters</title>

      <para>This category includes the following rules that match people based
      on their mutual relationship:</para>

      <variablelist>
        <varlistentry>
          <term>Relationship path between two people</term>

          <listitem>
            <para>This rule matches all ancestors of both people back to their
            common ancestors (if exist). This produces the "relationship path"
            between these two people, through their common ancestors.</para>

            <para>You can either enter the ID of each person into the
            appropriate text entry fields, or select people from the list by
            clicking their <guibutton>Select...</guibutton> buttons. In the
            latter case, the ID will appear in the text field after the
            selection was made.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <!-- =============== Appendices Sub-subsection ================ -->

    <sect1 id="filtref-misc">
      <title>Miscellaneous filters</title>

      <para>This category includes the following rules which do not naturally
      fit into any of the above categories:</para>

      <variablelist>
        <varlistentry>
          <term>Has the personal attribute</term>

          <listitem>
            <para>This rule matches people who have the personal attribute of
            the specified value. The specified personal attribute name should
            be selected from the menu. The specified value should be typed
            into the text entry field.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Has the family attribute</term>

          <listitem>
            <para>This rule matches people who have the family attribute of
            the specified value. The specified family attribute should be
            selected from the menu. The specified value should be typed into
            the text entry field.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Matches the filter named</term>

          <listitem>
            <para>This rule matches people who are matched by the specified
            filter. The specified filter name should be selected from the
            menu.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>
  </appendix>

  <appendix id="append-cmdline">
    <!-- $Id$ -->

    <!-- =============== Appendices Subsection ================ -->

    <title>Command line reference</title>

    <para>This appendix provides the reference to the command line
    capabilities available when launching GRAMPS from the terminal.</para>

    <note>
      <para>GRAMPS was designed to be an interactive program. Therefore it
      uses graphical display and cannot run from the true non-graphical
      console. It would take an enormous amount of effort to enable it to run
      in a text-only terminal. This is why the set of command line options
      does not aim to completely get rid of dependency on the graphical
      display. Rather, it merely makes certain (typical) tasks more
      convenient. It also allows one to execute these tasks from the scripts.
      However, the graphical display must be accessible at all times!</para>
    </note>

    <tip>
      <para>To summarize, the use of the command line options provides
      non-interactive behavior, but does not get rid of graphical display
      dependency. Take it or leave it!</para>
    </tip>

    <sect1 id="cmdline-options">
      <title>Available options</title>

      <para>This section provides the reference list of all command line
      options available in GRAMPS. If you want to know more than just a list
      of options, see next sections: <xref linkend="cmdline-operation" /> and
      <xref linkend="cmdline-examples" />.</para>

      <sect2 id="cmdline-opt-format">
        <title>Format options</title>

        <para>The format of any file destined for opening, importing, or
        exporting can be specified with the <command>-f
        <replaceable>format</replaceable></command> option. The acceptable
        <replaceable>format</replaceable> values are listed below.</para>

        <variablelist>
          <varlistentry>
            <term>grdb</term>

            <listitem>
              <para>GRAMPS database. This format is available for opening,
              import, and export. When not specified, it can be guessed if the
              filename ends with .grdb</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>gramps-xml</term>

            <listitem>
              <para>GRAMPS XML database. This format is available for opening,
              import, and export. When not specified, it can be guessed if the
              filename ends with .gramps</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>gedcom</term>

            <listitem>
              <para>GEDCOM file. This format is available for opening, import,
              and export. When not specified, it can be guessed if the
              filename ends with .ged</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>gramps-pkg</term>

            <listitem>
              <para>GRAMPS package. This format is available for import and
              export. When not specified, it can be guessed if the filename
              ends with .gpkg</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>geneweb</term>

            <listitem>
              <para>GeneWen file This format is available for import and
              export. When not specified, it can be guessed if the filename
              ends with .gw</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>wft</term>

            <listitem>
              <para>Web Family Tree. This format is available for export only.
              When not specified, it can be guessed if the filename ends with
              .wft</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>iso</term>

            <listitem>
              <para>CD image. This format is available for export only. It
              must always be specified explicitly.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <sect2 id="cmdline-opt-open">
        <title>Opening options</title>

        <para>There are two ways to give GRAMPS the name of the file to be
        opened:</para>

        <itemizedlist>
          <listitem>
            <para>supply bare file name</para>
          </listitem>

          <listitem>
            <para>use the <command>-O <filename>filename</filename></command>
            or <command>-open=<filename>filename</filename></command>
            option</para>
          </listitem>
        </itemizedlist>

        <para>If the filename is given without any option flag, the attempt to
        open the file will be made, and then the interactive GRAMPS session
        will be launched.</para>

        <tip>
          <para>If no option is given, just the file name, GRAMPS will ignore
          the rest of the command line arguments. Use the -O flag to open the
          file and do something with the data.</para>
        </tip>

        <para>The format can be specified with the <command>-f
        <replaceable>format</replaceable></command> or
        <command>--format=<replaceable>format</replaceable></command> option,
        immediately following the <filename>filename</filename>. If not
        specified, the guess will be attempted based on the
        <filename>filename</filename>.</para>

        <tip>
          <para>Only grdb, gramps-xml, and gedcom formats can be opened
          directly. For other formats, you will need to use the import option
          which will set up the empty database and then import data into
          it.</para>
        </tip>

        <tip>
          <para>Only a single file can be opened. If you need to combine data
          from several sources, you will need to use the import option.</para>
        </tip>
      </sect2>

      <sect2 id="cmdline-opt-import">
        <title>Import options</title>

        <para>The files destined for import can be specified with the
        <command>-i <filename>filename</filename></command> or
        <command>--import=<filename>filename</filename></command> option. The
        format can be specified with the <command>-f
        <replaceable>format</replaceable></command> or
        <command>--format=<replaceable>format</replaceable></command> option,
        immediately following the <filename>filename</filename>. If not
        specified, the guess will be attempted based on the
        <filename>filename</filename>.</para>

        <tip>
          <para>More than one file can be imported in one command. If this is
          the case, GRAMPS will incorporate the data from the next file into
          the database available at the moment.</para>
        </tip>

        <para>When more than one input file is given, each has to be preceded
        by <command>-i</command> flag. The files are imported in the specified
        order, i.e. <command> -i <filename>file1</filename> -i
        <filename>file2</filename> </command> and <command> -i
        <filename>file2</filename> -i <filename>file1</filename> </command>
        might produce different GRAMPS IDs in the resulting database.</para>
      </sect2>

      <sect2 id="cmdline-opt-export">
        <title>Export options</title>

        <para>The files destined for export can be specified with the
        <command>-o <filename>filename</filename></command> or
        <command>--output=<filename>filename</filename></command> option. The
        format can be specified with the <command>-f</command> option
        immediately following the <filename>filename</filename>. If not
        specified, the guess will be attempted based on the
        <filename>filename</filename>. For iso format, the
        <filename>filename</filename> is actually the name of directory the
        GRAMPS database will be written into. For grdb, gramps-xml, gedcom,
        wft, geneweb, and gramps-pkg, the <filename>filename</filename> is the
        name of the resulting file.</para>

        <tip>
          <para>More than one file can be exported in one command. If this is
          the case, GRAMPS will attempt to write several files using the data
          from the database available at the moment.</para>
        </tip>

        <para>When more than one output file is given, each has to be preceded
        by <command>-o</command> flag. The files are written one by one, in
        the specified order.</para>
      </sect2>

      <sect2 id="cmdline-opt-action">
        <title>Action options</title>

        <para>The action to perform on the imported data can be specified with
        the <command>-a <replaceable>action</replaceable></command> or
        <command>--action=<replaceable>action</replaceable></command> option.
        This is done after all imports are successfully completed.</para>

        <para>Currently available actions are:</para>

        <variablelist>
          <varlistentry>
            <term>summary</term>

            <listitem>
              <para>This action is the same as <menuchoice>
                  <guimenu>Reports</guimenu>

                  <guisubmenu>View</guisubmenu>

                  <guimenuitem>Summary</guimenuitem>
                </menuchoice></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>check</term>

            <listitem>
              <para>This action is the same as <menuchoice>
                  <guimenu>Tools</guimenu>

                  <guisubmenu>Database Processing</guisubmenu>

                  <guimenuitem>Check and Repair</guimenuitem>
                </menuchoice>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>report</term>

            <listitem>
              <para>This action allows producing reports from the command
              line. As reports generally have many options of their own, this
              action should be followed by the report option string. The
              string is given using the <command>-p
              <replaceable>option_string</replaceable></command> or
              <command>--options=<replaceable>option_string</replaceable></command>
              option.</para>

              <tip>
                <para>The report option string should satisfy the following
                conditions:</para>

                <itemizedlist>
                  <listitem>
                    <para>It must not contain any spaces. If some arguments
                    need to include spaces, the string should be enclosed with
                    quotation marks.</para>
                  </listitem>

                  <listitem>
                    <para>Option string must list pairs of option names and
                    values.</para>
                  </listitem>

                  <listitem>
                    <para>Within a pair, option name and value must be
                    separated by the equal sign.</para>
                  </listitem>

                  <listitem>
                    <para>Different pairs must be separated by commas.</para>
                  </listitem>
                </itemizedlist>
              </tip>

              <para>Most of the report options are specific for every report.
              However, there some common options.</para>

              <variablelist>
                <varlistentry>
                  <term>name=report_name</term>

                  <listitem>
                    <para>This mandatory option determines which report will
                    be generated. If the supplied report_name does not
                    correspond to any available report, the error message will
                    be printed followed by the list of available
                    reports.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>show=all</term>

                  <listitem>
                    <para>This will produce the list of names for all options
                    available for a given report.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>show=option_name</term>

                  <listitem>
                    <para>This will print the description of the functionality
                    supplied by the option_name, as well as what are the
                    acceptable types and values for this option.</para>
                  </listitem>
                </varlistentry>
              </variablelist>

              <para>Use the above options to find out everything about a given
              report.</para>

              <tip>
                <para>If an option is not supplied, the last used value will
                be used. If this report has never been generated before, then
                the value from last generated report will be used when
                applicable. Otherwise, the default value will be used.</para>
              </tip>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>When more than one output action is given, each has to be
        preceded by <command>-a</command> flag. The actions are performed one
        by one, in the specified order.</para>
      </sect2>
    </sect1>

    <!--       &cmdplug; -->

    <sect1 id="cmdline-operation">
      <title>Operation</title>

      <itemizedlist>
        <listitem>
          <para>If the first argument on the command line does not start with
          dash (i.e. no flag), GRAMPS will attempt to open the file with the
          name given by the first argument and start interactive session,
          ignoring the rest of the command line arguments.</para>
        </listitem>

        <listitem>
          <para>If the <command>-O</command> flag is given, then GRAMPS will
          try opening the supplied file name and then work with that data, as
          instructed by the further command line parameters.</para>

          <note>
            <para>Only one file can be opened in a single invocation of
            GRAMPS. If you need to get data from multiple sources, use the
            importing options by using <command>-i</command> flag.</para>
          </note>
        </listitem>

        <listitem>
          <para>With or without the <command>-O</command> flag, there could be
          multiple imports, exports, and actions specified further on the
          command line by using <command>-i</command>, <command>-o</command>,
          and <command>-a</command> flags.</para>
        </listitem>

        <listitem>
          <para>The order of <command>-i</command>, <command>-o</command>, or
          <command>-a</command> options with respect to each does not matter.
          The actual execution order always is: all imports (if any) -&gt; all
          exports (if any) -&gt; all actions (if any).</para>

          <note>
            <para>But opening must always be first!</para>
          </note>
        </listitem>

        <listitem>
          <para>If no <command>-O</command> or <command>-i</command> option is
          given, GRAMPS will launch its main window and start the usual
          interactive session with the empty database, since there is no data
          to process, anyway.</para>
        </listitem>

        <listitem>
          <para>If no <command>-o</command> or <command>-a</command> options
          are given, GRAMPS will launch its main window and start the usual
          interactive session with the database resulted from opening and all
          imports (if any). This database resides in the
          <filename>import_db.grdb</filename> file under the
          <filename>~/.gramps/import/</filename> directory.</para>
        </listitem>

        <listitem>
          <para>Any errors encountered during import, export, or action, will
          be either dumped to stdout (if these are exceptions handled by
          GRAMPS) or or to stderr (if these are not handled). Use usual shell
          redirections of stdout and stderr to save messages and errors in
          files.</para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1 id="cmdline-examples">
      <title>Examples</title>

      <variablelist>
        <varlistentry>
          <term>To import four databases (whose formats can be determined from
          their names) and then check the resulting database for errors, one
          may type:</term>

          <listitem>
            <para><command>gramps -i<filename>file1.ged</filename> -i
            <filename>file2.gpkg</filename> -i
            <filename>~/db3.gramps</filename> -i
            <filename>file4.wft</filename> -a
            <filename>check</filename></command></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>To explicitly specify the formats in the above example, append
          filenames with appropriate <command>-f</command> options:</term>

          <listitem>
            <para><command>gramps -i <filename>file1.ged</filename> -f
            <replaceable>gedcom</replaceable> -i
            <filename>file2.gpkg</filename> -f
            <replaceable>gramps-pkg</replaceable> -i
            <filename>~/db3.gramps</filename> -f
            <replaceable>gramps-xml</replaceable> -i
            <filename>file4.wft</filename> -f <replaceable>wft</replaceable>
            -a <replaceable>check</replaceable></command></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>To record the database resulting from all imports, supply
          <command>-o</command> flag (use <command>-f</command> if the
          filename does not allow GRAMPS to guess the format):</term>

          <listitem>
            <para><command>gramps -i <filename>file1.ged</filename> -i
            <filename>file2.gpkg</filename> -o
            <filename>~/new-package</filename> -f
            <replaceable>gramps-pkg</replaceable></command></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>To save any error messages of the above example into files
          <filename>outfile</filename> and <filename>errfile</filename>,
          run:</term>

          <listitem>
            <para><command>gramps -i <filename>file1.ged</filename> -i
            <filename>file2.dpkg</filename> -o
            <filename>~/new-package</filename> -f
            <replaceable>gramps-pkg</replaceable>
            &gt;<filename>outfile</filename> 2&gt;<filename>errfile</filename>
            </command></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>To import three databases and start interactive GRAMPS session
          with the result:</term>

          <listitem>
            <para><command>gramps -i <filename>file1.ged</filename> -i
            <filename>file2.gpkg</filename> -i
            <filename>~/db3.gramps</filename> </command></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>To open a database and, based on that data, generate timeline
          report in PDF format putting the output into the
          <filename>my_timeline.pdf</filename> file:</term>

          <listitem>
            <para><command>gramps -O <filename>file.grdb</filename> -a
            <replaceable>report</replaceable> -p
            <replaceable>name=timeline,off=pdf,of=my_timeline.pdf</replaceable>
            </command></para>

            <tip>
              <para>Use the <replaceable>name=timeline,show=all</replaceable>
              to find out about all available options for the timeline report.
              To find out details of a particular option, use
              <replaceable>show=option_name</replaceable>, e.g.
              <replaceable>name=timeline,show=off</replaceable> string.</para>

              <para>To learn about available report names, use
              <replaceable>name=show</replaceable> string.</para>
            </tip>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Finally, to start normal interactive session type:</term>

          <listitem>
            <para><command>gramps </command></para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>
  </appendix>

  <!-- ENTITY cmdplug SYSTEM "cmdplug.xml" -->

  <!-- ENTITY bugs SYSTEM "bugs.xml" -->

  <appendix id="gramps-about">
    <!-- $Id$ -->

    <title>About GRAMPS</title>

    <para>GRAMPS was written by Donald N. Allingham
    (<email>don@gramps-project.org</email>).</para>

    <para>The somewhat incomplete list of contributors includes (in
    alphabetical order): <itemizedlist>
        <listitem>
          <para>Larry Allingham</para>
        </listitem>

        <listitem>
          <para>Jens Arvidsson</para>
        </listitem>

        <listitem>
          <para>Marcos Bedinelli</para>
        </listitem>

        <listitem>
          <para>Douglas S. Blank</para>
        </listitem>

        <listitem>
          <para>Radu Bogdan Mare</para>
        </listitem>

        <listitem>
          <para>Alexander Bogdashevsky</para>
        </listitem>

        <listitem>
          <para>Richard Bos</para>
        </listitem>

        <listitem>
          <para>Nathan Bullock</para>
        </listitem>

        <listitem>
          <para>Lorenzo Cappelletti</para>
        </listitem>

        <listitem>
          <para>Pier Luigi Cinquantini</para>
        </listitem>

        <listitem>
          <para>Bruce J. DeGrasse</para>
        </listitem>

        <listitem>
          <para>Alexandre Duret-Lutz</para>
        </listitem>

        <listitem>
          <para>Billy C. Earney</para>
        </listitem>

        <listitem>
          <para>Baruch Even</para>
        </listitem>

        <listitem>
          <para>Bernd Felsche</para>
        </listitem>

        <listitem>
          <para>Egyeki Gergely</para>
        </listitem>

        <listitem>
          <para>Michel Guitel</para>
        </listitem>

        <listitem>
          <para>Steve Hall</para>
        </listitem>

        <listitem>
          <para>David R. Hampton</para>
        </listitem>

        <listitem>
          <para>Martin Hawlisch</para>
        </listitem>

        <listitem>
          <para>Anton Huber</para>
        </listitem>

        <listitem>
          <para>Frode Jemtland</para>
        </listitem>

        <listitem>
          <para>Greg Kuperberg</para>
        </listitem>

        <listitem>
          <para>Arkadiusz Lipiec</para>
        </listitem>

        <listitem>
          <para>Lars Kr. Lundin</para>
        </listitem>

        <listitem>
          <para>Radek Malcic</para>
        </listitem>

        <listitem>
          <para>Leonid Mamtchenkov</para>
        </listitem>

        <listitem>
          <para>Tino Meinen</para>
        </listitem>

        <listitem>
          <para>Frederick Noronha</para>
        </listitem>

        <listitem>
          <para>Jeffrey C. Ollie</para>
        </listitem>

        <listitem>
          <para>Donald A. Peterson</para>
        </listitem>

        <listitem>
          <para>Guillaume Pratte</para>
        </listitem>

        <listitem>
          <para>Laurent Protois</para>
        </listitem>

        <listitem>
          <para>Matthieu Pupat</para>
        </listitem>

        <listitem>
          <para>Trevor Rhodes</para>
        </listitem>

        <listitem>
          <para>Alexander Roitman</para>
        </listitem>

        <listitem>
          <para>Jason Salaz</para>
        </listitem>

        <listitem>
          <para>Julio Sanchez</para>
        </listitem>

        <listitem>
          <para>Bernd Schandl</para>
        </listitem>

        <listitem>
          <para>Martin Senftleben</para>
        </listitem>

        <listitem>
          <para>Gary Shao</para>
        </listitem>

        <listitem>
          <para>Jim Smart</para>
        </listitem>

        <listitem>
          <para>Steve Swales</para>
        </listitem>

        <listitem>
          <para>Eero Tamminen</para>
        </listitem>

        <listitem>
          <para>Samuel Tardieu</para>
        </listitem>

        <listitem>
          <para>Richard Taylor</para>
        </listitem>

        <listitem>
          <para>James Treacy</para>
        </listitem>

        <listitem>
          <para>Sebastian Voecking</para>
        </listitem>

        <listitem>
          <para>Xing Wang</para>
        </listitem>

        <listitem>
          <para>Tim Waugh</para>
        </listitem>

        <listitem>
          <para>Jesper Zedlitz</para>
        </listitem>
      </itemizedlist> If you know of somebody else who should be listed here,
    please let us know.</para>

    <para>To find more information about GRAMPS, please visit the <ulink
    type="http" url="http://gramps-project.org">GRAMPS Project Web
    page</ulink>.</para>

    <para>To report a bug or make a suggestion regarding this application or
    this manual, use the help menu in GRAMPS, or follow the directions on
    <ulink type="http" url="http://gramps.sourceforce.net/contact.html">this
    site.</ulink></para>

    <para>This program is distributed under the terms of the GNU General
    Public license as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version. A copy of
    this license can be found at this <ulink type="help"
    url="ghelp:gpl">link</ulink>, or in the file COPYING included with the
    source code of this program.</para>
  </appendix>
</book>