Writing teasps: Element and attributes

Choice of element

TBX provides a set of meta data elements, which are customized with a type attribute to represent various data categories. If you have adopted data categories from the default data category selection in the TBX specification, the “meta data-category” listed there is the name of the element you should use.

If you create novel data categories, you should choose an element consistent with the usage of the TBX specification. A complete list is in section 8.7 of the TBX spec, but these are the most relevant:

  • admin: for administrative data categories
  • descrip: for descriptive data categories in general
  • note: for human-readable notes (element serves only this data category)
  • termNote: for data categories that give the properties of a term or term component
  • ref: for data categories that cross-reference within the termbase
  • xref: for data categories that refer to external files or URLs

If your termbase includes term components, you will use termComp elements to map fields that contain them. If the term component fields are placed directly at the term level, this is all you will need. If you have some field such as “Syllabification” or “Morphology,” and the term component fields are subordinate to it, you will map it to termCompList.If your termbase includes parent fields and child fields, the elements mentioned above are always suitable for parent fields. They are usually suitable for child fields also, but TBX has complex rules about which elements may be subordinated to which. Fortunately, our program knows these rules and can help. If your data map out to an illegal combination, it will wrap the subordinate element in an XML comment (to preserve the validity of the TBX file) and issue a warning (to allow you to revise your mapping).

Choice of attributes

Meta data elements use the type attribute to carry the name of the specific data category they represent, and type is therefore mandatory on nearly every element listed on this page. Exceptions are as follows:

  • note cannot have a type because it only represents one data category.
  • xref is technically valid without type, but in our usage scenario such a thing is nonsense.
  • termComp has no type. In TBX, the kind of term component is indicated by the surrounding termCompList. If your termbase definition does not include a parent field that maps totermCompList, our program will supply one based on the target that the termComps are sent to.
  • type is generally supplied literally in the mapping, but termbase data can also be placed in it at processing time. This functionality is intended for the scenario where one MultiTerm field maps to multiple termCompList-based data categories. It may have other uses, but we don’t know of any.

The target attribute is mandatory on xrefs to give the filename or URI targeted, but most of the time it will be placed there from user data, rather than being supplied by the mapping. It is allowed on other meta data elements, but we doubt you will find much use for it.

JSON syntax

In each teasp in the mapping file, you will need a JSON string containing one nearly literal XML element:

"<descrip type=\"definition\"/>"

or

"<xref type='xGraphic'>Graphic</xref>"

for example. We say “nearly literal” for two reasons. First, JSON strings are delimited by double quotation marks, and so any double quotation marks inside the string must be escaped with backslashes, as shown in the first example. (XML also allows single quotation marks around attribute values, as shown in the second example, and we find we prefer this to escaping backslashes.) Second, the element will of course be modified when user data is placed in it. The first example will acquire textual content (and our program will take care of dividing it into a start tag and an end tag at that time). The second example has generic textual content, to which user data will add a target attribute.

Miscellaneous

On rules for subordinating one element to another, see the TBX spec, Annex D.4. If the parent field maps to an admin or to note, see the “May contain” list under adminGrp (which includes the element adminNote). If the parent field maps to a descrip, ref, or xref, see under descripGrp (including descripNote). For a parent termNote, see under termNoteGrp; for atermComp, under termCompGrp; and for a termCompList, under termCompList itself.

TBX includes two other meta data elements, which you will (probably) not use in your mapping. refObjectList is used to organize reference material in the back matter of a TBX document, but to use this feature requires cross-referencing information that MultiTerm does not export, and so this element is not supported by our converter program. transac documents changes to the termbase, and it is usually generated by MultiTerm and our converter without user intervention. It is conceivable that user-created data categories might map to further transactional information, but that possibility is beyond the scope of this manual.