Format of the Category File
The armorial descriptions in the database are stored using codes defined in a text file known as my.cat, which is roughly 128 KB in size.
You can download the category file via HTTP from https://oanda-update.digitalherald.org/my.cat
The category file is divided into three sections, each of which uses a different format:
- Features (around 350 lines) function as adjectives, such as
argentormaltese, providing additional details about a description. - Categories (around 450 lines) function as nouns, such as
CROSSorHUMAN FIGURE, providing the core content of a description. - Cross-references (around 2,750 lines) list additional terms which are grouped under another category, such as
woman - see human figure.
Categories
Categories are the core of armory descriptions.
Each category line contains a human-readable term, then a pipe character ("|"), followed by a capitalized category code.
For example, here are a selection of category lines.
axe|AXE azure field|AZ beast, bear|BEAST-BEAR beast, dog|DOG bird, demi|BIRD9DEMI bird, whole|BIRD cross, as charge|CRAC cross, throughout|CROSS field division, per fess|PFESS field division, per pale|PPALE pole axe|POLE-AXE
As you can see, the category code is sometimes a predictable capitalized version of the human-readable term, and other times is more idiosyncratic.
Most categories represent types of charges, but some correspond to solid fields or field divisions, and others indicate specific arrangments of charges.
Cross-References
Cross-references make it easier to find individual category terms.
Each cross-reference line contains a human-readable term, then either "see" or "see also", followed by one or more human-readable category names.
For example, here are a selection of cross-reference lines.
axe - see also pole axe broadaxe - see axe
The see also lines mark places where one category is being linked to another, related category, so in the above example so we can expect to find both axe and pole axe in the category list.
The see lines mark places where an additional term is being linked to an existing category, so the above example is telling us that there is no broadaxe category and instead all broadaxes are indexed under the axe category.
Some cross-reference lines direct you to more than one corresponding category, separated by and.
bluejay - see bird, whole and bird, demi swallow - see bird, whole and bird, demi
The above example shows that bluejays and swallows are each indexed in one of two distinct categories, either bird, whole or bird, demi.
Many of the cross references define varieties, heraldic synonyms, or related charges that are indexed together.
alaunt - see beast, dog cub, wolf - see beast, dog fox - see beast, dog husky - see beast, dog hyena - see beast, dog talbot - see beast, dog wolf - see beast, dog
Each of these is either a variety of dog (husky), or an old heraldic term for a variety of dog (alaunt, talbot), or a related canine that is indexed with dogs (fox, hyena, wolf).
Features
Features are used to provide additional details about armory descriptions.
Each feature line starts with a pipe character ("|"), then has a feature set name followed by a colon, and then the individual feature name.
For example, the cross_family feature set is used to mark subtypes of crosses. Its contents are defined in a series of lines like the below:
|cross_family:crosslet |cross_family:flory |cross_family:maltese
The feature name may optionaly be followed by one or more markers showing their relationship to other feature names.
For example, the tincture feature set is used to mark the coloration of fields or charges. Its contents are defined in a series of lines like the below:
|tincture:argent<light |tincture:ermine<fur<light |tincture:neutral=multicolor=fur
The first line defines a tincture code named argent, and indicates that it is a subtype of the tincture named light. The second line defines a tincture named ermine and marks it as a subtype of both fur and light. The third line defines a tincture named neutral and marks it as equivalent to both multicolor and fur.
The subtype relationship defined by the < chracter indicates that the term on the left is a more-specific feature encompased by the term on the right. For example, a search for CROSS:light should also match any armory that is marked as CROSS:argent. However, this relationship is not symatrical; if you search for CROSS:argent, it should not match armory that is marked as CROSS:light.
The equivalence relationship defined by the = chracter indicates a symetrical relationship between the terms. For example, a search for CROSS:neutral should also match any armory that is marked as CROSS:multicolor, and a search for CROSS:multicolor should also match any armory that is marked as CROSS:neutral.
Individual armory descriptions may combine multiple features from different feature sets. For example, an Maltese cross throughout argent might be coded as CROSS:maltese:argent
Individual armory descriptions never use more than one feature from a given feature set. For example, there will never be a cross with two different cross features such as CROSS:crosslet:maltese.
Some feature sets are only applicable to certain categories. For example, the features in the bird_posture feature set are only ever used with the BIRD or BIRD9DEMI categories.