<!DOCTYPE article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
<!ENTITY version "0.2.0"> <!-- replace with application version -->
]>
<!--
This is a GNOME documentation template, designed by the GNOME
Documentation Project Team. Please use it for writing GNOME
documentation, making obvious changes. In particular, all the words
written in UPPERCASE (with the exception of GNOME) should be
replaced. As for "legalnotice", please leave the reference
unchanged.
Remember that this is a guide, rather than a perfect model to follow
slavishly. Make your manual logical and readable. And don't forget
to remove these comments in your final documentation! ;-)
-->
<!--
(Do not remove this comment block.)
Maintained by the GNOME Documentation Project
http://developer.gnome.org/projects/gdp
Template version: 1.0.3
Template last modified: Nov 16, 2000
-->
<!-- =============Document Header ============================= -->
<article id="index"> <!-- please do not change the id -->
<artheader>
<title>gramps User Manual</title>
<copyright>
<year>2001</year>
<holder>Donald N. Allingham</holder>
</copyright>
<!-- translators: uncomment this:
<copyright>
<year>2001</year>
<holder>ME-THE-TRANSLATOR (Latin translation)</holder>
</copyright>
-->
<!-- do not put authorname in the header except in copyright - use
section "authors" below -->
<!-- Use this legal notice for online documents which depend on -->
<!-- core GNOME packages. -->
<legalnotice id="legalnotice">
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the <ulink type="help"
url="gnome-help:fdl"><citetitle>GNU Free Documentation
License</citetitle></ulink>, Version 1.1 or any later version
published by the Free Software Foundation with no Invariant Sections,
no Front-Cover Texts, and no Back-Cover Texts. A copy of the license
can be found <ulink type="help" url="gnome-help:fdl">here</ulink>.
</para>
<para>
Many of the names used by companies to distinguish their products and
services are claimed as trademarks. Where those names appear in any
GNOME documentation, and those trademarks are made aware to the members
of the GNOME Documentation Project, the names have been printed in caps
or initial caps.
</para>
</legalnotice>
<!-- Use this legal notice for documents which are placed on -->
<!-- the web, shipped in any way other than online documents -->
<!-- (eg. PS, PDF, or RTF), or which do not depend on the -->
<!-- core GNOME distribution. -->
<!-- -->
<!-- If you use this version, you must place the following -->
<!-- line in the document declaration at the top of your -->
<!-- document: -->
<!-- <!ENTITY FDL SYSTEM "fdl.sgml"> -->
<!-- and the following line at the bottom of your document -->
<!-- after the last </sect1>. -->
<!-- &FDL; -->
<!--
<legalnotice id="legalnotice">
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the <link linkend="fdl"><citetitle>GNU
Free Documentation License</citetitle></link>, Version 1.1 or any later
version published by the Free Software Foundation with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the
license can be found in <xref linkend="fdl">.
</para>
<para>
Many of the names used by companies to distinguish their products and
services are claimed as trademarks. Where those names appear in any
GNOME documentation, and those trademarks are made aware to the members
of the GNOME Documentation Project, the names have been printed in caps
or initial caps.
</para>
</legalnotice>
-->
<!-- This is the manual version, not application version. -->
<releaseinfo>
This is version 1.0 of the gramps manual.
</releaseinfo>
</artheader>
<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
<sect1 id="intro">
<title>Introduction</title>
<para>
gramps is an acronym for the Genealogical Research and Analysis
Management Programming System. It was conceived under the concept
that most genealogy programs were designed to provide the
researcher the capability to input information related to a
particular family tree. Most of these programs have allowed for
the arranging and storing of information consistent with the
GEDCOM standards. They usually provide a means for displaying
descendant or ancestral relationships by means of graphical
displays, charts, or reports. These may be augmented with
pictures or other media to enhance the data. Most provide for
inputting data on unconnected individuals/families that may or may
not have a relationship to the primary surname being researched.
Various other enhancements may also be provided in the
genealogical program that allows for different degrees of
importing and exporting data from other programs and printing of
the data contained in the various reports. gramps, on the other
hand, attempts to provide all of the common capabilities of these
programs, but, more importantly, to provide a capability not
common to these programs. This is the ability to input any bits
and pieces of information directly into gramps and
rearrange/manipulate any/all data events in the entire data base
(in any order or sequence) to assist the user in doing research,
analysis and correlation with the potential of filling
relationship gaps. In short, a tool that provides a way to input
all your research into one place and do your analysis and
correlation using the speed, power, and accuracy of your computer
instead of pencils and unmanageable reams of paper.
</para>
<para>
To run <application>gramps</application>, select
<menuchoice>
<guisubmenu>Programs</guisubmenu>
<guisubmenu>Applications</guisubmenu>
<guimenuitem>gramps</guimenuitem>
</menuchoice>
from the <guimenu>Main Menu</guimenu>, or type
<command>gramps</command> on the command line.
</para>
<para>
<application>gramps</application> is included in the
<filename>gramps</filename> package, which is part of the
GNOME desktop environment. This document describes version
&version; of <application>gramps</application>.
</para>
</sect1>
<!-- ================ Usage ================================ -->
<!-- This section should describe basic usage of the application. -->
<sect1 id="usage">
<title>Using gramps</title>
<para>
<application>gramps</application> is a genealogy program.
This section describes basic usage of
<application>gramps</application>.
</para>
</sect1>
<sect1 id="firsttime">
<title>Running gramps for the first time.</title>
<para>
This section should discuss the start up druid.
</para>
</sect1>
<sect1 id="mainwindow">
<title>Main Window</title>
<para>
Starting <application>gramps</application> opens the
<interface>Main window</interface>, shown in <xref
linkend="mainwindow-fig">. The window is at first empty.
<!-- ==== Figure ==== -->
<figure id="mainwindow-fig">
<title>gramps Main Window</title>
<screenshot>
<screeninfo>gramps Main Window</screeninfo>
<graphic fileref="mainwin" format="PNG" srccredit="Don Allingham">
</graphic>
</screenshot>
</figure>
<!-- ==== End of Figure ==== -->
</para>
</sect1>
<!-- ========= Basic Usage =========================== -->
<sect1 id="personlist">
<title>Person List</title>
<para>
The Person List window is the initial view seen on the main
window. It displays the name, gender, birth date, and death
date of all individuals in the database. At any time, you can
return to the this view either by pressing the People button at
the top of the screen, or by choosing the
<menuchoice>
<guisubmenu>View</guisubmenu>
<guimenuitem>Person List</guimenuitem>
</menuchoice>
entry from the menus.
</para>
<sect2>
<title>Selecting and Editing Individuals</title>
<para>
The Person List view lists the individuals in the database. A
individual can be selected as the active person by clicking on
an entry in the list. Once a person has been selected as the active
person, the person's name appears in the status bar in the lower
left hand corner of the window.
</para>
<para>
Once the active person has been selected, pressing the Edit
Person button will display the Edit Person dialog allowing you
to edit the individual's personal information. If the Edit
Person button is pressed without an active person being set, a
blank Edit Person dialog is presented, allowing you to enter a
new person. Double-clicking on a entry will set the active
person and bring up the individual in the Edit Person dialog.
</para>
<para>
Pressing the Add Person button will display a blank Edit Person
dialog, allowing you to add a new person to the database.
</para>
<para>
If the Delete Person button is pressed, the active person and
all of the personal information related to the active person are
removed from the database.
</para>
</sect2>
<sect2>
<title>Applying Filters</title>
<para>
<application>gramps</application> allows you to apply filters to
the Person List. When a filter is applied, the Person List will
only display the entries matching the filter. All of the entries
remain in the database, but are temporarily hidden.
</para>
<para>
There are three parts to a filter. The first part is the
selection of the filter to be applied. A filter is selected from
the option menu directly above the Person List. The second part
is an option qualifier. This qualifier provides more specific
information for the filter. Many filters do not require the
qualifier, and it will be grayed out if not needed. The third
part of the filter is the invert selection. When this option is
selected, <application>gramps</application> will display the
entries that do not match the filter.
</para>
<para>
A filter is not applied until the Apply button is pressed. The
filter will remain in effect until the next time the Apply
button is pressed.
</para>
</sect2>
<sect2>
<title>Sorting</title>
<para>
Four columns are shown in the Person List display. The entries in
the list can be sorted by three of the field: Name, Birth Date, or
Death Date. Clicking on the column label will cause the list to
be resorted by that column. Arrows on the label indicate whether
the list is sort by ascending or descending order.
</para>
<para>
If the list is already sorted by a particular column, clicking on
the same column label will switch sorting order. For example, if
the list is currently sorted in ascending order by Name, clicking
on the Name column header will resort the list in descending order.
</para>
</sect2>
</sect1>
<sect1 id="familyview">
<title>Family View</title>
<para>
The Family View window displays the spouses, parents, and children
of the active person. At any time, you can return to the this view
either by pressing the Family button at the top of the screen, or
by choosing the
<menuchoice>
<guisubmenu>View</guisubmenu>
<guimenuitem>Family View</guimenuitem>
</menuchoice>
entry from the menus.
</para>
<para>
This section should describe the family view.
</para>
</sect1>
<sect1 id="pedegreeview">
<title>Pedegree View</title>
<para>
The Pedegree View window displays the active person, the active
person's parents, and the active parent's grandparents in a somewhat
graphical manner. At any time, you can return to the this view
either by pressing the Pedegree button at the top of the screen, or
by choosing the
<menuchoice>
<guisubmenu>View</guisubmenu>
<guimenuitem>Pedgree</guimenuitem>
</menuchoice>
entry from the menus.
</para>
<para>
This section should describe the pedegree view.
</para>
</sect1>
<sect1 id="sourcelist">
<title>Source List</title>
<para>
The Source List window displays the different sources which have been
entered into the database. At any time, you can return to the this view
either by pressing the Sources button at the top of the screen, or
by choosing the
<menuchoice>
<guisubmenu>View</guisubmenu>
<guimenuitem>Sources</guimenuitem>
</menuchoice>
entry from the menus.
</para>
<para>
This section should describe the source list.
</para>
</sect1>
<!-- ============= Customization ============================= -->
<sect1 id="prefs">
<title>Customization</title>
<para>
To change the application settings, select
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Preferences...</guimenuitem>
</menuchoice>. This opens the
<interface>Preferences</interface> dialog, shown in <xref
linkend="preferences-fig">.
</para>
<figure id="preferences-fig">
<title>Preferences Dialog</title>
<screenshot>
<screeninfo>Preferences Dialog</screeninfo>
<graphic fileref="preferences" format="png" srccredit="Don Allingham">
</graphic>
</screenshot>
</figure>
<para>
</para>
</sect1>
<!-- ============= Generating Reports ============================= -->
<sect1 id="genreports">
<title>Generating Reports</title>
<para>
<application>gramps</application> can produce a wide variety of
reports. New report generators can be written by the user without
modifying the main program. For this reason, there may be more
reports available than are documented by this manual
</para>
<para>
Unlike many genealogy programs, <application>gramps</application>
does not directly print reports. Instead,
<application>gramps</application> produces reports in formats that
are understood by other programs. These formats include OpenOffice,
AbiWord, PDF, and HTML, among others. This allows the generated
reports to be modified after they are generated, stored for use
later, or emailed to another person.
</para>
<sect2 id="htmltemplates">
<title>Using HTML templates</title>
<para>
Many programs exist to convert GEDCOM files into HTML files that
can be viewed in a web browser. Most of these programs generate
HTML files according to their own predefined style. Since most
people have a style that they prefer, they are left with the option
of modifying hundreds of files by hand.
</para>
<para>
To solve this problem, <application>gramps</application> allows the
user to specify a template to be used for generating HTML files. At
the time the report is generated, if HTML is selected as the target
format, the user can select an HTML template to be used. Since the
template is chosen at report generation time, a different template
may be chosen each time, allowing the user to change the appearence
of the generated files at any time. Nearly any existing HTML file
can be used as an HTML template for
<application>gramps</application>.
</para>
<para>
When a file has been established as the HTML template file,
<application>gramps</application> uses the template for each file
that it generates. <application>gramps</application> starts each
file by copying data from the template until it reaches an HTML
comment uses as a marker. At that point,
<application>gramps</application> inserts its data into the output
file. <application>gramps</application> the continues reading the
until it reaches a second comment that tells it to resume copying
from the template.
</para>
<para>
<application>gramps</application> uses the string <function><!--
START --></function> to indicate where it should start inserting
its information, and the string <function><!-- STOP
--></function> to indicate where it should resume copying data
from the template. The effect is that
<application>gramps</application> will create a new document,
replacing everything between the <function><!-- START
--></function> and <function><!-- STOP --></function> comments
with the report information.
</para>
<para>
The comment markers should be at the beginning of a line in the HTML
template file. Adding the comments to an existing HTML document will
not affect the original HTML document in any way.
</para>
<para>
If no HTML template is specified, or if the specified template
cannot be read, <application>gramps</application> will use a
default, predefined template.
</para>
<para>
<figure id="templateexample">
<title>Sample HTML Template Example</title>
<programlisting>
<HTML>
<HEAD>
<TITLE>
This is my Title
</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<P>
This is a simple template. This text will appear in the html output.
</P>
<!-- START -->
<P>
This is where gramps will place its report information. Any
information between the two comments, including this paragraph,
will not appear in the gramps generated output.
</P>
<!-- STOP -->
<P>
This text, since it appears after the stop comment, will also
appear in every gramps generated file.
</P>
</BODY>
</HTML>
</programlisting>
</figure>
</para>
</sect2>
</sect1>
<!-- ============= Writing Filters ============================= -->
<sect1 id="writingfilters">
<title>Writing Filters</title>
<para>
Users can create their own filters and add them to
<application>gramps</application>. By adding the filter to the
user's private filter directory
(<filename class="directory">~/.gramps/filters</filename>),
the filter will be automatically
recognized the next time that the program is started.
</para>
<sect2 id="createfilter">
<title>Creating a filter</title>
<para>
Filters are written in the <application>python</application>
language. Each filter is initialized with the qualifier string.
The qualifier string passes an additional text string to the
filter. This string can be used to further qualify the filter.
For example, if the filter is used to match names, the qualifier
would be used to provide the name that is being compared against.
</para>
<para>
Each filter is a python class, and should be in its own separate
module (file). The module should consist of the filter class
definition, and three functions —
<function>create</function>, <function>need_qualifier</function>,
and <function>get_name</function>.
</para>
<para>
The <function>create</function> function takes a string as its
only argument, returns a instance of the filter class. The string
argument is the qualifier string used to provide more specific
information.
</para>
<para>
The <function>need_qualifier</function> function takes no
arguments, and returns either a 0 or 1 to indicate if a qualifier
string is needed by the filter. Regardless of what
<function>need_qualifier</function> indicates, a text string is
always passed to the filter and the <function>create</function>
function. The value returned by
<function>need_qualifier</function> indicates to the program
whether or not the qualifier field in the display should be
enabled or disabled.
</para>
<para>
The <function>get_name</function> function is used to provide a
description for the filter. This description is entered into
filter selection menus. If the filter is intended to be used by
others, it should be prepared for internationalization. This is
accomplished by importing the <function>intl</function> module,
add defining <function>_</function> to be
<function>intl.gettext</function>. The string returned by
<function>get_name</function> should be passed through the
<function>_</function> function to allow for conversion to the
target langauge.
</para>
<para>
All filters must be derived from the
<function>Filter.Filter</function> class. The
<function>__init__</function> task may be overridden, but if so,
should call the <function>__init__</function> function on the
<function>Filter.Filter</function> class. The parent class
provides the variable <function>self.text</function>, which
contains the text string passed as the qualifier.
</para>
<para>
All filter classes must define a <function>match</function>
function. The function takes one argument (other than
<function>self</function>), which is an object of type
<function>Person</function> to compare against. The function
should return a 1 if the person matches the filter, or a zero if
the person does not.
</para>
<figure id="filtersrc">
<title>Sample filter implementation</title>
<programlisting>
import Filter
import string
import intl
_ = intl.gettext
# class definition
class SubString(Filter.Filter):
def match(self,person):
name = person.getPrimaryName().getName()
return string.find(name,self.text) >= 0
# module functions
def get_name(s):
return _("Names that contain a substring")
def create(text):
return SubString(text)
def need_qualifier():
return 1
</programlisting>
</figure>
</sect2>
</sect1>
<!-- ============= Writing Reports ============================= -->
<sect1 id="writingreports">
<title>Writing Reports</title>
<para>
Users can create their own report generators and add them to
<application>gramps</application>. By adding the report generator
to the user's private filter directory (<filename
class="directory">~/.gramps/plugins</filename>), the report
generator filter will be automatically recognized the next time
that the program is started.
</para>
<sect2 id="createreport">
<title>Creating a report generator</title>
<para>
Like filters, report generators are written in the
<application>python</application> language. Fewer restrictions
are made on report generators than on filters. The report
generator is passed the current <application>gramps</application>
database and the active person. The generator needs to take
special care to make sure that it does not alter the database in
anyway.
</para>
<para>
The function <function>get_name</function> is used to provide the
name of the the report generator. As with a filter definition,
this string should support internationalization via the
<function>intl</function> module. The returned string consists of
two parts, separated by a forward slash. The first part of the
string is the category of the report generator.
<application>gramps</application> uses this part to group similar
reports together in the interface. The second part of the string
is the actual name of the reprot generator, and will be displayed
in the report menu.
</para>
<para>
A report generator module must supply the
<function>report</function> function, and can optionally define
the <function>get_description</function> and
<function>get_xpm_data</function> functions. The
<function>report</function> takes two arguments — a database
(of type <function>RelDataBase</function>) and the currently
selected person (of type <function>Person</function>). The
<function>report</function> is reponsible for generating the
actual report.
</para>
<para>
If the <function>get_description</function> is defined, it is used
to provide a more detailed description of the report. The
description is used to provide the user with more information in
the report selection window. The function takes no arguments, and
should return a text string.
</para>
<para>
If the <function>get_xpm_data</function> is defined, it is used to
provide an graphic logo for the report in the report selection
window. The function takes no arguments, and should return a list
of strings containing the XPM file data. The XPM image should be
48x48 pixels in size.
</para>
<figure id="reportsrc">
<title>Sample report implementation</title>
<programlisting>
import intl
_ = intl.gettext
def report(database,person):
... actual code ...
def get_description():
return "A detailed text description of what the report generator does"
def get_name():
return _("Category/report name")
def get_xpm_image():
return [
"... XPM image data"
]
</programlisting>
</figure>
</sect2>
<sect2 id="alittlehelp">
<title>A little help - Format Interfaces</title>
<para>
<application>gramps</application> provides some help with writing
reports. Several generic python classes exist that aid in the
writing of report generators. These classes provide an abstract
interface for a type of document, such as a drawing, word
processor document, or a spreadsheet. From these core classes,
<application>gramps</application> derives interfaces to various
document formats. This means that by coding to the generic word
processing class (<function>TextDoc</function>), a report
generator can instant access to multiple file formats (such as
HTML, OpenOffice, and AbiWord).
</para>
<para>
This scheme of deriving a output format from a generic base class
also makes it easier to add new formats. Creating a new
derivied class targeting a different format (such as
<application>KWord</application> or
<application>LaTeX</application>) makes it easy for existing
report generators to use the new formats.
</para>
</sect2>
</sect1>
<!-- ============= Writing Tools ============================= -->
<sect1 id="writingtools">
<title>Writing Tools</title>
<para>
</para>
</sect1>
<!-- ============= Various Sections ============================= -->
<!-- Here you should add, if necessary, several more sect1's,
describing other windows (besides the main one), file formats,
preferences dialogs, etc. as appropriate. Try not to make any of
these sections too long. -->
<!-- ============= Bugs ================================== -->
<!-- This section should describe known bugs and limitations of
the program if there are any - please be frank and list all
problems you know of. -->
<sect1 id="bugs">
<title>Known Bugs and Limitations</title>
<para>
This application has no known bugs.
</para>
</sect1>
<!-- ============= Authors ================================ -->
<sect1 id="authors">
<title>Authors</title>
<para>
<application>gramps</application> was written by Donald N. Allingham
(<email>donaldallingham@home.com</email>). To find more information about
<application>gramps</application>, please visit the <ulink
url="http://gramps.sourceforge.net" type="http">gramps Web
page</ulink>.
</para>
<para>
This manual was written by Donald N. Allingham
(<email>donaldallingham@home.com</email>) and Lawrence L. Allingham
(<email>llkla@erinet.com</email>).
</para>
<!-- For translations: uncomment this:
<para>
Latin translation was done by ME
(<email>MYNAME@MYADDRESS</email>). Please send all comments and
suggestions regarding this translation to SOMEWHERE.
</para>
-->
</sect1>
<!-- ============= Application License ============================= -->
<sect1 id="license">
<title>License</title>
<para>
This program is free software; you can redistribute it and/or
modify it under the terms of the <ulink type="help" url="gnome-help:gpl">
<citetitle>GNU General Public License</citetitle></ulink> as
published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later
version.
</para>
<para>
This program 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
<citetitle>GNU General Public License</citetitle> for more details.
</para>
<para>
A copy of the <citetitle>GNU General Public License</citetitle> is
included as an appendix to the <citetitle>GNOME Users
Guide</citetitle>. You may also obtain a copy of the
<citetitle>GNU General Public License</citetitle> from the Free
Software Foundation by visiting <ulink type="http"
url="http://www.fsf.org">their Web site</ulink> or by writing to
<address>
Free Software Foundation, Inc.
<street>59 Temple Place</street> - Suite 330
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
<country>USA</country>
</address>
</para>
</sect1>
</article>