<!--
	  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
-->
<!-- $Id: usage.xml,v 1.16.2.20 2005/12/11 05:24:19 dallingham Exp $ -->

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

    As commonly encountered in everyday life, there is usually more
    than one way to accomplish something in &app;. The alternatives to
    some actions will therefore be listed as 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>. 

      You will then be prompted with the <guilabel>Create GRAMPS
      database</guilabel> dialog asking to specify the name under
      which the new database will be stored.  The new database will be
      created in the BSDDB format, with <filename>.grdb</filename> as
      the default extension.

    </para>
    <note id="new-db-notdir-note">
      <title>Selecting file</title>
      <para>

        This version does not require selecting a directory for the
        database. Please select filename, as you would in any other
        application.

      </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.

    </para>
    <para>

      The filetype filter in the <guilabel>Open database</guilabel>
      dialog allows you to display files of a certain type. If the
      <guilabel>All files</guilabel> filter is selected (the default),
      all the files will be shown. The type will be determined by the
      extension of the selected filename.

    </para>
    <note id="open-db-note">
      <title>Selecting file</title>
      <para>

        Unlike the version 1.0.X of &app;, this version does not
        require selecting directory for the database. Please select
        filename, as you would in any other application.

      </para>
    </note>
    <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>
    <note id="open-db-note2">
      <title>Opening XML and GEDCOM databases</title>
      <para>

        This version allows direct opening and editing of &app; XML
        and GEDCOM databases. Please keep in mind that, unlike using
        the native grdb format, these formats require holding all data
        in memory. This leads to performance and memory consumption
        problems which grdb was designed to solve.

      </para>
      <para>

        While direct opening of a &app; XML or GEDCOM file is
        convenient for a small database, it may prove burdensome for
        large databases.  If you experience this, please consider
        creating a new native (grdb) database and importing your XML
        or GEDCOM data into it. This will make accessing your data
        much more efficient and quick.

      </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 &app;. Simply opening and viewing
	the file will not change it.  However, if any changes were
	made and they were not abandoned upon exit, exiting &app; will
	save the data, with possible data loss.

      </para>
    </warning>
    <para>
      To open a recently opened database, choose 

      <menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>Open Recent</guimenuitem>
      </menuchoice> 

      and select the filename from the list.  You can also use

      <menuchoice>
        <guimenu>Actions</guimenu>
        <guimenuitem>Recent Documents</guimenuitem>
      </menuchoice> 

      from the GNOME <guilabel>Actions</guilabel> menu.
    </para>
  </sect1>

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

  <sect1 id="save-db">
    <title>Saving a Database</title>
    <para>

      A consequence of the new database backend is that the changes,
      once approved by the user, are applied immediately.  Once you
      click <guibutton>OK</guibutton> in the Person, Family, Source,
      Place, Media object, or Event editor, all the changes made to
      this object are recorded in the database. No saving is
      necessary, or even possible.

    </para>
    <para>
      Choosing
      <menuchoice>
        <guimenu>Edit</guimenu>
        <guimenuitem>Undo</guimenuitem>
      </menuchoice> 
      allows you to undo the changes you made, one step at a time.
    </para>

    <tip id="save-tip">
      <title>Reverting the whole session</title>
      <para>

        If you would like to revert the whole editing session, choose
        <menuchoice><guimenu>File</guimenu><guimenuitem>Abandon
        changes and quit</guimenuitem></menuchoice>. This will be
        analogous to quitting without saving any changes in other
        applications.

      </para>
    </tip>
    <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, format) of your new
      database.

    </para>
    <note id="save-as-note">
      <title>"Save as" continues editing</title>
      <para>
        If you use the <guilabel>Save as...</guilabel> function, the
        editing in the main window is performed on the newly made
        copy. If this is not what you want to do, please consider
        using <guilabel>Export...</guilabel> instead.
      </para>
    </note>
  </sect1>

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

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

      Importing allows you to incorporate the data from other
      databases into your currently open &app; database. Currently,
      &app; can import data from the following formats: &app; database
      (grdb), GEDCOM, &app; XML, &app; package, and GeneWeb. All of
      these are available by choosing

      <menuchoice>
        <guimenu>File</guimenu>
        <guisubmenu>Import</guisubmenu>
      </menuchoice> 
      and selecting an appropriate file.

    </para>
    <para>

      &app; database (grdb), &app; XML, and &app; package are all
      native &app; formats in that there is no information loss
      resulting from reading from and writing into these formats.

      <variablelist>
        <varlistentry>
          <term>&app; database (grdb)</term>
          <listitem>
            <para>
              The native &app; database format is a specific form of
              Berkeley database (BSDDB) with 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>&app; XML</term>
          <listitem>
            <para>

              The &app; XML file was the default format for the
              previous stable version of &app;. 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 &app; 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>&app; package</term>
          <listitem>
            <para> 
              The package is a compressed archive containing the &app;
              XML file and all media objects (images, sound files,
              etc.) to which the database refers. The &app; package is
              created by exporting ( 
              <menuchoice>
                <guimenu>File</guimenu>
                <guimenuitem>Export...</guimenuitem>
              </menuchoice>
              ) data in that format.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>

    <tip id="import-tip">
      <title>Opening vs importing</title>
      <para>
        The difference between opening &app; database (in any format)
        and importing from &app; or GEDCOM database is that importing
        incorporates all the data into your currently open database,
        if any. In contrast, opening the database will switch from
        editing your current data to editing another file.
      </para>
    </tip>

    <para>
      After choosing an import format, you will be prompted with the
      <guilabel>Import database</guilabel> dialog asking you to
      specify the file name from which to import.
    </para>

    <note id="import-note">
      <title>Selecting file</title>
      <para>
        This version does not require selecting a directory for the
	database. Please select filename, as you would in any other
	application.
      </para>
    </note>

    <para>
      Upon starting the GEDCOM import, &app; will display the
      following GEDCOM import dialog with the summary of the
      information about the data. The information is updated as the
      import progresses.
    </para>

<!-- ==== Figure: GEDCOM Import ==== -->
    <figure id="gedcom-import-fig">
      <title>GEDCOM Import</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/gedcom-import.png" format="PNG" 
	               width="510" depth="490" scale="75"/>
          </imageobject>
          <textobject>
            <phrase>Shows GEDCOM Import Window.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>

<!-- ==== End of Figure ==== -->
    <para>
      Upon starting the &app; database or &app; package import, &app;
      will display the progress in the progress bar of its main window.
    </para>

    <para>
      If a media file is not found during import, the following dialog
      will prompt you for the possible actions:
    </para>

<!-- ==== Figure: Missing media window  ==== -->

    <figure id="missing-media-im">
      <title>Missing Media dialog</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/missing-media.png" 
	               format="PNG" width="493" depth="264"
		       scale="75"/>
          </imageobject>
          <textobject>
            <phrase>Shows Missing Media dialog.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>

