How To Use (Read Me First)
This Tag Library provides interactive documentation for the TBX Tag Set that you can access through a
Web browser. For example, these pages provide:
- alphabetical lists of element and attribute names,
- document hierarchy diagrams, and
- an “Index” section that works like the index at the back of many books. You can use it to find where a given item or topic is discussed. The index lists elements, attributes, and discussion topics under many related names and descriptions, so if you don’t know the exact tag name to use for something, try looking in the index under various related words, and you will most likely find a reference to the applicable tag or attribute.
You can use the Tag Library as a reference to look up XML tags and how to use them, to
browse around and familiarize yourself with these Tag Sets, to see examples of correct or
recommended usage, and even to find guidance for how to implement software to handle documents
that are marked up using the TBX Tag Set.
At the top level of the Tag Library (shown in the colored navigation bar to your left) there
are several main sections:
- How To Use (Read Me First)
- Root Element
- General Introduction
- Elements
- Attributes
- Document Hierarchy Diagrams
- Element Context Table
- Index
Moving Around in the Tag Library
As with most Web documents, you can click on links to travel from one topic to another and
use your browser’s “Back” button to backtrack through previously-visited
pages. In addition, there are three navigation aids on every page:
- At the
top is a horizontal Tab Bar with links to the primary topics in the Tag Library (e.g.,
“Elements” and “Attributes”). Clicking on a topic tab takes the user to the introduction for that section.
- To the left is a colored vertical
Navigation Bar with links to all parts of the Tag Library, including the Tag Library’s
introduction and the primary sections discussed earlier.
- At the very bottom of each page, in the far right corner is a “Back to Top” link.
Navigation Bar
The vertical Navigation Bar is used to move within sections as well as between sections.
- If a section has subsections, a triangle (
) appears next to the section’s
title. - Clicking on the triangle changes it to a triangle pointing
down (
) and opens a list of
sub-topics within that main section. - Clicking on a sub-topic goes directly to the corresponding discussion.
Elements in the Navigation Bar
Clicking on the triangle to the left of the word “Elements” will show a list of all the XML element types such as
<tbx:example> and
<tbx:grammaticalGender> that are defined in this Tag Set. 
(For those not familiar with the tag name of an element, hovering over the tag name will reveal its more English-like, descriptive equivalent; for example, hovering over the “<tbx:geographicalUsage>” will show “Geographical Usage”.)
Because there are many elements, you will
likely have to scroll down to find a particular one (using the scroll-bar immediately to the
right of the Navigation Bar, not the main scroll-bar for the entire browser window).
Clicking on the name of an element (in pointy brackets) will take you to a page for that
element, with detailed information about its use, content, and permissible contexts.
Attributes in the Navigation Bar
Similarly, clicking on the triangle before
the “Attributes” section will bring up a list of all the available
attributes.
An attribute that is
available on many elements will list each of those elements and explain any differences in usage. This
section also provides key attribute details such as whether the attribute is required or
optional, and provides lists of suggested values.
Collapsing the Vertical Navigation Bar
Some users, especially those consulting the Tag Library with small devices, want to use
the full width of their displays for the body of the entry. Click the “«” at the top of the navigation bar to
collapse the vertical navigation bar, and the “»” at the top left of the
header to re-open it.
All Element/Attribute Names Link
In all Tag Library sections except the “Document Hierarchy Diagrams”, when
the text mentions a specific element, attribute, or parameter entity, the name is linked to the
page that describes that item. This makes it easy to access related information.
Tag Library Sections
Root Element | Names the top-level (document) element for the TBX Tag Set. |
|---|---|
General Introduction | Describes the purpose, scope, extent, and original basis for the TBX Tag Set. |
Elements | All the element pages, arranged alphabetically. |
Attributes | All the attribute pages, arranged alphabetically. |
Document Hierarchy Diagrams | This section illustrates portions of a Tag Set’s structure that are nested or that have complex structures. These diagrams are graphical representations of the information on each Element page under the heading “Model
Description”. The diagrams use some special symbols that are described below. |
Element Context Table | The Context Table is an alphabetical list
of all the elements in this Tag Set. For each element, it shows all the elements that can
directly contain that element. This
is a great way to find out whether a certain element can be used in a certain context. This information is also available on each Element page under the heading “This element may be contained in”. |
Index | Works like the index at the back of many
books and can be used to find where a given item or topic is discussed. The index lists elements, attributes, section titles, and discussion topics under many related names and descriptions, so if you
don’t know the exact tag name to use for something, try looking in the index under various related words, and you will most likely find a reference to the applicable tag or attribute. |
Each Element Page
These pages start out with the XML name of the element they describe, followed by a more
English-like, descriptive name and a description. Many elements also have remarks that give
further details or help distinguish this element from similar structures.
There is also a description of which elements are allowed within the element and in what
combinations.
Most element pages include examples that show how the element can be used, often including
some context. These examples have been tested and validated against the model; however, portions are often
left out or replaced by “...” to keep examples manageable. In addition, the most
relevant parts of examples are highlighted so they are easy to find.
For more details see the Introduction to
Elements section.
Each Attribute Page
Attribute pages are organized very much like element pages. However, because an attribute
cannot have sub-elements, the description instead tells which elements can use the attribute,
what kind of attribute it is, and what the permitted and default values are (the default value
is used when the attribute is not specified at all on a particular instance of an
element).
Some common kinds of attributes are:
An XML identifier
(ID) | This kind of attribute must have a value that is an XML
NAME, which can consist of XML name characters (alphabetical characters, digits, period,
underscore, and hyphen), and cannot start with a digit. Every ID attribute value
in a single document must be unique and provides a way to link or refer to its element (for
example, using the
<tbx:crossReference> element).
ID attributes are generally named @id. |
|---|---|
Reference to an identifier
(IDREF) | This kind of attribute must have a value that is the
same as some ID value in the same document. IDREFs appear on elements
(such as
<tbx:crossReference>) that refer to other elements.
The IDREF attribute is named @target. |
Text, numbers, or special characters
(CDATA) | These attributes can take any string value at all. If
the attribute value is surrounded by single quotes, then single quotes cannot appear inside; if
the attribute value is surrounded by double quotes, then double quotes cannot appear inside. In
either case, the prohibited character can instead be represented by an XML character reference
such as “'”. XML elements cannot be placed within attribute
values. |
Finally, there may be a “Restrictions” section that specifies if the
attribute must always be specified or is optional.
For more details see the Introduction to
Attributes section.
The Document Hierarchy Diagrams
These diagrams illustrate portions of the hierarchical (nested) structure of a Tag Set.
Each diagram has one element “root” and may illustrate the structures of several
additional elements. For each element illustrated, its name appears in a box on the left, with
lines to boxes for each of its possible child-elements, which are in a column on the
right.
Boxes for child elements can have names and/or symbols within. If the box has merely
“...”, it means that the actual content has been omitted, to save space or
improve clarity. If it has an icon of a page with lines, it stands for text content rather than
an actual element.
If a box has an element name, then symbols at the left end of the box indicate whether
that element is required and/or repeatable. These symbols are called “occurrence
indicators”:
?
| means that the item is optional (zero or one) |
|---|---|
*
| means that the item may occur any number of times (zero or more) |
+
| means that the item must occur at least once, but may occur any number of times (one or
more) |
a thick vertical bar on the left of the box | means that the item is the “document element” (the top-most element such as
<tbx:termEntry> and is therefore
required |
(no symbol) | means that the item must occur exactly once |
The symbols at the right end of a box have these meanings:
˜ (a tilde) | means that the item may take one or more attributes |
|---|---|
a thick vertical bar on the right of the box | means that the item is expanded elsewhere (For example, if an element is permitted in
multiple places within a certain parent element, there is little point in repeating its
information many times.) |
The lines that connect a box to boxes on its right may either be squared-off or direct
(angled) lines. The former indicates that the boxes to the right must occur in the order shown;
the latter indicates that any order is permitted.
For more details and examples see the Document
Hierarchy Diagrams section.