How To Use (Read Me First)
The Tag Libraries provide interactive documentation for this Tag Set that you can access through Web browsers. Separate Tag Libraries in separate areas have been set up for each of the specific Tag Sets (Journal Archiving, Journal Publishing, and Article Authoring), and within those areas you can get to specific information in many ways, such as:
- alphabetical lists of element, attribute, and parameter entity names (the last of
these is mainly useful to NISO JATS users who customize this Tag Set);
- special overviews such as a “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 document.
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
- Full Article Samples
- Common Tagging Practice
- Implementing This Tag Set
- DTD, XSD, and RNG Downloads
- 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). When looking up elements, remember that the four Tag Sets differ slightly in which element types are available. For example, tags normally added by the publisher instead of the author, such as for journal issue information and publication dates, are not available in the Article Authoring Tag Set. (
)
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”.
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.
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.
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.
For more details see the Introduction to Elements section.
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.
These diagrams illustrate portions of the hierarchical (nested) structure of this 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 boxes 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 merely 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 a box indicate whether that element is required and/or repeatable. These symbols are called “occurrence indicators”:
? | means that the item is optional |
* | 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 |
a thick vertical bar on the left of the box | means that the item is the “document element”: the top-most element, such as <article> or <book> 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:
˜ | means that the item may have 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 left 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.