<!-- ==== End of Figure ==== -->
    <itemizedlist>
      <listitem>
        <para>
          To remove the object corresponding to the missing file as
          well as all the references to that object from various
          database records, click the <guibutton>Remove
          Object</guibutton> button. This will alter your database so
          that it will be in a consistent state, but all the
          references to the missing file will be gone. Use this option
          if the file is irrevocably lost and there is no possibility
          of ever replacing it.
        </para>
      </listitem>
      <listitem>
        <para>
          To keep the reference to the object corresponding to the
          missing file, click the <guibutton>Keep
          Reference</guibutton> button.  This will leave things as is,
          i.e. in an inconsistent state.  You could supply the missing
          file later, in which case you will have to copy it into your
          database directory. Choose this option if the replacement is
          possible, but not available right now.
        </para>
      </listitem>
      <listitem>
        <para>
          To supply the missing file during import, click the
          <guibutton>Select File</guibutton> button. This will copy
          the file you select in place of the missing file. No
          references will be altered in the database, and it will be
          in the consistent state. Use this option if the replacement
          is readily available.
        </para>
      </listitem>
      <listitem>
        <para>
          To automatically use the selection made in this dialog for
          all missing media files, check the <guilabel>Use this
          selection for all missing media files</guilabel> box. This
          will remember your choice and use it for all media files
          missing during this import, so that no further dialogs will
          be presented. Use this option if you anticipate many missing
          files and want to deal with all of them in the same manner.
        </para>
      </listitem>
    </itemizedlist>
  </sect1>
<!-- ================ Usage Subsection ================================ -->
  <sect1 id="export-data">
    <title>Exporting Data</title>
    <para>
      Exporting allows you to share any portion of your &app; database
      with other researchers as well as to make your database
      completely portable to another computer. Currently, &app; can
      export data to the following formats: &app; database (grdb),
      &app; XML, GEDCOM, &app; package, Web Family Tree, and GeneWeb.
    </para>
    <note id="export-note">
      <title>Export is saving a copy</title>
      <para>
         Exporting will create another file with the copy of your data.
        The database currently opened in your &app; window is NOT the
        file saved by your export. Future 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> druid. 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 druid: format selection</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/export-druid.png" format="PNG" 
	               width="500" depth="383" scale="75"/>
          </imageobject>
          <textobject>
            <phrase>Shows format selection page of an Export druid</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <sect2 id="export-gedcom">
      <title>GEDCOM export</title>
      <para> 
        GEDCOM export options allow you to fine tune your export (see
        <xref linkend="gedcom-export-fig"/>).  Choose the desired
        <guilabel>Encoding</guilabel> of the exported file.  Use the
        <guilabel>Filter</guilabel> pop-up menu to limit the scope of
        the export according to the stated rule.  Use the
        <guilabel>Target</guilabel> menu to select the desired GEDCOM
        dialect. Select your copyright statement from the
        <guilabel>Copyright</guilabel> menu. Check <guilabel>Do not
        include records marked private</guilabel> to disable the
        output of private records. Check <guilabel>Restrict data on
        living people</guilabel> to limit living people's data to
        family ties. With this option, information concerning birth,
        death, addresses, various events, etc. will be omitted in the
        exported GEDCOM file. If this option is selected, you can
        further choose whether to use the word "Living" as first name,
        exclude notes, and exclude sources for the living
        people. Check <guilabel>Reference images from path</guilabel>
        to tell &app; to use the specific path for your images when
        writing image references in GEDCOM.
      </para>
<!-- ==== Figure: GEDCOM Export ==== -->
      <figure id="gedcom-export-fig">
        <title>Export druid: GEDCOM options</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/gedcom-export.png" format="PNG" 
	                 width="500" depth="481" scale="75"/>
            </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 &app; formats</title>
      <variablelist>
        <varlistentry>
          <term>&app; database (grdb) export</term>
          <listitem>
            <para>
               Exporting to the native format will simply make a copy
               of your data under another name. It also may be useful
               if you have directly opened XML or GEDCOM file and
               would like to save it as the grdb file.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>&app; XML database export</term>
          <listitem>
            <para>
              Exporting into &app; XML format will produce a database
              compatible with the previous versions of &app;.  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>&app; package export</term>
          <listitem>
            <para>
              Exporting to &app; package will create a gzip-compressed
              tar archive (also known as tarball) which contains
              gramps database and copies of all media objects
              files. This is a useful format for moving your database
              to another machine or for sharing it with somebody,
              while retaining all the features provided by &app; .
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Export to CD</term>
          <listitem>
            <para>
              Exporting to CD will prepare your database and copies of
              all media objects files to be recorded to the CD. This
              is done through the <guilabel>burn:///</guilabel>
              location in Nautilus. After exporting to CD, go to the
              <guilabel>burn:///</guilabel> location by selecting
              <menuchoice>
                <guimenu>Go</guimenu>
                <guisubmenu>CD Creator</guisubmenu>
              </menuchoice> 

              in Nautilus menu (unless this location is already
              displayed by &app;). Your database directory will show
              up. To record it on to the CD, click the CD icon on the
              Nautilus toolbar, or select
              <menuchoice>
                <guimenu>File</guimenu>
                <guisubmenu>Write to CD</guisubmenu>
              </menuchoice> 
              in Nautilus menu.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
         If a media file is not found during export, the following
         dialog will prompt you for the possible actions:
      </para>

<!-- ==== Figure: Missing media window  ==== -->

      <figure id="missing-media-ex">
        <title>Missing Media dialog</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/missing-media.png" format="PNG" 
	                 width="434" depth="264" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Missing Media dialog.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

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

      <itemizedlist>
        <listitem>
          <para>
            To remove the object corresponding to the missing file
            as well as all the references to that object from
            various database records, click the <guibutton>Remove
            Object</guibutton> button. This will alter your database
            so that it will be in the consistent state, but all the
            references to the missing file will be gone. Use this
            option if the file is irrevocably lost and there is no
            possibility of ever replacing it.
          </para>
        </listitem>
        <listitem>
          <para>
            To keep the reference to the object corresponding to the
            missing file, click the <guibutton>Keep
            Reference</guibutton> button.  This will leave things as
            is, i.e. in the inconsistent state.  You could supply
            the missing file later, in which case you will have to
            copy it into your database directory. Choose this option
            if the replacement is possible, but not available right
            now.
          </para>
        </listitem>
        <listitem>
          <para>
            To supply the missing file during export, click the
            <guibutton>Select File</guibutton> button. This will
            copy the file you select in place of the missing
            file. No references will be altered in the database, and
            it will be in the consistent state. Use this option if
            the replacement is readily available.
          </para>
        </listitem>
        <listitem>
          <para>
            To automatically use the selection made in this dialog
            for all missing media files, check the <guilabel>Use
            this selection for all missing media files</guilabel>
            box. This will remember your choice and use it for all
            media files missing during this export, so that no
            further dialogs will be presented. Use this option if
            you anticipate many missing files and want to deal with
            all of them in the same manner.
          </para>
        </listitem>
      </itemizedlist>
    </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 the text file
              suitable as an input for the WFT program. Specific
              options include filter selection and the ability to
              restrict data on living people, that is to limit living
              people's data to 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 url="http://cristal.inria.fr/~ddr/GeneWeb/en/" 
	             type="http">this site.</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>Editing Data: Quick Start</title>
    <para> 
        Editing any portion of data allows you to amend and/or modify
	information stored in the database. The available editing
	options include editing personal data, relationship data, data
	about children and parents, and information about sources,
	places, and media objects used in the database. In short, any
	data stored in the database can be edited! Adding a new piece
	of information is the process of creating an appropriate empty
	data structure and subsequently editing that empty structure.
      </para>
    <para>
         This section refers mainly to the menu items and buttons as
         the main way of interacting with &app;. In addition to this,
         &app; provides an extensive set of key bindings. The detailed
         reference to the key bindings is found in the 
	 <xref linkend="append-keybind"/>.
       </para>
