TTT File Format

Instructions for Twistory 1.4

About Resources

Twistory comes with a folder of text resources called "ttt" and an index file called something like "index.ttt." Double-click on this file to open Twistory.

The files in the "ttt" folder are of two types, identified by their filename extensions. The extension ".ttt" stands for "twistory text." These files contain information on places, people and events. There are also files with the extension ".geo" which are actually just ".ttt" files, but which are so named as a comment that they contain only place data. (You can actually call the files anything you want.)

The other kind of file has the extension ".poly" for "polygon." These are also text files, but are most easily created and edited with a separate program called PolyTool, which is included with this release.

The following sections describe the format of the ".ttt" files. The characters "#," "<" and ">" are reserved. They may only be used as documented below. "C++ and C-style" comments may also be used. Here are examples of comments, which are ignored when Twistory reads a file:

This is not a comment.  /* This "C-type" comment begins and ends with an oblique
and an asterisk, which are reversed at the end. */  This is not a comment.
This is not a comment.  //  This "C++-type" comment begins with two obliques, and goes to the end of the line.
//  This is a comment.
This is not a comment.

The File Mark-up: #file

Twistory files are arranged in a hierarchy, and this markup is used to link them together. An index file (which can have any name) is used to list all files or sub-index files. As Twistory reads any file, if it finds the sequence "#file" it suspends reading the file it is in and opens the file whose name appears after the "#file" markup. The format is as follows:

#file "ttt/egypt.ttt"

This tells Twistory to look in the folder "ttt" for a file called "egypt.ttt" and to read its contents in right away, before finishing the current file.

The order in which files are listed in the index, and the order in which items appear in the files, is significant. For example, a place description must be read in before it is referred to in a person record.

The Era Mark-ups: #bc and #ad

These mark-ups have no fields, and are used to change the default era for dates. A change in the default era made within a file is forgotten once that file ends and reading returns to a file which is higher up the hierarchy. But a change is passed down to a lower file. The safest practice is to specify either #bc or #ad at the beginning of every file.

Fields

All of the information in a place, person, event, sphere, or menu-item record is in the form of fields, which have a common format. They all begin with a field identifier between the characters < and >. The following table summarises them. Some fields, like the name, <n>, can be used with different types of records. Others can only be used with one type. The letters c, p, e, s and i indicate which records they may be used with.

Following the table, the various fields are explained. The syntax line describes the format of the data which follows the field identifier. Remember that "white space" is always ignored in strings, i.e. tabs, carriage returns and comments and multiple spaces are all treated like single spaces. Spaces on either end of field data are ignored.

Mark-up Description Applicability Syntax Remarks

<n> name c p e s i string See note

<aka> alias or alternate name c p string

<reg> region (name of place) c s string This specifies the next larger region in geographical hierarchy. (The field <sup> was used for this in the first release.)

<l> geographic location c s georef

<rad> radius (in km) c s integer used by map to suppress legends at small scales

