How To Use (Read Me First)
Tag Libraries provide interactive documentation for a Tag Set that you can access through
Web browsers. Separate Tag Libraries have been set up for this BITS Book Tag Set as well as for each
of the JATS journal Tag Sets (Journal Archiving, Journal Publishing, and Article Authoring).
Each Tag Library provides specific information, such as:
- Alphabetical lists of the element, attribute, and parameter entity names defined in the
Tag Set (the last of
these is mainly useful to users who customize this Tag Set);
- Special overviews such as an “element context table” of what elements each
element may occur within;
- Tutorial chapters on concepts that are complex or that involve many different XML
element types, such as tagging bibliographic citations;
- Many links between related elements and discussions; and
- An index where you can look up concepts under a variety of names or descriptions, and
reach the relevant parts of the documentation.
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 this Tag Set; 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 this Tag Set.
At the top level of each Tag Set’s Tag Library there are several main sections:
- How To Use (Read Me First)
- General Introduction
- Elements
- Attributes
- Parameter Entities
- Document Hierarchy Diagrams
- Common Tagging Practice
- Accessibility
- Implementing This Tag Set
- Element Context Table
- Index
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. On most pages there is a Navigation Bar on the left, as shown below. This provides
links to each main section. In addition, next to each main section’s title there is a small
right-pointing triangle (
). Clicking on it will
show the list of sub-topics within each main section, and you can then click on a sub-topic
to go to the corresponding discussion. To collapse the expanded list, click on the
down-pointing triangle (
).
For example, clicking on the triangle to the left of the word “Elements”
will show a list of all the XML element types such as <p> and <table> that are defined
in this Tag Set. Because there are many element types, you will likely have to scroll down
to find a particular one (using the scroll-bar on the Navigation Bar, not the main
scroll-bar for the entire browser window).(
)
- The “Common Tagging Practice” section contains descriptions of more
general issues in how to use this Tag Set. For example, affiliations and keywords involve
numerous elements, attributes, and general design choices. These are discussed in special
sections, rather than under some particular related element(s). These sections are important
for learning to use this Tag Set well, and links to them are provided from elements and
attributes to which they are especially relevant.
- Clicking on a name in the “Elements” section will take you to a page for
that element, with detailed information about its use, content, and permissible
contexts.
- Similarly, the “Attributes” section lists all the available attributes.
An attribute that is available on many elements has only one description (the description
lists all the elements on which the attribute is available). This section also provides key
details such as permitted, recommended, or example values.
- The “Parameter Entities” section describes entities that are used in the
formal Tag Set definition (DTD). Most users can ignore these, but they are important if you
wish to customize this Tag Set.
- The “Element Context Table” has an alphabetical list of available
elements. For each one, it shows all the elements that can directly contain it. This is a
great way to find out whether a certain element can be used in a certain context. This
information can also be gleaned from the element’s Element page under “This element
may be contained in”.
- Finally, there is 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.
- The “Document Hierarchy Diagrams” section illustrates portions of this
Tag Set’s structure that are nested or that have complex structures. This information can
also be gleaned from the element’s Element page under “Model Description”.
The diagrams use some special symbols that are described below.
In all these sections except the Document Hierarchy Diagrams, when the text mentions
specific element types, attributes, or parameter entities, the name is linked to the page
that describes that item. This makes it easy to access related information.
These pages start out with the XML name of the element they describe, followed by a more
English-like, descriptive name and a definition. Many elements also have remarks that give
further details, a discussion of best practice, notes that may be helpful to users that need
to convert data into this Tag Set from other sources, and cross-references.
There is also a description of exactly what elements are allowed within the element and
in what combinations. This information is provided in three forms:
- Content Model — the “raw” content model in XML
syntax. This may contain parameters entities, of the form “%name;”, which
often stand in for commonly-used lists of elements. Users not familiar with formal XML
(DTD) syntax will likely prefer the “Expanded Content Model” or the
“Description”.
- Expanded Content Model — the content model with all parameter
entities expanded to their ultimate values. This list directly shows all the elements
that the described element can contain, and in what combination.
- Description — a text description of the allowable content, which is
much longer than the content models, but should be readily understandable without having
to learn the details of content models and their punctuation. These descriptions often
refer to categories of elements, such as “the address linking elements”.
These categories correspond to parameter entities that are shown in the
“raw” content model, and are re-used in many places.
For many elements, the “Document Hierarchy Diagrams” provides a fourth
descriptive form. This form is described below.
Most element pages include specific examples that show how the element can be used,
including any relevant context. These examples have all been tested and validated; 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.
The element page also lists what “module” the element is defined in.
This, like parameter entities, is not important to you unless you plan to customize this Tag
Set.
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 <xref> element).
ID attributes are generally named @id. |
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 that refer to other
elements such as <xref>.
IDREF attributes are generally named @rid. Some @rid attributes
are of type IDREFS, which is simply a space-separated list of
IDREF values. |
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. |
“xxx-type” attributes | There are many attributes whose names end in “-type”.
They are generally CDATA attributes as described above. They are
typically assigned tokens as values, containing no spaces. Typically if there are
spaces in the value, they separate multiple independent tokens, all of which apply.
For example, some element might be both of type
“important” and “normative”,
and be given type “important normative”. In many cases,
the Tag Library gives suggested values for such attributes. Unless specifically stated
otherwise, those values are not the only values permitted. |
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.