               Geneal - A family tree drawing program
               ======================================

Geneal is a system for outputing a family tree as a set of sheets, each
sheet containing ancestry, a particular generation, and comments.  The
sheets are intended to be held in a loose-leaf binder so that individual
sheets can be replaced as new information comes to hand, or as births or
deaths need to be recorded.  In this way, parts of the tree can be replaced
without having to reproduce the whole tree.  

The system requires access to a PostScript printer or PostScript interpreter,
and is independent of machine apart from this.  It will work on an MS-DOS,
Macintosh, UNIX, or VMS machine.  If you do not have a PostScript printer,
you may be able to get the free PostScript interpreter "GhostScript",
which will run on UNIX, MS-DOS or Macintosh machines, producing a bitmap
which can be viewed on the screen or sent to almost any type of printer.

Geneal consists of four files: 
1  the PostScript program "geneal" for drawing a family tree in separate 
   pages, 

2  a C program "ftindex.c" to build an index of the family tree pages

3  a C program "gedc2ft.c" to convert a GEDCOM file to Geneal format, so
   that it may be printed and have its corresponding index built.  This
   enables a database maintained by some other program to be handled by
   Geneal, assuming that the other program can export a GEDCOM copy of
   the database.

4  a text file "gedcom.tag", used when running "gedc2ft.c".