<rep> replaced area c string This field specifies an older area name (whose definition must precede this one's) which is temporally superceded by this area's name.

<col> colour c s i colour used in time-line bars

<wat> body of water c n/a boolean mark-up (no field following)

<nat> nationality c p string For a place, this is the national adjective, i.e. the name for a person who lives there. (The field <adj> was used for this in the first release.) For a person, this string should match the <nat> field of some region.

<c> place p e string This is used to specify the name of the place where a person lived or an event happened.

<info> additional information p e string Further information, which appears in "Info" windows; This should be in sentence form.

<ref> reference p e string This is used to specify the reference to literature, e.g. from which book the information came.

<sur> surname p string This is optional for a person. Use it if necessary to override the short forms that Twistory uses at large time scales.

<fem> female p i n/a boolean mark-up (no field following)

<o> occupation p i string This should match an occupation defined in a menu item.

<b> date of birth p date

<d> date of death p date

<gen> age of parent at birth p integer The age of a parent at the person's birth. This can be used instead of a birth year when it is more convenient. See note on order.

<tr> date of translation p date This is used in preference to <d> in a case where the person did not die, but was taken up.

<fa> father's name p string See note on order.

<mo> mother's name p string See note on order.

<ac>, <ap>, <pow>, <el> date of coming to power p date Use <ac> for accession, <ap> for appointment, <pow> for taking power, and <el> for election to office. Twistory treats these similarly.

<ab>, <depo>, <ret> date of leaving power p date Use <ab> for abdication, <depo> for being deposed, and <ret> for retirement from office. Twistory also treats these in a similar manner. It is not necessary to specify this date when it coincides with death.

<dep>, <arr>, <mov> dates of depature and arrival p e date Use these, along with <c>, to describe the travels of a person, or the itinerary of an event. The <mov> field specifies a transition between two places where the time spent travelling is not significant. Using <mov> has the same effect as using both <dep> and <arr> with the same dates.

<d> date e s date This field has the same abbreviation as date of death, above, but is parsed correctly in the context of an event or sphere record.

<e> ending date e s date

<t> event type e i string This should match an event type defined in a menu item

<tit> title e string The proper title of a publication. Twistory treats this as the name of the event. The use of quotation marks around it is discouraged.

<au> link to author, inventor, etc. e string Use the name or surname of a person.

<vic> winning side of battle e string name of country

<poly> polygon file name s string

<icon> icon for occupation or event type i string See note

<off> menu item initially unselected i n/a boolean mark-up (no field following)

Mark-up	Description	Applicability	Syntax	Remarks
<n>	name	c p e s i	string	See note
<aka>	alias or alternate name	c p	string
<reg>	region (name of place)	c s	string	This specifies the next larger region in geographical hierarchy. (The field <sup> was used for this in the first release.)
<l>	geographic location	c s	georef
<rad>	radius (in km)	c s	integer	used by map to suppress legends at small scales
<rep>	replaced area	c	string	This field specifies an older area name (whose definition must precede this one's) which is temporally superceded by this area's name.
<col>	colour	c s i	colour	used in time-line bars
<wat>	body of water	c	n/a	boolean mark-up (no field following)
<nat>	nationality	c p	string	For a place, this is the national adjective, i.e. the name for a person who lives there. (The field <adj> was used for this in the first release.) For a person, this string should match the <nat> field of some region.
<c>	place	p e	string	This is used to specify the name of the place where a person lived or an event happened.
<info>	additional information	p e	string	Further information, which appears in "Info" windows; This should be in sentence form.
<ref>	reference	p e	string	This is used to specify the reference to literature, e.g. from which book the information came.
<sur>	surname	p	string	This is optional for a person. Use it if necessary to override the short forms that Twistory uses at large time scales.
<fem>	female	p i	n/a	boolean mark-up (no field following)
<o>	occupation	p i	string	This should match an occupation defined in a menu item.
<b>	date of birth	p	date
<d>	date of death	p	date
<gen>	age of parent at birth	p	integer	The age of a parent at the person's birth. This can be used instead of a birth year when it is more convenient. See note on order.
<tr>	date of translation	p	date	This is used in preference to <d> in a case where the person did not die, but was taken up.
<fa>	father's name	p	string	See note on order.
<mo>	mother's name	p	string	See note on order.
<ac>, <ap>, <pow>, <el>	date of coming to power	p	date	Use <ac> for accession, <ap> for appointment, <pow> for taking power, and <el> for election to office. Twistory treats these similarly.
<ab>, <depo>, <ret>	date of leaving power	p	date	Use <ab> for abdication, <depo> for being deposed, and <ret> for retirement from office. Twistory also treats these in a similar manner. It is not necessary to specify this date when it coincides with death.
<dep>, <arr>, <mov>	dates of depature and arrival	p e	date	Use these, along with <c>, to describe the travels of a person, or the itinerary of an event. The <mov> field specifies a transition between two places where the time spent travelling is not significant. Using <mov> has the same effect as using both <dep> and <arr> with the same dates.
<d>	date	e s	date	This field has the same abbreviation as date of death, above, but is parsed correctly in the context of an event or sphere record.
<e>	ending date	e s	date
<t>	event type	e i	string	This should match an event type defined in a menu item
<tit>	title	e	string	The proper title of a publication. Twistory treats this as the name of the event. The use of quotation marks around it is discouraged.
<au>	link to author, inventor, etc.	e	string	Use the name or surname of a person.
<vic>	winning side of battle	e	string	name of country
<poly>	polygon file name	s	string
<icon>	icon for occupation or event type	i	string	See note
<off>	menu item initially unselected	i	n/a	boolean mark-up (no field following)

Names

This should be the most common, natural name for something. For a person, it should have both given name and surname. Middle names are discouraged, unless necessary to identify a person, or if the name they go by involves a middle name. For an event, it should be as short as possible, and not be especially capitalised. Try to avoid "type" words in event names, e.g. use "Titanic" rather than "sinking of the Titanic." The icon provides type information to the user.

Georef Format

Geographic References are given as the latitude and longitude concatenated together, in that order. Either one may be given in degrees, or degrees and minutes. Following the angle must appear one of the letters 'N' or 'S' for latitude, and 'E' or 'W' for longitude. NOTE: the degree part must consists of either 2 or 3 digits, not 1. If the angle is less than 10 degrees, a leading zero must be used. (Otherwise, it would be ambiguous whether a three-digit angle was greater than 99 degrees and given in whole degrees, or an angle less than 10 degrees with minutes following.)

Date Format

Dates are given in the format:

[ era ] year number [ era ] [ month name [ date number ] ] [ (uncertainty) ]

The square brackets indicate optional parts. The year is the only mandatory element. It may be preceded or followed by either "A.D." or "B.C." to indicate an era other than the default; it is necessary to do this for lives or events which span the boundary between the B.C. and A.D. eras, since the default era cannot be changed in mid-record.

Following the year, the month name or its abbreviation (not number) may appear, if it is known. If the month is given, the date of the month may follow.

Finally, an uncertainty may be given. There is already an implied uncertainty in any date that has only a year, or only year and month. For example, if only 1520 is stated, the actual date Twistory uses to draw the event is 1520 July 1, but the uncertainty will be plus or minus six months. To specify another uncertainty, put a number in round brackets following the date. (No spaces are necessary.) The units are those of the last element of the date. For example, 1889 May(3) means within three months of 1889 May 15.

Any date in a person's record (other than his or her birth date) may alternatively be identified by the age of that person at the time. This is only valid if the date of birth is given first. The age must be a whole number of years, and may have an uncertainty. This is the format:

"age" age in years [ (uncertainty) ]

A note on calendars: Twistory uses the Gregorian calendar starting in October of 1582, when the Vatican adopted it, and the Julian calendar before that. It took several hundred years for most of Europe to adopt the Gregorian calendar, so there is considerable confusion surrounding exact dates in the ensuing centuries. Different countries were 10 or more days apart in their reckoning during that time, and little or no care has been taken while assembling the resources for this program as to whether a date quoted was still in the old style (Julian) or already in the new style (Gregorian). Therefore one should be wary when comparing dates during the three or so centuries preceeding the 20th, unless he or she has taken care to convert all old style dates after 1582 into the new style. Furthermore, between 33 B.C. and 8 A.D., a problem with leap years means that the calendar was not even strictly Julian during that time, and before the Julian reform in 45 B.C., things get really confusing. While few milestones have exact dates recorded for them before 8 A.D., bear in mind that for those which do the calendar shown is not exactly the one in use then.

A note on uncertainties: An uncertainty associated with a date can mean several things. First, it can refer to an occurrence whose exact date is lost to history. If an ancient chronicler wrote that an event occured during a given year, but gave no date, we may assume that we will simply never know its exact day. Second, different historians in reconstructing a history with few dates may date an event within some time span according to likelihood or sequence. When I have come across contradictory time spans for an event, I have blended the two together into an inclusive (less certain, but more likely) period. Third, uncertainties may appear because I have simply made a judgment of my own (e.g. made a guess about someone's year of birth based on his children's). In this case, the uncertainty you see does not mean that a date is not known more accurately to historians; it means I haven't found out a more accurate date yet, but I wanted something reasonable to put it. Whatever their origin, there are two ways in which uncertainties may be understood: as rigid bounds within which an event must have occurred due to sequence; or as ranges of likelihood (gaussian, or "bell" curves, if you would) corresponding to some probability mass, say 75%. I have adhered more to the latter when assigning uncertainties. You may make your own decision in how you treat them in resources you compile.

A note on the order of <gen>, <b>, <d>, <fa> and <mo>: If <gen> is used, the generation difference will be reckoned from the birth of the parent who is mentioned before it. If <b> and/or <d> is used, it is best to give the <fa> and <mo> fields after them; this allows Twistory to better discriminate between people with the same name when finding the parent.

Colour Format

A colour can be specified by its RGB components, as integer percentages. For example, 100 100 100 means white, 0 0 0 means black, 100 0 0 means red, etc.

Some colours may be specified by name. The following words are recognised as colour constants: beige, black, blue, brown, burnt orange, chartreuse, chestnut, crimson, cyan, dark grey, emerald, forest green, fuchsia, green, grey, indigo, light brown, light grey, lime green, magenta, olive, orange, oxblood, pale cyan, pale green, pale yellow, periwinkle, pink, purple, red, rose, sapphire, sea green, sky blue, turquoise, ultramarine, violet, white and yellow.

The colours are used on the bars that indicate lifespans or extended events in the time-line window. A person is coloured according to his/her nationality, so place descriptions can have colour fields. An event is coloured according to its type, so event types (defined in menu-item records) can have colour fields too.

Icons

If no icon is specified for an occupation or event type, these default icons are used:

Custom icons can be used. See these tables of person icons and event icons. The icon is specified by putting its name in the <icon> field of a menu-item record.

It is possible to create additional icons if you are so inclined. You only need a program called "ResEdit," which is available free from Apple, and which is distributed with most development software. (Instructions on its use are not included here.) Make a copy of the Twistory application before modifying its resource fork. Create additional 'cicn' resources and give each one a name.