---

Ancestor+

Copyright © APDL 2003. All Rights Reserved

Appendix

Report Template files

Report templates are an extremely powerful feature of Ancestor+. They can consist of (almost) any type of file. Text files are simplest, but other types can be used, subject to certain restrictions. When a template file is used the program loads it and saves a copy of the file, substituting data taken from the database about the person or persons for certain 'tags' in the file. These tags consist of '\' followed by a three letter upper case mnemonic. One consequence of this is that you cannot use the '\' character anywhere in your document. If you do need to use it, then use two, one after the other, and the resulting file will then contain just one.

Use of this system means that the user is not restricted to a series of 'forms' for data export. You decide exactly how you want your reports to look, and you can create many different formats for different purposes.

Because the text which is substituted for the tag will normally be longer or shorter than the four characters used for the tag the resulting file will, if direct substitution is used, normally be longer than the template. With text files this is unimportant. However, for many types of file it is not possible to substitute data of a different length, so an alternative technique must be used. The 'fixed text' that makes up the form can be anything you like. However, the format of the text objects that hold the tags must be correct. When using a Drawfile the first such object you create must be the tag '\OVW' (OVerWrite). This text won't actually appear in the output file, so you can place it anywhere, but it must be created before any of the subsequent tags so it's found first when the Drawfile is 'scanned'. With a wordprocessor file this tag must appear before any other tag. Each subsequent object must begin with the tag and then have enough 'trailing spaces' to leave room for the data that will be substituted. If you don't include enough spaces the resulting file will be corrupt.

Some tags cannot be used in Overwrite mode. In fact, it's not actual tags than can't be used but structures. These are pairs of tags which form a 'loop' which is repeated a number of times until the appropriate data is 'used up' For example, when reporting a person's family links the number of links is variable. It could be none, or it could be half a dozen. Because the outcome is unpredictable it isn't possible to use a fixed format, so these structures can only be used in Insert mode. This does not preclude their use with wordprocessors like Ovation Pro or Impression. What you have to do is create your Template file as usual, but you do not need to leave any space for data, just type the tags. Now, don't save the file in the usual way. With Ovation Pro use 'Save story' and select DDL format, with Impression use 'Save text story' with 'Styles' enabled, with EasiWriter save the file as Rich Text (RTF).

All these are just special forms of textfile with font and formatting data. Unlike the 'real' document files created by the programs they can be modified and manipulated by Ancestor+ and the substitutions made and yet still re-loaded into the appropriate program, normally by dragging them to the program's icon on the icon bar.

When using RTF files with EasiWriter there is a 'quirk' that you need to be aware of. RTF uses the '\' character to precede formatting commands, and although this should not be a problem EasiWriter does seem to have difficulties where a tag follows a Tab in the original document. The solution is simple. After pressing the Tab key in EasiWriter and before you type the tag insert a single space. If you don't do this the first word or character of the data may be lost.

The following tags can be used. Those marked with '**' cannot be used in Overwrite mode.

• \NUM - Person, Family or Child's number
• \FOR - Forename
• \SUR - Surname
• \NAM - Full name (forename(s) followed by surname)
• \BYN - Byname
• \TTL - Title
• \DOB - Date of birth
• \DOD - Date of death
• \POB - Place of birth
• \POD - Place of death
• \YOB - Year of Birth
• \YOD - Year of Death
• \STA - Status
• \SEX - Sex
• \UN1 to \UN5 - Names of User Field 1 to 5
• \US1 to \US5 - Contents of User Field 1 to 5
• \NOT ** Insert Notes file
• \UFN ** Insert Unformatted Notes file (see text)
• \INS - Insert mode (default)
• \OVW - Overwrite mode
• \ADO - Text used for an Adopted child (see text)

The following structures can be used, and some tags can only be used within these structures.

• \FAM - Begin Family structure
• \ENF - End Family structure
• \CHI - Begin Child structure
• \ENC - End Child structure

The Child Structure can only be used from within a Family structure. In addition, the following tags can only be used within a Family structure -

• \DOM - Date of Marriage
• \DOE - Date of End of Marriage
• \YOM - Year of Marriage
• \YOE - Year of End of Marriage
• \POM - Place of Marriage
• \TYP - Type of union
• \RFE - Reason for ending
• \NCH - Number of Children
• \COM - 'Notes' field in Family window (COMment)
• \NOT - Notes file for the family
• \UFN - Unformatted Notes file for the family

The \NAM, \FOR, \SUR, \TTL and \BYN tag can be used within a Family structure but it will return the appropriate data for the spouse of the person from whose record the family structure was used.

Within a Child structure the following tags can be used.

• \NUM - Number
• \FOR - Forename
• \SUR - Surname
• \NAM - Full name (forename(s) followed by surname)
• \BYN - Byname
• \TTL - Title
• \DOB - Date of birth
• \DOD - Date of death
• \POB - Place of birth
• \POD - Place of death
• \YOB - Year of Birth
• \YOD - Year of Death
• \SEX - Sex
• \ADO - If child is adopted, insert appropriate text

If you want to insert Family and Child(ren) data but don't want to bother designing your own structures then Ancestor+ has two pre-defined systems. If you use the \CHI tag immediately followed by the \ENC tag thus

      \CHI\ENC

then you will get the children of a family reported as -

      [1st child name], born [year of birth]
      [2nd child name], born [year of birth]

where the text in brackets will be the actual data for that child.

If you use the \FAM tag immediately followed by the \ENF tag then the family will be reported in a standard format, thus;

  Family links:    number of links
    [1st spouse name], [year of marriage] to [end of marriage[, [num. children]
    [2nd spouse name], [year of marriage] to [end of marriage[, [num. children]

There is also an 'overall' structure which can be enclosed within the two tags \REP and \ENR (Repeat and End Repeat). This is used for multi-person reports where you may wish to include a 'preamble' text or heading that you don't want repeated for each person. Ancestor+ will only repeat the structure inside the \REP and \ENR tags for each individual, and so you preamble and anything you may wish to add at the end of the file will appear only once. If these tags aren't used then, when creating multiple reports, the whole of the file will be repeated for each person.

The \ADO tag is used within a \CHI structure to insert a word where a child is adopted into that family. By default the word is (Adopted), in brackets as shown, and with a leading space. If you want to change this, for example, you might prefer to shorten it to just '(A)', then insert the \ADO tag somewhere in the text before the first structure begins. All of the text on the line following the \ADO tag will then be inserted in a \CHI structure where the \ADO tag appears the child is adopted.

Leading spaces after the \ADO tag are normally stripped when the tag is used to define the word(s) to be used. If you want leading spaces insert an '=' character, then everything after the '=' sign will be used, including spaces, eg.

       \ADO =  (Adopted)

As there are two spaces between '=' and '(Adopted)' there would be two leading spaces whenever the word was used.

There are several example files included in the Reports sub directory of te User directory with the distribution copy of Ancestor+. Although these all work, they are not really intended for serious use, but just as examples for you to see how the system operates. The whole point of Template files is that you can use the method to create documents just the way you want, and it will be worthwhile spending some time experimenting with the system.

CSV file format

The 'People' file

• Line 1 Always 'Ancestor+ People'
  
• Line 2 Database title
  
• Line 3 Number of People records
  

There then follows the data, one person per line, with a linefeed terminating each line. Each CSV field contains the following data.

• Record number
  
• Surname
  
• Forename(s)
  
• Byname(s)
  
• Sex
  
• Status
  
• Title
  
• Date of Birth
  
• Place of Birth
  
• Date of Death
  
• Place of Death
  
• User Field 1
  
• User Field 2
  
• User Field 3
  
• User Field 4
  
• User Field 5
  

All dates must be in the correct format, ie. dd-mm-yyyy, using numbers for the months. Day and/or month may be omitted. The last one or two digits of the year can be '?' as described in the section on Dates. A 'modifier' character (a, b, c, e, +) can be attached as a prefix, and a 'J' or 'G' as a suffix.

Because of the length of the Name and User fields the length of a line in the People file can be quite large, over 700 characters. Many programs cannot accept lines longer than 255 characters.

The 'Unions' file

• Line 1 Always 'Ancestor+ Families'
  
• Line 2 Database title
  
• Line 3 Number of Family records
  

There then follows the data, one family record per line, with a linefeed terminating each line. Each CSV field contains the following data.

• Record number
  
• Type of union code
  
• Place of marriage
  
• Date of marriage
  
• Date of end of marriage
  
• Marriage ended by code
  
• Notes field
  
• Reference number of first partner
  
• Reference number of second partner
  
• Number of children
  

If the number of children is >0 there then follows a number of additional fields, each containing the reference number of the child. All people and children MUST be defined in the accompanying People file.

Keystroke shortcuts

• F3 - Open 'Save' box
  
• F4 - Open 'Search' window
  
• F8 - Restore Details or Family window to last Updated state ('undo')
  
• F9 - Clear all fields in Details or Family window
  
• Shift-Ctrl-Insert - Same as pressing Add or Update in Detail or Family windows
  
• Shift-Ctrl-A - Same as clicking on Add when adding new people or families
  
• Ctrl F1 to F9 - Type macro (only in Details and Family windows)

Database limitations

A person can be linked to only one 'natural' and one adopted set of parents.

Unlike some other systems Ancestor+ accepts same sex 'marriages' and, although it will issue warnings, it will permit you to create families where the date of birth of a child is widely outside the normally accepted range, thereby anticipating such developments as AID and surrogate mothers. Many programs will reject a date of birth of a child that is what it considers too long after the death of the Father or Mother.

A family does not require two parents. It is quite possible to create a 'social' family unit consisting of a single parent and several (presumably) adopted children.

The database itself uses variable length records, so it can be kept fairly compact while still allowing quite large fields. The maximum size of these fields is therefore set by the capacity of the various windows, and is - In the Details window -

• Surname, Forename, Byname and Title - 50 characters
• Place of Birth, Place of Death - 100 characters
• User fields - 100 characters

• Place of Marriage - 100 characters
• Note - 100 characters

If at any time in the future it was found necessary to increase these this could be done with no alteration in database structure.

There are no specific fields for items like Baptism and Burial dates and details. This is because it was felt that where these are required it would be better if the user simply used one of the User fields for that purpose. Where such data is not required (eg. anyone compiling a database of non-Christian subjects would find a Baptism field redundant) having dedicated fields would just add clutter. The five User fields can be readily adapted for data like baptism, burial, education, occupation, bar mitzvah, etc.

APDL