"geneal"
========
   To use "geneal", you must either have a PostScript printer, or a
   PostScript interpreter program which will convert a PostScript document
   into a bitmap.  You would prepare your family tree as a text file or,
   if you are using a genealogical database program, build the text file 
   by exporting the tree in GEDCOM format and converting to Geneal format
   with "gedc2ft.c".

   You would then copy "geneal" and your text file into a temporary file
   (concatenating them), and send this new file to the PostScript printer.
   The tree will be drawn automatically.

   If you are not using a special database program, then the following
   guidelines should assist in entering your information into the computer.

   Any text editor or word processor can be used for text entry, provided
   that you save the file as raw ASCII and not as a formated document.

   Each page of drawn tree will usually have four sections, a page title,
   an ancestry section, a generation section, and a comment section.  The 
   generation section must be present, the others are optional; however, a 
   new page is only forced when an ancestry section orr page title is 
   encountered after a generation or comment section, or if a generation 
   section is placed after a comment section;  in other words, two consecutive
   generation sections will be placed on the same page.  There can be
   several ancestry sections before a generation section, and all will
   be placed on the same page.

   Page title
   ----------

   A page title can be generated like this:

   <pagetitle>
   Thomas Spence = Nell Watts

   The text of the title must be on the next line following the <pagetitle> 
   keyword.  It will be centred in a bold font.  If any output has been placed
   on a page already, the <pagetitle> keyword will cause that page to be output,
   and the title placed on a new page.

   Ancestry section
   ----------------

   The ancestry section will look like this:

   <ancestry>
   Frederich Kuffner = Anna Margaretha Edinger
   <children>
   <>Charlie 
   <>Adam Kuffner = Amelia Rosalia Kuhn
   <>
   <>Anna 
   <>Peter 
   <>Carl Frederick 
   <>Katherine 
   <>Leonard 
   <>Mary 
	<children>
	<>Fred 
	<>Kate 
	<>George 
	<>Amelia Kuffner = Edmund Spence
	<>Mary 
	<>Margaratha Anna 
	<>Adam 
	<>Charlie 
	<>Teeny 
		<children>
		<>Edward 
		<>Annie 
		<*>Thomas Spence 
		<>Margaret 
		<>William 

   The "<ancestry>" keyword must commence in column 1.  Following this
   will be a person or couple, with their marital relationship indicated by
   "=" for formal marriage or "~" for a relationship of unknown status or
   one lacking formal legal recognition or publicly announced personal
   commitment.

   The "<children>" keyword commences a list of names of children by the
   most recent marital relationship.  

   Each child is preceded by a "<>" or a "<*>" symbol (to be consistent 
   with the generation sections;  any line not beginning with this will 
   be treated as a comment, which will be printed in place but will not 
   have a descent line drawn to it).  All of the children will be placed 
   below and to the right of the most recent line containing "=" or "~", 
   or commencing with "<*>".  In the above example, Charlie, Adam, Anna, 
   Peter, etc, will be placed below and to the right of Frederich;  Fred, 
   Kate, George, etc will be placed below and to the right of Adam Kuffner;  
   Edward, Annie, Thomas, etc will be below and to the right of Amelia 
   Kuffner.  Lines containing an "=", "~", or <*> will be printed in bold, 
   indicating the line of descent.

   There can be several ancestry sections, and each must begin with the
   "<ancestry>" keyword in column 1.  The position on the line of other
   items in the ancestry section is ignored by the program.  The layout
   adopted in the example above is for human readablity, rather than being
   a requirement of the program.

   Generation section
   ------------------

   This will typically look like:

   <generation>
	Thomas Spence [born 1909] =[11 Nov 1931] Nell Watts [born 1911//died 1985]
		<children>
		<>Betty Spence = Laurie Lamont
		   live in Charters Towers
			<children>
			<>Rosalyn Dawn Lamont = Daryl Shaffer
				<children>
				<>Darrin Shafer *
				<>Brendon Shafer
				<>Shannon Shafer
				<>Trent Shafer
				<nomorechildren>
			<>Rhonda Kay Lamont = John Smith
				<children>
				<>Laurel Ann Smith
				<>Sonia Kay Smith
				<nomorechildren>
			<nomorechildren>
		<>Graham Spence 
		   unmarried, living in Charters Towers
		<>Marjorie Spence = William Findley
		   2 children
		<>Norman Spence = Doreen ?
		  lived in Brisbane
			<children>
			<>Mark Spence = Mary ?
	                <nomorechildren>
	             ~ Christine Keeler
	                live in Southport
                        <children>
			<>Tania Spence
			<>Brett Spence
			<nomorechildren>
		<nomorechildren>

   It must begin with the "<generation>" keyword in column 1.

   As with the ancestry section, the next line will be a person or a couple,
   with "=" or "~" indicating their relationship.  Comments can be included
   in square brackets following a name or following the "=", and will be
   placed in a smaller font beneath the item they refer to.  Within the
   comment, "//" is interpreted to mean go to a new line.

   A list of children is preceded by "<children>" and followed by 
   "<nomorechildren>".  Within a list of children, there can be another
   list of children, interpreted as children of the preceding person.
   Each child must have "<>" in front of the name.  Lines not commencing
   with this or any other recognized keyword will be treated as comment
   relating to the previous individual, and will appear in a small font
   beneath that name.

   A convention that I adopt is to append an "*" character to a name if
   that person and descendents appear in more detail on another page.
   I also include a surname for each person rather than having it implied
   from the parents, as this assists in index generation and removes
   possible ambiguity.

   Separation can be indicated with a simple comment, or the keyword
   "<separated>", which will cause an appropriate comment to be placed.
   Divorce is treated similarly, with the keyword "<divorced>" being
   replaced with a comment.

   When a person has married several times, remarriage can be indicated
   by a line commencing with "=", or "~" if a de-facto relationship,
   as in the example above.  This will be drawn suitably below the
   first marriage, and a subsequent children list will be related to this
   relationship.

   A generation section might contain a single family, or grandchildren
   as well, depending on family size, the amount of accompanying comment,
   and the fancy of the person using Geneal.

   Comment section
   ---------------

   Any amount of text can be placed following a line containing "<comment>"
   commencing in column 1.  This text will be formated by Geneal to fill
   lines on the output page.  Empty lines will cause a new paragraph.
   The text can contain embedded layout marks of the form %mark%, where
   "mark" is one of the following.  More detail on the handling of layout
   marks is available in the documentation accompanying the "Quikscript"
   program, upon which Geneal is based.

   %FN,name%       Change font family.  The font name is given 
               by a three or four letter code.  Unrecognized codes will be ignored.
               Tim  (Times)         Hel  (Helvetica)
               Cou  (Courier)       Sym  (Symbol)
               Pal  (Palatino)      NewC  (New Century Schoolbook)
               Book  (Bookman)      Ava  (Avant Garde) 
               Cha  (Zapf Chancery) HelN  (Helvetica Narrow) 
               Din  (Zapf Dingbats) Uft  User-defined

   %BD%        Bold typeface.  To undo, use %LT%

   %C,number%  Special characters can be output by specifying the decimal 
               value of the character in the PostScript extended ASCII 
               table.  Several numbers can be specified, separated by 
               commas.  
               Eg.   Dash %C,208%     Bullet %C,183%     Minus %C,177% 
                     Degrees %C,202%  Minutes %C,194%    Seconds %C,205%
                     Pounds %C,163%   Cents %C,162%      Decimal point %C,180%

   %CL%        Centre the text following on this input line between the 
               current left margin and the current column right margin.  
               No new-line is automatically generated (Beware!).

   %DF,n,ch%   Dot fill using 'n' is an optional position on the page, and 
               'ch' is an optional fill-character.  It has a similar effect 
               to %TR, but in moving rightwards to the given position, dots 
               are placed regularly along the current line.  If the number 
               is not given, dots fill out to the right margin.  If a character
               or numeric code is given after the number, this character is 
               used instead of a dot.

   %FI%        Resume the default behaviour of output line filling (after 
               a %NF directive).  The lines of input are split into words, 
               and output so as to fill the lines within the set margins.

   %IT%        "Italic", or slanted font style.  To undo this command, use %RO%.

   %L%         Go to the start of a new line.  The horizontal position is 
               based on the left margin set by the most recent %TB 
               instruction, plus the paragraph body alignment.

   %LT%        Light typeface, the opposite of bold.

   %NC,number% Change the following page layout to multi-columns.  
               'number' is the number of columns.  If this command is 
               issued part way down a page, the multi-columnar layout
               commences from that position, so that text above is not 
               overwritten.

   %NC%        Go to the top of the next column.  In single column layout, 
               this will cause a new page.

   %NF%        No fill; lines input will not be reformated to fill the lines 
               output.  Each line of input will become a separate line in 
               output.  Words are still checked to ensure that they will 
               fit in the output line, and a new line will be forced if 
               words do not fit.

   %NP%        Start a new page.

   %P%         Start a new paragraph.  The parameters of the paragraph 
               will be the same as the previous paragraph.
               By default, paragraphs have the body aligned with the left 
               margin; there is no first line indentation; a blank line is 
               left between paragraphs; and a new paragraph will not start 
               within two lines of the bottom of the page, but instead be 
               placed at the top of the next page.

   %P,n1,n2,n3,n4%  Start a new paragraph.  
               Set the body alignment 'n1' MM to the right of the current 
               tab margin.  
               Indent the first line relative to the body by 'n2' MM.  
               Set the inter-paragraph gap to one plus 'n3' blank lines;  
               setting 'n3' to 0 will leave a single blank line between 
               paragraphs, and setting 'n3' to -1 will cause new paragraphs 
               to commence on a new line with no intervening blank line.  
               Set the minimum acceptable distance from the bottom of the 
               page for the start of a new paragraph to 'n4' MM;  the 
               default 'n4' is 30 MM.  If the distance 'n4' is more easily 
               measured as a number of inter-line gaps, this can be done 
               by preceding the number with the character "L".

               Any of the numeric fields can be altered without affecting 
               the others, by simply not providing numbers for the 
               unchanging field.  Eg. %P,,,-1% will go to a new paragraph, 
               leave unchanged the body alignment and first line 
               indentation, and set the inter-paragraph gap to zero (1-1) lines.

   PE          Flag the end of embedded PostScript; the following text will 
               be processed normally by Geneal.  Note the absence of % 
               delimiting characters.  This is actually a PostScript 
               procedure within Geneal.

   %PM,l,r,t,b%  Set the page margins, the distance from the page edges to 
               the text margins.  By default, these are 25, 19, 25, 19 MM 
               for left, right, top and bottom.  Numbers omitted are left 
               unchanged.

   %PN%        Number the pages, starting at page two on the following page.

   %PN,number% Number the pages, starting with the given number on the 
               current page.  If the number is zero, page numbering will 
               be disabled.

   %PS commands%  Run the PostScript commands that follow %PS on this
               line.  Beware strings!

   %PS%        The following input text will be interpreted as embedded 
               PostScript by the PostScript interpreter.  Anything following 
               on the current input line is ignored.  Text interpretation 
               by Geneal is reinstated with the PE PostScript command.  
               Accidental redefinition of names of Geneal procedures or 
               variables is prevented, so to change them, the Geneal 
               dictionary must be used, either with
                  QSdict begin...end
               or 
                  QSdict /name value put

   %RL%        The remainder of the line, or all characters up to the next 
               Geneal command on the current input line, are right-justified 
               on the output line.
               If the text is to be right-justified to a certain position, 
               this can be done with %RL,pos%, the position in MM.

   %RO%        "Roman", or normal vertical font style, the opposite of Italic.

   %SZ,number% Set the font height in printer's points.  A printer's point 
               is 1/72 of an inch.  Inter-line spacing is 1.17 times the 
               chosen height.  Default size is 12 on 14.  

   %T,n%       Move horizontally to the position, measured in millimetres, 
               relative to the default left margin, on the current line only.
               It provides a local "go to".

   %TB,number% Move to a new left-hand tab margin, measured in millimetres, 
               relative to the default left margin.  All following text 
               will be set to this margin.  

   %TR,n%      Move horizontally rightwards to the position, measured in 
               millimeters, relative to the default left margin, on the 
               current line only.  If the current position is already to 
               the right of this position, do not move left;  current 
               position will be unchanged.

   %VM,n%      Vertical move from the present position, to the start of 
               the line the requested number of millimeters below.  If the 
               new position is below the bottom margin, go to a new page 
               and move down the requested distance.

   %VT,n%      Vertical tab:  Go to the start of a new line at the given 
               position from the top of the page, measured in millimeters.

   %\%         Ignore any following text on the line.  This enables unprinted
               comments to be included in a document.  
               If "no fill" (%NF) applies, treat the following line as a 
               continuation of the current one.

   %_%         Output a blank character, and do not allow the space to be 
               the place where a line break occurs.  Sometimes, spaces are 
               wanted within a word, eg. a telephone number 268 8111.  
               To ensure that no line break occurs at the gap, it can be 
               represented by 268%_%8111.


   %%          Output a % symbol.  Whatever character is used to indicate
               layout marks within Geneal comments (% by default), then 
               repeating the character enables it to be output in ordinary 
               text.

               In many situations, a single % can be typed and it will be 
               treated as a single character to be output.  However, 
               Geneal will look at the next character to see if it can be 
               interpreted as a layout command, and if so, all following 
               characters up to the next % will be taken to be part of that 
               layout command.

   If you do not have access to A4 paper, which is assumed within Geneal,
   the page dimensions can be altered by replacing lines 15 and 16 with
   more suitable alternatives.

   If you wish to change the font sizes used by Geneal, they are specified
   on lines 17 to 19.  The number within the parentheses (SZ,8) is the
   size in printers points that is acutally used.  Fractional values are
   allowed.

   It is possible to have a border drawn around the tree part of the page,
   separating it from text that may follow.  To have this border drawn
   automatically, the number on line 20 (0 by default) would need to be
   modified.  A non-zero value indicates that a border is wanted, and is
   used as the distance from the text in placing the border.

   If a border is wanted around the entire page, a separate file is provided.
   To print such documents, send Geneal, the file border.qs, and your
   document together as a single unit to the printer.

   Each page will have a page number printed by default.  This can be
   suppressed by modifying line 22, replacing "true" with "false".


"ftindex.c"
===========
   You would use this program to generate an index to the pages of your
   family tree.  The index will look like:

   Lamont, Rhonda Kay     %TR,30%Frederich Kuffner / Adam...fner / Thomas Spence
   %P%Lamont, Rosalyn Dawn     %TR,30%Frederich Kuffner /...fner / Thomas Spence
   %P%Shafer, Brendon     %TR,30%Frederich Kuffner / Adam...fner / Thomas Spence
   %P%Shafer, Eric     %TR,30%Frederich Kuffner / Adam Ku...ence / Darrin Shafer

   where each person is listed, surname first, in alphabetic order, together
   with the names of ancestors.  The assumption is that pages of the tree
   will be ordered systematically based on this ancestry.  

   There will be layout marks, such as "%P%" and "%TR,30%", within the file
   to assist in printing the index neatly, using Geneal.

   To use this program, you will need to compile it with a C or C++ compiler
   before you can start.  How you do this will depend on the type of machine
   you are using.

   To run the program, you should type the name of the executable generated
   in the compilation step above, followed by all of the family tree files
   to be used in building the index, and then Return (Enter on some keyboards).  
   Ftindex will read each file in turn, extracting the name of the first 
   parent and each child from each generation section and associate with 
   that person the names found from the ancestry sections on that page.  
   This information is progressively sorted, using temporary files 
   "scrtmpf1.ftf" and "scrtmpf2.ftf" which are removed at the end, and 
   output into the file "index.qs".  This name is currently fixed within 
   the program.

   To get a printed copy of this index, copy "geneal" and "index.qs"
   to the printer as a single file.

   Ftindex examines names found in the generation section, and if the last
   part of the name (separated by a blank from the previous part) commences
   with '(', '?', or '*', the preceding part is used instead.  If only one 
   name part is present, no index entry is generated.


"gedc2ft.c"
===========
   This program is designed to read a GEDCOM file and convert it into
   Geneal format.  GEDCOM files are highly structured in their information
   content, whereas Geneal handles names, relationships, and comments.  
   Therefore, this program will convert much of the detail within a GEDCOM
   file into comment.

   GEDCOM has a large set of "tags" as part of its definition, and will
   accept new ones that a user might define.  "gedc2ft.c" has a dynamic
   scheme to handle many of these tags.  A file must be provided before
   running the program to indicate how the tags are to be handled.  Some
   tags should be replaced by some sensible text, such as:
      DEAT might be replaced by "died"
      BIRT might be replaced by "born"
   Some tags indicate structure of the document, but no text is needed
   in the output.  Some fields will need to be completely omitted.

   When using this program, you can provide a file of tag replacements,
   or you can use one that has been provided for you to start with,
   "gedcom.tag".  Beside each tag is either
      substitute text        The tag is replaced with this text.
      no substitute text     The tag is simply omitted in processing.
      -                      This record and any subsidiary ones are deleted.
    
   To use this program, you will need to compile it with a C or C++ compiler
   before you can start.  How you do this will depend on the type of machine
   you are using.

   To run the program, you should type the name of the executable generated
   in the compilation step above, followed by the name of the GEDCOM file
   to be converted, and then the name of the tag file to be used.  If you
   do not type the name of a tag file, by default "gedcom.tag" will be used.
   Then on the command line you should pipe the output to a file, eg ">file.ft"
   without the quotes, and type Return (Enter on some keyboards).
   The file ("file.ft" in this case) will be created, which can then be
   printed using "geneal".

   You may decide to hand-edit the created file if you are not happy with
   the output.  "gedc2ft.c" places one family to each page, and orders the
   ancestry sections longest first, since the longest is probably the one
   upon which the index will be based.  Comments within a GEDCOM file are
   often unstructured, and breaking into paragraphs will improve readability.
   

This set of programs is available by anonymous FTP from "ftp.adfa.oz.au" 
in the directory "pub/postscript".
                                          Graham Freeman
                                          gfreeman@cs.adfa.oz.au
                                          28 Apr 1994
