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. Starting gramps opens the Main window, shown in . The window is at first empty.

gramps Main Window

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.

"Category/report name" def report(database,person): ... actual code ... def get_description(): return "A detailed text description of what the report generator does" def get_xpm_image(): return [ "... XPM image data" ]

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