2001 Donald N. Allingham Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, 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 here. 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. This is version 1.0 of the gramps manual. 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. To run gramps, select Programs Applications gramps from the Main Menu, or type gramps on the command line. gramps is included in the gramps package, which is part of the GNOME desktop environment. This document describes version &version; of gramps. gramps is a genealogy program. This section describes basic usage of gramps. This section should discuss the start up druid. Starting gramps opens the Main window, shown in . The window is at first empty.

gramps Main Window

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 View Person List entry from the menus. 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. 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. Pressing the Add Person button will display a blank Edit Person dialog, allowing you to add a new person to the database. 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. gramps 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. 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, gramps will display the entries that do not match the filter. 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. 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. 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. 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 View Family View entry from the menus. This section should describe the family view. 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 View Pedgree entry from the menus. This section should describe the pedegree view. 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 View Sources entry from the menus. This section should describe the source list. To change the application settings, select Settings Preferences... . This opens the Preferences dialog, shown in .

Preferences Dialog

gramps 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 Unlike many genealogy programs, gramps does not directly print reports. Instead, gramps 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. 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. To solve this problem, gramps 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 gramps. When a file has been established as the HTML template file, gramps uses the template for each file that it generates. gramps starts each file by copying data from the template until it reaches an HTML comment uses as a marker. At that point, gramps inserts its data into the output file. gramps the continues reading the until it reaches a second comment that tells it to resume copying from the template. gramps uses the string <!-- START --> to indicate where it should start inserting its information, and the string <!-- STOP --> to indicate where it should resume copying data from the template. The effect is that gramps will create a new document, replacing everything between the <!-- START --> and <!-- STOP --> comments with the report information. 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. If no HTML template is specified, or if the specified template cannot be read, gramps will use a default, predefined template.

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

Users can create their own filters and add them to gramps. By adding the filter to the user's private filter directory (~/.gramps/filters), the filter will be automatically recognized the next time that the program is started. Filters are written in the python 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. 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 — create, need_qualifier, and get_name. The create 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. The need_qualifier 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 need_qualifier indicates, a text string is always passed to the filter and the create function. The value returned by need_qualifier indicates to the program whether or not the qualifier field in the display should be enabled or disabled. The get_name 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 intl module, add defining _ to be intl.gettext. The string returned by get_name should be passed through the _ function to allow for conversion to the target langauge. All filters must be derived from the Filter.Filter class. The __init__ task may be overridden, but if so, should call the __init__ function on the Filter.Filter class. The parent class provides the variable self.text, which contains the text string passed as the qualifier. All filter classes must define a match function. The function takes one argument (other than self), which is an object of type Person to compare against. The function should return a 1 if the person matches the filter, or a zero if the person does not.

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

Users can create their own report generators and add them to gramps. By adding the report generator to the user's private filter directory (~/.gramps/plugins), the report generator filter will be automatically recognized the next time that the program is started. Like filters, report generators are written in the python language. Fewer restrictions are made on report generators than on filters. The report generator is passed the current gramps database and the active person. The generator needs to take special care to make sure that it does not alter the database in anyway. The function get_name is used to provide the name of the the report generator. As with a filter definition, this string should support internationalization via the intl 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. gramps 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. A report generator module must supply the report function, and can optionally define the get_description and get_xpm_data functions. The report takes two arguments — a database (of type RelDataBase) and the currently selected person (of type Person). The report is reponsible for generating the actual report. If the get_description 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. If the get_xpm_data 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.

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" ]

gramps 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, gramps derives interfaces to various document formats. This means that by coding to the generic word processing class (TextDoc), a report generator can instant access to multiple file formats (such as HTML, OpenOffice, and AbiWord). 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 KWord or LaTeX) makes it easy for existing report generators to use the new formats. This application has no known bugs. gramps was written by Donald N. Allingham (donaldallingham@home.com). To find more information about gramps, please visit the gramps Web page. This manual was written by Donald N. Allingham (donaldallingham@home.com) and Lawrence L. Allingham (llkla@erinet.com). This program 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 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 GNU General Public License for more details. A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

Free Software Foundation, Inc. 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA