FTree User manual

This manual contains things that I think are useful and things that people have asked. If it doesn't answer your questions about how to use FTree.. email me and ask

Index


FTree Overview

FTree is a Linux application that allows you to create, view, edit and print genealogy data.

FTree is stand-alone and makes very few assumptions about your Linux environment. It does not depend on any specific desktop, distribution or version. All it requires is an X-Windows display, though it does have a limited command line mode that is appropriate for some scripted applications. It is distributed as a static linked executable that generally will run "out-of-the-box". There is no charge for FTree.

Data formats

FTree understands GEDCOM. GEDCOM is *the* standard way of sharing genealogy data. Almost all geanealogy tools can import and export GEDCOM. FTree uses GEDCOM as its native format. GEDCOM is text based and you can view the files in a text editor, though they can be complex. GEDCOM was created and defined by the The Church of Jesus Christ of Latter-day Saints and is extreemely powerful and flexible.

FTree will import trees exported from many commercial (non-Linux) genealogy applications. If you find a tree that it can't import, please let me know and I'll try to fix it.

Because GEDCOM is so versatile, FTree doesn't handle all posible features and some features it will preserve but currently does not provide means to view or edit. Where it detects features it can't handle it will warn when the file is loaded.

Some genealogy programs may also generate incorrect GEDCOM. Where possible FTree handles that as gracefully as it can. I attempt to fix problems I'm aware of.

See the section on compatability for more detail.

Practical Limits
FTree is designed as a small-medium size genealogy application. It holds things in memory while its working. In practical terms, that means on my old 486DX2 with 48M memory it is OK with trees of 1000+ people and gets pretty sluggish (probably too slow for practical use) at 5000 people. On a more modern system its probably fine upto about 10000-20000 people. Beyond that you need something with a proper database.

FTree can load files with many generations, the biggest I've seen is about 70.

Starting FTree

FTree is started from an Xterm or a GUI file browser. Just run "ftree". It is normally installed in "/usr/bin" or on older versions "/usr/X11R6/bin", but you can install it anywhere.

There are a number of arguements it will accept on the command line, but the most useful is the name of the file to open. If you don't provide a filename it will attempt to open the last file you worked on.

For more information on the commandline options see the man page and the section on commandline mode

The main window

The main window is divided into 3 main areas.
  1. the data entrypanel on the left is used to enter and display data.
  2. the pedigree panel and associated buttons on the right is used for navigation and to display a graphical pedigree picture.
  3. the roots browser at the bottom right of the main window allows the selection of "tree segments"

In addition to these main parts, there is a row of pulldown menu options at the top left which handle files, allow edit and delete options and control options.

The data entry panel

The data entry panel is built up from a series of overlayed sheets each selected by a tab at the top. There are currently four sheets, General, INDI, MARR and INFO.
General Tab
The general tab gives overview data. It is designed to provide enough information to do simple tree navigation and to add new individuals.

Force toggle button FTree will automatically take a surname from the persons father. This means that the surname will be inherited down the tree. However sometimes there is no father or the person may have taken a different surname or a different spelling of a surname. In this case you can enter a surname in the "surname" field in the GUI. When you do this the force indicator toggles to indicate that the surname has been "forced". Un-forcing will cause the surname to be calculated from the father again.

INDI Tab
MARR Tab
Move Tab
The Move tab provides the facilities to move individuals in and out of families. This allows marrying and unmarrying individuals and adding children or full branches into families.

There are 2 sections. The top half allows you to select the family you want to add to, and the bottom half allows you to select the individual to move into that family.

To move a child into a family, just select the parents in the top half of the screen, select the child in the lower half and press the move child into family button. If necessary this will detach the child from any current parents and move it into the new family.

To just detach a child from its current family, just select it in the lower half of the screen and press the unlink child from family button. In this case it doesn't matter whats selected in the top half of the screen.

To marry a spouse into a family, select the person to marry to in the top half of the screen and the person to marry in the bottom half. There are two options for how to marry individuals. If there is a family with only one spouse, the spouse window will show unknown. In this case using the marry spouse into family button will make the person in the lower window become the "unknown" spouse, whereas the marry to individual button will create a new family.

