Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
57954c387c
gramps/help/C/gramps-manual.xml
Don Allingham 57954c387c * help/C/figures/*.png: updates 
svn: r6956
2006-06-23 20:19:16 +00:00

8571 lines
333 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!--
User Manual for Gramps - a GTK+/GNOME based genealogy program
Copyright (C) 2003-2005 Alexander Roitman
This document is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-->
<book id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
<bookinfo>
<title>GRAMPS Manual V3.0</title>
<copyright>
<year>2001</year>
<holder>Donald N. Allingham</holder>
</copyright>
<copyright>
<year>2003-2005</year>
<holder>Alex Roitman</holder>
</copyright>
<!-- translators: uncomment this:
<copyright>
<year>2002</year>
<holder>ME-THE-TRANSLATOR (Latin translation)</holder>
</copyright>
-->
<!--
An address can be added to the publisher information. If a role is
not specified, the publisher/author is the same for all versions of the
document.
-->
<publisher>
<publishername>GRAMPS Project</publishername>
</publisher>
<legalnotice id="legalnotice">
<para>This manual is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.</para>
<para>This manual is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.</para>
<para>You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</para>
</legalnotice>
<!--
This file contains link to license for the documentation (GNU GPL), and
other legal stuff such as "NO WARRANTY" statement.
-->
<authorgroup>
<author>
<firstname>Alex</firstname>
<surname>Roitman</surname>
<affiliation>
<orgname>GRAMPS Project</orgname>
<address><email>shura@gramps-project.org</email></address>
</affiliation>
</author>
<author>
<firstname>Donald N.</firstname>
<surname>Allingham</surname>
<affiliation>
<orgname>GRAMPS Project</orgname>
<address><email>don@gramps-project.org</email></address>
</affiliation>
</author>
<!-- This is appropriate place for other contributors: translators,
maintainers, etc. Commented out by default.
<othercredit role="translator">
<firstname>Latin</firstname>
<surname>Translator 1</surname>
<affiliation>
<orgname>Latin Translation Team</orgname>
<address> <email>translator@gnome.org</email> </address>
</affiliation>
<contrib>Latin translation</contrib>
</othercredit>
-->
</authorgroup>
<!-- According to GNU GPL, revision history is mandatory if you are -->
<!-- modifying/reusing someone else's document. If not, you can omit it. -->
<!-- Remember to remove the &manrevision; entity from the revision entries other
-->
<!-- than the current revision. -->
<!-- The revision numbering system for GNOME manuals is as follows: -->
<!-- * the revision number consists of two components -->
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
<!-- is written in that desktop time frame is V2.0, the second version of the manual is V2.1, etc. -->
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
<!-- to V3.0, and so on. -->
<revhistory>
<revision>
<revnumber>GRAMPS Manual V3.0</revnumber>
<date>July 2006</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS Manual V2.5</revnumber>
<date>February 2004</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS Manual V2.4</revnumber>
<date>December 2003</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS Manual V2.3</revnumber>
<date>September 2003</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS Manual V2.2</revnumber>
<date>July 2003</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="author">Donald A. Peterson
<email>dpeterson@sigmaxi.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS Manual V2.1</revnumber>
<date>May 2003</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS Manual V2.0</revnumber>
<date>April 2003</date>
<revdescription>
<para role="author">Alex Roitman
<email>shura@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>GRAMPS User Manual V1.1</revnumber>
<date>2001</date>
<revdescription>
<para role="author">Donald N. Allingham
<email>don@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
<revision>
<revnumber>gramps User Manual V1.0</revnumber>
<date>2001</date>
<revdescription>
<para role="author">Donald N. Allingham
<email>don@gramps-project.org</email></para>
<para role="publisher">GRAMPS Project</para>
</revdescription>
</revision>
</revhistory>
<releaseinfo>This manual describes version 2.2.0 of GRAMPS.</releaseinfo>
</bookinfo>
<preface id="gramps-preface">
<title>Preface</title>
<para>GRAMPS is a software package designed for genealogical research.
Although similar to other genealogical programs, GRAMPS offers some unique
and powerful features, which we'll discuss below.</para>
<para>GRAMPS is a Open Source Software package, which means you are free
to make copies and distribute it to anyone you like. It's developed and
maintained by a worldwide team of volunteers whose goal is to make GRAMPS
powerful, yet easy to use.</para>
<sect1 id="why-gramps">
<title>Why use GRAMPS?</title>
<para>Most genealogy programs allow you to enter information about your
ancestors and descendants. Typically, they can display family
relationships through charts, graphs, or reports. Some allow you to
include pictures or other media. Most let you include information about
people even if those people are not related to the primary family you
happen to be researching. And they may include features that let you
exchange data with other programs and print different types of
reports.</para>
<para>GRAMPS has all these capabilities and more. Notably, it allows you
to integrate bits and pieces of data as they arise from your research
and to put them in one place -- your computer. You can then use your
computer to manipulate, correlate, and analyze your data, rather than
messing with reams of paper.</para>
</sect1>
<sect1 id="typography">
<title>Typographical conventions</title>
<para>In this book, some words are marked with special typography:
<itemizedlist>
<listitem>
<simpara><application>Applications</application></simpara>
</listitem>
<listitem>
<simpara><command>Commands</command> you type at the command
line</simpara>
</listitem>
<listitem>
<simpara><filename>Filenames</filename></simpara>
</listitem>
<listitem>
<simpara><replaceable>Replaceable text</replaceable></simpara>
</listitem>
<listitem>
<simpara><guilabel>Labels</guilabel> for buttons and other
portions of the graphical interface</simpara>
</listitem>
<listitem>
<simpara>Menu selections look like this: <menuchoice>
<guimenu>Menu</guimenu>
<guisubmenu>Submenu</guisubmenu>
<guimenuitem>Menu Item</guimenuitem>
</menuchoice></simpara>
</listitem>
<listitem>
<simpara><guibutton>Buttons</guibutton> you can click</simpara>
</listitem>
<listitem>
<simpara><userinput>Anything you type in</userinput></simpara>
</listitem>
</itemizedlist></para>
<para>The manual also provides assorted bits of additional information
in tips and notes, as follows. <tip id="example-tip">
<title>Example Tip</title>
<para>Tips and bits of extra information will look like this.</para>
</tip> <note id="example-note">
<title>Example Note</title>
<para>Notes will look like this.</para>
</note></para>
<para>Finally, there are warnings, notifying you where you should be
careful: <warning id="example-warning">
<title>Example Warning</title>
<para>This is what a warning looks like. If there's a chance you'll
run into trouble, you will be warned beforehand.</para>
</warning></para>
</sect1>
</preface>
<chapter id="gramps-getting-started">
<title>Getting Started</title>
<para>In this chapter, we'll begin with the basics. We'll show you how to
start GRAMPS and how to get help when you need it.</para>
<sect1 id="gramps-start">
<title>To Start GRAMPS</title>
<para>You can start GRAMPS in the following ways:</para>
<variablelist>
<varlistentry>
<term>From the <guimenu>Applications</guimenu> menu</term>
<listitem>
<para>Select GRAMPS from the list of programs displayed in your
computer's Applications menu. (The location and appearance of this
menu vary slightly from one distribution of Linux to another. On
the default GNOME desktop, you'll find GRAMPS in the <menuchoice>
<guimenu>Applications</guimenu>
<guisubmenu>Other</guisubmenu>
</menuchoice> menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>From the command line</term>
<listitem>
<para>If you're adept with Linux and like to work from the command
line, you can start GRAMPS by calling up a terminal window, typing
<command>gramps</command>, and then pressing
<keycap>Enter</keycap>.</para>
<para>If you would like GRAMPS to open a specific database or to
import a specific file on startup, you can supply the filename as
a command line argument:</para>
<para><filename>gramps filename.grdb</filename></para>
<para>where <filename>filename.grdb</filename> is the name of the
file you want to open. The command line provides many more ways to
start GRAMPS and perform different tasks.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="run-1st-time">
<title>Running GRAMPS for the first time</title>
<para>The first time you run the program, GRAMPS will display the
"Getting Started" dialogs. Follow the directions that guide you through
<guilabel>Researcher information</guilabel> and <guilabel>the LDS
extensions</guilabel> sections. You should find them to be
self-explanatory.</para>
<note id="note-dialog">
<title>Dialog boxes</title>
<para>We'll make frequent reference in this manual to dialogs. A
dialog is simply a pop-up window into which you can enter
information.</para>
</note>
<para>We recommend you enter your personal information when GRAMPS
prompts you for it. GRAMPS uses this information strictly so it can
create valid GEDCOM output files (which require information about the
files' creator). If you wish, you can choose not to supply this
information, but be aware that unless and until you do, any GEDCOM files
you export will not be valid.</para>
<figure id="druid-fig">
<title>GRAMPS Getting Started Window: Researcher Information</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/researcher.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Shows Researcher Information Window.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<tip id="preferences-tip">
<title>Entering personal information</title>
<para>This information can be entered at any time in the Preferences
dialog, under the Database/Researcher Information category.</para>
</tip>
</sect1>
<!---->
<sect1 id="choose-db-start">
<title>Choosing a database</title>
<para>If GRAMPS is started without a database selected, the initial
screen will have little functionality. Most operations will not be
available. To load a database, select either <guibutton>New</guibutton>
to create a new database, or <guibutton>Open</guibutton> to open an
existing database. GRAMPS keeps track of your recently opened databases,
and these can be selected by clicking on the arrow next to the
<guibutton>Open</guibutton> button and choosing from the drop down
menu.</para>
<figure id="first-open">
<title>Initial Window</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/first-open.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Initial Window.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!---->
</sect1>
<sect1 id="get-help">
<title>Obtaining Help</title>
<para>GRAMPS has a <menuchoice>
<guimenu>Help</guimenu>
</menuchoice> menu that you can consult at any time. It includes the
following items:</para>
<variablelist>
<varlistentry>
<term>User manual</term>
<listitem>
<para>An electronic version of the manual that you can access
while you work in GRAMPS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FAQ</term>
<listitem>
<para>A list of Frequently Asked Questions about GRAMPS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GRAMPS home page</term>
<listitem>
<para>A link to the GRAMPS' project web site.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GRAMPS mailing lists</term>
<listitem>
<para>Gives you direct access to GRAMPS' mailing list
archives.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Report a bug</term>
<listitem>
<para>Choose this item to file a bug report in our bug tracking
system. (Remember, GRAMPS is a living project. We want to know
about any problems you encounter so we can work to solve them for
everyone's benefit.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Show plugin status</term>
<listitem>
<para>Use this item to display the status of any plugins you may
have added.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open example database</term>
<listitem>
<para>Select this item to load the example database that is
included in your GRAMPS package. This database is composed of
fictitious people and serves as a useful example for learning how
to work with GRAMPS.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="gramps-mainwin">
<title>Main Window</title>
<para>When you open a database (either existing or new), the following
window is displayed:</para>
<!-- ==== Figure: Main Window ==== -->
<figure id="mainwin-fig" pgwide="1">
<title>GRAMPS Main Window</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/mainwin.png" format="PNG"
scale="100" width="" />
</imageobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The main GRAMPS window contains the following elements:</para>
<variablelist>
<varlistentry>
<term>Menubar</term>
<listitem>
<para>The menubar is located at the very top of the window (right
below the window title) and provides access to all the features of
GRAMPS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Toolbar</term>
<listitem>
<para>The toolbar is located right below the menubar. It gives you
access to the most frequently used functions of GRAMPS. You can set
options that control how it appears by going to <menuchoice>
<guimenu>Edit</guimenu>
<guisubmenu>Preferences</guisubmenu>
</menuchoice>. You can also hide it entirely by going to
<menuchoice>
<guimenu>View</guimenu>
<guisubmenu>Toolbar</guisubmenu>
</menuchoice>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Progress Bar</term>
<listitem>
<para>The Progress Bar is located in the lower left corner of the
GRAMPS window. It displays the progress of time consuming
operations, such as opening and saving large data bases, importing
and exporting to other formats, generating web sites, etc. When you
are not doing these types of operations, the Progress Bar is
blank.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Status Bar</term>
<listitem>
<para>The Status Bar is located to the right of the Progress Bar, on
the very bottom of the GRAMPS window. It displays information about
current GRAMPS activity and contextual information about the
selected items. The behavior of the Status Bar can be adjusted in
the Preferences dialog, which can be found by selecting <menuchoice>
<guimenu>Edit</guimenu>
<guisubmenu>Preferences</guisubmenu>
</menuchoice>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Display area</term>
<listitem>
<para>The largest area in the center of the GRAMPS window is the
display area. What it displays depends on the currently selected
View. We'll discuss Views in detail below.</para>
</listitem>
</varlistentry>
</variablelist>
<!-- ================ Main Window Subsection -->
<sect1 id="gramps-views">
<title>Views</title>
<para>Genealogical information is very broad and can be extremely
detailed. Displaying it poses a challenge that GRAMPS takes on by
dividing and organizing the information into a series of Views. Each
View displays a portion of the total information, selected according to
a particular category. This will become clearer as we explore the nine
different Views, listed below:</para>
<itemizedlist>
<listitem>
<para>People</para>
<para>Displays the list of all people in the database</para>
</listitem>
<listitem>
<para>Relationships</para>
<para>Shows the relationships between the selected person and other
people. This includes parents, spouses, and children</para>
</listitem>
<listitem>
<para>Family List</para>
<para>Shows the list of all families in the database</para>
</listitem>
<listitem>
<para>Pedigree View</para>
<para>Displays a graphical ancestor tree for the selected
person</para>
</listitem>
<listitem>
<para>Events</para>
<para>Displays the list of all events in the database</para>
</listitem>
<listitem>
<para>Sources View</para>
<para>Displays the list of all sources in the database</para>
</listitem>
<listitem>
<para>Places View</para>
<para>Displays the list of all places in the database</para>
</listitem>
<listitem>
<para>Media View</para>
<para>Displays the list of all media objects in the database</para>
</listitem>
<listitem>
<para>Repositories</para>
<para>Displays the list of all repositories in the database.</para>
</listitem>
</itemizedlist>
<para>Before we launch into a description of each View, let's first
explain how to switch between Views.</para>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="view-modes">
<title>Switching Views and Viewing Modes</title>
<para>As mentioned above there are six different Views. In addition,
there are two different Viewing Modes. You can tell at a glance which
Viewing Mode you are in: If you see icons listed vertically in a
sidebar at the left of the window, you are in the Sidebar Viewing
Mode. If instead you see a series of "notebook tabs" (labeled People,
Family, Pedigree, Sources, Places, Media) that run horizontally across
the window, then you are in the Tabbed Viewing Mode. You can switch
from one Viewing Mode to another by selecting <menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Sidebar</guimenuitem>
</menuchoice> from the Sidebar menu item.</para>
<para>If you're in the Sidebar Viewing Mode, you can select the View
you want by clicking one of the sidebar icons.</para>
<!-- ==== Figure: Sidebar Mode ==== -->
<figure id="side-nofilt-fig">
<title>Sidebar Viewing Mode</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/mainwin.png" format="PNG"
scale="100" width="" />
</imageobject>
<textobject>
<phrase>Shows sidebar viewing mode.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>If you're in the Tabbed Viewing Mode, you can select the View
you want by clicking the corresponding notebook tab.</para>
<!-- ==== Figure: Tabbed Notebook Mode ==== -->
<figure id="noside-nofilt-fig">
<title>Tabbed Viewing Mode</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/noside-nofilt.png"
format="PNG" scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows tabbed viewing mode.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</sect2>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="people-view">
<title>People View</title>
<para>When GRAMPS first opens a database, it displays the People View
(<xref linkend="side-nofilt-fig" /> and <xref
linkend="noside-nofilt-fig" />). This view lists all the people stored
in the database.</para>
<para>You'll note that people are grouped according to their family
names. To the left of each family name is an arrow. Clicking it once
will reveal the entire list of people sharing that name. Clicking the
arrow again will "roll up" the list and show only the family
name.</para>
<para>By default, the People View, displays the following columns:
<guilabel>Names</guilabel>, GRAMPS <guilabel>ID</guilabel> numbers,
<guilabel>Gender</guilabel>, and their <guilabel>Birth</guilabel> and
<guilabel>Death dates</guilabel>. You can add or remove columns to and
from the display by calling up the <guilabel>Column Editor</guilabel>
dialog (<menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Column Editor</guimenuitem>
</menuchoice>) and checking or unchecking the boxes listed. You can
also change the position of a column in People View by clicking and
dragging it to a new position in the Editor. Once you have made the
changes you want, click <guibutton>OK</guibutton> to exit the Editor
and see your changes in the People View.</para>
<note id="columns-tip">
<title>Column Editor</title>
<para>The Column Editor is available in all Views and works the same
way in each.</para>
</note>
<!-- ==== Figure: Enabled Filter ==== -->
<figure id="column-editor-fig">
<title>Column Editor Dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/column-editor.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows column editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ================ Main Window Sub-sub-subsection -->
<sect3 id="filters">
<title>Filters</title>
<para>Genealogical databases can contain information on many people,
families, places, and objects. It's therefore possible for a View to
contain a long list of data that's difficult to work with. GRAMPS
gives you two different means for controlling this condition by
allowing you to filter a list to a more manageable size. These
methods are Search and Filtering.</para>
<para>Search is a simple but fast method of searching the columns
displayed on the screen. Typing the characters into the Search box
and clicking the Find button will display only lines that match the
text.</para>
<para>Alternatively, you can enable the Filter sidebar, which will
be displayed on the right hand side of the display. When the filter
sidebar is displayed, the Search bar is not displayed. The Filter
side bar allows you to interactive build a set of filter rules that
can be applied to the display. The filter is applied based on the
rules and the data, not on the screen display.</para>
<!-- ==== Figure: Enabled Filter ==== -->
<figure id="side-filt-fig">
<title>Filter Controls Displayed</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/side-filt.png"
format="PNG" scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows filter controls.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>When GRAMPS opens a database, no filtering is in effect. In
People View, for example, all people in the database are listed by
default.</para>
</sect3>
</sect2>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="relationships-view">
<title>Relationships View</title>
<para>The Relationships View displays the family relationships of a
selected person that we call the Active person. Specifically, it shows
his or her parents, spouses, and children.</para>
<para>The Relationships View is designed to allow for quick
navigation. You can quickly change the selected person simply by
clicking the name of any person listed on the page. Each name is
actually a hypertext link, similar to a web page.</para>
<!-- ==== Figure: Family View ==== -->
<figure id="family-fig">
<title>Relationsihps View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/family.png" format="PNG"
scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows Relationships View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The Relationships View displays the following sections:</para>
<variablelist>
<varlistentry>
<term>Active person</term>
<listitem>
<para>At the top of the screen, name, ID, birth, and death
information of the active person is displayed. If a photo of the
person is available, it is show on the right hand side. Next to
the person's name is a symbol indicating gender, and an Edit
button. Clicking the <guibutton>Edit</guibutton> button will
allow you to edit all of the person's individual information in
an Edit Person dialog.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Parents</term>
<listitem>
<para>The next sections display the person's parents and
siblings. Since it is possible to have multiple sets of parents,
it is possible to have several Parents sections. You can control
how much information is displayed by using the
<guimenu>View</guimenu> menu. The view menu allows you to show
or hide details (the birth and death information) and to show or
hide siblings. Next to each person listed is an
<guibutton>Edit</guibutton> button, which will allow you to edit
all the details of that particular person.</para>
<para>You may add, edit, or delete family information using the
buttons next to the Parents label. You can add a set of parents
by either selecting the Add button (the first button) or the
<guibutton>Select</guibutton> button (the second button). The
<guibutton>Add</guibutton> button will create a new family with
the active person listed as a child. The
<guibutton>Select</guibutton> button will allow you to choose
from a list of existing families, and then add the person as a
child to that family.</para>
<warning>
<para>If you are not careful, it is possible to create
multiple families with the same parents. This is rarely what
the user wants to do. If you attempt to add a new family that
has the same parents as an existing family, GRAMPS will issue
a warning dialog. If you get this dialog, you should probably
Cancel the edit, and then use the
<guibutton>Select</guibutton> button to select the existing
family.</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>Family</term>
<listitem>
<para>Similar to the Parents section is the Family section,
which displays families where the person is a parent. Because it
is possible to have mulitple familes, it is possible to have
multiple Family sections. Each family section displays the
spouse and any children.</para>
<note>
<para>We use the term <emphasis>spouse</emphasis> for sake of
simplicity. However, please note that
<emphasis>spouse</emphasis> may in fact be a domestic partner,
a partner in a civil union, or various other similar
relationships between two people. <emphasis>Spouse</emphasis>
relationships are not required to be only between a male and
female.</para>
</note>
<para>You may add, edit, or delete family information using the
buttons next to the Family label. You can add a spouse by
clicking the Add button (the first button), which will create a
new family with the active person listed as a father or mother.
Selecting the Edit button will allow you to edit the displayed
family. Clicking the Delete button will remove the person from
the displayed family.</para>
<warning>
<para>Removing a person from a family does not delete the
family. The person is removed as the father or mother, and any
other relationships in the family continue to exist.</para>
</warning>
<note>
<para>We use the terms <emphasis>father</emphasis> and
<emphasis>mother</emphasis> for the sake of simplicity. Even
if there are no children in a family, the
<emphasis>father</emphasis> and <emphasis>mother</emphasis>
terminology is still used. In the case of male/male or
female/female relationships, one of the
<emphasis>father</emphasis> and <emphasis>mother</emphasis>
labels should be considered to be convience labels, and should
be considered as interchangable.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="family-list-view">
<title>Family List View</title>
<para>The Family List View displays a list of all families in the
database. From this view, you may add, edit, or delete families. The
default display lists the ID, Father, Mother, and Relationship.
Children cannot be displayed on the screen in this view.</para>
<!-- ==== Figure: Family View ==== -->
<figure id="family-list">
<title>Family List View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/family-list.png"
format="PNG" scale="" width="" />
</imageobject>
<textobject>
<phrase>Family List View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<warning>
<para>Unlike the Relationships View, clicking the Remove button in
this view will remove the family from the database. All people will
remain, but all relationships between the people in the family will
be removed.</para>
</warning>
<!-- ==== End of Figure ==== -->
</sect2>
<sect2 id="pedigree-view">
<title>Pedigree View</title>
<para>The Pedigree View displays a family tree of the Active person's
ancestors. The Pedigree View shows up to four generations, depending
on the size of the window. Each person is indicated by a box labeled
with his or her name, birth and death information, and optionally an
image if available. Two lines branch from each box. The top one shows
the person's father and the bottom one the mother. Solid lines
represent birth relations, while dashed lines represent non-birth
relations such as adoption, step-parenthood, guardianship, etc.</para>
<!-- ==== Figure: Pedigree View ==== -->
<figure id="pedigree-fig">
<title>Pedigree View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/pedigree.png"
format="PNG" scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows Pedigree View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>To the left of the Active person is a left arrow button. If the
Active person has children, clicking this button expands a list of the
Active person's children. Selecting one of the children makes that
child the active Person.</para>
<para>The appearance of the children's names in the menu
differentiates the <emphasis>dead ends</emphasis> of the tree from the
continuing branches. Children who have children themselves appear in
the menu in the boldface and italic type, while children without
children (<emphasis>dead ends</emphasis>) appear in a regular font. If
the Active person has only one child, no menu will be displayed (since
there is only one choice) and the child will become the Active person
when the arrow button is clicked.</para>
<!-- ==== Figure: Pedigree View ==== -->
<figure id="pedigree-child-cut-fig">
<title>Children Menu</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/pedigree-child-cut.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Children Menu in Pedigree View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The right-hand side of the window shows two right arrow buttons.
When the top button is clicked, the Father of the Active person
becomes the Active person. Clicking the bottom button makes the Mother
of the Active person the Active person.</para>
<!-- ==== Figure: Pedigree View ==== -->
<figure id="pedigree-siblings-cut-fig">
<title>Personal Context Menu</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=""
fileref="figures/pedigree-siblings-cut.png"
format="PNG" scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows Context Menu in Pedigree View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>Right-clicking on any person's box in the Pedigree View will
bring up the "context menu". Among other useful items, the context
menu has sub-menus listing <guilabel>Spouses</guilabel>,
<guilabel>Siblings</guilabel>, <guilabel>Children</guilabel>, and
<guilabel>Parents</guilabel> of that person. "Greyed-out" sub-menus
indicate the absence of the data in the appropriate category.
Similarly to the children menu above, Childrens' and Parents' menus
distinguish continuing lines from dead ends.</para>
</sect2>
<sect2>
<title>Events View</title>
<para>New in version 2.2 is the inclusion of an Events View. Events
can be shared between between multiple people and multiple families.
The Events View lists the all the events recorded in the database. The
default view displays the <guilabel>Description</guilabel>,
<guilabel>ID</guilabel>, <guilabel>Type</guilabel>,
<guilabel>Date</guilabel>, <guilabel>Place</guilabel> and
<guilabel>Cause</guilabel> of the event.</para>
<figure id="events-fig">
<title>Events View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/events.png" format="PNG"
scale="" width="" />
</imageobject>
<textobject>
<phrase>Events View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<warning>
<para>Because events can be shared, you should take the extra time
to give each event a unique and meaningful description. This will
help you find the correct event if you decide to share
events.</para>
</warning>
<para>The list of Events can be sorted in the usual manner, by
clicking on the column heading. Clcking once sorts in ascending order,
clicking again sorts in descending order. The <guilabel>Column
Editor</guilabel> dialog can be used to add, remove and rearrange the
displayed columns.</para>
</sect2>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="sources-view">
<title>Sources View</title>
<para>Sources View lists the sources of certain information stored in
the database. These can include various documents (birth, death, and
marriage certificates, etc.), books, films, journals, private diaries,
- nearly anything that can provide genealogical evidence. GRAMPS gives
you the option to provide a source for each event you record (births,
deaths, marriages, etc.). The Source View lists the
<guilabel>Title</guilabel>, <guilabel>ID</guilabel>, and
<guilabel>Author</guilabel> of the source, as well as any
<guilabel>Publication</guilabel> information that may be associated
with it.</para>
<para>The list of Sources can be sorted in the usual manner, by
clicking on a column heading. Clicking once sorts in ascending order,
clicking again sorts in descending order. The <guilabel>Column
Editor</guilabel> dialog can be used to add, remove and rearrange the
displayed columns.</para>
<!-- ==== Figure: Sources View ==== -->
<figure id="sources-fig">
<title>Sources View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/sources.png" format="PNG"
scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows Sources View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</sect2>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="places-view">
<title>Places View</title>
<para>The Places View lists the geographical places in which the
events of the database took place. These could be places of birth,
death, and marriages of people, as well as their home, employment,
education addresses, or any other conceivable reference to the
geographical location. The Places View lists the places'
<guilabel>Name</guilabel>, <guilabel>ID</guilabel>, <guilabel>Church
Parish</guilabel>, <guilabel>City</guilabel>,
<guilabel>County</guilabel>, <guilabel>State</guilabel>, and
<guilabel>Country</guilabel>. All of these columns can be used for
sorting by the usual sorting rules. The <guilabel>Column
Editor</guilabel> dialog may be used to add, remove and rearrange the
displayed columns.</para>
<!-- ==== Figure: Places View ==== -->
<figure id="places-fig">
<title>Places View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/places.png" format="PNG"
scale="" width="" />
</imageobject>
<textobject>
<phrase>Shows Places View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</sect2>
<!-- ================ Main Window Sub-subsection -->
<sect2 id="media-view">
<title>Media View</title>
<para>The Media View is a list of Media Objects used in the database.
Media Objects are any files that relate somehow to the stored
genealogical data. Technically, any file can be stored as a Media
Object. Most frequently, these are images, audio files, animation
files, etc. The list box on the bottom lists the
<guilabel>Name</guilabel>, <guilabel>ID</guilabel>,
<guilabel>Type</guilabel>, and <guilabel>Path</guilabel> of the Media
Object. The <guilabel>Column Editor</guilabel> dialog may be used to
rearrange the displayed columns, which obey usual sorting rules. The
top part of the GRAMPS window shows a preview (if available) and
information about the Media Object.</para>
<!-- ==== Figure: Media View ==== -->
<figure id="media-fig">
<title>Media View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/media.png" format="PNG"
scale="" width="" />
</imageobject>
<textobject>
<phrase>Media View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</sect2>
<sect2>
<title>Repositories View</title>
<para>Version 2.2 adds support for Repositories. A repository can be
thought of as a collection of sources. Each source in the database can
reference a repository (such as a library) in which it belongs. The
functionality of the Repositories View is similar to the other
views.</para>
<figure id="repository-fig">
<title>Repositories View</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/repository.png"
format="PNG" scale="" width="" />
</imageobject>
<textobject>
<phrase>Repositories View.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
</sect2>
</sect1>
</chapter>
<chapter id="gramps-usage">
<title>Usage</title>
<para>Now we turn to a detailed exploration of the day-to-day use of
GRAMPS. First, we should point out that GRAMPS often offers more than one
way to do the same task. We'll try to point out some of these alternatives
where appropriate.</para>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="new-db">
<title>Starting a New Database</title>
<para>To start a new database, choose <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice> or select the <guibutton>New</guibutton> button from the
toolbar. You will then be asked to give the new database a name.</para>
<note id="new-db-notdir-note">
<title>GRAMPS databases</title>
<para>GRAMPS stores your data in a Berkeley database, sometimes known
as BSDDB. These files have ".grdb" as their default extension. The
extension is automatically added to your filename.</para>
</note>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="open-db">
<title>Opening a Database</title>
<para>To open a database, either choose <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open</guimenuitem>
</menuchoice> or click the <guibutton>Open</guibutton> button on the
Toolbar. The <guilabel>Open database</guilabel> dialog will appear and
you'll see a list of files. If you don't see the file you're looking
for, make sure the All files filter is selected. (This dialog has a
"filetype" filter, meaning it may only be showing files that have a
certain extension.)</para>
<para>To open a recently accessed database, choose either <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open Recent</guimenuitem>
</menuchoice> or the down arrow next to the
<guibutton>Open</guibutton> button and select the filename from the
list.</para>
<para>If you do not have "write permissions" for the selected database,
it will be opened in a Read Only mode. In this mode, the data may be
viewed, but no changes will be made to the database. To indicate this
mode, the title of the main window will be appended with <guilabel>(Read
Only)</guilabel> text.</para>
<para>GRAMPS allows you to open certain databases that have not been
saved in GRAMPS' own file format. These include XML and GEDCOM
databases. But you should be aware that if the XML or GEDCOM database is
relatively large, you may encounter some performance problems. These can
be avoided by creating a new GRAMPS database and importing your
XML/GEDCOM data into it.</para>
<note id="open-db-note2">
<title>Opening XML and GEDCOM databases</title>
<para>XML and GEDCOM databases require all data to be held in memory.
GRAMPS' native grdb format does not. Thus, a database with a grdb
format can access data quicker and more efficiently.</para>
</note>
<warning id="open-db-warn">
<title>GEDCOM Editing</title>
<para>Please keep in mind that some information in a GEDCOM file may
be lost during import into GRAMPS. Simply opening and viewing the file
will not change it. However, if any changes were made and they were
not abandoned upon exit, exiting GRAMPS will save the data, with
possible data loss.</para>
</warning>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="save-db">
<title>Saving Changes to Your Database</title>
<para>GRAMPS saves your changes as soon as you apply them. This means,
for example, that any time you click <guibutton>OK</guibutton> when
using GRAMPS, your changes are immediately recorded and saved. There is
no separate "save" command (although there is a "save as" command that
we'll discuss later.)</para>
<para>You can undo changes you've made by selecting <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Undo</guimenuitem>
</menuchoice>. If you select this command repeatedly, your most recent
changes will be undone one at a time.</para>
<para>If you want to return your database to the way it was when you
opened it, select <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Abandon changes and quit</guimenuitem>
</menuchoice>. (This is just like quitting without saving in other
programs.)</para>
<para>If you would like to save your database under a different name,
you can do so by choosing <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as...</guimenuitem>
</menuchoice> and specifying the name (and, optionally, the format) of
your new database. Note that "Save as" will allow you to continue
editing the newly saved database. If this is not what you want to do,
you may wish to use the "Export" command instead.</para>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="import-data">
<title>Importing Data</title>
<para>Importing allows you to bring data from other genealogy programs
into a GRAMPS database. Currently, GRAMPS can import data from the
following formats:</para>
<itemizedlist>
<listitem>
<para>Another GRAMPS database (having the "grdb" file
extension),</para>
</listitem>
<listitem>
<para>GEDCOM</para>
</listitem>
<listitem>
<para>GRAMPS XML</para>
</listitem>
<listitem>
<para>GRAMPS package</para>
</listitem>
<listitem>
<para>GeneWeb</para>
</listitem>
</itemizedlist>
<note id="import-note">
<title>Importing vs. opening</title>
<para>Please recognize that importing a database is different from
opening a database. When you import, you are actually bringing data
from one database into a GRAMPS database. When you open a file, you
are editing your original file.</para>
</note>
<para>To import data, select <menuchoice>
<guimenu>File</guimenu>
<guisubmenu>Import</guisubmenu>
</menuchoice>. The <guilabel>Import database</guilabel> dialog will
open, asking you to specify the file you wish to import.</para>
<warning id="import-dataloss">
<title>Data loss with some formats</title>
<para>It is important to note that the importing process is not
perfect for GEDCOM and GeneWeb databases. There is a chance that some
of the data in these databases will not be imported into
GRAMPS.</para>
</warning>
<para>The GRAMPS database (grdb), GRAMPS XML, and GRAMPS package are all
native GRAMPS formats. There is no risk of information loss when import
or exporting to these formats.</para>
<variablelist>
<varlistentry>
<term>GRAMPS database (grdb)</term>
<listitem>
<para>The native GRAMPS database format is a specific form of
Berkeley database (BSDDB) with a special structure of data tables.
This format is binary and architecture-dependent. It is very quick
and efficient, but not generally portable across computers with
different binary architecture (e.g. i386 vs alpha).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GRAMPS XML</term>
<listitem>
<para>The GRAMPS XML file was the default format for older
versions of GRAMPS. Unlike the grdb format, it is architecture
independent and human-readable. The database may also have
references to non-local (external) media objects, therefore it is
not guaranteed to be completely portable. The GRAMPS XML database
is created by saving ( <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save As...</guimenuitem>
</menuchoice> ) or exporting ( <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Export...</guimenuitem>
</menuchoice> ) data in that format</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GRAMPS package</term>
<listitem>
<para>The GRAMPS package is a compressed archive containing the
GRAMPS XML file and all media objects (images, sound files, etc.)
to which the database refers. Because it contains all the media
objects, this format is completely portable. The GRAMPS package is
created by exporting ( <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Export...</guimenuitem>
</menuchoice> ) data in that format.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If you import information from another GRAMPS database or GRAMPS
XML database, you will see the progress of the operation in the progress
bar of GRAMPS' main window.</para>
<!-- Missing media is commented out for now. This may be deleted in the near future -->
<!--
<para>If a media file is not found during import, you'll be prompted to
take one of the actions indicated in <xref
linkend="missing-media-im" />.</para>
<figure id="missing-media-im">
<title>Missing Media dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="264" fileref="figures/missing-media.png"
format="PNG" width="493" />
</imageobject>
<textobject>
<phrase>Shows Missing Media dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<itemizedlist>
<listitem>
<para>If you don't have the missing file and have no possibility of
replacing it, click the <guibutton>Remove Object</guibutton> button.
This will remove the object that corresponds to the missing file as
well as all the references in the database to that object.</para>
</listitem>
<listitem>
<para>If you're not sure where the missing file is, but think you
still have it or may be able to find it, click the <guibutton>Keep
Reference</guibutton> button. If and when you find the file, you can
simply copy it into your database directory and have access to it
through GRAMPS.</para>
</listitem>
<listitem>
<para>If you can supply the missing file during the import
operation, 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.</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 GRAMPS database
with other researchers as well as to enable you to transfer your data to
another computer. Currently, GRAMPS can export data to the following
formats: GRAMPS database (grdb), GRAMPS XML, GEDCOM, GRAMPS package, Web
Family Tree, and GeneWeb.</para>
<note id="export-note">
<title>Export is saving a copy</title>
<para>When you export, you are saving a copy of the currently opened
database. Exporting creates another file with a copy of your data.
Note that the database that remains opened in your GRAMPS window is
NOT the file saved by your export. Additional editing of the currently
opened database will not alter the copy produced by the export.</para>
</note>
<para>To export data, choose <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Export</guimenuitem>
</menuchoice>. This will bring up the <guilabel>Export</guilabel>
assistant. Its pages will guide you through the format selection (see
<xref linkend="export-druid-fig" />), file selection, and format
specific export options (see <xref linkend="gedcom-export-fig" />).
After a final confirmation page, the export will be performed according
to the choices you have made. At any time, you can click the
<guibutton>Back</guibutton> and revise any selection, and then go
forward to redo the export.</para>
<!-- ==== Figure: GEDCOM Export ==== -->
<figure id="export-druid-fig">
<title>Export assistant: format selection</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="383" fileref="figures/export-druid.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows format selection page of an Export
assistant</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<sect2 id="export-gedcom">
<title>Exporting into the GEDCOM format</title>
<para>GRAMPS allows you to export a database into the common GEDCOM
format. It provides options that allow you to fine tune your export
(see <xref linkend="gedcom-export-fig" />).</para>
<variablelist>
<varlistentry>
<term>Encoding</term>
<listitem>
<para>Since different languages use different characters, it is
important to tell a GEDCOM file what character set is used. The
two formats traditionally accepted are ASCII and ANSEL. Since
all ASCII characters are valid ANSEL characters, GRAMPS does not
provide an option for ASCII.</para>
<para>Because ANSEL is not commonly used, some genealogy
programs will accept ANSI (more commonly know as ISO-8859-1) and
Unicode character sets. Only select ANSI or Unicode if you know
any program that attempts to read the GEDCOM file will
understand these character sets.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Filter</term>
<listitem>
<para>The filter allows you to export a limited amount of data,
based on the criteria you select.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Target</term>
<listitem>
<para>While GEDCOM is a standard, not every program implements
it in the same way. This can lead to data loss. GRAMPS can
reduce the data loss in some cases. You can tell GRAMPS what
program is the target, and GRAMPS will customize the exported
file for that program. If your program is not listed, choose the
"GEDCOM 5.5 Standard".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Copyright</term>
<listitem>
<para>Allows you to select a statement to describe your
Copyright claim.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>No not include records marked private</term>
<listitem>
<para>Check this box to prevent private records from being
included in the exported file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Restrict data on living people</term>
<listitem>
<para>Check this box to limit the information exported for
living people. This means that all information concerning their
birth, death, addresses, significant events, etc., will be
omitted in the exported GEDCOM file. If you choose this option,
you will be given additional options to limit further the data
on living people. For example, you can choose to substitute the
word "Living" for the first name; you can exclude notes; and you
can exclude sources for living people.</para>
<para>Sometimes, it is not always obvious from the data if
someone is actually alive. GRAMPS uses an advanced algorithm to
try to determine if a person could still be alive. Remember,
GRAMPS is making its best guess, and it may not always be able
to guess correctly all the time. Please double check your
data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Reference images from path</term>
<listitem>
<para>Check this box to tell GRAMPS to use the specific path for
your images when writing image references in GEDCOM.</para>
<para>This option allows specify where your image files are
located. This is useful when you are transfering your GEDCOM
file from one computer to another. It tells the program that is
importing the data where your images are.</para>
</listitem>
</varlistentry>
</variablelist>
<!-- ==== Figure: GEDCOM Export ==== -->
<figure id="gedcom-export-fig">
<title>Export assistant: GEDCOM options</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="481" fileref="figures/gedcom-export.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows GEDCOM options page of an Export druid</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Export ==== -->
</sect2>
<sect2 id="export-gramps-formats">
<title>Export into GRAMPS formats</title>
<variablelist>
<varlistentry>
<term>GRAMPS database (grdb) export</term>
<listitem>
<para>Exporting to the GRAMPS native format will simply make a
copy of your data under another name. Exporting to this format
can also be useful if you have directly opened an XML or GEDCOM
file and would like to save it as the grdb file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GRAMPS XML database export</term>
<listitem>
<para>Exporting into GRAMPS XML format will produce a database
compatible with the previous versions of GRAMPS. As XML is a
text-based human-readable format, you may also use it to take a
look at your data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GRAMPS package export</term>
<listitem>
<para>Exporting to the GRAMPS package format will create a
compressed file that contains the database and copies of all
associated media files. This is useful if you want to move your
database to another computer or to share it with someone.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Export to CD</term>
<listitem>
<para>Exporting to CD will prepare your database and copies of
all media object files for recording onto a CD. To actually burn
the CD, you will need to go to the GNOME
<guilabel>burn:///</guilabel> location, which can be accessed by
navigating through Nautilus: After exporting to CD, select
<menuchoice>
<guimenu>Go</guimenu>
<guisubmenu>CD Creator</guisubmenu>
</menuchoice> in the Nautilus menu. Your database directory
will show up. To burn it to the CD, click the CD icon on the
Nautilus toolbar, or select <menuchoice>
<guimenu>File</guimenu>
<guisubmenu>Write to CD</guisubmenu>
</menuchoice> in the Nautilus menu.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If a media file is not found during export, you will see the
same <guilabel>Missing Media</guilabel> dialog you encounter with
GEDCOM export.</para>
</sect2>
<sect2 id="export-other-formats">
<title>Export into other formats</title>
<variablelist>
<varlistentry>
<term>Web Family Tree</term>
<listitem>
<para>Exporting to Web Family Tree will create a text file that
can be used by the Web Family Tree program. Export options
include filter selection and the ability to limit data on living
people to that of their family ties.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GeneWeb</term>
<listitem>
<para>Exporting to GeneWeb will save a copy of your data into a
popular web genealogy format. To find out more about GeneWeb and
its format, visit <ulink type="http"
url="http://cristal.inria.fr/~ddr/GeneWeb/en/">http://cristal.inria.fr/~ddr/GeneWeb/en/</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>vCalendar and vCard</term>
<listitem>
<para>Exporting to vCalendar or vCard will save information in a
format used in many calendaring and addressbook applications,
sometimes called PIM for Personal Information Manager.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="gramps-edit-quick">
<title>Entering and Editing Data: Quick Start Overview</title>
<para>This section is designed to give you the basic knowledge necessary
to start putting your genealogical information into GRAMPS. It will
explain how to enter people into the database and how to specify their
family relationships. (A more detailed explanation will follow in the
section entitled <xref linkend="gramps-edit-complete" />.)</para>
<para>First, let's identify the types of information you can enter into
your GRAMPS database. These include:</para>
<itemizedlist>
<listitem>
<para>Personal information about an individual (names, addresses,
birth and death dates, etc.)</para>
</listitem>
<listitem>
<para>Information about an individual's relationships (marriages,
divorces, civil unions, etc.)</para>
</listitem>
<listitem>
<para>Information about an individual's parents and children</para>
</listitem>
<listitem>
<para>Sources that document your research</para>
</listitem>
</itemizedlist>
<note id="keybind">
<title>Keybindings</title>
<para>In addition to interacting with GRAMPS through menu items and
buttons, you can use its extensive set of "keybindings." For more
information, see <xref linkend="append-keybind" />.</para>
</note>
<para>Now let's take a quick look at how you can enter and edit these
various types of information.</para>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-add-pers">
<title>To Add or Edit a Person</title>
<para>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).</para>
<para>To edit information about a person already present in the
database, select the person from the People View and click the
<guibutton>Edit</guibutton> button on the toolbar.</para>
<note id="person-menu">
<title>Alternate ways of adding or editing a person</title>
<para>You can also use <guilabel>Add...</guilabel> and
<guilabel>Edit...</guilabel> menu items available under
<guimenu>Edit</guimenu>. Or you can right-click on the person and
select <guilabel>Add...</guilabel> or <guilabel>Edit...</guilabel>
from the context menu that pops up.</para>
</note>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-spec-rel">
<title>To Specify a Relationship</title>
<para>To specify a relationship, select the person for whom the
relationship applies. Switch to the Family View (<xref
linkend="family-fig" />) and you'll see this individual indicated as
the "Active person".</para>
<para>Now a question: Does the person who will form the relationship
with the Active person already exist in the database? If yes, click
the middle button to the right of the Spouse box. You'll then be able
to browse through the list of people in the database to select the one
you want. If not, click the topmost button to the right of the Spouse
box. This will allow you to add a new person to the database and to
specify the relationship this person has to the Active person.</para>
<note id="spouse-filter">
<title>Filtering</title>
<para>By default, GRAMPS filters the displayed list to show only
those people who could theoretically have a relationship with the
Active Person. That is, GRAMPS only shows those people whose birth
dates and death dates fit within the lifetime of the Active Person.
If you wish, you can add a person to the list by clicking the
<guibutton>+</guibutton> button. To completely override the filter
and display all people from the database, check the <guilabel>Show
all</guilabel> box.</para>
</note>
<para>To edit an existing relationship, double-click in the Spouse
box. If there is more than one relationship in the list, you can
select the spouse or partner you want from the list before
double-clicking.</para>
<note id="spouse-alt-edit">
<title>Alternate ways of editing relationships.</title>
<para>Most of the functions described above are also available in
the context menu that pops up when you right-click.</para>
</note>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-spec-par">
<title>To Specify Parents</title>
<para>To specify the parents for a person, highlight that individual
in the People View and then switch to the Family View (<xref
linkend="family-fig" />). Your selected person will be indicated as
the Active person. Click the <guibutton>+</guibutton> button to the
right of the <guilabel>Active person's parents</guilabel> list box.
This will bring up the <guilabel>Choose Parents</guilabel> dialog. You
will see three sections, one for father, one for mother, and one for
specifying the relationships between everyone.</para>
<para>If the father and mother of the Active person are already stored
in your database, you can scroll through the lists and make your
selections. If they are not in the database, you can click
<guibutton>+</guibutton> to add them.</para>
<note id="parent-filter">
<title>Filtering</title>
<para>By default, GRAMPS 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 Show all box for each
list.</para>
</note>
<para>To specify parents of the Active person's spouse, switch to
Family View and then click the <guibutton>+</guibutton> button to the
right of the Spouse's parents list box.</para>
<para>To edit information about parents who are already present in the
database, move the mouse over the corresponding parents' box and
double-click.</para>
<note id="parents-alt-menu">
<title>Alternate ways of specifying parents</title>
<para>These functions can also be performed by right-clicking on the
parents' box and using the context menu that pops up.</para>
</note>
</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 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 to the family who is already present in
the database.</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 you want, you can add a person to the list by clicking
the <guibutton>Add...</guibutton> button. By default, GRAMPS 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
right-clicking in the children's box and using the context menu that
pops up. Again, most of the above functions are available through this
context menu.</para>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-add-img">
<title>Adding Photos and Other Media Objects</title>
<para>You can add photos and other media objects to individual people,
events, sources, and places. You can also add images that might not be
limited to a single person or event (for example, group family
photos).</para>
<para>If you want to add an image to a single person, switch to the
People View (<xref linkend="side-nofilt-fig" />), select a person, and
then click the <guibutton>Edit</guibutton> icon on the toolbar. This
will bring up the <guilabel>Edit Person</guilabel> dialog (<xref
linkend="edit-pers-fig" />). Next, select the
<guilabel>Gallery</guilabel> tab, and click the
<guibutton>+</guibutton> button to call up the <guilabel>Select a
media object</guilabel> dialog. Type a filename or browse to find the
image file you want and then provide a title for that image. Keep
adding images until you are done.</para>
<para>To add images related to a relationship (for example, a
marriage), switch to the Family View (<xref linkend="family-fig" />)
and double-click on the Spouse box. This calls up the
<guilabel>Marriage/Relationship editor</guilabel> dialog. Select the
<guilabel>Gallery</guilabel> tab and click the
<guibutton>+</guibutton> button to add an image.</para>
<para>To add images related to a source or a place, first switch to
the Source View (<xref linkend="sources-fig" />) or Place View (<xref
linkend="places-fig" />). Select the source or place you want and then
either double-click on it or click the <guibutton>Edit</guibutton>
icon on the toolbar. Select the <guilabel>Gallery</guilabel> tab and
click the <guibutton>+</guibutton> button to add an image.</para>
<para>Finally, to add images that you want to include in the database,
but hare are not limited to any particular person, relationship,
source or place, switch to the Media View (<xref
linkend="media-fig" />). Then click the <guibutton>Add</guibutton>
icon on the toolbar to add an image. If you have already added any
images to any individual galleries, you will also find them listed in
the Media View.</para>
<note id="alt-add-image">
<title>Alternate way of adding images to galleries</title>
<para>An image can always be added to any gallery by using
drag-and-drop. Items can be dragged from the Media View, any
gallery, the desktop, the file manager or a web browser and dropped
on the target gallery, adding the image to the gallery.</para>
</note>
<para>In any gallery, you can also use the <guibutton>Edit</guibutton>
to edit image information and the <guibutton>-</guibutton> button and
to remove the image reference from that gallery.</para>
<note id="remove-image-from-gallery">
<title>Removing an image from a gallery</title>
<para>Removing a media object from a gallery does not remove the
image from the database. To completely remove the image from the
database, delete it from Media View by first selecting it and then
clicking the <guibutton>Remove</guibutton> icon on the
toolbar.</para>
</note>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-edit-src-plc">
<title>To Edit Sources and Places</title>
<para>To add a source or a place to the database, switch to the
appropriate Source View (<xref linkend="sources-fig" />) or Place View
(<xref linkend="places-fig" />). Then click the
<guibutton>Add</guibutton> icon on the toolbar to add a source/place.
Enter the information into the <guilabel>Source Editor</guilabel> (or
<guilabel>Place Editor</guilabel>) dialog.</para>
<para>To edit information about sources and places already present in
the database, switch to the appropriate view, select an entry you
would like to view/modify, and then click the
<guibutton>Edit</guibutton> icon on the toolbar. Alternatively, you
may double-click on the entry to edit it.</para>
</sect2>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="gramps-edit-complete">
<title>Enterng and Editing Data: Complete Description</title>
<para>The previous section offered you a quick overview of how to enter
and edit data in GRAMPS. This section continues that discussion in much
greater detail.</para>
<para>As we have seen above, GRAMPS offers you a series of Views. Each
of these Views gives you opportunities to enter and edit information. In
fact, you can often get to the same information from different
Views.</para>
<para>In GRAMPS, information is entered and edited through what we call
dialogs. Since we use that term frequently, we should define what we
mean by it:</para>
<para>A dialog is a pop-up window that provides one or more forms for
entering and editing data that fits a certain category. Examples in
GRAMPS include the Edit Person dialog and the Marriage/Relationship
dialog, among many others.</para>
<para>A dialog often includes a series of "notebook tabs" that group the
information into subcategories. For example, the Edit Person dialog has
notebook tabs for subcategories such as Events, Attributes, Addresses,
and Notes, among others.</para>
<note id="edit-button-note">
<title>Add, Remove, and Edit buttons</title>
<para>In most cases, GRAMPS uses a <guibutton>+</guibutton> to
correspond to <guibutton>Add</guibutton>, a <guibutton>-</guibutton>
correspond to <guibutton>Remove</guibutton>, and an icon of a pen on a
sheet of paper to denote <guibutton>Edit</guibutton>. We will continue
referring to the latter as the <guibutton>Edit</guibutton> button,
while using <guibutton>+</guibutton> and <guibutton>-</guibutton> to
denote the two former buttons.</para>
</note>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-pers">
<title>Editing Information About People</title>
<para>Information about people is entered and edited through the
<guilabel>Edit Person</guilabel> dialog. This dialog can be invoked
from different Views in the following ways:</para>
<variablelist>
<varlistentry>
<term>From the People View:</term>
<listitem>
<itemizedlist>
<listitem>
<para>Double-click the name of the person whose data you
would like to edit</para>
</listitem>
<listitem>
<para>Select the name by single click and then click the
<guibutton>Edit</guibutton> button on the toolbar.</para>
</listitem>
<listitem>
<para>Select the name and then press
<keycap>Enter</keycap>.</para>
</listitem>
<listitem>
<para>Select <guimenuitem>Edit...</guimenuitem> from the
<guisubmenu>Edit</guisubmenu> menu of GRAMPS</para>
</listitem>
<listitem>
<para>Select <guimenuitem>Edit</guimenuitem> from the
context menu that appears upon right-click on the
name.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>From the Family View:</term>
<listitem>
<para>To edit active person's data, move the mouse into the
<guilabel>Active person</guilabel> box.</para>
<para>To edit Spouse's data, shift-click the
<guilabel>Spouse</guilabel> entry.</para>
<para>From the <guilabel>Spouse</guilabel> and
<guilabel>Children</guilabel> boxes you can select the desired
person, right-click, and use the context menu that pops
up.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>From the Pedigree View:</term>
<listitem>
<para>Double-click in the box having the name of the person
whose data you want to edit.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In each of the above cases, the <guilabel>Edit Person</guilabel>
dialog will appear:</para>
<!-- ==== Figure: Edit Person dialog ==== -->
<figure id="edit-pers-fig">
<title>Edit Person dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-person.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Edit Person dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The top of the window shows the name of the person whose data is
being edited. Below this name are ten "notebook tabs" containing
different categories of available information. Click any tab to view
and edit its contents. Clicking the <guibutton>OK</guibutton> button
at the bottom will apply all the changes made in all tabs and close
the dialog window. Clicking the <guibutton>Cancel</guibutton> button
will close the window without applying any changes. If any data in any
tabs were modified, an alert window will appear, prompting you to
choose from the following options: close the dialog without saving
changes, cancel the initial cancel request, or save the
changes.</para>
<note>
<para>Clicking <guibutton>OK</guibutton> will immediately save
changes to the database. There is no need for a Save operation,
since all changes are immediate.</para>
</note>
<tip>
<para>If a tab label is in boldface type, this means it contains
data. If not, it has no data.</para>
</tip>
<para>The tabs reflect the following categories of personal
data:</para>
<variablelist>
<varlistentry>
<term>General</term>
<listitem>
<para>The <guilabel>General</guilabel> tab contains general
information about the person. This includes <guilabel>Given
name</guilabel>, <guilabel>Family name</guilabel>,
<guilabel>Family prefix</guilabel> (such as "de" or "van"),
<guilabel>Suffix</guilabel> (e.g. Jr. or III),
<guilabel>Title</guilabel> (e.g. Dr. or Rev.),
<guilabel>Nickname</guilabel> (Bob for Robert),
<guilabel>Type</guilabel> of the name (birth name, married name,
etc.) 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, a menu
appears below the field containing database entries that match
your partial input. This gives you a shortcut by letting you
select an entry that already exists in the database rather than
having to type it all out. You can select the entry using your
mouse or using your arrow and <keycap>Enter</keycap>
keys.</para>
<para>The <guilabel>Edit</guilabel> (that is, the "pen and
paper" icon) next to the <guilabel>Family name</guilabel> entry
field invokes the <guilabel>Name Editor</guilabel> dialog. This
dialog allows editing the preferred name in full detail (see
<xref linkend="adv-an" />).</para>
<para>The <guilabel>Gender</guilabel> radio buttons offer the
choice of person's gender : <guilabel>male</guilabel>,
<guilabel>female</guilabel>, and
<guilabel>unknown</guilabel>.</para>
<para>Clicking the colored "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 the
<guibutton>Edit</guibutton> button located next to the birth and
death LED buttons will bring up a dialog allowing you to edit
the birth or death details (see <xref
linkend="adv-ev" />).</para>
<para>The field <guilabel>ID</guilabel> displays the GRAMPS ID
number which identifies the user in the database. This value
helps you distiguish between people who have the same name. You
may enter any unique value you want. If you do not provide a
value, GRAMPS will automatically select a value for you.</para>
<para>The <guilabel>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
let you mark whether or not the person's record is complete and
whether or not the record is private.</para>
<para>The <guilabel>Events</guilabel> tab lets you view and edit
any events relevant to the person. The bottom part of the window
lists all such events stored in the database. The top part shows
the details of the currently selected event in the list (if
any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> allow
you to add, modify, and remove an event record from the
database. Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when an
event is selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Names</term>
<!-- ==== Figure: Edit Person dialog - Names ==== -->
<listitem>
<para>The <guilabel>Names</guilabel> tab lets you view and edit
any alternate names the person may have. The bottom part of the
window lists all alternate names for the person stored in the
database. The top part shows the details of the currently
selected name in the list (if any). The buttons
<guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> allow the addition, modification, and
removal of an alternate name from the database. Note that the
Edit and - buttons become available only when an alternate name
is selected from the list.</para>
<figure id="edit-pers-names-fig">
<title>Edit Person dialog - Names</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=" "
fileref="figures/edit-person-names.png"
format="PNG" width=" " />
</imageobject>
<textobject>
<phrase>Shows Names Tab of Edit Person dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<para>When you add a new name or edit an existing name, the
<guilabel>Name Editor</guilabel> dialog is invoked. This dialog
is described in the section below (see <xref
linkend="adv-an" />).</para>
<!-- ==== End of Figure ==== -->
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Attributes</term>
<listitem>
<para>The <guilabel>Attributes</guilabel> tab lets you view and
assign attributes to the person. You have complete freedom to
define and use attributes. For example, attributes might be
assigned to describe the person's physical characteristics or
personality traits.</para>
<para>Note that each attribute listed in the
<guilabel>Attribute</guilabel> dialog consists of two parts: the
Attribute itself and a Value associated with that Attribute.
This so-called "Parameter-Value" pairing can help you organize
and systematize your research. For example, if you define "Hair
color" as an Attribute for a person, "Hair Color" will become a
selectable Attribute for all other people. The Value of Hair
Color for person A might be red, and brown for person B. In
similar fashion, you might define an Attribute like "Generosity"
and use the Value of "Enormous" to describe a particularly
generous person.</para>
<para>The bottom part of the dialog window displays the list of
all Attributes stored in the database. The top part shows the
details of the currently selected attribute in the list (if
any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, and remove an attribute record from the
database. Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when an
attribute is selected from the list.</para>
<!-- ==== Figure: Edit Person dialog - Attributes ==== -->
<figure id="edit-pers-attributes-fig">
<title>Edit Person dialog - Attributes</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=""
fileref="figures/edit-person-attributes.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Attributes Tab of Edit Person
dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Addresses</term>
<listitem>
<para>The <guilabel>Addresses</guilabel> tab lets you view and
record the various addresses of the person. The bottom part of
the window lists all addresses stored in the database. The top
part shows the details of the currently selected address in the
list (if any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> allow
you to correspondingly add, modify, and remove an address record
from the database. Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when an
address is selected from the list.</para>
<para>Some reports allow you to restrict data on living people.
In particular, that option will omit their addresses.</para>
<!-- ==== Figure: Edit Person dialog - Addresses ==== -->
<figure id="edit-pers-addresses-fig">
<title>Edit Person dialog - Addresses</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=" "
fileref="figures/edit-person-addresses.png"
format="PNG" width=" " />
</imageobject>
<textobject>
<phrase>Shows Addresses Tab of Edit Person
dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Notes</term>
<listitem>
<!-- ==== Figure: Edit Person dialog - Notes ==== -->
<figure id="edit-pers-notes-fig">
<title>Edit Person dialog - Notes</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=" "
fileref="figures/edit-person-notes.png"
format="PNG" width=" " />
</imageobject>
<textobject>
<phrase>Shows Notes Tab of Edit Person dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The <guilabel>Notes</guilabel> tab provides a place to
record various items about the person that do not fit neatly
into other categories. To add a note or modify existing notes
simply edit the text in the text entry field.</para>
<para>The <guilabel>Format</guilabel> option lets you set the
way the note will appear in reports and web pages. If you select
"Flowed," the text generated will have single spaces put in
place of all multiple spaces, tabs, and single end-of-line
characters. A blank line inserted between two blocks of text
will signal a new paragraph; additional inserted lines will be
ignored.</para>
<para>If you select the Preformatted option, the text in reports
and web pages will appear exactly as you enter it in the Notes
dialog.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Sources</term>
<listitem>
<!-- ==== Figure: Edit Person dialog - Sources ==== -->
<figure id="edit-pers-sources-fig">
<title>Edit Person dialog - Sources</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=" "
fileref="figures/edit-person-sources.png"
format="PNG" width=" " />
</imageobject>
<textobject>
<phrase>Shows Sources Tab of Edit Person
dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The <guilabel>Sources</guilabel> tab allows you to view
and document the sources for the information you collect. These
might be general sources that do not describe a specific event,
but which nevertheless yield information about the person. For
example, if Aunt Martha's memoirs mention her great-grandson
Paul, the researcher may assume that this Paul actually existed
and cite Aunt Martha's memoirs as the source that justifies this
assumption.</para>
<tip>
<para>Sources which document specific events are best recorded
as sources of the event (under the <guilabel>Events</guilabel>
tab) instead of as a source of the person. The person's
<guilabel>Sources</guilabel> tab is best used for any sources
not specificly connected to any other data.</para>
</tip>
<para>The central part displays the list of all source
references stored in the database in relation to the person. The
buttons <guibutton>+</guibutton>, <guibutton>Edit</guibutton>,
and <guibutton>-</guibutton> allow you to correspondingly add,
modify, and remove a source reference to this person. Note that
the <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
buttons become available only when a source reference is
selected from the list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Gallery</term>
<listitem>
<para>The <guilabel>Gallery</guilabel> tab lets you view and
store photos, videos, and other media objects that are
associated with the person. The central part of the window lists
all such media objects. Any object in the form of a valid image
file will result in the display of a thumbnail view of the
image. For other objects such as audio files, movie files, etc.,
a corresponding file type icon is displayed instead.</para>
<tip>
<para>The first available image in the gallery will be also
displayed in the <guilabel>Image</guilabel> area in the
<guilabel>General</guilabel> tab.</para>
</tip>
<para>The buttons <guibutton>+</guibutton>,
<guibutton>Select</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> let you add a new image to the
database, link to an image already stored in the database,
modify an image, and remove a given media object from the
person's gallery. Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when a
media object is selected from the list.</para>
<!-- ==== Figure: Edit Person dialog - Gallery ==== -->
<figure id="edit-pers-gallery-fig">
<title>Edit Person dialog - Gallery</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=""
fileref="figures/edit-person-gallery.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Gallery Tab of Edit Person
dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<note>
<para>Removing a media object from a person's gallery does not
remove it from the database. It only removes the reference to
that object from this person's record.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Internet</term>
<listitem>
<para>The <guilabel>Internet</guilabel> tab displays Internet
addresses relevant to the person. The bottom part lists all such
Internet addresses and accompanying descriptions. The top part
shows the details of the currently selected addresses in the
list (if any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, and remove an Internet address. The "Go" button
(represented by an icon having a green arrow and yellow circle)
opens your web browser and takes you directly to the highlighted
page. Note that the <guibutton>Edit</guibutton>,
<guibutton>-</guibutton>, and <guibutton>Go</guibutton> buttons
become available only when an address is selected from the
list.</para>
<!-- ==== Figure: Edit Person dialog - Internet ==== -->
<figure id="edit-pers-internet-fig">
<title>Edit Person dialog - Internet</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=""
fileref="figures/edit-person-internet.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Internet Tab of Edit Person
dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>LDS</term>
<listitem>
<para>The <guilabel>LDS</guilabel> (Latter Days Saints) tab lets
you view and edit information about LDS ordinances of the
person. These are LDS Baptism, Endowment, and Sealed to Parents
ordinances, as labeled inside the tab. Each ordinance is
described by its date, LDS temple, and Place where it happened.
An additional pop-up menu, "Parents," is available for the
Sealed to Parents ordinance. Each ordinance can be further
described through the selections available in the Status pop-up
menu. It can also be include notes and references to sources
through the corresponding <guibutton>Sources...</guibutton> and
<guibutton>Note</guibutton> buttons.</para>
<!-- ==== Figure: Edit Person dialog - LDS ==== -->
<figure id="edit-pers-lds-fig">
<title>Edit Person dialog - LDS</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth=""
fileref="figures/edit-person-lds.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows LDS Tab of Edit Person dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-dates">
<title>Editing Dates</title>
<para>This section describes how to enter and modify dates. Since
dates are so important in genealogical research, GRAMPS takes special
care to preserve and use any date information available.</para>
<para>Information can be entered into a date field by directly typing
it or by invoking the Date selection dialog. Both methods will be
discussed below, but first, we will cover some important features of
dates as they are used in GRAMPS.</para>
<sect3 id="adv-dates-types">
<title>Date types</title>
<para>Dates in GRAMPS are classified according to the following
types:</para>
<variablelist>
<varlistentry>
<term>Regular</term>
<listitem>
<para>A "regular" date is one which includes a specific day,
date, or month. It can be complete (e.g., June 6, 1990) or
partial (e.g., July 1977).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Before</term>
<listitem>
<para>A "before" date is one that can only be identified as
occurring before a certain day, month, or year.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>After</term>
<listitem>
<para>An "after" date is one that occurs after a certain day,
month, or year.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Range</term>
<listitem>
<para>A "range" describes a time period during which the event
occurred. For example, "between January 1932 and March
1932."</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Span</term>
<listitem>
<para>A "span" describes a time period during which a
condition existed. For example, "from May 12, 2000 to February
2, 2002."</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="adv-dates-parsing">
<title>Date formats and parsing rules</title>
<para>GRAMPS recognizes dates entered in a variety of formats. The
default numeric format is that which is conventional for the
environment is which GRAMPS is operating; that is, DD.MM.YYYY for
most European countries, MM/DD/YYYY for the U.S., and so on.</para>
<para>Besides exact dates, GRAMPS recognizes many dates that are not
regular: before, after, about, ranges and spans. It also understands
the quality: estimated or calculated. Finally, it supports partial
dates and many alternative calendars. Below is the list of date
entry rules to allow precise date parsing.</para>
<note>
<title>Date parsing rules</title>
<para>The list only applys to the English version of GRAMPS. If
you are using localized version of GRAMPS, your version may or may
not provide a localized date parser. At the time of this writing,
localized parsers exist for French, German, Russian, Finnish,
Dutch and Spanish languages.</para>
<para>If the localized parser is available for your version,
chances are that other rules are in effect. If there is no manual
in your language yet, you may try following your instinct and go
with the common ways of denoting dates in your language. If all
else fails, use the <guilabel>Date selection</guilabel> dialog
described below.</para>
</note>
<itemizedlist>
<listitem>
<para>Regular single dates can be entered just as you would
write them. Examples: May 24, 1961 or January 1, 2004.</para>
</listitem>
<listitem>
<para>Dates that are not regular should start with the quality:
<guilabel>estimated</guilabel> or
<guilabel>calculated</guilabel>, if applicable. Example: est.
1961, or calc 2005. (Note that a quality does not need to be
specified for regular dates.)</para>
</listitem>
<listitem>
<para>After the quality should appear the type. If the type is
<guilabel>before</guilabel>, <guilabel>after</guilabel>, or
<guilabel>about</guilabel>, you scan specify the type by writing
"before", "after" or "about". If the type is a range, write
"between DATE and DATE", and if the type is a span, write "from
DATE to DATE". patterns, where DATE is a single date.</para>
<para>Examples: est from 2001 to 2003, before June 1975, est
about 2000, calc between May 1900 and January 1, 1990.</para>
</listitem>
<listitem>
<para>Partial dates are entered simply by omitting unknown
information. Examples: May 1961 and 2004.</para>
</listitem>
<listitem>
<para>Alternate calendars are calendars other than the Gregorian
calendar. Currently, GRAMPS supports Hebrew, French Republican,
Julian, Islamic, and Persian alternate calendars. To specify the
calendar other than the default Gregorian, append the name of
the calendar to the date string, e.g. "January 9, 1905
(julian)".</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="adv-dates-led">
<title>Date Validity Indicators</title>
<para>GRAMPS uses color circles to indicate the validity of the
entered date.</para>
<tip>
<title>Date LED buttons</title>
<para>The color circles are also referred to as the LED buttons.
Clicking on an LED button will invoke the <guilabel>Date
selection</guilabel> dialog described in detail below, see <xref
linkend="adv-dates-gui" /></para>
</tip>
<itemizedlist>
<listitem>
<para>A green circle means that the date is valid and complete
regular date (e.g. May 24, 1961). In simple terms, green means
that the date corresponds to a unique date.</para>
</listitem>
<listitem>
<para>Yellow circle means that the date is valid but is not a
regular date. This could be the date of a different type: a
before date (before May 25, 1962), an after date (after May,
1960), an about date (about May 23, 1961), a range (between May
1, 1961 and May 31, 1961), or a span (from May 1, 1961 to May
31, 1961). It can also be a complete single date, but with
quality of Estimated or Calculated. Finally, it could be a
partial date, i.e. a regular quality single date missing some
portion, e.g. May 1961 or 1961.</para>
<para>While partial dates do not uniquely define the day, they
allow at least for some type of comparisons between the
dates.</para>
</listitem>
<listitem>
<para>Red circle means that the date is not recognized as a
valid date (e.g. "Christmas week of 61", or "the summer when I
had surgery"). In such a case the date will be stored as a text
string and therefore cannot be compared other dates. As you can
see, it is best to avoid such date entries. It would be better,
for example, to enter a date of "December 1961" and then to add
the note "Christmas week of '61."</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="adv-dates-gui">
<title>Graphical User Interface for Entering Dates</title>
<para>While the above parsing rules provide a guide for you to type
in most common dates, you can also use <guilabel>Date
selection</guilabel> dialog. The dialog is particularly useful for
building a complex date or for simply insuring that your information
is entered in a way GRAMPS will understand. The <guilabel>Date
selection</guilabel> dialog can be invoked by clicking the colored
circle button next to the date entry field.</para>
<!-- ==== Figure: Date selection dialog ==== -->
<para><figure id="adv-dates-gui-fig">
<title>Date selection dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/date-selection.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Date selection dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure></para>
<!-- ==== End of Figure ==== -->
<para>The <guilabel>Calendar</guilabel> menu lets you choose a
calendar other than the default Gregorian. The
<guilabel>Quality</guilabel> menu gives you the choices of Regular,
Estimated, or Calculated. The <guilabel>Type</guilabel> menu allows
you establish the exact date type: Regular, Before, After, About,
Range, Span, and Text only. You can set the
<guilabel>Date</guilabel> by setting the day, the month, and the
year. In the event that your date type is Range or Span, the
<guilabel>Second date</guilabel> will be activated. Finally, the
<guilabel>Text comment</guilabel> text entry field allows storing an
arbitrary text string along with the date.</para>
<note>
<para>If you have an important comment to make about a date, you
are better off doing so in a Note that corresponds to the event
than in the Text comment field of the Date selection dialog. We
recommend this for the following reason: If you enter a date by
typing it directly into the date field (that is, not via the Date
selector dialog), your entry will be copied and stored as the text
comment string when GRAMPS parses the entered text. Thus, any
comment that may have been there prior to the parsing will be
overwritten.</para>
</note>
</sect3>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-rel">
<title>Editing Information About Relationships</title>
<para>Information about relationships is entered and edited through
the <guilabel>Marriage/Relationship Editor</guilabel> dialog. This
dialog is invoked from Family View by double-clicking the Spouse
box</para>
<note>
<para>You can also invoke this dialog by right-clicking inside the
Spouse box and selecting "Edit relationship" item from the context
menu that pops up.</para>
</note>
<!-- ==== Figure: Edit Relationship dialog ==== -->
<figure id="edit-rel-fig">
<title>Marriage/Relationship Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-rel.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Marriage/Relationship Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The top of the window shows the names of the people whose
relationship is being edited. The main part of the window displays
seven notebook tabs representing different categories of information
about the relationship. Click any tab to view or edit the information
it contains. The bottom part has <guibutton>OK</guibutton> and
<guibutton>Cancel</guibutton> buttons. Clicking the
<guibutton>OK</guibutton> button at any time will apply all the
changes made in all tabs and close the dialog window. Clicking the
<guibutton>Cancel</guibutton> button at any time will close the window
without applying any changes. If any of the data in any tab is
modified, an alert window will appear that will prompt you choose
between closing the dialog without saving changes, canceling the
initial cancel request, or saving the changes.</para>
<note>
<para>Clicking <guibutton>OK</guibutton> will immediately save
changes to the database. This version of GRAMPS does not have a
separate saving function, all changes are immediate.</para>
</note>
<tip>
<para>If a tab label is in boldface type, this means it contains
data. If not, it has no data.</para>
</tip>
<para>The tabs provide the following information categories of
relationship data:</para>
<variablelist>
<varlistentry>
<term>General</term>
<listitem>
<para>The <guilabel>General</guilabel> tab lets you edit the
Relationship type. The available types (such as Married,
Unmarried, etc.) can be chosen from the drop-down
<guilabel>Relationship type</guilabel> menu. The
<guilabel>GRAMPS ID</guilabel> field displays the ID number
which labels this relationship in the database. The
<guilabel>Last changed</guilabel> label shows the last time the
relationship was modified. Finally, the Information is complete
check button indicates whether the record of this relationship
is complete or not.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Events</term>
<listitem>
<para>The <guilabel>Events</guilabel> tab lets you view and edit
events relevant to the relationship. The bottom part displays
the list of all such events stored in the database. The top part
shows the details of the currently selected event in the list
(if any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, or remove an event record from the database.
Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when an
event is selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Attributes</term>
<listitem>
<para>The <guilabel>Attributes</guilabel> tab lets you view and
edit particular information about the relationship that can be
expressed as attributes. The bottom part displays the list of
all such attributes stored in the database. The top part shows
the details of the currently selected attribute in the list (if
any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, or remove an attribute. Note that the
<guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
become available only when an attribute is selected from the
list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Notes</term>
<listitem>
<para>The <guilabel>Notes</guilabel> tab lets you view and edit
notes associated with the relationship. These could be any
comments which do not naturally fit into the "Parameter-Value"
pairs available to Attributes. To add a note or modify existing
notes simply edit the text in the text entry field.</para>
<para>The <guilabel>Format</guilabel> option lets you set the
way the note will appear in reports and web pages. If you select
Flowed, the text generated will have single spaces put in place
of all multiple spaces, tabs, and single end-of-line characters.
A blank line inserted between two blocks of text will signal a
new paragraph; additional inserted lines will be ignored.</para>
<para>If you select the Preformatted option, the text in reports
and web pages will appear exactly as you enter it in the Notes
dialog.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Sources</term>
<listitem>
<para>The <guilabel>Sources</guilabel> tab lets you view and
edit the sources which provide evidence for the relationship.
These might be documents that refer to the relationship, but
which do not necessarily document it officially. For example, if
Aunt Martha's memoirs mention that her great-grandson Paul was
married, the researcher may take this as evidence of the
relationship between Paul and his wife existed and cite the
memoirs as the source for this assumption.</para>
<note>
<para>Sources that document specific events such as marriages
or divorces are better filed in relation to those events,
under the Events tab.</para>
</note>
<para>The central part of the Sources window displays the list
of all source references associated with the relationship. The
buttons <guibutton>+</guibutton>, <guibutton>Edit</guibutton>,
and <guibutton>-</guibutton> allow let you add, modify, and
remove a source reference to this relationship. Note that the
<guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
become available only when a source reference is selected from
the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Gallery</term>
<listitem>
<para>The <guilabel>Gallery</guilabel> tab lets you store and
display photos and other media objects associated with the
relationship. The central part of the window lists all such
objects and gives you a thumbnail preview of image files. Other
objects such as audio files, movie files, etc., are represented
by a generic GRAMPS icon. The buttons <guilabel>+</guilabel>,
<guilabel>Select</guilabel>, <guilabel>Edit</guilabel>, and
<guilabel>-</guilabel> let you add a new image, add a reference
to an existing image, modify an existing image, and remove a
media object's link to the relationship. Note that the
<guilabel>Edit</guilabel> and <guilabel>-</guilabel> buttons
become available only when a media object is selected from the
list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>LDS</term>
<listitem>
<para>The <guilabel>LDS</guilabel> (Latter Days Saints) tab
displays information about the LDS <guilabel>Sealed to
Spouse</guilabel> ordinance. The data can include date, LDS
temple, and Place. The status of the ordinance can be described
through the selections available in the
<guilabel>Status</guilabel> pop-up menu and can also be
referenced in the corresponding
<guibutton>Sources...</guibutton> and
<guibutton>Note</guibutton> buttons.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-src">
<title>Editing Information About Sources</title>
<para>To edit source data, switch to the Sources View and select the
desired entry in the list of sources. Double-click that entry or click
the <guibutton>Edit</guibutton> icon on the toolbar to invoke the
following <guilabel>Source Editor</guilabel> dialog:</para>
<!-- ==== Figure: Source Editor dialog ==== -->
<figure id="edit-src-fig">
<title>Source Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-src.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Source Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The main part of the window displays four notebook tabs
containing different categories of information. Click a tab to view or
edit its contents. The bottom part of the window has
<guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> buttons.
Clicking <guibutton>OK</guibutton> will apply all the changes made in
all tabs and close the dialog window. Clicking the
<guibutton>Cancel</guibutton> button will close the window without
applying any changes.</para>
<note>
<para>Clicking <guibutton>OK</guibutton> will immediately save
changes to the database (write on disk). All changes are
immediate.</para>
</note>
<tip>
<para>If a tab label is in boldface type, this means it contains
data. If not, it has no data.</para>
</tip>
<para>The tabs provide the following information categories of source
data:</para>
<variablelist>
<varlistentry>
<term>General</term>
<listitem>
<para>The <guilabel>General</guilabel> tab lets you define basic
information about the source: its <guilabel>Title</guilabel>,
<guilabel>Author</guilabel>, <guilabel>Abbreviation</guilabel>,
and <guilabel>Publication information</guilabel>. You can type
this information directly into the adjacent fields.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Note</term>
<listitem>
<para>The <guilabel>Note</guilabel> tab provides a place to
record various information about the source that does not fit
neatly into other categories. To add a note or modify existing
notes simply edit the text in the text entry field.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Data</term>
<listitem>
<para>The <guilabel>Data</guilabel> tab displays "Key/Value"
pairs that may be associated with the source. These are similar
to the "Attributes" used for other types of GRAMPS records. The
difference between these Key/Value pairs and Attributes is that
Attributes may have source references and notes, while Key/Value
data may not.</para>
<para>The central part of the window lists all existing
Key/Value pairs. The buttons <guibutton>+</guibutton> and
<guibutton>-</guibutton> let you add and remove pairs. To modify
the text of Key or Value, first select the desired entry. Then
click in either the Key or Value cell of that entry and type
your text. When you are done, click outside the cell to exit
editing mode.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Gallery</term>
<listitem>
<para>The <guilabel>Gallery</guilabel> tab lets you store and
display photos and other media objects associated with a given
source (for example, a photo of a birth certificate). The
central part of the window lists all such media objects and
gives you a thumbnail preview of image files. Other objects such
as audio files, movie files, etc., are represented by a generic
GRAMPS icon. The buttons <guibutton>+</guibutton>,
<guibutton>Select</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> let you add a new image, add a
reference to an existing image, modify an existing image, and
remove a media object's link to the source. Note that the
<guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
become available only when a media object is selected from the
list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>References</term>
<listitem>
<para>The <guilabel>References</guilabel> tab lists all the
database records that refer to this source, if any. The list can
be ordered by any of its column headings:
<guilabel>Type</guilabel>, <guilabel>ID</guilabel>, or
<guilabel>Name</guilabel>. Double-clicking an entry allows you
to view and edit the record.</para>
<note>
<para>Only primary objects can be shown in the
<guilabel>References</guilabel> tab: Person, Family, Event,
Place, or Media object. Secondary objects such as Names and
Attributes can only be accessed through the primary objects to
which they belong.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-plc">
<title>Editing Information About Places</title>
<para>To edit information about places, switch to the Places View and
select the desired entry from the list of places. Double-click that
entry or click the <guibutton>Edit</guibutton> button on the toolbar
to bring up the following <guilabel>Place Editor</guilabel>
dialog:</para>
<!-- ==== Figure: Place Editor dialog ==== -->
<figure id="edit-plc-fig">
<title>Place Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-plc.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Place Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The main part of the window displays seven notebook tabs
containing different categories of information. Click a tab to view or
edit its contents. The bottom part of the window has
<guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> buttons.
Clicking <guibutton>OK</guibutton> will apply all the changes made in
all tabs and close the dialog window. Clicking the
<guibutton>Cancel</guibutton> button will close the window without
applying any changes.</para>
<note>
<para>Clicking <guibutton>OK</guibutton> will immediately save
changes to the database). All changes are immediate.</para>
</note>
<tip>
<para>If a tab label is in boldface type, this means it contains
data. If not, it has no data.</para>
</tip>
<para>The tabs represent following categories of place data:</para>
<variablelist>
<varlistentry>
<term>General</term>
<listitem>
<para>The <guilabel>General</guilabel> tab you view and edit the
basic information about the place: the
<guilabel>Title</guilabel> which labels it in the database,
<guilabel>City</guilabel>, <guilabel>Church parish</guilabel>,
<guilabel>County</guilabel>, <guilabel>State</guilabel>,
<guilabel>Country</guilabel>, <guilabel>Longitude</guilabel>,
and <guilabel>Latitude</guilabel>. You can type this information
directly into the adjacent fields.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Other names</term>
<listitem>
<para>The <guilabel>Other names</guilabel> tab lets you view and
edit other names by which the place might be known. The bottom
part of the window lists all other names of the place stored in
the database. The top part of the window shows the details of
the currently selected name in the list (if any). The buttons
<guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> let you add, modify, and remove a name
record. Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when a
name is selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Note</term>
<listitem>
<para>The <guilabel>Note</guilabel> tab displays any comments or
notes concerning the place. To add a note or modify existing
notes simply edit the text in the text entry field.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Sources</guilabel></term>
<listitem>
<para>The <guilabel>Sources</guilabel> tab lets you view and
edit sources relevant to a place. The central part of the window
lists all such source references stored in the database. The
buttons <guibutton>+</guibutton>, <guibutton>Edit</guibutton>,
and <guibutton>-</guibutton> let you add, modify, and remove a
source reference associated with a place. Note that the
<guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
become available only when a source reference is selected from
the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Gallery</term>
<listitem>
<para>The <guilabel>Gallery</guilabel> tab lets you store and
display photos and other media objects associated with a given
place. The central part of the window lists all such media
objects and gives you a thumbnail preview of image files. Other
objects such as audio files, movie files, etc., are represented
by a generic GRAMPS icon. The buttons <guibutton>+</guibutton>,
<guibutton>Select</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> let you add a new image, add a
reference to an existing image, modify an existing image, and
remove a media object's link to the place. Note that the
<guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
become available only when a media object is selected from the
list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Internet</term>
<listitem>
<para>The <guilabel>Internet</guilabel> tab contains Internet
addresses relevant to the place. The bottom part of the window
lists all such Internet addresses stored in the database. The
top part shows the details of the currently selected address in
the list (if any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, and remove an Internet address. The
<guibutton>Go</guibutton> button (represented by an icon with a
green arrow and yellow circle) opens your browser and takes you
to the web page corresponding to the highlighted Internet
address. Note that the <guibutton>Edit</guibutton>,
<guibutton>-</guibutton>, and <guibutton>Go</guibutton> buttons
become available only when an address is selected from the
list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>References</term>
<listitem>
<para>The <guilabel>References</guilabel> tab indicates any
database records (events or LDS ordinances) that refer to a
place. This information cannot be modified from the Place Editor
dialog. Instead, the corresponding database record (e.g., a
birth event) has to be brought up and its place reference
edited.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-media">
<title>Editing Information About Media Objects</title>
<para>To edit media data, switch to the Media View and select the
desired entry in the list of sources. Double-click on that entry or
click <guibutton>Edit</guibutton> on the toolbar to invoke the
following <guilabel>Media Properties Editor</guilabel> dialog:</para>
<!-- ==== Figure: Edit Media Properties dialog ==== -->
<figure id="edit-media-fig">
<title>Media Properties Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-media.png"
format="PNG" width="" />
</imageobject>
<textobject>
<phrase>Shows Media Properties Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>A thumbnail preview of the object is presented, along with a
summary of its properties (ID, path, and object type). The central
part of the window displays five notebook tabs containing different
categories of information. Click a tab to view or edit its contents.
The bottom part of the window has <guibutton>OK</guibutton> and
<guibutton>Cancel</guibutton> buttons. Clicking
<guibutton>OK</guibutton> will apply all the changes made in all tabs
and close the dialog window. Clicking the
<guibutton>Cancel</guibutton> button will close the window without
applying any changes.</para>
<note>
<para>Clicking <guibutton>OK</guibutton> will immediately save
changes to the database (write on disk). All changes are
immediate.</para>
</note>
<tip>
<para>If a tab label is in boldface type, this means it contains
data. If not, it has no data.</para>
</tip>
<para>The tabs represent the following categories of media
data:</para>
<variablelist>
<varlistentry>
<term>General</term>
<listitem>
<para>The <guilabel>General</guilabel> tab lets you view and
edit the object's Title and Date. You can type this information
directly into the corresponding fields. For the Date, you can
also enter information by clicking the LED button and invoking
the <guilabel>Date selection</guilabel> dialog.</para>
<note>
<para>Every media object is referred to by its Path. The user
is responsible for keeping track of the object files. GRAMPS
will only reference and display the contents, not manage the
files themselves.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Attributes</term>
<listitem>
<para>The <guilabel>Attributes</guilabel> tab lets you view and
edit particular information about the media object that can be
expressed as Attributes. The bottom part displays the list of
all such attributes stored in the database. The top part shows
the details of the currently selected attribute in the list (if
any). The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, or remove an attribute. Note that the
<guibutton>Edit</guibutton> and <guibutton>-</guibutton> buttons
become available only when an attribute is selected from the
list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Notes</term>
<listitem>
<para>The <guilabel>Note</guilabel> tab provides a place to
record various information about the source that does not fit
neatly into other categories. This area is particularly useful
for recording information that does not naturally fit into the
"Parameter/Value" pairs available to Attributes. To add a note
or modify existing notes simply edit the text in the text entry
field.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>References</term>
<listitem>
<para>The <guilabel>References</guilabel> tab indicates any
database records that refer to a given media object. The list
can be ordered according to any of its column headings:
<guilabel>Type</guilabel>, <guilabel>ID</guilabel>, or
<guilabel>Name</guilabel>. Double-clicking an entry allows you
to view and edit the corresponding record.</para>
<note>
<para>Only primary objects can be shown in the
<guilabel>References</guilabel> tab: Person, Family, Event,
Source, or Place. The secondary objects such as Names and
Attributes, although able to refer the media object, will only
show up through their primary objects to which they
belong.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-ev">
<title>Editing Information About Events</title>
<para>Events are edited through the <guilabel>Event Editor</guilabel>
dialog. This dialog can be accessed from either the <guilabel>Edit
Person</guilabel> dialog or the
<guilabel>Marriage/Relationship</guilabel> dialog.</para>
<!-- ==== Figure: Event Editor dialog ==== -->
<figure id="edit-ev-fig">
<title>Event Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-ev.png" format="PNG"
width="" />
</imageobject>
<textobject>
<phrase>Shows Event Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The central part of the window displays five notebook tabs
containing different categories of information. Click a tab to view or
edit its contents. The bottom part of the window has
<guibutton>OK</guibutton> and <guibutton>Cancel</guibutton> buttons.
Clicking <guibutton>OK</guibutton> will apply all the changes made in
all tabs and close the dialog window. Clicking the
<guibutton>Cancel</guibutton> button will close the window without
applying any changes.</para>
<tip>
<para>If a tab label is in boldface type, this means it contains
data. If not, it has no data.</para>
</tip>
<para>The tabs provide the following information categories of the
event data:</para>
<variablelist>
<varlistentry>
<term>General</term>
<listitem>
<para>The <guilabel>General</guilabel> tab lets you view and
edit basic information about the event: its
<guilabel>Type</guilabel>, <guilabel>Date</guilabel>,
<guilabel>Place</guilabel>, <guilabel>Cause</guilabel>, and
<guilabel>Description</guilabel>. You can type this information
directly into the adjacent fields. The type can be selected from
available types listed in the Event type drop-down menu. The
rest of the information can be typed in the appropriate text
entry fields. Checking the Private record box marks the event
record as private and allows it to be omitted from
reports.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Sources</term>
<listitem>
<para>The <guilabel>Sources</guilabel> tab lets you view and
edit sources relevant to an event. The central part of the
window lists all such source references stored in the database.
The buttons <guibutton>+</guibutton>,
<guibutton>Edit</guibutton>, and <guibutton>-</guibutton> let
you add, modify, and remove a source reference associated with a
place. Note that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when a
source reference is selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>Note</term>
<listitem>
<para>The <guilabel>Note</guilabel> tab provides a place to
record notes or comments about the event. To add a note or
modify existing notes simply edit the text in the text entry
field.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<!-- END OF EDIT -->
<sect2 id="adv-si">
<title>Editing Source References</title>
<para>Source references connect a Source to another object and allow
you to provide additional information about the source. When adding
source references to events, places, etc., the following dialog
appears:</para>
<!-- ==== Figure: Source Information dialog ==== -->
<figure id="edit-si-fig">
<title>Source Information dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-si.png" format="PNG"
width="" />
</imageobject>
<textobject>
<phrase>Shows Source Information dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The dialog includes two main headings, <guilabel>Source
selection</guilabel> and <guilabel>Source details</guilabel>.
<guilabel>Source selection</guilabel> displays the
<guilabel>Title</guilabel> of the Source, its
<guilabel>Author</guilabel>, and <guilabel>Publication
information</guilabel>. The <guilabel>Title</guilabel> can be selected
from the available sources listed in the drop-down menu. If the source
you are referencing is not already in the database, you can enter it
by clicking <guibutton>New...</guibutton> and filling out the invoked
<guilabel>Source Editor</guilabel> dialog.</para>
<para>The <guilabel>Source details</guilabel> section indicates the
details associated with the particular reference to this Source:
<guilabel>Confidence</guilabel>,
<guilabel>Volume/Film/Page</guilabel>, <guilabel>Date</guilabel>,
<guilabel>Text</guilabel>, and <guilabel>Comments</guilabel>. You can
choose the Confidence level from the <guilabel>Confidence</guilabel>
drop-down menu. The remaining details can be typed in the
corresponding text entry fields.</para>
<tip>
<para>Information in this dialog is specific to the particular
reference. A single source can be referenced many times, and all
such references will have in common the overall source information.
This dialog lets you provide reference-specific data, such as
relevant quotes, comments, confidence, page numbers, etc., to
further specify and document the reference.</para>
</tip>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-an">
<title>Names</title>
<para>Names are edited through the following <guilabel>Name
Editor</guilabel> dialog:</para>
<!-- ==== Figure: Names Editor dialog ==== -->
<figure id="edit-an-fig">
<title>Name Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-an.png" format="PNG"
width="" />
</imageobject>
<textobject>
<phrase>Shows Name Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The top of the window shows the dialog title including the name
of the person whose name is being edited. The central part of the
window displays three notebook tabs containing different categories of
available information. You can bring any tab to the top for viewing or
editing by clicking on the appropriate tab heading. The bottom part
has <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton>
buttons. Clicking the <guibutton>OK</guibutton> button at any time
will apply all the changes made in all tabs and close the dialog
window. Clicking the <guibutton>Cancel</guibutton> button at any time
will close the window without applying any changes.</para>
<tip>
<para>The tab labels reflect the presence of corresponding
information: if the tab contains any data, its label appears
boldface; if the tab has no data then its label appears regular (not
bold).</para>
</tip>
<para>The tabs provide the following information categories of the
name data:</para>
<variablelist>
<varlistentry>
<term><guilabel>General</guilabel></term>
<listitem>
<para>The <guilabel>General</guilabel> tab allows editing of
general information about the name: given name, family name,
patronymic (a form of father's name used in some languages, e.g.
Russian), family prefix, suffix, title, and type of the name.
The information can be typed in the appropriate text entry
fields. The family name and the type can be also selected from
available choices listed in the appropriate drop-down
menus.</para>
<para><guilabel>Options</guilabel> allow you to adjust specific
grouping, sorting, and displaying properties of this name, as
well as to provide the date corresponding to the name. The
<guilabel>Grouping</guilabel> field provides an alternative
grouping node for a given name, overriding the default grouping
based on the family name. This may be necessary with similar
family names that need to be grouped together -- for example
Russian names Ivanov and Ivanova are considered the same, but
difference in gender is reflected in different spelling. To
enable typing into this field, check the
<guilabel>Override</guilabel> check button. The <guilabel>Sort
as</guilabel> and <guilabel>Display as</guilabel> determine the
manner in which the name appears in the People View and in the
reports. The <guilabel>Date</guilabel> can provide information
on the validity of this name -- use spans as necessary. Check
the <guilabel>Private record</guilabel> box to mark this name
record as private. This will give you a chance to omit this name
from being included in reports, if you choose so among the
report generation options.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Sources</guilabel></term>
<listitem>
<para>The <guilabel>Sources</guilabel> tab displays information
about sources relevant to this name and controls allowing its
modification. The central part displays the list of all such
sources' references stored in the database. The buttons
<guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> allow you to correspondingly add,
modify, and remove a source reference to this name. Note that
the <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
buttons become available only when a source reference is
selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Note</guilabel></term>
<listitem>
<para>The <guilabel>Note</guilabel> tab displays any notes
concerning the name. To add a note or modify existing notes
simply edit the text in the text entry field.</para>
<para>The <guilabel>Format</guilabel> option allows you to set
the appearance of the note in the output (i.e. in reports and
web pages). Selecting <guilabel>Flowed</guilabel> will replace
all multiple spaces, tabs, and single end-of-line characters
with single space in the output. The two consecutive new lines
(i.e. an empty line) denote a new paragraph. Selecting
<guilabel>Preformatted</guilabel> will honor all multiple spaces
tabs, and new lines, so that the output will appear as it is
entered into the text entry field.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-at">
<title>Attributes</title>
<para>Attributes are edited through the following <guilabel>Attribute
Editor</guilabel> dialog:</para>
<!-- ==== Figure: Attribute Editor dialog ==== -->
<figure id="edit-at-fig">
<title>Attribute Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-at.png" format="PNG"
width="" />
</imageobject>
<textobject>
<phrase>Shows Attribute Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The top of the window shows the dialog title including the name
of the person whose attribute is being edited. The central part of the
window displays three notebook tabs containing different categories of
available information. You can bring any tab to the top for viewing or
editing by clicking on the appropriate tab heading. The bottom part
has <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton>
buttons. Clicking the <guibutton>OK</guibutton> button at any time
will apply all the changes made in all tabs and close the dialog
window. Clicking the <guibutton>Cancel</guibutton> button at any time
will close the window without applying any changes.</para>
<tip>
<para>The tab labels reflect the presence of corresponding
information: if the tab contains any data, its label appears
boldface; if the tab has no data then its label appears regular (not
bold).</para>
</tip>
<para>The tabs provide the following information categories of the
attribute data:</para>
<variablelist>
<varlistentry>
<term><guilabel>General</guilabel></term>
<listitem>
<para>The <guilabel>General</guilabel> tab allows editing of the
most general information about the attribute: name of the
attribute and its value. The information can be typed in the
appropriate text entry fields. The attribute name can also be
selected from available choices (if any) listed in the
<guilabel>Attribute </guilabel> drop-down menu. Check the
<guilabel>Private record</guilabel> box to mark this attribute
record as private. This will give you a chance to omit this
attribute from being included in the reports, if you choose so
among the report generation options.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Sources</guilabel></term>
<listitem>
<para>The <guilabel>Sources</guilabel> tab displays information
about sources relevant to this attribute and controls allowing
its modification. The central part displays the list of all such
sources references stored in the database. The buttons
<guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> allow you to correspondingly add,
modify, and remove a source reference to this attribute. Note
that the <guibutton>Edit</guibutton> and
<guibutton>-</guibutton> buttons become available only when a
source reference is selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Note</guilabel></term>
<listitem>
<para>The <guilabel>Note</guilabel> tab displays any notes
concerning the attribute. To add a note or modify existing notes
simply edit the text in the text entry field.</para>
<para>The <guilabel>Format</guilabel> option allows you to set
the appearance of the note in the output (i.e. in reports and
web pages). Selecting <guilabel>Flowed</guilabel> will replace
all multiple spaces, tabs, and single end-of-line characters
with single space in the output. The two consecutive new lines
(i.e. an empty line) denote a new paragraph. Selecting
<guilabel>Preformatted</guilabel> will honor all multiple spaces
tabs, and new lines, so that the output will appear as it is
entered into the text entry field.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-ad">
<title>Addresses</title>
<para>Addresses are edited through the following <guilabel>Address
Editor</guilabel> dialog:</para>
<!-- ==== Figure: Address Editor dialog ==== -->
<figure id="edit-ad-fig">
<title>Address Editor dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="" fileref="figures/edit-ad.png" format="PNG"
width="" />
</imageobject>
<textobject>
<phrase>Shows Address Editor dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The top of the window shows the dialog title including the name
of the person whose address is being edited. The central part of the
window displays three notebook tabs containing different categories of
available information. You can bring any tab to the top for viewing or
editing by clicking on the appropriate tab heading. The bottom part
has <guibutton>OK</guibutton> and <guibutton>Cancel</guibutton>
buttons. Clicking the <guibutton>OK</guibutton> button at any time
will apply all the changes made in all tabs and close the dialog
window. Clicking the <guibutton>Cancel</guibutton> button at any time
will close the window without applying any changes.</para>
<tip>
<para>The tab labels reflect the presence of corresponding
information: if the tab contains any data, its label appears
boldface; if the tab has no data then its label appears regular (not
bold).</para>
</tip>
<para>The tabs provide the following information categories of the
address data:</para>
<variablelist>
<varlistentry>
<term><guilabel>General</guilabel></term>
<listitem>
<para>The <guilabel>General</guilabel> tab allows editing of the
most general information about the address: date, street
address, city or county, state or province, country, the postal
code, and the phone number. The information can be typed in the
appropriate text entry fields. Check the <guilabel>Private
record</guilabel> box to mark this address record as private.
This will give you a chance to omit this address from being
included in reports, if you choose so among the report
generation options.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Sources</guilabel></term>
<listitem>
<para>The <guilabel>Sources</guilabel> tab displays information
about sources relevant to this address and controls allowing its
modification. The central part displays the list of all such
sources references stored in the database. The buttons
<guibutton>+</guibutton>, <guibutton>Edit</guibutton>, and
<guibutton>-</guibutton> allow you to correspondingly add,
modify, and remove a source reference to this address. Note that
the <guibutton>Edit</guibutton> and <guibutton>-</guibutton>
buttons become available only when a source reference is
selected from the list.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Note</guilabel></term>
<listitem>
<para>The <guilabel>Note</guilabel> tab displays any notes
concerning the address. To add a note or modify existing notes
simply edit the text in the text entry field.</para>
<para>The <guilabel>Format</guilabel> option allows you to set
the appearance of the note in the output (i.e. in reports and
web pages). Selecting <guilabel>Flowed</guilabel> will replace
all multiple spaces, tabs, and single end-of-line characters
with single space in the output. The two consecutive new lines
(i.e. an empty line) denote a new paragraph. Selecting
<guilabel>Preformatted</guilabel> will honor all multiple spaces
tabs, and new lines, so that the output will appear as it is
entered into the text entry field.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="adv-merge">
<title>Merging records</title>
<para>Sometime several records in the database turn out to be
describing the same object: same person, same place, or same source.
It could happen either when the data is entered twice by mistake, or
when new information reveals that the two entries refer to the same
person. It can also happen after importing GEDCOM obtained from a
relative, whose database overlaps with your existing data.</para>
<para>Whenever you detect duplicate records, merging them a useful way
of correcting the situation.</para>
<tip>
<para>To make a merge, exactly two records have to be selected in
the appropriate view (People View, Sources View, or Places View).
This is accomplished by selecting one entry and then selecting
another person while holding down <keycap>Ctrl</keycap> key.</para>
</tip>
<sect3 id="adv-merge-people">
<title>Merge People</title>
<para>There are two ways of merging personal records:
<guilabel>Compare and Merge</guilabel> and <guilabel>Fast
Merge</guilabel>, both available from the <guimenu>Edit</guimenu>
menu.</para>
<note>
<para>Merging people does not discard any information with either
method. The decisions you make during the merge only affect which
data will become primary and which will become secondary for the
resulting merged record.</para>
</note>
<variablelist>
<varlistentry>
<term><guilabel>Compare and Merge</guilabel></term>
<listitem>
<para>When exactly two people are selected, choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Compare and Merge...</guimenuitem>
</menuchoice> to invoke <guilabel>Compare People</guilabel>
dialog.</para>
<!-- ==== Figure: Compare People dialog ==== -->
<figure id="comp-people-fig">
<title>Compare People dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="469"
fileref="figures/comp-people.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows Compare People dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The dialog allows you to make a decision on whether or
not the selected records should be merged. If you decide that
the records should not be merged, despite similar names, you
may click <guibutton>Cancel</guibutton> to close the dialog
without making any changes. If you decide to proceed with
merging, select the appropriate <guilabel>Select</guilabel>
radio button to specify the record to be used as the source of
primary data, then click <guibutton>Merge and
close</guibutton>.</para>
<para>The data from the other record will be kept as alternate
data. Specifically, all names from the other record will
become alternate names of the merged record. Similarly,
parents, spouses, and children of the other record will become
alternate parents, spouses, and children of the merged record,
and so on.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Fast Merge</guilabel></term>
<listitem>
<para>When exactly two people are selected, choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Fast Merge</guimenuitem>
</menuchoice> to invoke <guilabel>Merge People</guilabel>
dialog.</para>
<!-- ==== Figure: Compare People dialog ==== -->
<figure id="merge-people-fig">
<title>Merge People dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="245"
fileref="figures/merge-people.png"
format="PNG" width="382" />
</imageobject>
<textobject>
<phrase>Shows Merge People dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The dialog allows you to quickly merge two records,
specifying the record to be used as the source of primary
data. The data from the other record will be kept as alternate
data. Specifically, all names from the other record will
become alternate names of the merged record. Similarly,
parents, spouses, and children of the other record will become
alternate parents, spouses, and children of the merged record,
and so on.</para>
<tip>
<para>If you are not certain whether or not you need to
merge the records, or which record to specify as the source
of primary data, use <guilabel>Compare and Merge</guilabel>
method described above..</para>
</tip>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<!-- ================ Usage Sub-subsection ================ -->
<sect3 id="adv-merge-sources">
<title>Merge Sources</title>
<para>When exactly two sources are selected, choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Compare and Merge...</guimenuitem>
</menuchoice> to invoke <guilabel>Merge Sources</guilabel>
dialog.</para>
<!-- ==== Figure: Merge Sources dialog ==== -->
<figure id="merge-src-fig">
<title>Merge Sources dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="224" fileref="figures/merge-src.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows Merge Sources dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The dialog allows you to make a decision on whether or not the
selected records should be merged. If you decide that the records
should not be merged, despite similar titles, you may click
<guibutton>Cancel</guibutton> to close the dialog without making any
changes. If you decide to proceed with merging, choose the
appropriate radio button to specify the title, author, abbreviated
title, publication information, and the ID to be used for the merged
record, then click <guibutton>OK</guibutton>.</para>
</sect3>
<sect3 id="adv-merge-places">
<title>Merge Places</title>
<para>When exactly two places are selected, choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Compare and Merge...</guimenuitem>
</menuchoice> to invoke <guilabel>Select title</guilabel>
dialog.</para>
<!-- ==== Figure: Select title dialog ==== -->
<figure id="merge-plc-fig">
<title>Merge Places dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="185" fileref="figures/merge-plc.png"
format="PNG" width="400" />
</imageobject>
<textobject>
<phrase>Shows Select title dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The dialog allows you to make a decision on whether or not the
selected records should be merged. If you decide that the records
should not be merged, despite similar titles, you may click
<guibutton>Cancel</guibutton> to close the dialog without making any
changes. If you decide to proceed with merging, choose the
appropriate radio button to specify the title of the merged record,
or specify <guilabel>Other</guilabel> and enter new text, then click
<guibutton>OK</guibutton>.</para>
</sect3>
</sect2>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="gramps-nav">
<title>Navigation</title>
<para>As long as any database is open, GRAMPS is focused on a single
person usually referred to as an Active person. This allows you to view
or modify the data concerning this person, his or her immediate family,
etc. Navigating in the database (i.e. moving from person to person) is
in fact nothing else but changing the Active person. This section
describes many alternative ways to navigate through the database using
both the complex and the convenient interfaces GRAMPS provides. All
these ways eventually accomplish the same thing, but some are more
convenient than others, depending what you are doing in GRAMPS at the
moment.</para>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-people">
<title>Using the People View</title>
<para>The most intuitive way to select an active person is to use the
People View (see <xref linkend="people-view" />). When in the People
View, just select the name of the desired person from the list by
clicking that list entry. The person you have selected becomes active.
The statusbar updates to reflect the change of the active
person.</para>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-family">
<title>Using the Family View</title>
<para>When in the Family View (see <xref
linkend="relationships-view" />), you can easily navigate between the
members of the displayed family as follows:</para>
<itemizedlist>
<listitem>
<para>To make the currently selected spouse the active person,
click the double-arrow button to the right of the active person
box. Alternatively, right-click into the spouse box and select
<guilabel>Make the selected spouse an active person</guilabel>
item from the context menu.</para>
</listitem>
<listitem>
<para>To make the currently selected parents the active family
(thereby making father the active person and mother the selected
spouse), click the right-arrow button to the right of the active
person's parents box. Alternatively, right-click into the active
person's parents box and select <guilabel>Make the selected
parents the active family</guilabel> item from the context
menu.</para>
</listitem>
<listitem>
<para>To make the currently selected spouse's parents the active
family (thereby making father the active person and mother the
selected spouse), click the right-arrow button to the right of the
spouse's parents box. Alternatively, right-click into the spouse's
parents box and select <guilabel>Make the selected parents the
active family</guilabel> item from the context menu.</para>
</listitem>
<listitem>
<para>To make the currently selected child the active person,
click the left-arrow button to the right of the children box.
Alternatively, right-click into the children box and select
<guilabel>Make the selected child an active person</guilabel> item
from the context menu.</para>
</listitem>
</itemizedlist>
<para>In addition to this, GRAMPS provides an extensive set of
keyboard navigation options. The detailed reference to the key
bindings is found in the <xref linkend="append-keybind" />.</para>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-pedigree">
<title>Using the Pedigree View</title>
<para>The Pedigree View (see <xref linkend="pedigree-view" />) also
allows you to move along the family tree. The benefit of this method
is that you can see more than one generation of the family tree. Also,
you can jump directly from a great-grandson to a great-grandfather
without going through the intermediate generations.</para>
<para>Note that after changing the active person in the Pedigree View,
the display is re-adjusted to show four generations, starting from the
newly selected Active person. When in the Pedigree View, you can
easily navigate between the members of the displayed family tree as
follows:</para>
<itemizedlist>
<listitem>
<para>To make any displayed person the active person, double-click
the line that connects to the left side of the corresponding
box.</para>
</listitem>
<listitem>
<para>To make a child of the currently active person (if any) the
active person, click the left arrow button to the left of the
corresponding box. If there is more than one child, the button
expands to the menu listing the children to choose from.</para>
</listitem>
<listitem>
<para>To move the whole family tree one generation back, click on
the corresponding right arrow button on the right-hand side of the
display area. Clicking the upper button will move the tree along
the paternal line. Clicking the lower button will move the tree
along the maternal line.</para>
<para>Clicking either of these buttons is completely equivalent to
double-clicking the lines connecting to the left of the
corresponding boxes for father and mother.</para>
</listitem>
</itemizedlist>
<para>You can also quickly access any of the spouses, siblings,
children, or parents of any displayed person. To do this, move the
mouse over the desired person's box and right-click to invoke a
context menu. The appropriate menu items will contain submenus listing
all spouses, siblings, children, and parents of the corresponding
person.</para>
<tip>
<title>Advantages of using right-click menus</title>
<itemizedlist>
<listitem>
<para>Direct access to spouse and siblings</para>
</listitem>
<listitem>
<para>Complete lists of all member of all categories, not only
the preferred members.</para>
</listitem>
</itemizedlist>
</tip>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-default">
<title>Setting the Home Person</title>
<para>One and only one person in the database can be selected as the
Home person. Once the Home person is selected, moving to that person
becomes a matter of a single click, regardless of which view you are
using at the moment.</para>
<para>To set the Home person, first navigate to that person using any
method you like. Then choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Set Home person</guimenuitem>
</menuchoice>. Once this is done, you can move to the Home person
from anywhere in the database by simply clicking the
<guibutton>Home</guibutton> icon on the toolbar. You can also choose
<menuchoice>
<guimenu>Go</guimenu>
<guimenuitem>Home</guimenuitem>
</menuchoice> from the menu or select <guilabel>Home</guilabel> item
from any context menu available on the right click.</para>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-history">
<title>Using history-based tools</title>
<para>GRAMPS also features a powerful set of history-based navigation
tools. These tools are similar to those commonly used in web browsers.
They include <guilabel>Back</guilabel> and
<guilabel>Forward</guilabel> items available from the <menuchoice>
<guimenu>Go</guimenu>
</menuchoice> menu, context menus (available in People, Family, and
Pedigree views), and the toolbar buttons. They also include the list
of the recent selections available under the <menuchoice>
<guimenu>Go</guimenu>
</menuchoice> menu that allows you to jump directly to any of the
recent selections. Finally, right-clicking on the
<guibutton>Back</guibutton> and <guibutton>Forward</guibutton> toolbar
buttons invokes the popup menu with corresponding portion of the
history. Select any item from the menu to jump directly to it.</para>
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-bookmk">
<title>Bookmarking People</title>
<para>Similar to setting the Home person, you can bookmark other
people from the database to simplify further navigation. To bookmark a
person, first navigate to that person, then choose <menuchoice>
<guimenu>Bookmarks</guimenu>
<guimenuitem>Add bookmark</guimenuitem>
</menuchoice>. To move to that person from anywhere in the database,
choose <menuchoice>
<guimenu>Bookmarks</guimenu>
<guisubmenu>Go to bookmark</guisubmenu>
<guimenuitem><replaceable>Person's
name</replaceable></guimenuitem>
</menuchoice>.</para>
<para>You can manage your bookmarks by choosing <menuchoice>
<guimenu>Bookmarks</guimenu>
<guimenuitem>Edit bookmarks...</guimenuitem>
</menuchoice>. This opens the following <guilabel>Edit
Bookmarks</guilabel> dialog with the list of bookmarks and the
controls to modify this list.</para>
<!-- ==== Figure: Edit Bookmarks dialog ==== -->
<figure id="edit-bm-fig">
<title>Edit Bookmarks dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="376" fileref="figures/edit-bm.png"
format="PNG" width="412" />
</imageobject>
<textobject>
<phrase>Shows Edit Bookmarks dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</sect2>
<!-- ================ Usage Sub-subsection ================ -->
<sect2 id="gramps-nav-find">
<title>Finding records</title>
<para>To find a record in a database, first switch to the appropriate
View that provides the list of the desired records: People, Sources,
Places, or Media. Then start typing the name of a person or the title
of a Source, Place, or Media object that you are looking for,
respectively. You may also press <keycap>Ctrl+F</keycap> to turn on
the search mode, but simply staring to type is also enough.</para>
<!-- ==== Figure: Type-ahead find ==== -->
<figure id="find-people-fig">
<title>Type-ahead find</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="352" fileref="figures/find-people.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows type-ahead find.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>As you type, the first record in the list that is compatible
with your input will be selected.</para>
<tip>
<title>Finding People</title>
<para>For more complex people searches you may want to use filters.
Enable filter controls by choosing <menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Filter</guimenuitem>
</menuchoice>, select the desired filter, and click
<guibutton>Apply</guibutton>. For details, see <xref
linkend="filters" /></para>
</tip>
</sect2>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="gen-reports">
<title>Generating Reports</title>
<para>Reports are the most common form of the output produced by
genealogical research. The majority of genealogical software puts a lot
of emphasis on developing nice looking reports. GRAMPS is no exception
in this regard, offering a choice of a variety of reports. GRAMPS can
generate reports in a multitude of open formats, both text based and
graphical. GRAMPS can also produce screen based reports that are
convenient for viewing a summary of your database. Finally, GRAMPS can
generate a web site suitable for immediate posting on the Internet. All
of these are almost infinitely flexible. If you wish to modify or extend
the default format of GRAMPS report, you can design and choose the style
for each of your reports.</para>
<para>All reports can be accessed through the menu by choosing
<menuchoice>
<guimenu>Reports</guimenu>
<guisubmenu><replaceable>Report Type</replaceable></guisubmenu>
<guimenuitem><replaceable>Particular
Report</replaceable></guimenuitem>
</menuchoice>. Alternatively, you can browse the complete selection of
available reports along with their brief descriptions in a
<guilabel>Report Selection</guilabel> dialog invoked by clicking the
<guibutton>Reports</guibutton> icon on the toolbar.</para>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="subst-values">
<title>Substitution Values</title>
<para>Many of the graphical reports allow you to customize the
information on the display. Variable substituions are used to
substitute date for a particular symbol. There are two styles of
variables. The difference between the two styles is how empty data is
handled.</para>
<para>The first style of variables are preceeded by a '$'. If the
variable evaluates to an empty string, the variable is replaced with
the empty string. The second style of variables are preceeded by a
'%'. If the variable evaluates to an empty string, the line that
contains the variable is removed from the output.</para>
<variablelist>
<varlistentry>
<term>$n/%n</term>
<listitem>
<para>Displays the person's name in the form of FirstName
LastName</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$N/%N</term>
<listitem>
<para>Displays the person's name in the form of LastName,
FirstName</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$i/%i</term>
<listitem>
<para>Displays the GRAMPS ID associated with the person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$b/%b</term>
<listitem>
<para>Displays the person's date of birth</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$B/%B</term>
<listitem>
<para>Displays the person's place of birth</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$d/%d</term>
<listitem>
<para>Displays the person's date of death</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$D/%D</term>
<listitem>
<para>Displays the person's place of death</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$s/%s</term>
<listitem>
<para>Displays the name of the person's preferred spouse in the
form of FirstName LastName</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$S/%S</term>
<listitem>
<para>Displays the name of the person's preferred spouse in the
form of LastName, FirstName.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$m/%m</term>
<listitem>
<para>Displays the marriage date of the person and the preferred
spouse.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$M/%M</term>
<listitem>
<para>Displays the place assocated with the marriage of the
person and the preferred spouse.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="rep-books">
<title>Books</title>
<para>Currently, the only available report under this category is the
Book Report.</para>
<para>The Book Report creates a single document (i.e. a Book)
containing a collection of graphical and textual reports.
Consequently, this allows for a very rich set of documents that GRAMPS
can produce.</para>
<para>When Book Report is selected, the following book configuration
dialog appears:</para>
<!-- ==== Figure: Book Report dialog ==== -->
<figure id="rep-book-fig">
<title>Book Report dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="524" fileref="figures/bookreport.png"
format="PNG" width="510" />
</imageobject>
<textobject>
<phrase>Shows Book Report dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The <guilabel>Book name</guilabel> text entry field is used to
save the book (a set of configured selections) for future use. The top
pane lists the items available for inclusion in the book. The bottom
pane lists the currently selected items in the order they will appear
in the book.</para>
<para>The horizontal set of buttons by the <guilabel>Book
name</guilabel> field operates on the whole book. Click the
<guibutton>Clear</guibutton> button to clear all items from the
current book. Click the <guibutton>Save</guibutton> button to save the
current book (under the name typed in the <guilabel>Book
name</guilabel> text entry field) for future use.</para>
<tip>
<para>Saving the book also saves the configuration for each
item.</para>
</tip>
<para>Click the <guibutton>Open</guibutton> button to load the book
from the list of previously saved books. Finally, click the
<guibutton>Edit books</guibutton> button to invoke the editable list
of available books.</para>
<para>The vertical set of buttons to the right of the bottom pane
operates on the selected book item. Click the
<guibutton>Add</guibutton> button to add selected item from the
available list to the current book. Click the
<guibutton>Remove</guibutton> button to remove an item from the
current book. Use <guibutton>Up</guibutton> and
<guibutton>Down</guibutton> to change the items order in the current
book. Click the <guibutton>Setup</guibutton> button to configure the
options of the selected item of the current book.</para>
<para>The configuration dialogs invoked by
<guibutton>Setup</guibutton> are item-specific. If you choose not to
configure the item, same defaults will be used for all needed options.
The common option for almost all book items is the center person: the
person on whom the item is centered. Thanks to this option, you can
create a book with items centered on different people (e.g. your mom's
and dad's ancestors as separate chapters). By default, the center
person is set to the active person.</para>
<para>Almost all items available for inclusion in the book are textual
or graphical reports, and are therefore available in the form of
standalone reports. The exception is the following items which are
only available as book items:</para>
<variablelist>
<varlistentry>
<term>Title Page</term>
<listitem>
<para>This item produces a customized Title page. You can
configure the text of title, subtitle, and the footer of the
page. An image can be optionally placed between the subtitle and
the footer. Because of its configurability, this item can be
used to create title pages for the whole book, its chapter, or
even a single item.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Custom Text</term>
<listitem>
<para>This item produces a page with three paragraphs, each
containing custom text. The appearance of the text can be
adjusted by using custom styles. This item was meant to be used
for epigraphs, dedications, explanations, notes, and so
forth.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="rep-codegen">
<title>Code Generators</title>
<para>This category contains reports that produce code intended to be
run through the computer, rather than the usual formatted output for
human reading. The only code generator currently available in GRAMPS
is the Relationship Graph producing the GraphViz description of the
graph.</para>
<para>The Relationship Graph creates a complex relationship graph in
GraphViz format. The GraphViz <command>dot</command> tool can
transform the graph into postscript, jpeg, png, vrml, svg, and other
formats. GraphViz tools are freely available from the <ulink
type="http" url="http://www.graphviz.org">GraphViz site</ulink>.
Specific options for this report include filter and number of
generations considered, as well as several GraphViz-specific options
related to pagination, color, and details of the graph.</para>
<tip>
<para>If you are not interested in GraphViz code itself and just
want to generate graphical output, GRAMPS can do it for you under
the hood. Look for <guilabel>Relationship Graph</guilabel> in the
Graphical Reports category, <xref linkend="rep-graph" /></para>
</tip>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="rep-graph">
<title>Graphical Reports</title>
<para>Graphical reports represent information in forms of charts and
graphs. Most of the options are common among graphical reports,
therefore they will be described only once, at the end of this
section. The few options which are specific to a given report will be
described directly in that report's entry.</para>
<para>The following graphical reports are currently available in
GRAMPS:</para>
<variablelist>
<varlistentry>
<term>Ancestor Chart</term>
<listitem>
<para>This report generates the chart of people who are
ancestors of the Active person. Specific options include the
number of generations considered and the format of the displayed
entries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Ancestor Chart (Wall Chart)</term>
<listitem>
<para>This report is similar to the Ancestor Chart report. It
provides more options which make it useful for generating huge
charts suitable for a poster or a wall chart. These options
include the ability to compress the report (getting rid of an
empty space) and the option to fit the whole chart on to a
single page. In the latter case, the contents of the chart is
scaled down appropriately.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Descendant Graph</term>
<listitem>
<para>This report generates a graph of people who are
descendants of the Active person. Specific options include the
format of the displayed entries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Fan Chart</term>
<listitem>
<para>This report produces a chart resembling a fan, with Active
person in the center, parents the the semicircle next to it,
grandparents in the next semicircle, and so on, for a total of
five generations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Relationship Graph</term>
<listitem>
<para>This report creates a complex relationship graph in
GraphViz format and then converts into graphical output running
it through the the GraphViz <command>dot</command> tool behind
the scene. Specific options for this report include filter,
options for dates and places for the events, and whether to
include URLs and IDs for individuals and families. There are
also several GraphViz-specific options related to pagination,
color, and details of the graph.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Statistics Chart</term>
<listitem>
<para>This report can collect and display a wealth of
statistical data about your database. Specific options include
filter, sorting methods, and additional birth- and gender-based
limit for inclusion into statistics. You can also set the
minimum number of items to qualify for the bar chart, so that
the charts with fewer items will generate a pie chart instead.
The <guilabel>Chart Selection</guilabel> tab allows you to check
which charts you want to include in your report.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Timeline Graph</term>
<listitem>
<para>This report outputs the list of people with their
lifetimes represented by intervals on a common chronological
scale. Specific options include filter, sorting method, and the
title of the report.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Common options for graphical reports are the filename of the
output, the format of the output, selected style, page size and
orientation. Optionally, the reports can be immediately opened with
the default application.</para>
<tip>
<para>The options used in reports are persistent: each report
remembers its options used last time.</para>
</tip>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="rep-text">
<title>Text Reports</title>
<para>Text reports represent the desired information as formatted
text. Most of the options are common among text reports, therefore
they will be described only once, at the end of this section. The
options which are specific to a given report will be described
directly in that report's entry.</para>
<para>The following text reports are currently available in
GRAMPS:</para>
<variablelist>
<varlistentry>
<term>Ahnentafel Report</term>
<listitem>
<para>This report lists the active person and his or her
ancestors along with their vital data. The people are numbered
in a special way which is an established standard called
Ahnentafel. The active person is given number 1. His or her
father and mother have numbers 2 and 3, respectively. This rule
holds for every person while going back in generations: father's
parents are numbered 4 and 5, and mother's parents are numbered
6 and 7, fathers always numbered with even and mothers with odd
numbers. Therefore, for any person having number N in this tree,
the numbers of father and mother are 2N and 2N+1,
respectively.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Complete Individual Report</term>
<listitem>
<para>This report provides individual summaries similar to that
of the Individual Summary report. The advantage of this report
is the specific filter option. Depending on the filter choice
(active person only, his or her descendants, his or her
ancestors, or entire database), the report may contain from one
to many individual summaries. Another option for this report is
the inclusion of source information when listing events.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Comprehensive Ancestors Report</term>
<listitem>
<para>This report produces a comprehensive description of
ancestors of the active person. The highlights of this report
include elaborate layout, images of children, present and former
spouses, and source citations. Specific options: number of
backward generations to consider, whether to cite sources, and
whether to break pages between generations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Descendant Report</term>
<listitem>
<para>This report produces a brief description of descendants of
the active person. Specific options: number of forward
generations to consider.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Detailed Ancestral Report</term>
<listitem>
<para>This report covers in detail the ancestors of the active
person. It includes vital data (birth and death) as well as
marriages. Specific options: number of backward generations to
consider, as well as a variety of options regarding the exact
contents to include.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Detailed Descendant Report</term>
<listitem>
<para>This report covers in detail the descendants of the active
person. It includes vital (birth and death) information as well
as marriages. Specific options: number of forward generations to
consider.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FTM Style Ancestral Report</term>
<listitem>
<para>This report creates an ancestral report similar to that
produced by the Family Tree Maker (tm) program. It covers in
detail the active person and his/her ancestors It includes vital
information as well as marriages, children, and notes. Specific
options: number of backward generations to consider.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FTM Style Descendant Report</term>
<listitem>
<para>This report creates a descendant report similar to that
produced by the Family Tree Maker (tm) program. It covers in
detail the active person and his/her descendants. It includes
vital information as well as marriages, children, and notes.
Specific options: number of forward generations to
consider.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Family Group Report</term>
<listitem>
<para>This creates a family group report, showing information on
a set of parents and their children. Specific options: the
spouse (available only if the active person has more than one
spouse).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Individual Summary</term>
<listitem>
<para>This report produces a detailed summary on the active
person. The report includes all the facts known to the database
about that person.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Common options for text reports are the filename of the output,
the format of the output, selected style, page size and orientation.
For HTML reports, there is no page information. Instead, HTML options
include the choice of the HTML template, either available in GRAMPS or
a custom template defined by you. Optionally, the reports can be
immediately opened with the default application.</para>
<tip>
<para>The options used in reports are persistent: each report
remembers its options used last time.</para>
</tip>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="rep-view">
<title>View Reports</title>
<para>View reports are representing overall summaries of the database
information available immediately for on-screen viewing. The following
view reports are currently available in GRAMPS:</para>
<variablelist>
<varlistentry>
<term>Number of ancestors</term>
<listitem>
<para>This report displays the number of ancestors of the active
person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Summary of the database</term>
<listitem>
<para>This report displays the overall statistics concerning
number of individuals of each gender, various incomplete entries
statistics, as well as family and media statistics.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="rep-web">
<title>Web Page</title>
<para>The only available report in this category is the Narrative Web
Site report. It generates a web site (that is, a set of linked web
pages), for a set of selected individuals.</para>
<sect3 id="rep-web-narr">
<title>Narrative Web Site</title>
<variablelist>
<varlistentry>
<term>Introduction</term>
<listitem>
<para>GRAMPS 2.0.6 introduced the Narrative Web generator. The
new tool provides considerably more functionality than the
older web generator. Instead of using HTML templates to
customize the pages, CSS style sheets are used.</para>
<para>More information is now displayed about each person,
along with information about sources, places, and media
objects. Introduction pages can be added to provide additional
information, such as family history.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Selecting the output</term>
<listitem>
<para>Genealogy records can generate a lot of files. Many web
servers have a difficult time with many files in a single
directory. The Narrative Web Generator strives to keep the
number of files per directory to a managable level. To do
this, a hierarchy of directores is created. The generated
files names are not intuitive, but are unique per person.
Subsequent runs will geneate identical file names, making it
easy to replace files.</para>
<para>By default, the output files are written to the
specified directory. Because of the number of files and
directories that are created, it may be difficult to transfer
the files to an external web host. To aid in this, you may
directly create a gzip'd tar file to more easily upload the
data. This is the format that should be used if you would like
to take advantage of the free genealogy page hosting at the
<ulink type="http"
url="http://family.gramps-project.org">GRAMPS web hosting
site</ulink>.</para>
<para>To select the gzip'd tar file, select the
<guilabel>Store web pages in .tar.gz archive</guilabel>
option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Applying a filter</term>
<listitem>
<para>Like the previous web page generator, and most of the
other GRAMPS reports, you can control what is included in the
output by choosing a filter. Several default filters are
provided for you, but you are free to use the Custom Filter
Editor tool to create your own.</para>
<para>Any person matching this filter who is not excluded due
to the privacy rules, will be included in the output. The
default filter includes all people in the database.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Applying a style sheet</term>
<listitem>
<para>GRAMPS provides six built in style sheets for your web
page. Each of these style sheets produces a unique look for
your pages. The generated style sheet is named
<filename>narrative.css</filename>. You may edit this file if
you wish to further customize your site.</para>
<para>If you make modifications to your style sheet, you need
to be aware the regenerating the pages with the same output
directory will overwrite your changes to this file. To prevent
this from happening, make sure you choose <guilabel>No style
sheet</guilabel> for subsequent runs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Character set encoding</term>
<listitem>
<para>Because of GRAMPS internationalization ability, the
default character set for the HTML pages is UTF-8. This
provides support for virtually all characters.</para>
<para>The Apache web server is sometimes misconfigured to
override the character set specified in an HTML page. This
causes problems with the UTF-8 character set generated by
GRAMPS, distorting characters on the screen.</para>
<para>If your web server is misconfigured and you do not have
priveledge to fix the configururation, you may solve this
problem by overriding the default character set to match what
your web server may be expecting.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Copyright notice</term>
<listitem>
<para>International copyright law reserves all rights to your
data. You own the data, and people must get your permission to
use it. In genealogy, however, sharing data is a common ideal.
It this case, you may wish to grant the user more
rights.</para>
<para>While the default for GRAMPS is to place a notice
indicating that all rights are reserved, we give you the
option to place your site under one of several of the Create
Commons licenses. With a Creative Commons license, you grant
user's certain permission to use your data without requiring
them to contact you directly for permission.</para>
<para>See the <ulink type="http"
url="http://creativecommons.org/">Creative Commons</ulink> web
site for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Controlling page generation</term>
<listitem>
<para>Three additional pages can be generated by the web page
generator. The Home page is a page that will display an image
and a whatever text you wish. To enable this page, choose a
Media Object from the <guilabel>Home Media/Note ID</guilabel>
menu on the <guilabel>Page Generation</guilabel> tab. If the
Media Object contains an image, the image is displayed at the
top of the page. If the Media Object contains a Note, the
Note's text is used for the text of the page. A second page,
the Introduction page, works similarly. Just choose the Media
Object in the <guilabel>Introduction Media/Note ID</guilabel>
menu.</para>
<para>If you choose to include a contact page, the researcher
information stored in the database is displayed, along with
the information specified in the <guilabel>Publisher
contact/Note ID</guilabel> menu. Please use this page with
caution, since you may consider your contact information to be
private.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Privacy</term>
<listitem>
<para>Privacy of personal information is an important issue on
the web today. GRAMPS tries to give you control over the
information that is presented.</para>
<para>GRAMPS provides two options to control the privacy of
your information. If you select the <guilabel>Do not include
records marked private</guilabel> option, any data that is
marked as private will not be displayed on the generated site.
If you select <guilabel>Restrict information on living
people</guilabel>, GRAMPS will attempt to determine which
people have the potential of still being alive, and will omit
these people from the database. Some countries have laws that
indicate that a certain number of years must pass after
someone's death before information can be published. The
<guilabel>Years to restrict from person's death</guilabel>
option allows you to specifiy how many years a person must be
deceased before the information is included.</para>
<para>Please note that it is your responsibility to double
check all information in the pages for any privacy
information. GRAMPS cannot be held responsible for any privacy
issues.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Adding custom code your pages</term>
<listitem>
<para>If you are not interested in customizing your pages, you
may skip the section.</para>
<para>The previous web generator allowed you to customize your
pages using HTML templates. Your data would be substituted for
certain markers in the code.</para>
<para>This method proved to be too cumbersome for most users.
The Narrative Web Page Generator introduces a simpler
mechanism. On the <guilabel>Page Generation</guilabel> tab,
you may specify text (including HTML code) that will be
inserted into each page, separately for the header and the
footer.</para>
<para>To create this code, you need to create a Media Object
marked as an internal note. To create this, add a new Media
Object in the Media View, and select the internal note option.
You may then enter your HTML code.</para>
<para>To insert the code from the internal notes into the web
pages, select the appropriate Media Objects from the
<guilabel>HTML user header</guilabel> and <guilabel>HTML user
footer</guilabel> menus. Two div sections will be added to the
pages - userheader and userfooter. The corresponding HTML code
is inserted into the HTML page surrounded by div markers. You
can customize your style sheet to provide additional
formatting and positioning information to control these
sections.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
</sect1>
<!-- ================ Usage Subsection ================================ -->
<sect1 id="gramps-tools">
<title>Running Tools</title>
<para>GRAMPS tools allow you to perform various types of analysis of
your genealogical data. Typically, the tools do not produce output in
form of printouts or files. Instead, they produce screen output
immediately available for the researcher. However, when appropriate, you
can save the results of running a tool into a file. Tools present one of
the major strengths of GRAMPS compared to the most genealogical
software.</para>
<para>The tools can be accessed through the menu by choosing <menuchoice>
<guimenu>Tools</guimenu>
<guisubmenu><replaceable>Tool Section</replaceable></guisubmenu>
<guimenuitem><replaceable>Particular
Tool</replaceable></guimenuitem>
</menuchoice>. Alternatively, you can browse the complete selection of
available tools along with their brief descriptions in a <guilabel>Tool
Selection</guilabel> dialog invoked by clicking the
<guibutton>Tools</guibutton> icon on the toolbar.</para>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="tools-ae">
<title>Analysis and Exploration</title>
<para>This section contains tools which analyze and explore the
database, but do not alter it. The following analysis and exploration
tools are currently available in GRAMPS:</para>
<variablelist>
<varlistentry>
<term>Compare individual events</term>
<listitem>
<para>This tool compares events across the selected group of
people. The people for this comparison are chosen with the use
of custom filters. The custom filters can be created in the
Custom Filter Editor (see <xref linkend="tools-util-cfe" />)
that can be invoked by clicking the <guilabel>Custom Filter
Editor</guilabel> button. The resulting table produced by this
tool can be saved as a spreadsheet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Interactive descendant browser</term>
<listitem>
<para>This tool builds a tree with the active person being the
root. Children branch from their parents in the usual manner.
Use this tool for a quick glance of a person's
descendants.</para>
<tip>
<para>Double-clicking on tree node will bring up the
<guilabel>Edit Person</guilabel> dialog allowing to view or
modify the personal data.</para>
</tip>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="tools-db">
<title>Database Processing</title>
<para>This section contains tools which may modify your database. The
tools from this section are used mostly for finding and correcting
errors in the data. The following database processing tools are
currently available in GRAMPS:</para>
<note>
<para>The modifications will only be performed upon your explicit
consent, except for the automatic fixes performed by <guilabel>Check
and repair database</guilabel> tool.</para>
</note>
<variablelist>
<varlistentry>
<term>Check and repair database</term>
<listitem>
<para>This tool checks the database for integrity problems,
fixing the problems it can. Specifically, the tool is checking
for:</para>
<itemizedlist>
<listitem>
<para>Broken family links. These are the cases when a
person's record refers to a family while the family's record
does not refer to that person, and vice versa.</para>
</listitem>
<listitem>
<para>Missing media objects. The missing media object is the
object whose file is referenced in the database but does not
exist. This can happen when the file is accidentally
deleted, renamed, or moved to another location.</para>
</listitem>
<listitem>
<para>Empty families. These are the family entries which
have no reference to any person as their member.</para>
</listitem>
<listitem>
<para>Parent relationship. This checks all families to
ensure that father and mother are not mixed up. The check is
also made that parents have different gender. If they have
common gender then their relationship is renamed to
"Partners".</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Extract information from names</term>
<listitem>
<para>This tool searches the entire database and attempts to
extract titles and nicknames that may be embedded in a person's
<guilabel>Given name</guilabel> field. If any information could
be extracted, the candidates for fixing will be presented in the
table. You may then decide which to repair as suggested and
which not to.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Find possible duplicate people</term>
<listitem>
<para>This tool searches the entire database, looking for the
entries that may represent the same person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Fix capitalization of family names</term>
<listitem>
<para>This tool searches the entire database and attempts to fix
the capitalization of family names. The aim is to have
conventional capitalization: capital first letter and lower case
for the rest of the family name. If deviations from this rule
are detected, the candidates for fixing will be presented in the
table. You may then decide which to repair as suggested and
which not to.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Rename personal event types</term>
<listitem>
<para>This tool allows all the events of a certain name to be
renamed to a new name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Reorder GRAMPS IDs</term>
<listitem>
<para>This tool reorders the GRAMPS IDs according to the
defaults of GRAMPS.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="tools-debug">
<title>Debug</title>
<para>This section contains debugging tools that are not of general
interest for many of the users of GRAMPS. If you're not interested in
debugging or developing GRAMPS you may safely skip this
section.</para>
<variablelist>
<varlistentry>
<term>Python evaluation window</term>
<listitem>
<para>Enter expression into the <guilabel>Evaluation
Window</guilabel>, get the output in <guilabel>Output
Window</guilabel>. Any errors should end up in the
<guilabel>Error Window</guilabel>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Reload plugins</term>
<listitem>
<para>Makes an attempt to reload all plugins.</para>
<note>
<para>This tool is itself a plugin, but it will not reload
itself!</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>Show uncollected objects</term>
<listitem>
<para>Provides the window listing all uncollected objects.
Depending on the system settings, recently abandoned GUI objects
may still be uncollected.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!-- =============== Usage Sub-subsection ================ -->
<sect2 id="tools-util">
<title>Utilities</title>
<para>This section contains tools allowing you to perform a simple
operation on a portion of data. The results can be saved in your
database, but they will not modify your existing data. The following
utilities are currently available in GRAMPS:</para>
<sect3 id="tools-util-cfe">
<title>Custom Filter Editor</title>
<para>The Custom Filter Editor builds custom filters that can be
used to select people included in reports, exports, and other tools
and utilities. This is in fact a very powerful tool in genealogical
analysis.</para>
<para>When you launch it, the <guilabel>User defined
filters</guilabel> dialog appears that lists all the filters (if
any) previously defined by you. Click the
<guibutton>Add...</guibutton> button to define a new filter. Once
you have designed your filters, you can edit, test, and delete
selected filters using the <guibutton>Edit...</guibutton>,
<guibutton>Test...</guibutton>, and <guibutton>Delete</guibutton>
buttons, respectively. All the filters displayed in the list will be
automatically saved along with your database and will be available
with subsequent sessions of GRAMPS.</para>
<note>
<para>The changes made to the filters only take effect when you
click the <guibutton>Apply and close</guibutton> button.</para>
</note>
<para>Clicking the <guibutton>Add...</guibutton> button invokes the
following <guilabel>Define filter</guilabel> dialog:</para>
<!-- ==== Figure: Define filter dialog ==== -->
<figure id="cfe-df-fig">
<title>Define filter dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="410" fileref="figures/cfe-df.png"
format="PNG" width="400" />
</imageobject>
<textobject>
<phrase>Shows Define filter dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>Type the name for your new filter into the
<guilabel>Name</guilabel> field. Enter any comment that would help
you identify this filter in the future into the
<guilabel>Comment</guilabel> field. Add as many rules to the
<guilabel>Rule list</guilabel> as you would like to your filter
using <guibutton>Add...</guibutton> button. If the filter has more
than one rule, select one of the <guilabel>Rule
operations</guilabel>. This allows you to choose whether all rules
must apply, only one (either) rule must apply, or exactly one
(either) rule must apply, in order for the filter to generate a
match. If your filter has only one rule, this selection has no
effect.</para>
<para>Check <guilabel>Return values that do not match the filter
rules</guilabel> to invert the filter rule. For example, inverting
"has a common ancestor with I1" rule will match everyone who does
not have a common ancestor with that person).</para>
<para>Clicking the <guibutton>Add...</guibutton> button invokes the
following <guilabel>Add Rule</guilabel> dialog:</para>
<!-- ==== Figure: Add Rule dialog ==== -->
<figure id="cfe-ar-fig">
<title>Add Rule dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="297" fileref="figures/cfe-ar.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows Add Rule dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The pane on the left-hand side displays available filter rules
arranged by their categories in an expandable tree. For detailed
filter rule reference, see <xref linkend="append-filtref" />. Click
on the arrows to fold/unfold the appropriate category. Select the
rule from the tree by clicking on its name. The right-hand side
displays the name, the description, and the values for the currently
selected rule. Once you are satisfied with your rule selection and
its values, click <guibutton>OK</guibutton> to add this rule to the
rule list of the currently edited filter. Clicking
<guibutton>Cancel</guibutton> will abort adding the rule to the
filter.</para>
<tip>
<para>A filter you have already designed may be used as a rule for
another filter. This gives you nearly infinite flexibility in
custom-tailoring your selection criteria that can be later used in
most of the exports, reports, and some of the tools (such as
comparing individual events).</para>
</tip>
</sect3>
<sect3 id="tools-util-scratch-pad">
<title>Scratch Pad</title>
<para>This tool provides a temporary note pad to store database
records for easy reuse. In short, this is a sort of the
copy-and-paste functionality extended from textual objects to other
types of records used in GRAMPS.</para>
<tip>
<para>Scratch Pad makes extensive use of drag-and-drop
technique.</para>
</tip>
<para>To invoke Scratch Pad, either choose <menuchoice>
<guimenu>Tools</guimenu>
<guisubmenu>Utilities</guisubmenu>
<guimenuitem>Scratch Pad</guimenuitem>
</menuchoice> or click the <guilabel>ScratchPad</guilabel> button
on the toolbar. The following window will appear:</para>
<!-- ==== Figure: Scratch Pad tool ==== -->
<figure id="scratch-pad-fig">
<title>Scratch Pad tool</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata depth="246" fileref="figures/scratch-pad.png"
format="PNG" width="500" />
</imageobject>
<textobject>
<phrase>Shows Add Scratch Pad tool.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>Scratch Pad supports addresses, attributes (both personal and
family), events (both personal and family), names, media objects
references, source references, URLs, and of course textual
information of notes and comments. To store any type of these
records, simply drag the existing record on to the Scratch Pad from
the corresponding editor dialog. To reuse the record, drag it from
the Scratch Pad on to the corresponding place in the editor, e.g.
Address tab, Attribute tab, etc.</para>
<tip>
<para>Some objects are showing the link icon on the left. This
indicates that dragging such selection will produce a reference to
an existing object, not copy the object itself.</para>
<para>For example, the media object file will not be duplicated.
Instead, the reference will be made to an existing media object,
which will result in the local gallery entry.</para>
</tip>
<tip>
<para>Scratch Pad storage is persistent within a single GRAMPS
session. Closing the window will not lose the stored records.
However, exiting GRAMPS will.</para>
</tip>
</sect3>
<sect3 id="tools-util-other">
<title>Other tools</title>
<variablelist>
<varlistentry>
<term>Generate SoundEx codes</term>
<listitem>
<para>This utility generates SoundEx codes for the names of
people in the database. Please visit the <ulink type="http"
url="http://www.archives.gov/research_room/genealogy/census/soundex.html">NARA
Soundex Indexing page</ulink> to learn more about Soundex
Indexing System.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Relationship calculator</term>
<listitem>
<para>This utility calculates and displays the relationship of
any person to the active person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Verify the database</term>
<listitem>
<para>This utility allows you to verify the database based on
the set of criteria specified by you.</para>
<tip>
<title>Difference between Verify tool and previously
described Check tool</title>
<para>The Check tool detects inconsistencies in the database
structure. The Verify tool, however, is detecting the
records that do not satisfy your particular criteria.</para>
</tip>
<para>For example, you may want to make sure that nobody in
your database had children at the age of 98. Based on common
sense, such a record would indicate an error. However, it is
not a consistency error in the database. Besides, someone
might have a child at the age of 98 (although this rarely
happens). The Verify tool will display everything that
violates your criteria so that you can check whether the
record is erroneous or not. The ultimate decision is
yours.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
</sect1>
</chapter>
<chapter id="gramps-settings">
<!-- $Id$ -->
<title>Settings</title>
<sect1 id="gramps-prefs">
<title>Preferences</title>
<para>Most of the settings in GRAMPS, are configured in the
<guilabel>Preferences</guilabel> dialog. To invoke it, choose
<menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Preferences...</guimenuitem>
</menuchoice>.</para>
<!-- ==== Figure: Type-ahead find ==== -->
<figure id="prefs-fig">
<title>Preferences dialog</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/prefs.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Shows Preferences dialog.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
<para>The pane on the left displays the tree of available option
categories. Selecting a tree node will display the corresponding options
in the right side of the dialog.</para>
<sect2 id="gramps-prefs-db">
<title>Database</title>
<para>This category contains preferences relevant to the database
itself. It has the following subcategories:</para>
<variablelist>
<varlistentry>
<term><guilabel>General</guilabel></term>
<listitem>
<variablelist>
<varlistentry>
<term><guilabel>Automatically load last
database</guilabel></term>
<listitem>
<para>Check this box to automatically load the last open
database on startup.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Family name guessing</guilabel></term>
<listitem>
<para>This option affects the initial family name of a
child when he/she is added to the database.</para>
<tip>
<para>This option only affects the initial family name
guessed by GRAMPS when the <guilabel>Edit
Person</guilabel> dialog is launched. You can modify
that name the way you see fit. Set this option to the
value that you will most frequently use, as it will save
you a lot of typing.</para>
</tip>
<para>If <guilabel>None</guilabel> is selected, no
guessing will be attempted. Selecting <guilabel>Father's
surname</guilabel> will use the family name of the father.
Selecting <guilabel>Combination of mother's and father's
surname</guilabel> will use the father's name followed by
the mother's name. Finally, <guilabel>Icelandic
style</guilabel> will use the father's given name followed
by the "sson" suffix (e.g. the son of Edwin will be
guessed as Edwinsson).</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>GRAMPS IDs</guilabel></term>
<listitem>
<para>Enter ID prefixes for various kinds of database entries
into the corresponding text entry fields.</para>
<tip>
<para>The ID prefixes use formatting conventions common for C,
Python, and other programming languages. For example, the %04d
expands to an integer, prepended with zeros to have the total
width of four digits. If you would like IDs to be 1, 2, 3,
etc, simply set the formatting parameter to %d.</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Researcher Information</guilabel></term>
<listitem>
<para>Enter your personal information in the corresponding text
entry fields. Although GRAMPS requests information about you,
this information is used only so that GRAMPS can create valid
GEDCOM output files. A valid GEDCOM file requires information
about the file's creator. If you choose, you may leave the
information empty, however none of your exported GEDCOM files
will be valid.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="gramps-prefs-display">
<title>Display</title>
<para>This category contains preferences relevant to displaying
database records and controls in GRAMPS. It has the following
subcategories:</para>
<variablelist>
<varlistentry>
<term><guilabel>General</guilabel></term>
<listitem>
<variablelist>
<varlistentry>
<term><guilabel>Default view</guilabel></term>
<listitem>
<para>This determines which view will appear when you
start GRAMPS. Choose between Person and Family
views.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Family view style</guilabel></term>
<listitem>
<para>This selects between the two available styles of the
Family view layout. The <guilabel>Left to right</guilabel>
style is similar to the Family Tree Maker (tm), while the
<guilabel>Top to bottom</guilabel> is similar to the
Reunion.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Always display the LDS ordinance
tabs</guilabel></term>
<listitem>
<para>Check this box to have LDS ordinance tabs displayed.
If you do not know what LDS is then you probably should
not check it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Display Tip of the Day</guilabel></term>
<listitem>
<para>Check this box to have the <guilabel>Tip of the
Day</guilabel> dialog appear on every startup. The tips
are displayed randomly from the large collection of
information bits on GRAMPS.</para>
<tip>
<para>The <guilabel>Tip of the Day</guilabel> is likely
to be useful for new user of GRAMPS.</para>
</tip>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Dates</guilabel></term>
<listitem>
<para>Select the display format for the dates from the available
formats listed in this menu.</para>
<tip>
<para>Available date display formats are language-specific.
Depending on whether or not there is a GRAMPS date displayer
available for your language, you may or may not have a lot of
choices.</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Toolbar and Statusbar</guilabel></term>
<listitem>
<variablelist>
<varlistentry>
<term><guilabel>Toolbar</guilabel></term>
<listitem>
<para>Select the desired appearance of the toolbar icons
from the menu. Selecting <guilabel>GNOME
Settings</guilabel> will use the overall settings selected
for your GNOME desktop.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Statusbar</guilabel></term>
<listitem>
<para>Select the desired contents displayed in the
statusbar using the radio buttons.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="gramps-prefs-other">
<title>Other settings</title>
<para>Besides <guilabel>Preferences</guilabel> dialog, there are other
settings available in GRAMPS. For various reasons they have been made
more readily accessible, as listed below.</para>
<variablelist>
<varlistentry>
<term>Column Editor</term>
<listitem>
<para>The columns of the list views may be added, removed, or
reordered in a <guilabel>Column Editor Dialog</guilabel>, see
<xref linkend="column-editor-fig" />. Only checked columns will be
shown in the view. To change their order, drag any column to its
desired place inside the editor. Clicking
<guibutton>OK</guibutton> will reflect the changes in the
appropriate view. To invoke <guilabel>Column Editor
Dialog</guilabel>, choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Column Editor...</guimenuitem>
</menuchoice>.</para>
<tip>
<para>The <guilabel>Column Editor</guilabel> is available and
works in the same way for all list views. Specifically, it is
available for People View, Family View (children list). Sources
View, Places View, and Media View.</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term>Setting Home person</term>
<listitem>
<para>The Home person is the person who becomes active when
database opened, when <guibutton>Home</guibutton> button is
clicked or the <guimenuitem>Home</guimenuitem> menu item is
selected from either <guimenu>Go</guimenu> menu or the right-click
context menu anywhere.</para>
<para>To set Home person, make the desired person active and then
choose <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Set Home person...</guimenuitem>
</menuchoice>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Adjusting viewing controls</term>
<listitem>
<para>Whether the toolbar, the sidebar, or the filter (People View
only) are displayed in the main window is adjusted through the
<guimenu>View</guimenu> menu.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="gramps-prefs-adv">
<title>Advanced manipulation of settings</title>
<warning>
<para>The contents of this section is outside the scope of interest of
a general user of GRAMPS. If you proceed with tweaking the options on
the low level you may damage your GRAMPS installation. Be careful. YOU
HAVE BEEN WARNED!</para>
</warning>
<para>By default, GRAMPS stores its settings using gconf2 system. All
the settings used in this version of GRAMPS are stored in subdirectories
under <filename>/apps/gramps/</filename> in the gconf2 namespace.
Accessing the keys can be done either using
<command>gconftool-2</command> command line tool, or the
<command>gconf-editor</command> GUI tool.</para>
<para>All keys are documented, and the notification mechanisms are used
as appropriate. Therefore, updating keys from outside of GRAMPS should
lead to updating GRAMPS in real time, without necessarily restarting
it.</para>
</sect1>
</chapter>
<!-- $Id$ -->
<appendix id="faq">
<title>Frequently Asked Questions</title>
<para>This appendix contains the list of questions that frequently come up
in mailing list discussions and forums. This list is by no means complete.
If you would like to add questions/answers to this list, please email your
suggestions to <ulink type="mailto"
url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink></para>
<variablelist>
<varlistentry>
<term>What is GRAMPS?</term>
<listitem>
<para>GRAMPS is the Genealogical Research and Analysis Management
Program System. In other words, it is a personal genealogy program
letting you store, edit, and research genealogical data using the
powers of your computer.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Where do I get it and how much does it cost?</term>
<listitem>
<para>GRAMPS can be downloaded from <ulink type="http"
url="http://sf.net/projects/gramps">http://sf.net/projects/gramps</ulink>
at no charge. GRAMPS is an Open Source project covered by the GNU
General Public License. You have full access to the source code and
are allowed to distribute the program and source code freely.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Does it work with Windows (tm)?</term>
<listitem>
<para>No. GRAMPS uses the GTK and GNOME libraries. While the GTK
libraries have been ported to Windows, the GNOME libraries have not.
This, however, may change in the future.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Does it work with the Mac?</term>
<listitem>
<para><ulink type="http" url="http://fink.sourceforge.net"> The Fink
project</ulink> has ported <ulink type="http"
url="http://fink.sourceforge.net/pdb/package.php/gramps"> some older
versions</ulink> of GRAMPS to OSX (tm). The Mac OSX port is not
directly supported by the GRAMPS project, primarily because none of
the GRAMPS developers have access to Mac OSX and because OSX is not
Free Software.</para>
<para>This version of GRAMPS (2.2.0) does not appear to have been
ported by the Fink project. Please contact the Fink project for more
information.</para>
<para>Some people have had success using the DarwinPorts instead of
the Fink project.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Does it work with KDE?</term>
<listitem>
<para>Yes, as long as the required GNOME libraries are
installed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Do I really have to have GNOME installed?</term>
<listitem>
<para>Yes, but you do not have to be running the GNOME
desktop.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>What version of GNOME do I need?</term>
<listitem>
<para>This version of gramps requires GNOME 2.8.0 or higher.
Previous versions in 1.0.x series required GNOME 2.0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is GRAMPS compatible with other genealogical software?</term>
<listitem>
<para>GRAMPS makes every effort to maintain compatibility with
GEDCOM, the general standard of recording genealogical information.
We have import and export filters that enable GRAMPS to read and
write GEDCOM files.</para>
<para>It is important to understand that the GEDCOM standard is
poorly implemented -- virtually every genealogical software has its
own "flavor" of GEDCOM. As we learn about new flavor, the
import/export filters can be created very quickly. However, finding
out about the unknown flavors requires user feedback. Please feel
free to inform us about any GEDCOM flavor not supported by GRAMPS,
and we will do our best to support it!</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Can GRAMPS read files created by other genealogy
programs?</term>
<listitem>
<para>See above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Can GRAMPS write files readable by other genealogy
programs?</term>
<listitem>
<para>See above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Can GRAMPS print a genealogical tree for my family?</term>
<listitem>
<para>Yes. Different people have different ideas of what a
genealogical tree is. Some think of it as a chart going from the
distant ancestor and listing all his/her descendants and their
families. Others think it should be a chart going from the person
back in time, listing the ancestors and their families. Yet other
people think of a table, text report, etc.</para>
<para>GRAMPS can produce any of the above, and many more different
charts and reports. Moreover, the plugin architecture enables users
(you) to create their own plugins which could be new reports,
charts, or research tools.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>In what formats can GRAMPS output its reports?</term>
<listitem>
<para>Text reports are available in HTML, PDF, AbiWord, KWord,
LaTeX, RTF, and OpenOffice formats. Graphical reports (charts and
diagrams) are available in PostScript, PDF, SVG, OpenOffice, and
GraphViz formats.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is GRAMPS compatible with the Internet?</term>
<listitem>
<para>GRAMPS can store web addresses and direct your browser to
them. It can import data that you download from the Internet. It can
export data that you could send over the Internet. GRAMPS is
familiar with the standard file formats widely used on the Internet
(e.g. JPEG, PNG, and GIF images, MP3, OGG, and WAV sound files,
QuickTime, MPEG, and AVI movie files, etc). Other than that, there
is little that a genealogical program can do with the
Internet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Can I create custom reports/filters/whatever?</term>
<listitem>
<para>Yes. There are many levels of customization. One is creating
or modifying the templates used for the reports. This gives you some
control over the fonts, colors, and some layout of the reports. You
can also use GRAMPS controls in the report dialogs to tell what
contents should be used for a particular report. In addition to
this, you have an ability to create your own filters -- this is
useful in selecting people based on criteria set by you. You can
combine these filters to create new, more complex filters. Finally,
you have an option to create your own plugins. These may be new
reports, research tools, import/export filters, etc. This assumes
some knowledge of programming in Python.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>What standards does GRAMPS support?</term>
<listitem>
<para>The nice thing about standards is that there never is a
shortage of them. GRAMPS is tested to support the following flavors
of GEDCOM: GEDCOM5.5, Brother's Keeper, Family Origins, Family Tree
Maker, Ftree, GeneWeb, Legacy, Personal Ancestral File, Pro-Gen,
Reunion, and Visual Genealogie.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>What is the maximum database size (bytes) GRAMPS can
handle?</term>
<listitem>
<para>GRAMPS has no hard limits on the size of a database that it
can handle. Starting with this release, GRAMPS no longer loads all
data into memory, which allows it to work with a much larger
database than before. In reality, however, there are practical
limits. The main limiting factors are the available memory on the
system and the cache size used for BSDDB database access. With
common memory sizes these days, GRAMPS should have no problem using
databases with tens of thousands of people.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>How many people can GRAMPS database handle?</term>
<listitem>
<para>We have found that on a typical system, GRAMPS tends to bog
down after the database has around 150,000 people. Again, this is
dependent on how much memory you have.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Why is GRAMPS running so slowly?</term>
<listitem>
<para>It does not anymore! Just try out the current version,
2.2.0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>My database is really big. Is there a way around loading all the
data into memory?</term>
<listitem>
<para>Starting with this release, GRAMPS no longer loads all data
into memory, which allows it to work with a much larger database
than before.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>I want to rerun the Startup dialog. How do I do this?</term>
<listitem>
<para>GRAMPS keeps a flag in the GNOME configuration database to
indicate that the startup dialog has been run. To cause GRAMPS to
rerun this, the flag needs to be reset. This can be done with the
following command:</para>
<para><command>gconftool-2 -u
/apps/gramps/behavior/startup</command></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Why are non-latin characters displayed as garbage in PDF/PS
reports?</term>
<listitem>
<para>This is a limitation of the builtin fonts of PS and PDF
formats. To print non-latin text, use the Print... in the format
selection menu of the report dialog. This will use the gnome-print
backend, which supports PS and PDF creation, as well as direct
printing.</para>
<para>If you only have latin text, the PDF option will produce a
smalled PDF compared to that created by gnome-print, simply because
no font information will be embedded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Why can I not add/remove/edit columns to the lists in People
View and Family View?</term>
<listitem>
<para>Now you can! Just try out the current version, 2.2.0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>I would like to contribute to GRAMPS by writing my favorite
report. How do I do that?</term>
<listitem>
<para>The easiest way to contribute to reports, filters, tools, etc.
is to copy an existing GRAMPS report, filter, or tool. If you can
create what you want by modifying existing code -- great! If your
idea does not fit into the logic of any existing GRAMPS tool, the
<ulink type="http"
url="http://gramps.sourceforge.net/phpwiki/index.php/GrampsDevelopersPage">following
page</ulink> may provide some help in writing your own plugin from
scratch.</para>
<para>If you need more help or would like to discuss your idea with
us, please do not hesitate to contact us at <ulink type="mailto"
url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink></para>
<para>To test your work in progress, you may save your plugin under
<replaceable>$HOME/.gramps/plugins</replaceable> directory and it
should be found and imported on startup. The correctly written
plugin will register itself with GRAMPS, create menu item, and so
on.</para>
<para>If you are happy with your plugin and would like to contribute
your code back to the GRAMPS project, you are very welcome to do so
by contacting us at <ulink type="mailto"
url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink></para>
</listitem>
</varlistentry>
<varlistentry>
<term>I found a bug and I want it fixed right now! What do I
do?</term>
<listitem>
<para>The best thing you can do is to fix the bug and send the patch
to <ulink type="mailto"
url="mailto:gramps-devel@lists.sf.net">gramps-devel@lists.sf.net</ulink>
:-)</para>
<para>A good bug report would include:</para>
<itemizedlist>
<listitem>
<para>Version of gramps you were using when you encountered the
bug (available through <menuchoice>
<guisubmenu>Help</guisubmenu>
<guimenuitem>About</guimenuitem>
</menuchoice> menu item).</para>
</listitem>
<listitem>
<para>Language under which gramps was run (available by
executing</para>
<para><command>echo $LANG</command></para>
<para>in your terminal).</para>
</listitem>
<listitem>
<para>Symptoms indicating that this is indeed a bug.</para>
</listitem>
<listitem>
<para>Any Traceback messages, error messages, warnings, etc,
that showed up in your terminal or a in separate traceback
window.</para>
</listitem>
</itemizedlist>
<para>Most problems can be fixed quickly provided there is enough
information. To ensure this, please follow up on your bug reports.
In particular, if you file a bug report with sf.net bug tracker,
PLEASE log in to sf.net before filing (register your free account if
you don't have one). Then we will have a way of contacting you
should we need more information. If you choose to file your report
anonymously, at least check every so often whether your report page
has something new posted, as it probably would.</para>
<para>If the above explanations seem vague, please follow <ulink
type="http"
url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">this
link.</ulink></para>
</listitem>
</varlistentry>
<varlistentry>
<term>It is obvious that GRAMPS absolutely needs to become a
(client-server/web-based/PHP/weblog/Javascript/C++/distributed/KDE/Motif/Tcl/Win32/C#/You-name-it)
application. When is this going to happen?</term>
<listitem>
<para>The surest way to see it happen is to get it done by yourself.
Since GRAMPS is free/open source, nobody prevents you from taking
all of the code and continuing its development in whatever direction
you see fit. In doing so, you may consider giving your new project
another name to avoid confusion with the continuing GRAMPS
development. If you would like the GRAMPS project to provide advice,
expertise, filters, etc., we will gladly cooperate with your new
project, to ensure compatibility or import/export options to your
new format of a project.</para>
<para>If, however, you would like the GRAMPS project to to adopt
your strategy, you would need to convince GRAMPS developers that
your strategy is good for GRAMPS and superior to the present
development strategy.</para>
</listitem>
</varlistentry>
</variablelist>
</appendix>
<appendix id="append-keybind">
<!-- $Id$ -->
<title>Keybindings reference</title>
<para>Most of the standard menu items define equivalent keybindings. These
are apparent because they are displayed on the right of the menu item.
However, some keybindings are not associated with any items in the
menu.</para>
<para>This appendix contains the list of keybindings that are not
displayed in menus of GRAMPS.</para>
<sect1 id="keybind-lists">
<title>List Views</title>
<para>The following bindings are available in all list views: People
View, Sources View, Places View, and Media View.</para>
<informaltable frame="topbot">
<tgroup cols="2">
<colspec colname="col1" />
<colspec colname="col2" />
<thead>
<row valign="top">
<entry colname="col1" colsep="0"
valign="top"><para>Key</para></entry>
<entry colname="col2" valign="top"><para>Function</para></entry>
</row>
</thead>
<tbody>
<row valign="top">
<entry><para><keycap>Enter</keycap></para></entry>
<entry><para>Invoke <guilabel>Edit Person</guilabel> dialog with
the selected person.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 id="keybind-family">
<title>Family View</title>
<para>The bindings available in the Family View depend on where the
focus is. The following tables list the bindings for all focus
targets.</para>
<variablelist>
<varlistentry>
<term>Focus on the Active Person</term>
<listitem>
<informaltable frame="topbot">
<tgroup cols="2">
<colspec colname="col1" />
<colspec colname="col2" />
<thead>
<row valign="top">
<entry colname="col1" colsep="0"
valign="top"><para>Key</para></entry>
<entry colname="col2"
valign="top"><para>Function</para></entry>
</row>
</thead>
<tbody>
<row valign="top">
<entry><para><keycap>Enter</keycap></para></entry>
<entry><para>Invoke <guilabel>Edit Person</guilabel>
dialog with the active person.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Ctrl</keycap>+<keycap>Down</keycap>
or
<keycap>Ctrl</keycap>+<keycap>Right</keycap></para></entry>
<entry><para>Swap the Active Person and the selected
spouse. Use <keycap>Ctrl</keycap>+<keycap>Down</keycap> in
standard Family View and
<keycap>Ctrl</keycap>+<keycap>Right</keycap> in
alternative Family View.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</varlistentry>
<varlistentry>
<term>Focus on the Spouse box</term>
<listitem>
<informaltable frame="topbot">
<tgroup cols="2">
<colspec colname="col1" />
<colspec colname="col2" />
<thead>
<row valign="top">
<entry colname="col1" colsep="0"
valign="top"><para>Key</para></entry>
<entry colname="col2"
valign="top"><para>Function</para></entry>
</row>
</thead>
<tbody>
<row valign="top">
<entry><para><keycap>Enter</keycap></para></entry>
<entry><para>Edit relationship between the Active Person
and the selected spouse.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Shift</keycap>+<keycap>Enter</keycap></para></entry>
<entry><para>Edit the personal information for the
selected spouse.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Insert</keycap></para></entry>
<entry><para>Add a person from the database to the spouse
list.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Shift</keycap>+<keycap>Insert</keycap></para></entry>
<entry><para>Add a new person to the database and to the
spouse list.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Delete</keycap></para></entry>
<entry><para>Delete the selected spouse from the spouse
list. The spouse is not deleted from the
database.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Ctrl</keycap>+<keycap>Up</keycap> or
<keycap>Ctrl</keycap>+<keycap>Left</keycap></para></entry>
<entry><para>Swap the selected spouse and the Active
Person. Use <keycap>Ctrl</keycap>+<keycap>Up</keycap> in
standard Family View and
<keycap>Ctrl</keycap>+<keycap>Left</keycap> in alternative
Family View.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</varlistentry>
<varlistentry>
<term>Focus on the Parents box</term>
<listitem>
<informaltable frame="topbot">
<tgroup cols="2">
<colspec colname="col1" />
<colspec colname="col2" />
<thead>
<row valign="top">
<entry colname="col1" colsep="0"
valign="top"><para>Key</para></entry>
<entry colname="col2"
valign="top"><para>Function</para></entry>
</row>
</thead>
<tbody>
<row valign="top">
<entry><para><keycap>Enter</keycap></para></entry>
<entry><para>Edit relationship between the parents and
their child (either the Active Person or the selected
spouse, depending which parents box the focus is
in).</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Insert</keycap></para></entry>
<entry><para>Add a new set of parents from the database to
the list.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Shift</keycap>+<keycap>Insert</keycap></para></entry>
<entry><para>Add a new set of parents to the database and
to the list.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Delete</keycap></para></entry>
<entry><para>Delete the selected parents from the list.
The parents are not deleted from the
database.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Ctrl</keycap>+<keycap>Right</keycap>
or
<keycap>Ctrl</keycap>+<keycap>Down</keycap></para></entry>
<entry><para>Make the selected parents the active family.
Use <keycap>Ctrl</keycap>+<keycap>Right</keycap> in
standard Family View and
<keycap>Ctrl</keycap>+<keycap>Down</keycap> in alternative
Family View.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</varlistentry>
<varlistentry>
<term>Focus on the Children box</term>
<listitem>
<informaltable frame="topbot">
<tgroup cols="2">
<colspec colname="col1" />
<colspec colname="col2" />
<thead>
<row valign="top">
<entry colname="col1" colsep="0"
valign="top"><para>Key</para></entry>
<entry colname="col2"
valign="top"><para>Function</para></entry>
</row>
</thead>
<tbody>
<row valign="top">
<entry><para><keycap>Enter</keycap></para></entry>
<entry><para>Edit relationship between the child and
his/her parents (the Active Person and the selected
spouse).</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Shift</keycap>+<keycap>Enter</keycap></para></entry>
<entry><para>Edit the personal information for the
selected child.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Insert</keycap></para></entry>
<entry><para>Add a new person from the database to the
children list.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Shift</keycap>+<keycap>Insert</keycap></para></entry>
<entry><para>Add a new person to the database and to the
children list.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Delete</keycap></para></entry>
<entry><para>Delete the selected child from the list. The
child is not deleted from the database.</para></entry>
</row>
<row valign="top">
<entry><para><keycap>Ctrl</keycap>+<keycap>Left</keycap>
or
<keycap>Ctrl</keycap>+<keycap>Up</keycap></para></entry>
<entry><para>Make the selected child the Active Person.
Use <keycap>Ctrl</keycap>+<keycap>Left</keycap> in
standard Family View and
<keycap>Ctrl</keycap>+<keycap>Up</keycap> in alternative
Family View.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</appendix>
<appendix id="append-filtref">
<!-- $Id$ -->
<title>Filter rules reference</title>
<para>This appendix lists of all the filter rules currently defined in
GRAMPS. Each of these rules is available for use when creating custom
filters, see <xref linkend="tools-util-cfe" />. The rules are listed by
their categories.</para>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-general">
<title>General filters</title>
<para>This category includes the following most general rules:</para>
<variablelist>
<varlistentry>
<term>Has complete record</term>
<listitem>
<para>This rule matches all people whose records are marked as
complete. Currently, the completeness of personal information is
marked manually, in the <guilabel>Edit Person</guilabel>
dialog.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People with incomplete names</term>
<listitem>
<para>This rule matches all people with either given name or
family name missing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is bookmarked person</term>
<listitem>
<para>This rule matches all people who are on the bookmark
list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has text matching substring of</term>
<listitem>
<para>This rule matches all people whose records contain specified
substring. All textual records are searched. Optionally, the
search can be made case sensitive, or a regular expression
match.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Everyone</term>
<listitem>
<para>This rule matches any person in the database. As such it is
not very useful on its own except for testing purposes. However,
it may be useful in combinations with other rules.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People probably alive</term>
<listitem>
<para>This rule matches all people whose records do not indicate
their death and who are not unreasonably old, judging by their
available birth data and today's date.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has a name</term>
<listitem>
<para>This rule matches any person whose name matches the
specified value in full or in part. For example, Marta Ericsdotter
will be matched by the rule using the value "eric" for the family
name.</para>
<para>Separate values can be used for Given name, Family name,
Suffix, and the Title. The rule returns a match if, and only if,
all non-empty values are (partially) matched by a person's name.
To use just one value, leave the other values empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has the Id</term>
<listitem>
<para>This rule matches any person with a specified GRAMPS ID. The
rule returns a match only if the ID is matched exactly.</para>
<para>You can either enter the ID into a text entry field, or
select a person from the list by clicking
<guibutton>Select...</guibutton> button. In the latter case, the
ID will appear in the text field after the selection was
made.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is default person</term>
<listitem>
<para>This rule matches the default (home) person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People marked private</term>
<listitem>
<para>This rule matches people whose records are marked as
private.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a female</term>
<listitem>
<para>This rule matches any female person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People who have images</term>
<listitem>
<para>This rule matches people with images in their
galleries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People without a birth date</term>
<listitem>
<para>This rule matches people missing birth date.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a male</term>
<listitem>
<para>This rule matches any male person.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-event">
<title>Event filters</title>
<para>This category includes the following rules that match people based
on their recorded events:</para>
<variablelist>
<varlistentry>
<term>Has the birth</term>
<listitem>
<para>This rule matches people whose birth event matches specified
values for Date, Place, and Description. The rule returns a match
even if the person's birth event matches the value partially. The
matching rules are case-insensitive. For example, anyone born in
Sweden will be matched by the rule using the value "sw" for the
Place.</para>
<para>The rule returns a match if, and only if, all non-empty
values are (partially) matched by a person's birth. To use just
one value, leave the other values empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has the death</term>
<listitem>
<para>This rule matches people whose death event matches specified
values for Date, Place, and Description. The rule returns a match
even if the person's death event matches the value partially. The
matching rules are case-insensitive. For example, anyone who died
in Sweden will be matched by the rule using the value "sw" for the
Place.</para>
<para>The rule returns a match if, and only if, all non-empty
values are (partially) matched by a person's death. To use just
one value, leave the other values empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has source of</term>
<listitem>
<para>This rule matches people whose records refer to the
specified source.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has the personal event</term>
<listitem>
<para>This rule matches people that have a personal event matching
specified values for the Event type, Date, Place, and Description.
The rule returns a match even if the person's event matches the
value partially. The matching rules are case-insensitive. For
example, anyone who graduated in Sweden will be matched by the
rule using the Graduation event and the value "sw" for the
Place.</para>
<para>The personal events should be selected from a pull-down
menu. The rule returns a match if, and only if, all non-empty
values are (partially) matched by the personal event. To use just
one value, leave the other values empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has the family event</term>
<listitem>
<para>This rule matches people that have a family event matching
specified values for the Event type, Date, Place, and Description.
The rule returns a match even if the person's event matches the
value partially. The matching rules are case-insensitive. For
example, anyone who was married in Sweden will be matched by the
rule using the Marriage event and the value "sw" for the
Place.</para>
<para>The family events should be selected from a pull-down menu.
The rule returns a match if, and only if, all non-empty values are
(partially) matched by the personal event. To use just one value,
leave the other values empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Witness</term>
<listitem>
<para>This rule matches people who are present as a witness in the
event. If the personal or family event type is specified, only the
events of this type will be searched.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People with incomplete events</term>
<listitem>
<para>This rule matches people missing date or place in any
personal event.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Families with incomplete events</term>
<listitem>
<para>This rule matches people missing date or place in any family
event of any of their families.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-family">
<title>Family filters</title>
<para>This category includes the following rules that match people based
on their family relationships:</para>
<variablelist>
<varlistentry>
<term>People with children</term>
<listitem>
<para>This rule matches people with children.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People with multiple marriage records</term>
<listitem>
<para>This rule matches people with more than one spouse.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People with no marriage records</term>
<listitem>
<para>This rule matches people with no spouses.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>People who were adopted</term>
<listitem>
<para>This rule matches adopted people.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has the relationships</term>
<listitem>
<para>This rule matches people with a particular relationship. The
relationship must match the type selected from the menu.
Optionally, the number of relationships and the number of children
can be specified.</para>
<para>The rule returns a match if, and only if, all non-empty
values are (partially) matched by a person's relationship. To use
just one value, leave the other values empty.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is spouse of filter match</term>
<listitem>
<para>This rule matches people married to someone who is matched
by the specified filter. The specified filter name should be
selected from the menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a child of filter match</term>
<listitem>
<para>This rule matches people for whom either parent is matched
by the specified filter. The specified filter name should be
selected from the menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a parent of filter match</term>
<listitem>
<para>This rule matches people whose child is matched by the
specified filter. The specified filter name should be selected
from the menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a sibling of filter match</term>
<listitem>
<para>This rule matches people whose sibling is matched by the
specified filter. The specified filter name should be selected
from the menu.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-ancestral">
<title>Ancestral filters</title>
<para>This category includes the following rules that match people based
on their ancestral relations to other people:</para>
<variablelist>
<varlistentry>
<term>Is an ancestor of</term>
<listitem>
<para>This rule matches people who are ancestors of the specified
person. The Inclusive option determines whether the specified
person should be considered his/her own ancestor (useful for
building reports).</para>
<para>You can either enter the ID into a text entry field, or
select a person from the list by clicking
<guibutton>Select...</guibutton> button. In the latter case, the
ID will appear in the text field after the selection was
made.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is an ancestor of person at least N generations away</term>
<listitem>
<para>This rule matches people who are ancestors of the specified
person and are at least N generations away from that person in
their lineage. For example, using this rule with the value of 2
for the number of generations will match grandparents,
great-grandparents, etc., but not the parents of the specified
person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is an ancestor of person not more than N generations
away</term>
<listitem>
<para>This rule matches people who are ancestors of the specified
person and are no more than N generations away from that person in
their lineage. For example, using this rule with the value of 2
for the number of generations will match parents and grandparents,
but not great-grandparents, etc., of the specified person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has a common ancestor with</term>
<listitem>
<para>This rule matches people who have common ancestors with the
specified person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has a common ancestor with filter match</term>
<listitem>
<para>This rule matches people who have common ancestors with
someone who is matched by the specified filter. The specified
filter name should be selected from the menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is an ancestor of filter match</term>
<listitem>
<para>This rule matches people who are ancestors of someone who is
matched by the specified filter. The specified filter name should
be selected from the menu.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-descendant">
<title>Descendant filters</title>
<para>This category includes the following rules that match people based
on their descendant relations to other people:</para>
<variablelist>
<varlistentry>
<term>Is a descendant of</term>
<listitem>
<para>This rule matches people who are descendants of the
specified person. The Inclusive option determines whether the
specified person should be considered his/her own descendant
(useful for building reports).</para>
<para>You can either enter the ID into a text entry field, or
select a person from the list by clicking
<guibutton>Select...</guibutton> button. In the latter case, the
ID will appear in the text field after the selection was
made.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a descendant of person at least N generations away</term>
<listitem>
<para>This rule matches people who are descendants of the
specified person and are at least N generations away from that
person in their lineage. For example, using this rule with the
value of 2 for the number of generations will match grandchildren,
great-grandchildren, etc., but not the children of the specified
person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a descendant of person not more than N generations
away</term>
<listitem>
<para>This rule matches people who are descendants of the
specified person and are no more than N generations away from that
person in their lineage. For example, using this rule with the
value of 2 for the number of generations will match children and
grandchildren, but not great-grandchildren, etc., of the specified
person.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a descendant of filter match</term>
<listitem>
<para>This rule matches people who are descendants of someone who
is matched by the specified filter. The specified filter name
should be selected from the menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Is a descendant family member of</term>
<listitem>
<para>This rule not only matches people who are descendants of the
specified person, but also those descendants' spouses.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-relat">
<title>Relationship filters</title>
<para>This category includes the following rules that match people based
on their mutual relationship:</para>
<variablelist>
<varlistentry>
<term>Relationship path between two people</term>
<listitem>
<para>This rule matches all ancestors of both people back to their
common ancestors (if exist). This produces the "relationship path"
between these two people, through their common ancestors.</para>
<para>You can either enter the ID of each person into the
appropriate text entry fields, or select people from the list by
clicking their <guibutton>Select...</guibutton> buttons. In the
latter case, the ID will appear in the text field after the
selection was made.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- =============== Appendices Sub-subsection ================ -->
<sect1 id="filtref-misc">
<title>Miscellaneous filters</title>
<para>This category includes the following rules which do not naturally
fit into any of the above categories:</para>
<variablelist>
<varlistentry>
<term>Has the personal attribute</term>
<listitem>
<para>This rule matches people who have the personal attribute of
the specified value. The specified personal attribute name should
be selected from the menu. The specified value should be typed
into the text entry field.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Has the family attribute</term>
<listitem>
<para>This rule matches people who have the family attribute of
the specified value. The specified family attribute should be
selected from the menu. The specified value should be typed into
the text entry field.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Matches the filter named</term>
<listitem>
<para>This rule matches people who are matched by the specified
filter. The specified filter name should be selected from the
menu.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</appendix>
<appendix id="append-cmdline">
<!-- $Id$ -->
<!-- =============== Appendices Subsection ================ -->
<title>Command line reference</title>
<para>This appendix provides the reference to the command line
capabilities available when launching GRAMPS from the terminal.</para>
<note>
<para>GRAMPS was designed to be an interactive program. Therefore it
uses graphical display and cannot run from the true non-graphical
console. It would take an enormous amount of effort to enable it to run
in a text-only terminal. This is why the set of command line options
does not aim to completely get rid of dependency on the graphical
display. Rather, it merely makes certain (typical) tasks more
convenient. It also allows one to execute these tasks from the scripts.
However, the graphical display must be accessible at all times!</para>
</note>
<tip>
<para>To summarize, the use of the command line options provides
non-interactive behavior, but does not get rid of graphical display
dependency. Take it or leave it!</para>
</tip>
<sect1 id="cmdline-options">
<title>Available options</title>
<para>This section provides the reference list of all command line
options available in GRAMPS. If you want to know more than just a list
of options, see next sections: <xref linkend="cmdline-operation" /> and
<xref linkend="cmdline-examples" />.</para>
<sect2 id="cmdline-opt-format">
<title>Format options</title>
<para>The format of any file destined for opening, importing, or
exporting can be specified with the <command>-f
<replaceable>format</replaceable></command> option. The acceptable
<replaceable>format</replaceable> values are listed below.</para>
<variablelist>
<varlistentry>
<term>grdb</term>
<listitem>
<para>GRAMPS database. This format is available for opening,
import, and export. When not specified, it can be guessed if the
filename ends with .grdb</para>
</listitem>
</varlistentry>
<varlistentry>
<term>gramps-xml</term>
<listitem>
<para>GRAMPS XML database. This format is available for opening,
import, and export. When not specified, it can be guessed if the
filename ends with .gramps</para>
</listitem>
</varlistentry>
<varlistentry>
<term>gedcom</term>
<listitem>
<para>GEDCOM file. This format is available for opening, import,
and export. When not specified, it can be guessed if the
filename ends with .ged</para>
</listitem>
</varlistentry>
<varlistentry>
<term>gramps-pkg</term>
<listitem>
<para>GRAMPS package. This format is available for import and
export. When not specified, it can be guessed if the filename
ends with .gpkg</para>
</listitem>
</varlistentry>
<varlistentry>
<term>geneweb</term>
<listitem>
<para>GeneWen file This format is available for import and
export. When not specified, it can be guessed if the filename
ends with .gw</para>
</listitem>
</varlistentry>
<varlistentry>
<term>wft</term>
<listitem>
<para>Web Family Tree. This format is available for export only.
When not specified, it can be guessed if the filename ends with
.wft</para>
</listitem>
</varlistentry>
<varlistentry>
<term>iso</term>
<listitem>
<para>CD image. This format is available for export only. It
must always be specified explicitly.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="cmdline-opt-open">
<title>Opening options</title>
<para>There are two ways to give GRAMPS the name of the file to be
opened:</para>
<itemizedlist>
<listitem>
<para>supply bare file name</para>
</listitem>
<listitem>
<para>use the <command>-O <filename>filename</filename></command>
or <command>-open=<filename>filename</filename></command>
option</para>
</listitem>
</itemizedlist>
<para>If the filename is given without any option flag, the attempt to
open the file will be made, and then the interactive GRAMPS session
will be launched.</para>
<tip>
<para>If no option is given, just the file name, GRAMPS will ignore
the rest of the command line arguments. Use the -O flag to open the
file and do something with the data.</para>
</tip>
<para>The format can be specified with the <command>-f
<replaceable>format</replaceable></command> or
<command>--format=<replaceable>format</replaceable></command> option,
immediately following the <filename>filename</filename>. If not
specified, the guess will be attempted based on the
<filename>filename</filename>.</para>
<tip>
<para>Only grdb, gramps-xml, and gedcom formats can be opened
directly. For other formats, you will need to use the import option
which will set up the empty database and then import data into
it.</para>
</tip>
<tip>
<para>Only a single file can be opened. If you need to combine data
from several sources, you will need to use the import option.</para>
</tip>
</sect2>
<sect2 id="cmdline-opt-import">
<title>Import options</title>
<para>The files destined for import can be specified with the
<command>-i <filename>filename</filename></command> or
<command>--import=<filename>filename</filename></command> option. The
format can be specified with the <command>-f
<replaceable>format</replaceable></command> or
<command>--format=<replaceable>format</replaceable></command> option,
immediately following the <filename>filename</filename>. If not
specified, the guess will be attempted based on the
<filename>filename</filename>.</para>
<tip>
<para>More than one file can be imported in one command. If this is
the case, GRAMPS will incorporate the data from the next file into
the database available at the moment.</para>
</tip>
<para>When more than one input file is given, each has to be preceded
by <command>-i</command> flag. The files are imported in the specified
order, i.e. <command> -i <filename>file1</filename> -i
<filename>file2</filename> </command> and <command> -i
<filename>file2</filename> -i <filename>file1</filename> </command>
might produce different GRAMPS IDs in the resulting database.</para>
</sect2>
<sect2 id="cmdline-opt-export">
<title>Export options</title>
<para>The files destined for export can be specified with the
<command>-o <filename>filename</filename></command> or
<command>--output=<filename>filename</filename></command> option. The
format can be specified with the <command>-f</command> option
immediately following the <filename>filename</filename>. If not
specified, the guess will be attempted based on the
<filename>filename</filename>. For iso format, the
<filename>filename</filename> is actually the name of directory the
GRAMPS database will be written into. For grdb, gramps-xml, gedcom,
wft, geneweb, and gramps-pkg, the <filename>filename</filename> is the
name of the resulting file.</para>
<tip>
<para>More than one file can be exported in one command. If this is
the case, GRAMPS will attempt to write several files using the data
from the database available at the moment.</para>
</tip>
<para>When more than one output file is given, each has to be preceded
by <command>-o</command> flag. The files are written one by one, in
the specified order.</para>
</sect2>
<sect2 id="cmdline-opt-action">
<title>Action options</title>
<para>The action to perform on the imported data can be specified with
the <command>-a <replaceable>action</replaceable></command> or
<command>--action=<replaceable>action</replaceable></command> option.
This is done after all imports are successfully completed.</para>
<para>Currently available actions are:</para>
<variablelist>
<varlistentry>
<term>summary</term>
<listitem>
<para>This action is the same as <menuchoice>
<guimenu>Reports</guimenu>
<guisubmenu>View</guisubmenu>
<guimenuitem>Summary</guimenuitem>
</menuchoice></para>
</listitem>
</varlistentry>
<varlistentry>
<term>check</term>
<listitem>
<para>This action is the same as <menuchoice>
<guimenu>Tools</guimenu>
<guisubmenu>Database Processing</guisubmenu>
<guimenuitem>Check and Repair</guimenuitem>
</menuchoice>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>report</term>
<listitem>
<para>This action allows producing reports from the command
line. As reports generally have many options of their own, this
action should be followed by the report option string. The
string is given using the <command>-p
<replaceable>option_string</replaceable></command> or
<command>--options=<replaceable>option_string</replaceable></command>
option.</para>
<tip>
<para>The report option string should satisfy the following
conditions:</para>
<itemizedlist>
<listitem>
<para>It must not contain any spaces. If some arguments
need to include spaces, the string should be enclosed with
quotation marks.</para>
</listitem>
<listitem>
<para>Option string must list pairs of option names and
values.</para>
</listitem>
<listitem>
<para>Within a pair, option name and value must be
separated by the equal sign.</para>
</listitem>
<listitem>
<para>Different pairs must be separated by commas.</para>
</listitem>
</itemizedlist>
</tip>
<para>Most of the report options are specific for every report.
However, there some common options.</para>
<variablelist>
<varlistentry>
<term>name=report_name</term>
<listitem>
<para>This mandatory option determines which report will
be generated. If the supplied report_name does not
correspond to any available report, the error message will
be printed followed by the list of available
reports.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>show=all</term>
<listitem>
<para>This will produce the list of names for all options
available for a given report.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>show=option_name</term>
<listitem>
<para>This will print the description of the functionality
supplied by the option_name, as well as what are the
acceptable types and values for this option.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Use the above options to find out everything about a given
report.</para>
<tip>
<para>If an option is not supplied, the last used value will
be used. If this report has never been generated before, then
the value from last generated report will be used when
applicable. Otherwise, the default value will be used.</para>
</tip>
</listitem>
</varlistentry>
</variablelist>
<para>When more than one output action is given, each has to be
preceded by <command>-a</command> flag. The actions are performed one
by one, in the specified order.</para>
</sect2>
</sect1>
<!-- &cmdplug; -->
<sect1 id="cmdline-operation">
<title>Operation</title>
<itemizedlist>
<listitem>
<para>If the first argument on the command line does not start with
dash (i.e. no flag), GRAMPS will attempt to open the file with the
name given by the first argument and start interactive session,
ignoring the rest of the command line arguments.</para>
</listitem>
<listitem>
<para>If the <command>-O</command> flag is given, then GRAMPS will
try opening the supplied file name and then work with that data, as
instructed by the further command line parameters.</para>
<note>
<para>Only one file can be opened in a single invocation of
GRAMPS. If you need to get data from multiple sources, use the
importing options by using <command>-i</command> flag.</para>
</note>
</listitem>
<listitem>
<para>With or without the <command>-O</command> flag, there could be
multiple imports, exports, and actions specified further on the
command line by using <command>-i</command>, <command>-o</command>,
and <command>-a</command> flags.</para>
</listitem>
<listitem>
<para>The order of <command>-i</command>, <command>-o</command>, or
<command>-a</command> options with respect to each does not matter.
The actual execution order always is: all imports (if any) -&gt; all
exports (if any) -&gt; all actions (if any).</para>
<note>
<para>But opening must always be first!</para>
</note>
</listitem>
<listitem>
<para>If no <command>-O</command> or <command>-i</command> option is
given, GRAMPS will launch its main window and start the usual
interactive session with the empty database, since there is no data
to process, anyway.</para>
</listitem>
<listitem>
<para>If no <command>-o</command> or <command>-a</command> options
are given, GRAMPS will launch its main window and start the usual
interactive session with the database resulted from opening and all
imports (if any). This database resides in the
<filename>import_db.grdb</filename> file under the
<filename>~/.gramps/import/</filename> directory.</para>
</listitem>
<listitem>
<para>Any errors encountered during import, export, or action, will
be either dumped to stdout (if these are exceptions handled by
GRAMPS) or or to stderr (if these are not handled). Use usual shell
redirections of stdout and stderr to save messages and errors in
files.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="cmdline-examples">
<title>Examples</title>
<variablelist>
<varlistentry>
<term>To import four databases (whose formats can be determined from
their names) and then check the resulting database for errors, one
may type:</term>
<listitem>
<para><command>gramps -i<filename>file1.ged</filename> -i
<filename>file2.gpkg</filename> -i
<filename>~/db3.gramps</filename> -i
<filename>file4.wft</filename> -a
<filename>check</filename></command></para>
</listitem>
</varlistentry>
<varlistentry>
<term>To explicitly specify the formats in the above example, append
filenames with appropriate <command>-f</command> options:</term>
<listitem>
<para><command>gramps -i <filename>file1.ged</filename> -f
<replaceable>gedcom</replaceable> -i
<filename>file2.gpkg</filename> -f
<replaceable>gramps-pkg</replaceable> -i
<filename>~/db3.gramps</filename> -f
<replaceable>gramps-xml</replaceable> -i
<filename>file4.wft</filename> -f <replaceable>wft</replaceable>
-a <replaceable>check</replaceable></command></para>
</listitem>
</varlistentry>
<varlistentry>
<term>To record the database resulting from all imports, supply
<command>-o</command> flag (use <command>-f</command> if the
filename does not allow GRAMPS to guess the format):</term>
<listitem>
<para><command>gramps -i <filename>file1.ged</filename> -i
<filename>file2.gpkg</filename> -o
<filename>~/new-package</filename> -f
<replaceable>gramps-pkg</replaceable></command></para>
</listitem>
</varlistentry>
<varlistentry>
<term>To save any error messages of the above example into files
<filename>outfile</filename> and <filename>errfile</filename>,
run:</term>
<listitem>
<para><command>gramps -i <filename>file1.ged</filename> -i
<filename>file2.dpkg</filename> -o
<filename>~/new-package</filename> -f
<replaceable>gramps-pkg</replaceable>
&gt;<filename>outfile</filename> 2&gt;<filename>errfile</filename>
</command></para>
</listitem>
</varlistentry>
<varlistentry>
<term>To import three databases and start interactive GRAMPS session
with the result:</term>
<listitem>
<para><command>gramps -i <filename>file1.ged</filename> -i
<filename>file2.gpkg</filename> -i
<filename>~/db3.gramps</filename> </command></para>
</listitem>
</varlistentry>
<varlistentry>
<term>To open a database and, based on that data, generate timeline
report in PDF format putting the output into the
<filename>my_timeline.pdf</filename> file:</term>
<listitem>
<para><command>gramps -O <filename>file.grdb</filename> -a
<replaceable>report</replaceable> -p
<replaceable>name=timeline,off=pdf,of=my_timeline.pdf</replaceable>
</command></para>
<tip>
<para>Use the <replaceable>name=timeline,show=all</replaceable>
to find out about all available options for the timeline report.
To find out details of a particular option, use
<replaceable>show=option_name</replaceable>, e.g.
<replaceable>name=timeline,show=off</replaceable> string.</para>
<para>To learn about available report names, use
<replaceable>name=show</replaceable> string.</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term>Finally, to start normal interactive session type:</term>
<listitem>
<para><command>gramps </command></para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</appendix>
<!-- ENTITY cmdplug SYSTEM "cmdplug.xml" -->
<!-- ENTITY bugs SYSTEM "bugs.xml" -->
<appendix id="gramps-about">
<!-- $Id$ -->
<title>About GRAMPS</title>
<para>GRAMPS was written by Donald N. Allingham
(<email>don@gramps-project.org</email>).</para>
<para>The somewhat incomplete list of contributors includes (in
alphabetical order): <itemizedlist>
<listitem>
<para>Larry Allingham</para>
</listitem>
<listitem>
<para>Jens Arvidsson</para>
</listitem>
<listitem>
<para>Marcos Bedinelli</para>
</listitem>
<listitem>
<para>Douglas S. Blank</para>
</listitem>
<listitem>
<para>Radu Bogdan Mare</para>
</listitem>
<listitem>
<para>Alexander Bogdashevsky</para>
</listitem>
<listitem>
<para>Richard Bos</para>
</listitem>
<listitem>
<para>Nathan Bullock</para>
</listitem>
<listitem>
<para>Lorenzo Cappelletti</para>
</listitem>
<listitem>
<para>Pier Luigi Cinquantini</para>
</listitem>
<listitem>
<para>Bruce J. DeGrasse</para>
</listitem>
<listitem>
<para>Alexandre Duret-Lutz</para>
</listitem>
<listitem>
<para>Billy C. Earney</para>
</listitem>
<listitem>
<para>Baruch Even</para>
</listitem>
<listitem>
<para>Bernd Felsche</para>
</listitem>
<listitem>
<para>Egyeki Gergely</para>
</listitem>
<listitem>
<para>Michel Guitel</para>
</listitem>
<listitem>
<para>Steve Hall</para>
</listitem>
<listitem>
<para>David R. Hampton</para>
</listitem>
<listitem>
<para>Martin Hawlisch</para>
</listitem>
<listitem>
<para>Anton Huber</para>
</listitem>
<listitem>
<para>Frode Jemtland</para>
</listitem>
<listitem>
<para>Greg Kuperberg</para>
</listitem>
<listitem>
<para>Arkadiusz Lipiec</para>
</listitem>
<listitem>
<para>Lars Kr. Lundin</para>
</listitem>
<listitem>
<para>Radek Malcic</para>
</listitem>
<listitem>
<para>Leonid Mamtchenkov</para>
</listitem>
<listitem>
<para>Tino Meinen</para>
</listitem>
<listitem>
<para>Frederick Noronha</para>
</listitem>
<listitem>
<para>Jeffrey C. Ollie</para>
</listitem>
<listitem>
<para>Donald A. Peterson</para>
</listitem>
<listitem>
<para>Guillaume Pratte</para>
</listitem>
<listitem>
<para>Laurent Protois</para>
</listitem>
<listitem>
<para>Matthieu Pupat</para>
</listitem>
<listitem>
<para>Trevor Rhodes</para>
</listitem>
<listitem>
<para>Alexander Roitman</para>
</listitem>
<listitem>
<para>Jason Salaz</para>
</listitem>
<listitem>
<para>Julio Sanchez</para>
</listitem>
<listitem>
<para>Bernd Schandl</para>
</listitem>
<listitem>
<para>Martin Senftleben</para>
</listitem>
<listitem>
<para>Gary Shao</para>
</listitem>
<listitem>
<para>Jim Smart</para>
</listitem>
<listitem>
<para>Steve Swales</para>
</listitem>
<listitem>
<para>Eero Tamminen</para>
</listitem>
<listitem>
<para>Samuel Tardieu</para>
</listitem>
<listitem>
<para>Richard Taylor</para>
</listitem>
<listitem>
<para>James Treacy</para>
</listitem>
<listitem>
<para>Sebastian Voecking</para>
</listitem>
<listitem>
<para>Xing Wang</para>
</listitem>
<listitem>
<para>Tim Waugh</para>
</listitem>
<listitem>
<para>Jesper Zedlitz</para>
</listitem>
</itemizedlist> If you know of somebody else who should be listed here,
please let us know.</para>
<para>To find more information about GRAMPS, please visit the <ulink
type="http" url="http://gramps-project.org">GRAMPS Project Web
page</ulink>.</para>
<para>To report a bug or make a suggestion regarding this application or
this manual, use the help menu in GRAMPS, or follow the directions on
<ulink type="http" url="http://gramps.sourceforce.net/contact.html">this
site.</ulink></para>
<para>This program is distributed under the terms of the GNU General
Public license as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version. A copy of
this license can be found at this <ulink type="help"
url="ghelp:gpl">link</ulink>, or in the file COPYING included with the
source code of this program.</para>
</appendix>
</book>
Reference in New Issue View Git Blame Copy Permalink