From 02adfa2bfc1f3c2638422dd139f5b4781b99f759 Mon Sep 17 00:00:00 2001 From: Don Allingham Date: Fri, 1 Jun 2001 01:20:50 +0000 Subject: [PATCH] updated documentation svn: r75 --- gramps/doc/gramps.sgml | 212 +++++++++++++++++++++++++++++++---------- 1 file changed, 161 insertions(+), 51 deletions(-) diff --git a/gramps/doc/gramps.sgml b/gramps/doc/gramps.sgml index 2b0312ec9..df6769982 100644 --- a/gramps/doc/gramps.sgml +++ b/gramps/doc/gramps.sgml @@ -33,7 +33,7 @@
- GRAMPS User Manual + gramps User Manual 2001 Donald N. Allingham @@ -42,7 +42,7 @@ - This is version 1.0 of GRAMPS manual. + This is version 1.0 of the gramps manual. @@ -118,7 +118,7 @@ Introduction - GRAMPS is an acronym for the Genealogical Research and Analysis + 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 @@ -133,11 +133,11 @@ 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 + 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 + 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 @@ -146,10 +146,8 @@ correlation using the speed, power, and accuracy of your computer instead of pencils and unmanageable reams of paper. - - - To run GRAMPS, select + To run gramps, select Programs Applications @@ -157,13 +155,12 @@ from the Main Menu, or type gramps on the command line. - - + - GRAMPS is included in the + gramps is included in the gramps package, which is part of the GNOME desktop environment. This document describes version - &version; of GRAMPS. + &version; of gramps. @@ -172,26 +169,26 @@ - Using GRAMPS + Using gramps - GRAMPS is a genealogy program. + gramps is a genealogy program. This section describes basic usage of - GRAMPS. + gramps. Person List - Starting GRAMPS opens the + Starting gramps opens the Main window, shown in . The window is at first empty.
- GRAMPS Main Window + gramps Main Window - GRAMPS Main Window + gramps Main Window @@ -248,13 +245,118 @@ + + + + Generating Reports + + 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. + + + Using HTML templates + + 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. + + +
+ Sample HTML Template Example + +<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> + +
+ + + + + Writing Filters Users can create their own filters and add them to - GRAMPS. By adding the filter to the + gramps. By adding the filter to the user's private filter directory (~/.gramps/filters), the filter will be automatically @@ -273,8 +375,9 @@ 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 two functions — create, - and need_qualifier. + definition, and three functions — + create, need_qualifier, + and get_name. The create function takes a string as its @@ -294,10 +397,16 @@ enabled or disabled. - The module documentation string (a text string as the first - statement in the module) is used for the description of the - module. This is the description that gets entered into filter - selection menus. + 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 @@ -319,18 +428,24 @@
Sample filter implementation -"Names that contain a substring" - import Filter import string +import intl +_ = intl.gettext + +# class definition class SubString(Filter.Filter): - "Names that contain a substring" 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) @@ -347,7 +462,7 @@ def need_qualifier(): Writing Reports Users can create their own report generators and add them to - GRAMPS. By adding the report generator + 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 @@ -359,20 +474,22 @@ def need_qualifier(): 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 + 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 python documentation string (the first text string and first - statement) of the module is used to name the report generator. The - 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. + 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 @@ -454,19 +571,11 @@ def get_xpm_image(): Authors - GRAMPS was written by Donald N. Allingham + gramps was written by Donald N. Allingham (donaldallingham@home.com). To find more information about - GRAMPS, please visit the GRAMPS Web - page. Please send all comments, suggestions, and bug - reports to the GNOME - bug tracking database. (Instructions for submitting bug - reports can be found - on-line.) You can also use Bug Report - Tool (bug-buddy), available in the - Utilities submenu of Main - Menu, for submitting bug reports. + gramps, please visit the gramps Web + page. @@ -531,3 +640,4 @@ def get_xpm_image(): +