<!-- ================ Usage Sub-subsection ================ -->
    <sect2 id="gramps-add-pers">
      <title>To Add a Person</title>
      <para> 
        To add a person to the database, switch to the People View
	(<xref linkend="side-nofilt-fig"/>) and then 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). To edit information about a person already
	present in the database, select an entry you would like to
	view/modify, and then click the <guibutton>Edit</guibutton>
	icon on the toolbar.
      </para>
      <para>
         You can also use <guilabel>Add...</guilabel> and
         <guilabel>Edit...</guilabel> menu items available under the
         <guimenu>Edit</guimenu>. Or you can right-click on the
         person and select <guilabel>Add...</guilabel> or
         <guilabel>Edit...</guilabel> from the invoked context menu.
      </para>
    </sect2>
<!-- ================ Usage Sub-subsection ================ -->
    <sect2 id="gramps-spec-rel">
      <title>To Specify a Relationship</title>
      <para>

        To specify a relationship, first switch to the Family View
	(<xref linkend="family-fig"/>). Then click one of the two top
	buttons on the right of the spouse box. The topmost button
	adds a new person to the database and to the relationship,
	while the second top button adds a person that is already in a
	database to the relationship.
      </para>
      <para> 
        If using the second button, select the spouse/partner from the
        list and specify the relationship using the menu at the
        bottom. If necessary, you can add a person to the list by
        clicking the <guibutton>+</guibutton> button. &app; will
        filter the displayed list of people based on the apparent
        relationship possibility. Specifically, shown are the people who
        could possibly be in relationship with the active person, as
        judged by the available birth and death information. To
        override this and display all people from the database, check
        the <guilabel>Show all</guilabel> box.
      </para>
      <para>
	To edit information about a relationship already present in
        the database, move the mouse over the
        <guilabel>Spouse</guilabel> box and double-click.  If the
        relationship lists has more than one person, you can specify
        the preferred spouse/partner by selecting an appropriate item
        from the context menu available upon right-clicking into the
        spouse box. Also, most of the above function are available
        from the items of this context menu.
      </para>
    </sect2>
<!-- ================ Usage Sub-subsection ================ -->
    <sect2 id="gramps-spec-par">
      <title>To Specify Parents</title>
      <para>
        To specify parents of an active person, first switch to the
	Family View (<xref linkend="family-fig"/>). Then click the
	<guibutton>+</guibutton> button on the right of the active
	person's parents list box. Select the parents from two lists
	and specify the parents' relationships to the active person
	using menus at the bottom.  You can also specify parents'
	relationship to each other.  If necessary, you can add a
	person to the list by clicking the
	<guibutton>Add...</guibutton> button.
      </para>
      <para> 
        The top and bottom lists contain males and females,
	respectively. By default, &app; will limit both lists to
	people who could possibly be the parents (judged by the date
	of birth) of the active person. To override this, check the
	<guilabel>Show all</guilabel> box for each list.
      </para>
      <para>
        To specify parents of the active person's spouse, switch to
	the Family View and then click the <guibutton>+</guibutton>
	button on the right of the spouse's parents list box. To edit
	information about parents already present in the database,
	move the mouse over the corresponding parents' box and
	double-click. All these functions can also be performed by
	right-clicking on the parents' box and selecting an
	appropriate item from the context menu.
      </para>
    </sect2>
<!-- ================ Usage Sub-subsection ================ -->
    <sect2 id="gramps-spec-ch">
      <title>To Specify Children</title>
      <para>
        To specify children of an active person, switch to the Family
	View (<xref linkend="family-fig"/>) and then click either the
	second or the third button from the top on the right of the
	children list box. The second button adds a child to the
	database and to the family, while the third button adds a
	child already present in the database to the family.
      </para>
      <para> 
        If using the third button, select a child from the list and
	specify the child's relationship with father and mother using
	menus at the bottom. If necessary, you can add a person to the
	list by clicking the <guibutton>Add...</guibutton> button. By
	default, &app; will limit the lists to people who could
	possibly be the child (judged by the date of birth) of the
	active person. To override this, check the <guilabel>Show
	all</guilabel> box.
      </para>
      <para>
        The relationship of the child to the parents can be modified
        by selecting an appropriate item from the context menu
        available upon right-clicking into the children box. Also,
        most of the above function are available from the items of
        this context menu.
      </para>
    </sect2>