For example if there are kids already in the tree, attached to one spouse, make sure the spouse with the kids is the one in the "Family" panel and the "missing" spouse in the "Person to Move" panel and use marry spouse into family.. e with the kids here.

To unmarry two individuals, select them in the top half of the screen and press the unmarry spouse from family button. The spouse will be detached from the family, leaving children and any other data still in place.

Selection of individuals can be done by either finding then on the browsers or entering their IDs in the ID windows or using the large left arrow buttons that will take the trees current selected node.
The display buttons will make the chosen individual the current selected individual in the tree diagram.

LDS Tab
This allows entry of LDS "Baptism", "Endowment", "Child Sealing" and "Family Sealing" events. You only need to care about this if there is any chance you are going to submit back the the master LDS records.

I'm not aware of anyone who has ever actually used this in anger.

INFO Tab
This sheet has the GEDCOM header data on it. The fields are not changable but allow you to see information about the file and where it has come from.

The pedigree panel or "Canvas"

This panel allows the display of pedigree diagram of the currently selected part of the tree. (I often refer to this as the display canvas). The currently selected individual will be displayed in red with the current spouse and child displayed in orange. Generally all other individuals will be displayed in green.

Pedigree panel mouse buttons
Within this panel, the mouse is active and all three mouse buttons perform different functions. The default configuration is

It is possible to change the button assignments using the canvas_buttons configuration option.

Below the pedigree panel there are up to five buttons. The final two are only visible if you enlarge the main window.

The Roots Browser

The roots browser displays all unique roots of the currently loaded tree. The tree roots are determined automatically when the data file is loaded. The definition of a tree root is any individual with no ancestors and who has a spouse with no ancestors. Additionally the spouse must not already be in a tree as another root.

Clicking on one of the entries in the roots browser will change the segment of data displayed in the pedigree panels to be the one selected. If the current individual does not appear in the new tree segment, the root of the new segment will become the new selected individual.

Compatability Issues

This section provides more detail about features of FTree that may be relevant if you need to work with other genealogy systems.

FTree should be able to read data from any application that exports a "lineage-linked" GEDCOM. I know FTree has imported files from a large number of applications. I have tested files from
ApplicationVersions
LifelinesLIFELINES 3.0.2
Family Tree Maker for WindowsFTW 4.0, 6.0, 9.0
Family Origins(R) for WindowsFamilyOrigins 6.0
Personal Ancestral FilePAF 4.0.4.18, 5.1.12.0
Brothers KeeperBROSKEEP 5.2 WINDOWS, 6.0 WINDOW
GeneWebgwb2ged 2.07
Family Tree for JavaFAMILY_TREE_FOR_JAVA 0.0.8
Visual GenealogieVISUGENE 2000.02.28
Scion GenealogistSCION_AMIGA 5.08

It is likely that some GEDCOM tags will not be handled. When this happens, FTree shows a warning dialog when the file is loaded, detailing the number of lines it couldn't handle and providing some information about whats in the line. By using the .ftree logfile option this can also be stored to file for later analysis.

Date formats

GEDCOM is fairly clear about date formatting, but does also permit a free-form text string. Unfortunately many geneology programs export GEDCOM files with very non-standard date strings and also non-date data in the date fields. FTree actually tries to decode dates fully and recodes them in a standard format.

To allow maximum inteoperability, FTree tries hard to work out what was intended and will cope with many different forms. If all else fails FTree will now fall back to storing the un-decoded text.

Patterns used are day month year, year month day and month day year. FTree uses simple heuristics to guess the format, for instance if the 2nd field is greater than 12, but less than or equal to 31, it could be the day, so look at the first field and see if it could be the month. Note that dates like 2 3 2005 could be day-month or month-day so will be decoded by the 1st patern. Hence in this case it will be interpreted as the 2nd march. Ideally months should be supplied textually, eliminating such ambiguity. The minimum abreviations accepted for months are "ja","f","mar","ap","may","jun","jul","au","s", "o","n","d".

The following qualifiers and text in dates are supported, some are GEDCOM standard and some are ones I have found in other peoples files; "abt" or "about", "cir" or "c ", "bet", "est", "cal", "bef", "aft", "nth qtr", "nth quarter", "and".

FTree supports only the standard gregorian calendar, mainly because I don't understand the other GEDCOM calendars and I've not had anyone want them.

FTree will use space, slash, dash, dot, comma or tab as seperators within a date.

FTree will also accept a "?" appended to many date fields.

The following are examples of correctly parsed dates, this is not exhaustive.

	23 jan 2002, 23/jan/2002, 23-jan-2002 or 23.jan.2002 or 23,jan,2002
	jan 23 2002, jan 2002, 2002, 2002 jan, 2002 jan 23
	q1 2002, 1st qtr 2002, 1st Quarter 2002
	abt 23 jan 2002     or about 23 jan 2002
	cir 23 jan 2002     or c 23 jan 2002
	bef 23 jan 2002
	aft 23 jan 2002
	bet 22 jan 2002 and 2002 jan 24
	bet 22 jan 2002 - 2002 jan 24
	est bet est 23 jan 2002 and cal 28 jan 2002

GEDCOM Limits

GEDCOM imposes limits on many field lengths. At this time, FTree does not police or enforce those limits. As such FTree can write files that applications that rely on the limits may have problems with.

Reports, Printing and Plotting

FTree allows a number of different print an plot reports to be generated. As of version 2.0, they are all (except the user configurable report) accessed from the File->Reports menu.

Reports can be displayed in a window on screen, sent to a printer or left in a file. The graphic reports are generally only file or printer.

FTree generally generates postscript output, either directly as with the plotting functions, or via helper applications as for printing. It assumes you either have a postscript printer or a printer device that runs through a filter.

To output direct to a printer, put the printer queue name (eg lp or ps) in the "to printer" box and make sure the printer type is set to "postscript".
Alternatively, to just leave the output in a file, click on the "output to file" toggle and put a file name there (eg plot.ps). This will save the postscript data to the file but not attempt to send it to the printer.

Some of the print reports use groff and nenscript as helpers. The commands used are

	nenscript -B -1 -W -fCourier8 -Pxxxx
or
	groff -t -mm -Tps | lpr -Pxxxx
where the xxxx will be replaced with the printer name.

The nenscript option is used for printing single entries.

Note that for plotting, a paper size of A4 is assumed. You can change it by setting the "plot_papertype" .ftree option. FTree knows about A0, A1, A2, A3, A4, A5, A6, B0, B1, B2, B3, B4, B5, ArchE, ArchD, ArchC, ArchB, ArchA, Foolscap, Letter, Legal.

There are a number of different reports that can be generated

Full details

Data on everyone in the tree in ID order (this does not at the moment print all the data - I need to fix that)

Graphic Chart

A postscript version of whats shown on the display canvas chart.

Web Chart

An html version of a piece of the display canvas chart in 'lineart'. If you wish to use this inconjunction with the Web Details report, enable the HTMI INDI Links option and put the file in the directory generated by the Web Details report. The links will then all tie up.

Web Details

An html navigable dump of a part of the tree. Generates a main html file, and a directory of individual data files. Give a file name of mytree.html this generates that file and a directory mytree_files.

Related Marriages

Ever wanted to know if any couple in the tree have a blood tie? This will tell you.

Event Locations

A list of events

Indented Desendant

The traditional descendant list

Dot Bloodline File

This will generate a raw 'dot' file that can be fed into the graphviz package to generate a graphic tree picture. you need to run dot to make the picture. There is a version of dot (called ftree-dot) available with of the FTree release.

The command for dot is placed in a comment at the top of the dot file.

In the dot image, gender is indicated by colour, F=pink, M=blue and unknown is yellow.

Dot FamilyLine File

Similar to the Dot Bloodline File but shows familes and mariages as well as individuals. Marriages are shown as brown trapezoids.

User configurable report

This option does not yet appear in the GUI menus. It is only available via the command line/script mode facility.

This is a generic report generator. It is still fairly embryonic, but allows you to define your own report. It includes access to a number of data fields and the ability to navigate the tree. The detail is likely to change and may move to be more XML like in future.

To use this feature you need to make a report format configuration file. An example is provided in the release, normally installed in

	/usr/share/ftree-version/examples/ftree.fpt
To use it you need to run FTree from a command line with the -nox option. The following example will pick up royal.ged and ftree.fpt from the current directory and generate myreport.txt.
	echo "gprint ftree.fpt myreport.txt" | ftree -nox royal.ged