<!-- ================ Usage Sub-subsection ================ -->
    <sect2 id="gramps-add-img">
      <title>To Add Images</title>
      <para>
        You can add images (as well as other media objects) to
	individual people, events, sources, places, as well as images
	generally related to the database (e.g. group family photos).
      </para>
      <para> 
        To add images related 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
	to invoke the <guilabel>Edit Person</guilabel> Dialog
        (<xref linkend="edit-pers-fig"/>). Then, select the
	<guilabel>Gallery</guilabel> tab, and click the
	<guibutton>+</guibutton> button to invoke the <guilabel>Select
	a media object</guilabel> dialog. Type the filename or select
	a file with the image, then provide a title for that
	image. Keep adding images until you are done.
      </para>
      <para> 
        To add images related to a relationship (e.g. marriage),
	switch to the Family View (<xref linkend="family-fig"/>) and
	then double-click on the Spouse box invoke 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 Sources View (<xref linkend="sources-fig"/>) or Places
	View (<xref linkend="places-fig"/>), respectively. Then select
	the appropriate source or place and then either double-click
	on it or click the <guibutton>Edit</guibutton> icon on the
	toolbar to invoke the <guilabel>Source Editor</guilabel> (or
	<guilabel>Place Editor</guilabel>) dialog. Select the
	<guilabel>Gallery</guilabel> tab and click the
	<guibutton>+</guibutton> button to add an image.
      </para>
      <para> 
        Finally, to add images that are generally related to the
	database but not limited to any person, relationship, source,
	or place in particular, 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>
      <para> 
        In any gallery, you can also use the
	<guibutton>Edit</guibutton> and <guibutton>-</guibutton>
	buttons to edit image information and to remove the image
	reference from that gallery. Note that in all galleries
	removing the reference to the image 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>
    </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 Sources View (<xref linkend="sources-fig"/>) or
	Places 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>Editing Data: Complete Description</title>
    <para> 
      This section provides a complete description of all editing
      options for all pieces of data in the &app; database. It refers
      mainly to the menu items and buttons as the main way of
      interacting with &app;.  In addition to this, &app; provides an
      extensive set of keybindings.  The detailed reference to the
      keybindings is found in the <xref linkend="append-keybind"/>.
    </para>
    <note id="edit-button-note">
      <title>Add, Remove, and Edit buttons</title>
      <para>
         In order to save precious screen space, most of the
         <guibutton>Add</guibutton>, <guibutton>Remove</guibutton>,
         and <guibutton>Edit</guibutton> buttons no longer are labeled
         with text. Instead, the first two use
         <guibutton>+</guibutton> and <guibutton>-</guibutton> icons,
         and the third uses the icon depicting a pen on top of a paper
         sheet.
      </para>
      <para>
        Reference the latter as the
        <guibutton>Edit</guibutton> button, while using
        <guibutton>+</guibutton> and <guibutton>-</guibutton> to
        denote the former two buttons.
      </para>
    </note>

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

    <sect2 id="adv-pers">
      <title>Personal Information</title>
      <para> 
          Editing of personal data can be performed in the following
	  ways:
        </para>
      <variablelist>
        <varlistentry>
          <term>From the People View:</term>
          <listitem>
            <para> 
              Double-click the name of the person whose data you would
	      like to edit, or select the name by single click and
	      then click the <guibutton>Edit</guibutton> icon on the
	      toolbar. You may also select the name and then press
	      <keycap>Enter</keycap>. Finally, you may select
	      <guimenuitem>Edit...</guimenuitem> from the
	      <guisubmenu>Edit</guisubmenu> menu of &app; or choose
	      <guimenuitem>Edit</guimenuitem> from the context menu
	      that appears upon right-click on the name.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>From the Family View:</term>
          <listitem>
            <para>
  	      To edit active person's data, move the mouse into the
	      <guilabel>Active person</guilabel> box, then
	      double-click, or use any of the menu items described
	      above.  To edit Spouse's data, Shift-click desired
	      spouse entry. Also, from <guilabel>Spouse</guilabel> and
	      <guilabel>Children</guilabel> boxes you may select the
	      desired person, right-click, and then select the menu
	      item from the context menu to edit the selected person's
	      data.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>From the Pedigree View:</term>
          <listitem>
            <para>
 	      Move the mouse into the box bearing the name of the
	      person whose data you would like to edit, then
	      double-click.
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para> 
          With either method, the following <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 fileref="figures/edit-person.png" format="PNG" 
                         width="500" depth="413" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Edit Person dialog. </phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

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

      <para> 
        The top of the window shows the name of the person whose
	data is being edited. The main part of the window displays
	ten 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. If any of the data in any tab were modified, the
	alert window will appear with the choices of 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 (write on disk).  This version of
          &app; does not have a separate saving function, all
          changes are immediate.
        </para>
      </note>
      <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
	 personal data:
      </para>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>General</guilabel>
          </term>
          <listitem>
            <para> 
   	      The <guilabel>General</guilabel> tab allows editing of
 	      general information about the person. This includes
 	      the text entry fields of <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.)  and <guilabel>Date</guilabel> and
 	      <guilabel>Place</guilabel> of birth and death. Some of
 	      these (<guilabel>Family name</guilabel>,
 	      <guilabel>Type</guilabel>, and both
 	      <guilabel>Place</guilabel> fields), also provide
 	      autocompletion feature: as you type in these fields,
 	      the menu is displayed below the field with the
 	      available entries from the database that are
 	      compatible with your partial input. This allows for a
 	      quick selection of an available entry by selecting it
 	      from the menu, either using the mouse or arrows and
 	      <keycap>Enter</keycap> key.
            </para>
            <para>
              The <guilabel>Edit</guilabel> button located by the
              <guilabel>Family name</guilabel> entry allows editing
              the preferred name in complete detail, by invoking
              the <guilabel>Name Editor</guilabel> dialog (see
              <xref linkend="adv-an"/>).
            </para>
            <para>
	      The <guilabel>Gender</guilabel> radio buttons offer the
	      choice of person's gender between
	      <guilabel>male</guilabel>, <guilabel>female</guilabel>,
	      and <guilabel>unknown</guilabel>.  Clicking the colored
	      circle buttons (green, yellow, or red, also called LED
	      buttons) located next to the birth and death Date fields
	      will bring up the <guilabel>Date Selection</guilabel>
	      dialog allowing detailed modification of the date, see
	      <xref linkend="adv-dates"/>.  Clicking either
	      <guibutton>Edit</guibutton> button located next to the
	      birth and death LED buttons will bring up a dialog
	      allowing you to edit the corresponding event (birth or
	      death) details, see <xref linkend="adv-ev"/>.  The field
	      <guilabel>ID</guilabel> displays an internal &app; ID
	      number which identifies the user in the database. The
	      <guilabel>Image</guilabel> area shows the first image
	      available in the <guilabel>Gallery</guilabel> of this
	      person (if any exist).
	    </para>
            <para>
              Finally, the <guilabel>Information is
	      complete</guilabel> and <guilabel>Information is
	      private</guilabel> check buttons provides the way to
	      mark whether this person's record is complete or not and
	      whether it is a private record.
             </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Names</guilabel>
          </term>
          <listitem>

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

            <figure id="edit-pers-names-fig">
              <title>Edit Person dialog - Names</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-names.png" 
		               format="PNG" width="500" depth="252" scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Names Tab of Edit Person dialog.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>

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

            <para> 
              The <guilabel>Names</guilabel> tab displays information
 	      concerning alternate names of the person and the
 	      controls allowing their modification. The bottom part
 	      displays the list of all alternate names of 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 record
 	      from the database.  Note that the
 	      <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
 	      buttons become available only when an alternate name is
 	      selected from the list.
  	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Events</guilabel>
          </term>
          <listitem>
<!-- ==== Figure: Edit Person dialog - Events ==== -->
            <figure id="edit-pers-events-fig">
              <title>Edit Person dialog - Events</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-events.png" 
		               format="PNG" width="500" depth="278" scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Events Tab of Edit Person dialog.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
<!-- ==== End of Figure ==== -->
            <para>
              The <guilabel>Events</guilabel> tab displays information
	      about the events relevant to the person and controls
	      allowing its modification. 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> allow you to
	      correspondingly 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>
            <guilabel>Attributes</guilabel>
          </term>
          <listitem>
<!-- ==== Figure: Edit Person dialog - Attributes ==== -->
            <figure id="edit-pers-attributes-fig">
              <title>Edit Person dialog - Attributes</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-attributes.png" 
		               format="PNG" width="500" depth="231" 
                               scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Attributes Tab of Edit Person dialog.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
<!-- ==== End of Figure ==== -->
            <para>
              The <guilabel>Attributes</guilabel> tab displays
	      information about the attributes of the person and
	      controls allowing their modification. These could be any
	      personal attributes of a person whose description
	      naturally fits into Parameter-Value pairs (e.g. enormous
	      generosity can be stored as the parameter "Generosity"
	      with the value "Enormous", etc.). The bottom part
	      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> allow you to correspondingly
	      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>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Addresses</guilabel>
          </term>
          <listitem>
<!-- ==== Figure: Edit Person dialog - Addresses ==== -->
            <figure id="edit-pers-addresses-fig">
              <title>Edit Person dialog - Addresses</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-addresses.png" 
		               format="PNG" width="500" depth="272" 
			       scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Addresses Tab of Edit Person dialog.</phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
<!-- ==== End of Figure ==== -->
            <para>
              The <guilabel>Addresses</guilabel> tab displays
	      information about the addresses of the person and the
	      controls allowing their modification. The bottom part
	      displays the list of 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 the
              addresses of people who are currently alive.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Notes</guilabel>
          </term>
          <listitem>
<!-- ==== Figure: Edit Person dialog - Notes ==== -->
            <figure id="edit-pers-notes-fig">
              <title>Edit Person dialog - Notes</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-notes.png" 
		               format="PNG" width="500" depth="228"
			       scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Notes Tab of Edit Person dialog. </phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
<!-- ==== End of Figure ==== -->

            <para>
              The <guilabel>Notes</guilabel> tab displays information
     	      about the notes concerning the person. These could be
     	      any notes 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 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>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Sources</guilabel>
          </term>
          <listitem>

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

            <figure id="edit-pers-sources-fig">
              <title>Edit Person dialog - Sources</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-sources.png" 
		               format="PNG" width="500" depth="147"
			       scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Sources Tab of Edit Person dialog.</phrase>
                    </textobject>
                </mediaobject>
              </screenshot>

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

            <para>
              The <guilabel>Sources</guilabel> tab displays
	      information about the sources related to the person and
	      controls allowing its modification.  These could be any
	      general sources which refer to the person but do not
	      describe specifically any event.  For example, Aunt
	      Martha's memoirs may mention her great grandson Paul, so
	      the researcher may assume that this person (Paul)
	      existed and cite the memoirs as the source for this
	      assumption.
	    </para>
            <tip>
              <para>
                Sources documenting specific events are better
		recorded in relation to those events, under the
		<guilabel>Events</guilabel> tab. The person's
		<guilabel>Sources</guilabel> tab is best used for
		general source references.
              </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>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Gallery</guilabel>
          </term>
          <listitem>

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

            <figure id="edit-pers-gallery-fig">
              <title>Edit Person dialog - Gallery</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-gallery.png" 
		               format="PNG" width="500" depth="182"
			       scale="75" />
                  </imageobject>
                  <textobject>
                    <phrase>Shows Gallery Tab of Edit Person dialog. </phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>

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

            <para>
              The <guilabel>Gallery</guilabel> tab displays
	      information about media objects associated with the
	      person and controls allowing subsequent
	      modification. The central part shows the list of all
	      such media objects.  For media object which are valid
	      image files, previews of images are displayed. 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> allow you to correspondingly
              add a new image, add a reference to an image already
              stored in the database, modify, and remove a media
              object reference to this person. Note that the
              <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
              buttons become available only when a media object is
              selected from the list.  
            </para>
            <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>
            <guilabel>Internet</guilabel>
          </term>
          <listitem>

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

            <figure id="edit-pers-internet-fig">
              <title>Edit Person dialog - Internet</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-internet.png" 
		               format="PNG" width="500" depth="218"
			       scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows Internet Tab of Edit Person dialog. </phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>

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

            <para>
              The <guilabel>Internet</guilabel> tab displays
      	      information about Internet addresses relevant to the
      	      person and the controls allowing data modification. The
      	      bottom part displays the list of all such Internet
      	      addresses stored in the database. 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> allow you to correspondingly
      	      add, modify, and remove an Internet address record from
      	      the database. The button <guibutton>Go</guibutton>
      	      allows opening a web-page with the corresponding address
      	      with your default browser. 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>
            <guilabel>LDS</guilabel>
          </term>
          <listitem>

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

            <figure id="edit-pers-lds-fig">
              <title>Edit Person dialog - LDS</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/edit-person-lds.png" 
		               format="PNG" width="500" depth="403"
			       scale="75"/>
                  </imageobject>
                  <textobject>
                    <phrase>Shows LDS Tab of Edit Person dialog. </phrase>
                  </textobject>
                </mediaobject>
              </screenshot>
            </figure>
<!-- ==== End of Figure ==== -->
            <para>
              The <guilabel>LDS</guilabel> tab displays information
	      about LDS ordinances of the person and controls allowing
	      modification. These are <guilabel>LDS
	      baptism</guilabel>, <guilabel>Endowment</guilabel>, and
	      <guilabel>Sealed to parents</guilabel> 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 <guilabel>Parents</guilabel> is
	      available for the <guilabel>Sealed to parents</guilabel>
	      ordinance.  Each ordinance can further be described by
	      its status through the selections available in the
	      <guilabel>Status</guilabel> pop-up menu and can also be
	      referenced by sources and notes via corresponding
	      <guibutton>Sources...</guibutton> and
	      <guibutton>Note</guibutton> buttons.
  	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

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

    <sect2 id="adv-dates">
      <title>Dates</title>
      <para> 
        This section describes the details of entering and modifying
	dates.  Dates are important in genealogical research, so &app;
	goes a long way to preserve and use any date information
	available.
      </para>
      <sect3 id="adv-dates-led">
        <title>Date types and validity indicators</title>
        <para>
          &app; 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> 
              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 is uniquely defined up to a day.
            </para>
          </listitem>
          <listitem>
            <para> 
              Yellow circle means that the date is valid but is not a
	      regular date. This could be the date of an alternative
	      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").  n that case the date will be
	      stored as a text string. Therefore, no comparison with
	      other dates will be available. It is best to avoid such
	      date entries. Same information can be entered as a note
	      for the event of interest instead of a date. In the
	      example considered, a better things to do is to enter
	      December 1961 as a date and "Christmas week of 61" as a
	      note.
            </para>
          </listitem>
        </itemizedlist>
      </sect3>
      <sect3 id="adv-dates-parsing">
        <title>Acceptable date entries</title>
        <para>
          &app; recognizes many formats of exact dates. The numeric
          formats are determined by the default environment &app; is
          running under. Most European countries use DD.MM.YYYY, the
          US commonly uses MM/DD/YYYY, and so on.
        </para>
        <para>
          Besides exact dates, &app; 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 below is only valid for English. If you are using
            localized version of &app;, your version may or may not
            provide a localized date parser.  At the time of this
            writing, localized parsers exist for French, Russian, and
            Spanish languages.
          </para>
          <para>
            If the localized parser is available for your version,
            chances are that other rules are in effect. If there's 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 in the letter: May 24, 1961 or January 1,
	      2004.
            </para>
          </listitem>
          <listitem>
            <para> 
              Dates that are not regular should start with the
              quality: estimated or calculated, if applicable. Regular
              quality does not need to be specified, as it is the
              default. Example: est. 1961, or calc 2005.
            </para>
          </listitem>
          <listitem>
            <para> 
              Next should appear the type: before, after, or about.
	      Ranges are denoted with "between DATE and DATE" and
	      spans use "from DATE to DATE" patterns, where DATE
	      stands for 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: May 1961, 2004.
            </para>
          </listitem>
          <listitem>
            <para>
              Alternate calendars are calendars other than Gregorian
              calendar. Currently, &app; 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-gui">
        <title>Graphical User Interface for entering dates</title>
        <para>
           While the above rules provide a quick and easy way for
          entering most common dates, sometimes there is a need to
          either build a complex date or simply check the date using
          graphical user interface. The <guilabel>Date
          selection</guilabel> dialog can be invoked by clicking the
          color circle button (also known as the LED 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 fileref="figures/date-selection.png" format="PNG"
		             width="400" depth="270" scale="75"/>
                </imageobject>
                <textobject>
                  <phrase>Shows Date selection dialog. </phrase>
                </textobject>
              </mediaobject>
            </screenshot>
          </figure>
        </para>

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

        <para>
          The <guilabel>Calendar</guilabel> menu allows the choice of
          any supported calendar. The <guilabel>Quality</guilabel>
          menu provides choices of Regular, Estimated, or Calculated
          quality. The <guilabel>Type</guilabel> menu allows to adjust
          the exact date type: Regular, Before, After, About, Range,
          Span, and Text only.  A set of controls labeled
          <guilabel>Date</guilabel> allows setting the day, the month,
          and the year for a date. The second set of controls,
          <guilabel>Second date</guilabel>, is disabled for all dates
          except for those of Range and Span type. For ranges and
          spans, the <guilabel>Second date</guilabel> controls allow
          setting the details of the second date. Finally, the
          <guilabel>Text comment</guilabel> text entry field allows
          storing an arbitrary text string along with the date.
        </para>
        <note>
          <para>
            If you enter the date outside this dialog, i.e. as a text
	    in any date entry field, that text will be copied and
	    stored as the text comment string during parsing of
	    entered text.
	  </para>
          <para>
            Therefore, the comment only lives until the next parsing.
	    If you have some important text corresponding to the date,
	    you are probably better off by saving that text as a Note
	    for the corresponding event.
	  </para>
        </note>
      </sect3>
    </sect2>

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

    <sect2 id="adv-rel">
      <title>Relationship Data</title>
      <para> 
        Editing of relationship data is performed in the following
	<guilabel>Marriage/Relationship Editor</guilabel> dialog which
	appears after double-clicking on the spouse box in the Family
	View. Alternatively, you may invoke this dialog by
	right-clicking into the spouse box and selecting
	<guilabel>Edit relationship</guilabel> item from the context
	menu.
      </para>
<!-- ==== Figure: Edit Relationship dialog ==== -->
      <figure id="edit-rel-fig">
        <title>Marriage/Relationship Editor dialog</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/edit-rel.png" format="PNG"
	                 width="500" depth="258" scale="75"/>
            </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 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. If any of the data in any tab were modified, the
	alert window will appear with the choices of 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 (write on disk).  This version of
          &app; does not have a separate saving function, all changes
          are immediate.
        </para>
      </note>
      <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
	relationship 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 relationship: the
	      relationship type.  The available types (such as
	      married, partners, etc.) can be chosen from the
	      drop-down <guilabel>Relationship type</guilabel> menu.
	      The <guilabel>ID</guilabel> field displays &app; ID
	      number which labels this relationship in the
	      database. The <guilabel>Last changed</guilabel> label
	      shows the last modification time for this relationship.
	      Finally, the <guilabel>Information is
	      complete</guilabel> check button provides the way to
	      mark whether this relationship's record is complete or
	      not.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Events</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Events</guilabel> tab displays information
	      about the events relevant to the relationship and the
	      controls allowing modification. 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> allow you to
	      correspondingly 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>
            <guilabel>Attributes</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Attributes</guilabel> tab displays
	      information about the attributes of the relationship and
	      the controls allowing modification. 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> allow you to correspondingly
	      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>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Notes</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Notes</guilabel> tab displays information
	      about the notes concerning the relationship. These could
	      be any notes 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 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>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Sources</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Sources</guilabel> tab displays
	      information about he sources related to the relationship
	      and controls allowing its modification. These could be
	      any general sources which refer to the relationship but
	      do not describe specifically any event.  For example,
	      Aunt Martha's memoirs may mention that her great
	      grandson Paul was married, so the researcher may assume
	      that this relationship (between Paul and his wife)
	      existed and cite the memoirs as the source for this
	      assumption.
  	    </para>
            <note>
              <para> 
                Sources documenting specific events such as marriages
		or divorces are better filed in relation to those
		events, under the <guilabel>Events</guilabel> tab.
               </para>
            </note>
            <para>
              The central part displays the list of all source
	      references stored in the database for this
	      relationship. The buttons <guibutton>+</guibutton>,
	      <guibutton>Edit</guibutton>, and
	      <guibutton>-</guibutton> allow you to correspondingly
	      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>
            <guilabel>Gallery</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Gallery</guilabel> tab displays
	      information about media objects associated with the
	      relationship and the controls allowing modification of
	      such. The central part shows the list of all such media
	      objects.  For media object which are valid image files
	      previews of images are displayed. For other objects such
	      as audio files, movie files, etc., a generic &app; icon
	      is displayed instead.  The buttons
	      <guibutton>+</guibutton>, <guibutton>Select</guibutton>,
	      <guibutton>Edit</guibutton>, and
	      <guibutton>-</guibutton> allow you to correspondingly
	      add a new image, add a reference to an image already
	      stored in the database, modify, and remove a media
	      object reference to this relationship.  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>
            <guilabel>LDS</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>LDS</guilabel> tab displays information
	      about the LDS <guilabel>Sealed to spouse</guilabel>
	      ordinance of the person and the controls allowing
	      modification. The data can include date, LDS temple, and
	      Place where it happened. The ordinance can further be
	      described by its status through the selections available
	      in the <guilabel>Status</guilabel> pop-up menu and can
	      also be referenced by sources and notes via
	      corresponding <guibutton>Sources...</guibutton> and
	      <guibutton>Note</guibutton> buttons.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
<!-- ================ Usage Sub-subsection ================ -->
    <sect2 id="adv-src">
      <title>Source Data</title>
      <para> 
        To edit source data, switch to the Sources View and select the
	desired entry in the list of sources. Double-click on 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 fileref="figures/edit-src.png" format="PNG"
	                 width="450" depth="256" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Source Editor dialog. </phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
<!-- ==== End of Figure ==== -->

      <para> 
        The top of the window shows the <guilabel>Source
	Editor</guilabel> title of the dialog. The main part of the
	window displays four 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>
      <note>
        <para>
          Clicking <guibutton>OK</guibutton> will immediately save
	  changes to the database (write on disk).  This version of
	  &app; does not have a separate saving function, all
	  changes are immediate.
        </para>
      </note>
      <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 
	source 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 source: its
	      title, author, abbreviated title, and publication
	      information. This information can be typed in the
	      appropriate text entry fields.
  	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Note</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Note</guilabel> tab displays any notes
	      concerning the source. 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>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Data</guilabel>
          </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 record
	      types. The difference from these Key/Value pairs and the
	      attributes is that the attributes may have source
	      references and notes, while the Key/Value data may
	      not.
	    </para>
            <para> 
              The central part shows the list of all Key/Value pairs,
	      if any.  The buttons <guibutton>+</guibutton> and
	      <guibutton>-</guibutton> allow you to correspondingly
	      add and remove pairs. To modify the text of Key or
	      Value, first select the desired entry (may be an empty
	      entry when new pair has just been added). Then click
	      into either Key or Value cell inside that entry and edit
	      the text in place.  When you are done, click outside the
	      cell to exit editing mode.
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Gallery</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Gallery</guilabel> tab displays
      	      information about media objects associated with the
      	      given source and controls allowing its modification. The
      	      central part shows the list of all such media
      	      objects. For media object which are valid image files
      	      previews of images are displayed. For other objects such
      	      as audio files, movie files, etc., a generic &app; icon
      	      is displayed instead.  The buttons
      	      <guibutton>+</guibutton>, <guibutton>Select</guibutton>,
      	      <guibutton>Edit</guibutton>, and
      	      <guibutton>-</guibutton> allow you to correspondingly
      	      add a new image, add a reference to an image already
      	      stored in the database, modify, and remove a media
      	      object reference to this 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>
            <guilabel>References</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>References</guilabel> tab displays
	      information about database records that refer to this
	      source. If the source is not referenced from any
	      database record, the tab shows an empty list.  If the
	      source is referenced from many records, the tab will
	      list all of them. The list can be ordered by any of its
	      column headers: <guilabel>Type</guilabel>,
	      <guilabel>ID</guilabel>, or
	      <guilabel>Name</guilabel>. Double-clicking on the list
	      entry opens up an editor for a corresponding record
	      allowing to view or modify the record.
	    </para>
            <note>
              <para>
                Only primary objects can be shown in the
		<guilabel>References</guilabel> tab: Person, Family,
		Event, Place, or Media object. The secondary objects
		such as Names and Attributes, although may refer the
		source, will only show up through their primary
		objects they belong to.
	      </para>
            </note>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

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

    <sect2 id="adv-plc">
      <title>Place Data</title>
      <para> 
        To edit place data, switch to the Places View and select the
	desired entry in the list of places. Double-click on that
	entry or click the <guibutton>Edit</guibutton> icon on the
	toolbar to invoke 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 fileref="figures/edit-plc.png" format="PNG"
	                 width="450" depth="411" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Place Editor dialog. </phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

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

      <para> 
        The top of the window shows the <guilabel>Place
	Editor</guilabel> title of the dialog. The main part of the
	window displays seven 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>
      <note>
        <para>
          Clicking <guibutton>OK</guibutton> will immediately save
	  changes to the database (write on disk).  This version of
	  &app; does not have a separate saving function, all
	  changes are immediate.
        </para>
      </note>
      <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 
	place 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 place: the title
	      which labels it in the database, city, church parish,
	      county, state, country, longitude, and latitude.  This
	      information can be typed in the appropriate text entry
	      fields.
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Other names</guilabel>
          </term>
          <listitem>
            <para> 
	      The <guilabel>Other names</guilabel> tab displays
	      information concerning other names by which the place
	      might be known and the controls allowing their
	      modification. The bottom part displays the list of all
	      other names of the place 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 you to
	      correspondingly add, modify, and remove a name record
	      from the database. 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>
            <guilabel>Note</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Note</guilabel> tab displays any notes
	      concerning the place. 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>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Sources</guilabel>
          </term>
          <listitem>
            <para> 
	      The <guilabel>Sources</guilabel> tab displays
	      information about sources relevant to this place and
	      controls allowing its modification.  The central part
	      displays the list of all such source 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
	      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>
            <guilabel>Gallery</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Gallery</guilabel> tab displays
	      information about media objects associated with the
	      given place and the controls allowing its
	      modification. The central part shows the list of all
	      such media objects. For media objects which are valid
	      image files previews of images are displayed. For other
	      objects such as audio files, movie files, etc., a
	      generic &app; icon is displayed instead.  The buttons
	      <guibutton>+</guibutton>, <guibutton>Select</guibutton>,
	      <guibutton>Edit.</guibutton>, and
	      <guibutton>-</guibutton> allow you to correspondingly
	      add a new image, add a reference to an image already
	      stored in the database, modify, and remove a media
	      object reference to this 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>
            <guilabel>Internet</guilabel>
          </term>
          <listitem>
            <para>
	      The <guilabel>Internet</guilabel> tab displays
	      information about Internet addresses relevant to the
	      place and controls allowing its modification. The bottom
	      part displays the list of all such Internet addresses
	      stored in the database. 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> allow you to correspondingly
	      add, modify, and remove an Internet address record from
	      the database. The button <guibutton>Go</guibutton>
	      allows you to open a web-page with the corresponding
	      address with your default browser. 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>
            <guilabel>References</guilabel>
          </term>
          <listitem>
            <para>
               The <guilabel>References</guilabel> tab displays
	       information about database records (events or LDS
	       ordinances) that refer to this place. If the place is
	       not referenced from any database record, the tab shows
	       an empty list.  If the place is referenced from many
	       records, the tab will list all of them. This
	       information cannot be modified from the <guilabel>Place
	       Editor</guilabel> dialog. Instead, the corresponding
	       database record (e.g. 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>Media Data</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 fileref="figures/edit-media.png" format="PNG"
	                 width="450" depth="286" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Media Properties Editor dialog. </phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

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

      <para> 
        The top of the window shows the dialog title. Below the title
	is the preview of an object and the summary of its properties
	(ID, path, and object type). The central part of the window
	displays four 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>
      <note>
        <para>
           Clicking <guibutton>OK</guibutton> will immediately save
	   changes to the database (write on disk).  This version of
	   &app; does not have a separate saving function, all changes
	   are immediate.
        </para>
      </note>
      <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 
	media object data:
      </para>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>General</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>General</guilabel> tab allows editing the
	      title which labels this object in the database. The
	      title can be typed in the appropriate text entry
	      field. The <guilabel>Date</guilabel> field allows
	      entering the date by typing, while the LED button beside
	      it will invoke a <guilabel>Date selection</guilabel>
	      dialog for setting the date graphically.
            </para>
            <note>
              <para>
                 &app; no longer has a concept of local media objects.
		 Every media object is referred to by its path. The
		 users are responsible for keeping track of the object
		 files. &app; will only reference and display the
		 contents, not manage the files themselves.
	       </para>
            </note>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Attributes</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Attributes</guilabel> tab displays
	      information about the attributes of the media object and
	      controls allowing its modification. 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> allow you to correspondingly
	      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>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Notes</guilabel>
          </term>
          <listitem>
            <para>
	      The <guilabel>Notes</guilabel> tab displays information
	      about the notes concerning the media object. These could
	      be any notes 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 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>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>References</guilabel>
          </term>
          <listitem>
            <para>
	      The <guilabel>References</guilabel> tab displays
	      information about database records that refer to this
	      media object. If the object is not referenced from any
	      database record, the tab shows an empty list.  If the
	      object is referenced from many records, the tab will
	      list all of them. The list can be ordered by any of its
	      column headers: <guilabel>Type</guilabel>,
	      <guilabel>ID</guilabel>, or
	      <guilabel>Name</guilabel>. Double-clicking on the list
	      entry opens up an editor for a corresponding record
	      allowing to view or modify the 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 they belong to.
	      </para>
            </note>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

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

    <sect2 id="adv-ev">
      <title>Events</title>
      <para> 
        Events are edited through the following <guilabel>Event
	Editor</guilabel> dialog: 
      </para>
 
<!-- ==== Figure: Event Editor dialog ==== -->

      <figure id="edit-ev-fig">
        <title>Event Editor dialog</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/edit-ev.png" format="PNG"
	                 width="450" depth="316" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Event 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 persons whose event is being edited. The central
	part of the window displays four 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 event 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 event: its type,
	      date, place, cause, and description. The type can be
	      selected from available types listed in the
	      <guilabel>Event type </guilabel> drop-down menu. The
	      rest of the information can be typed in the appropriate
	      text entry fields.  Check the <guilabel>Private
	      record</guilabel> box to mark this event record as
	      private. This will give you a chance to omit this event
	      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 event 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
	      event. 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 event. 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>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Witnesses</guilabel>
          </term>
          <listitem>
            <para>
              The <guilabel>Witnesses</guilabel> tab displays
	      information about witnesses relevant to this event and
	      controls allowing its modification.  The central part
	      displays the list of all such witnesses stored in the
	      database. The buttons <guibutton>+</guibutton>,
	      <guibutton>Edit</guibutton>, and
	      <guibutton>-</guibutton> allow you to correspondingly
	      add, modify, and remove a witness reference to this
	      event, see <xref linkend="adv-wit"/>. Note that the
	      <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
	      buttons become available only when a witness reference
	      is selected from the list.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

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

    <sect2 id="adv-si">
      <title>Source Information</title>
      <para> 
        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 fileref="figures/edit-si.png" format="PNG"
	                 width="450" depth="489" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Source Information dialog. </phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
<!-- ==== End of Figure ==== -->

      <para> 

        The top of the window shows the dialog title. The central part
	displays the source information. 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 and close the dialog
	window. Clicking the <guibutton>Cancel</guibutton> button at
	any time will close the window without applying any changes.

      </para>
      <para> 

        The source can be selected from available sources listed in
	the <guilabel>Title</guilabel> drop-down menu. If the source
	you are referencing is not present in the database yet, you
	can enter it into the database. To do this, click the
	<guibutton>New...</guibutton> button and enter source
	information into the invoked <guilabel>Source
	Editor</guilabel> dialog. You can also set the details
	specific for this particular reference: confidence,
	volume/file/page, date, text, and comments. Choose the
	confidence level from the <guilabel>Confidence</guilabel>
	drop-down menu.  The rest of the details can be typed in the
	appropriate 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 fileref="figures/edit-an.png" format="PNG"
	                 width="400" depth="509" scale="75"/>
            </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 fileref="figures/edit-at.png" format="PNG"
	                 width="430" depth="248" scale="75"/>
            </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 fileref="figures/edit-ad.png" format="PNG"
	                 width="450" depth="376" scale="75"/>
            </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-wit">
      <title>Witnesses</title>
      <para> 
        Witnesses are edited through the following <guilabel>Witness
	Editor</guilabel> dialog:
      </para>

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

      <figure id="edit-wi-fig">
        <title>Witness Editor dialog</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/edit-wi.png" format="PNG"
	                 width="450" depth="259" scale="75"/>
            </imageobject>
            <textobject>
              <phrase>Shows Witness Editor dialog. </phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>

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

      <para> 

        The top of the window shows the dialog title. The central part
	of the window displays information about the witness. 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 and close the dialog window. Clicking the
	<guibutton>Cancel</guibutton> button at any time will close
	the window without applying any changes.

      </para>
      <para>

        The witness name can be entered in two ways, depending upon
	whether the witness is a person already stored in the database
	or not (unrelated person).

      </para>
      <tip>
        <para>

          If the person you would like to add as a witness is in fact
	  a member of the database, it is better to use the first
	  method below.

        </para>
      </tip>
      <variablelist>
        <varlistentry>
          <term>Person from the database</term>
          <listitem>
            <para> 

	      If the person's data are stored in a database, check
	      <guilabel>Person is in the database</guilabel> box. Then
	      click the <guibutton>Select</guibutton> button to invoke
	      <guilabel>Select Person</guilabel> dialog. Choose the
	      person from that dialog and click the
	      <guibutton>OK</guibutton> button. The
	      <guilabel>Person</guilabel> text field will display the
	      name of the person you selected.

	    </para>
            <note>
              <para>

	        Even though the person's name is displayed in the
		<guilabel>Person</guilabel> field, it is not available
		for direct editing.

              </para>
            </note>
          </listitem>
        </varlistentry>
      </variablelist>
      <variablelist>
        <varlistentry>
          <term>Unrelated person</term>
          <listitem>
            <para> 

	      If the person is not in the database, make sure that
	      <guilabel>Person is in the database</guilabel> box is
	      unchecked.  Then enter the name or any description of a
	      person into the <guilabel>Person</guilabel> text entry
	      field. This information is stored as entered, and this
	      is the only place it is stored.  In other words, there
	      is no reference to that person in the entire database
	      except for this witness reference. If the person is in
	      fact a member of the database, it is advised to use the
	      former method.

  	    </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para> 

        The <guilabel>Comment</guilabel> text area allows you to enter
	any comments concerning the witness. To add a comment or to
	modify existing comments simply edit the text in the text
	area.

      </para>
    </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 fileref="figures/comp-people.png" format="PNG"
		                 width="500" depth="469" scale="75"/>
                    </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 fileref="figures/merge-people.png" 
		                 format="PNG" width="382" depth="245"
				 scale="75"/>
                    </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 fileref="figures/merge-src.png" format="PNG"
		           width="500" depth="224" scale="75"/>
              </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 fileref="figures/merge-plc.png" format="PNG"
		           width="400" depth="185" scale="75"/>
              </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, &app; 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 &app; provides. All
	these ways eventually accomplish the same thing, but some are
	more convenient than others, depending what you are doing in
	&app; 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="family-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, &app; 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> 
 
        &app; 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 fileref="figures/edit-bm.png" format="PNG"
	                 width="412" depth="376" scale="75"/>
            </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 fileref="figures/find-people.png" format="PNG"
	                 width="500" depth="352" scale="75"/>
            </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. &app;
      is no exception in this regard, offering a choice of a variety
      of reports.  &app; can generate reports in a multitude of open
      formats, both text based and graphical. &app; can also produce
      screen based reports that are convenient for viewing a summary
      of your database.  Finally, &app; 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 &app; 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 &app; 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 fileref="figures/bookreport.png" format="PNG"
	                 width="510" depth="524" scale="75"/>
            </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 &app; 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 url="http://www.graphviz.org" type="http">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, &app; 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
	&app;:

      </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 &app;:

      </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 &app; 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 &app;:

      </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>
			&app; 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 url="http://family.gramps-project.org"
          type="http">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
          &app; 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 url="http://creativecommons.org/"  type="http">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. &app; tries to give you control over the information that is presented.
          </para>
          
          <para>&app; 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>,
          &app; 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. &app; 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> 

        &app; 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 &app; 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 &app;: 

      </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 &app;:

      </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 &app; IDs</term>
          <listitem>
            <para>
	      This tool reorders the &app; IDs according to the
	      defaults of &app;.
	    </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 &app;. If you're not
	interested in debugging or developing &app; 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 &app;:

      </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 &app;.

	</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 fileref="figures/cfe-df.png" format="PNG"
		           width="400" depth="410" scale="75"/>
              </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 fileref="figures/cfe-ar.png" format="PNG"
		           width="500" depth="297" scale="75"/>
              </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 &app;.

	</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 fileref="figures/scratch-pad.png" format="PNG"
		           width="500" depth="246" scale="75"/>
              </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 &app;
	    session. Closing the window will not lose the stored
	    records. However, exiting &app; 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
		url="http://www.archives.gov/research_room/genealogy/census/soundex.html"
		type="http">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>