See the section on script mode for more detail of how to use the FTree command line mode and what other commands are available. Eventually this command will be integrated into the GUI.

The example ftree.fpt file includes some comments about how to use the facilities. This is still very embryonic and experimental.

gprint is a simple substitution mechanism. At its core is a series of stacks of individuals that it is going to report data for. Initially there is one stack and it has one person in it. That is the current individual. The current individual is (in order of priority) either the person set with a currentindi command, the current person stored in the .ftree file or the first person in the GEDCOM file.

For each individual on the stack the same data is reported and the same actions carried out. You then choose to add other individuals. Actions allow you to push other people on the current stack, or create a new stack. You can push onto the top or the bottom of the stack.

Data or actions are indicated by "Tags". A tag is a sequence like


	_SNAME_: _BIRTH_._DATE_

This sequence will report the surname of the current person and the birth date seperated by a colon. Typical output would be

	Jones: 12 Dec 2002

The ".fpt" control file contains three sections. One provides a header prefix on the file, one a trailer postfix and the third the main person data. In the prefix and postfix no tag substitution happens. They are just output verbatim.
A typical ".fpt" file would contain


	_HEADSTART_
	Header text
	_HEADEND_

	_TAILSTART_
	Trailer text
	_TAILEND_

	_PERSONSTART_
	The real per-person body
	_PERSONEND_

The data tags that can be used in the main person section are as follows:

The control tags that can be used in the main person section are as follows:

Script Mode

FTree has a basic script mode that will allow access to a small subset of functions from a commandline/script environment without needing an X-windows display.

This is accessed by starting FTree with


	ftree -nox filename.ged

This will provide an "ftree>" prompt.

This facility is at an early stage of development. At present the only useful thing it provides acces to is the textmode plotting functions.
A simple example would be

	ftree -nox filename.ged
	ftree> currentindi 5
	ftree> set plot_options "ancestor descendant"
	ftree> textplot plot.txt
	ftree> set plot_options "ancestor descendant html html_indilinks"
	ftree> textplot plot.html
	ftree> exit
This would select the person (INDIvidial) with ID 5 in the tree and then do a text plot to plot.txt and a plot with html options enabled to plot.html.
An example of scripted usage would be
	/bin/echo 'currentindi 5\ntextplot plot.txt' | ftree -nox mytree.ged

Script commands

Configuration files and variables

These variables can be set in the .ftree configuration file and modified when in script mode with the set command.

The .ftree file should be placed in your home directory. FTree will load it on startup and then may update some values in the file whilst running.
Some variables are used by FTree to store internal state and user preferences between sessions. Some are set on the preferences panel, some implicitly by the program and a few can only be set directly in the .ftree file.

Internationalisation

Normally internationalisation is handled by the GUI toolkit. Unfortunately the toolkit used in FTree does not have that kind of support.

This means that its a little more work to handle extended characters, however it is possible in a number of cases. If you are having problems and want to investigate the problem, please contact me. I have a system with a simple window manager and US-ascii keyboard, so testing is hard. Support requires 2 components which are set up independently. Firstly you need to ensure the correct display fonts are loaded. The GUI toolkit only supports 8-bit and not 16-bit fonts. If your local language can be handled by an 8-bit font, it should be possible to display those characters. For Europe, a suitable font may be the iso8859-2 font. This has standard 7-bit ascii characters in the first 128 characters an an assortment of other extended characters in the second 128 positions. FTree is more or less 8-bit clean internally so this can work well. As a test there is a simple gedcom file that displays the full 8-bit character set. The results should look as below for some standard fonts.
ISO8859-1
ISO8859-2

See below for more information about fonts and font probing.

Once the display problem is resolved, the second issue is to be able to handle the characters from the keyboard. How you do this depends on your setup. If you are using your X-Windows server to manage internationalisation then the keyboard keys are mapped automatically and the correct key codes should be sent to FTree.
If you are using a display manager to provide the mapping, the keys will arrive incorrectly and you need to tell FTree how to perform the mapping you want.

There is a facility in FTree that will allow the use of the ALT key to indicate these special characters. For example, ALT-A could be made to generate A-Acute.

This is accomplished using the metacharacters option in the .ftree file. To use this option you must have at least software version 2.0.4 (not 2.0).

Polish
I think you want A-comma, C-acute, E-comma, L-cross, N-acute, O-acute, S-acute, Z-acute, Z-dot

        
    metacharacters a=0xb1,A=0xa1,c=0xe6,C=0xc6,e=0xea,E=0xca,l=0xb3,L=0xa3,n=0xf1,
        N=0xd1,o=0xf3,O=0xc3,s=0xb6,S=0xa6,z=0xbc,Z=0xac,.=0xbf,>=0xaf
It needs to be one single line. It puts Z-dot on the .> key.

Czech
I think for czech you want the following characters
A-Acute, C-Caron, D-Caron, E-Acute, E-Caron, I-Acute, N-Caron, O-Acute, R-Caron, S-Caron, T-Caron, U-Acute, U-Ring, Y-Acute, Z-Caron

  metachatacters a=0xe1,A=0xc1,c=0xe8,C=0xc8,d=0xef,D=0xcf,e=0xe9,E=0xc9,
        i=0xed,I=0xcd,n=0xf2,N=0xd2,o=0xf3,O=0xd3,r=0xf8,R=d8,s=0xb9,S=0xa9,t=0xbb,T=0xab,
        u=0xfa,U=0xda,y=0xfd,Y=0xdd,z=0xbe,Z=0xae
This must be entered as a single line, and does not map e-caron or u-ring.

Fonts

FTree uses 2 different sets of fonts by default. One set is loaded by xforms and this is used for all the buttons, menus and textboxes. They are set by doing a lookup on a set of strings like

	"-*-helvetica-medium-r-*-*-*-*-*-*-p-*-*-*"
	"-*-helvetica-medium-o-*-*-*-*-*-*-p-*-*-*"
	"-*-courier-medium-r-*-*-*-*-*-*-m-*-*-*"

The other is used for doing the displays on the graphics canvases. This second font is by default the same as the X-server default font. (note that the X-server default font can be changed using the "-fn font" option to the server - see the man page Xserver(1)) On my system this is set to the alias "fixed" which translates to

	-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-1

It is possible to override both sets of fonts with an additive mask. Setting the variables font and canvasfont in the .ftree file will allow fonts to be changed.

The variables take the same format as a font string name. Any section that is left blank will use the default value built into ftree. so setting font to the value

	font -------------iso8859-2
will attempt to find an iso8859-2 (east europe) version of the standard fonts.
The base font string for the canvasfont is
	"-*-fixed-medium-r-semicondensed-*-*-120-*-*-*-*-*-*"

Useful tips

You can see your font path by using

	xset q
You can look at what fonts match a specific font description using xlsfonts for example
        xlsfonts -fn '-*-helvetica-medium-r-*-*-*-100-*-*-p-*-*-*'

will give something like

        -adobe-helvetica-medium-r-normal--10-100-75-75-p-0-iso8859-1
        -adobe-helvetica-medium-r-normal--10-100-75-75-p-0-iso8859-2
        -adobe-helvetica-medium-r-normal--10-100-75-75-p-56-iso8859-1
        -adobe-helvetica-medium-r-normal--10-100-75-75-p-56-iso8859-2
Which one loaded will depend on the order of your fontpath. An other tool thats useful is xfontsel.

For the European fonts based on iso8859-2 the rpm packages I needed could be checked for as follows

	rpm -q fonts-ISO8859-2
	rpm -q fonts-ISO8859-2-75dpi
	rpm -q fonts-ISO8859-2-100dpi

Note that in some places you may see a single '?' in the middle of the font string like

	"-*-helvetica-medium-r-*-*-*-?-*-*-p-*-*-*"
This is used by xforms to substitue the character size. Normal text is 100 and menus are often 120.

Good references for font information include

Startup processing

When FTree starts it reads configuration information from 3 places Where a configurable option can be set in more than one place, the command line will always override the config file which in turn will override the Xresource database.
The following options can be set
OptionDescriptionXrdb.ftreecommand line
Geometry Main window initial size and position ftree*geometry: geometry -geometry
Colour mode Sets traditional or "washes whiter" colour scheme ftree*whitewash: colour_mode whitewash -whitewash

Last modified: _LAST_MODIFIED_
Email: