◇◆
Structure of the Tag Library
This “Tag Library” is provided as a service to users of ANSI/NISO Z39.102-2017, STS:
Standards Tag Suite; the Tag Library is not part of ANSI/NISO Z39.102-2017. It contains non-normative information that is intended to
be helpful to users of ANSI/NISO Z39.102-2017.
The Tag Library is organized onto a number of chapters, each divided into sections
(which may also be divided into further sections). Navigation around the Tag Library
is through the Navigation Panel (Navbar) and through numerous direct links between
related components.
The table below outlines the structure and chapters (with their subsections) of this
document:
|
Getting Started
|
Basic information for first time users and reference for experienced users, this chapter
describes the Tag Library document, how to navigate around the web pages of the complex
document, and introductory material for the NISO STS Tag Suite. Also includes the
Hierarchy Diagrams, which are useful as introductions as well as reference.
|
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Elements
|
Descriptions of the elements used in the NISO STS Tag Suite. The elements are listed
in order by tag name. (For information on how each Element page is organized, see
Introduction to Elements.)
|
||||||||||||||||
|
Attributes
|
Descriptions of the attributes in the NISO STS Tag Suite. Attributes are listed in
order by the name
used in tagging documents and in the schemas. (For information on how each Attribute
page is organized, see Introduction to Attributes.)
|
||||||||||||||||
|
Finding Information in Tag Library
|
Contains three aids for locating a NISO STS element, attribute, an element’s context,
and related information:
|
||||||||||||||||
|
Tagging Documents
|
How to use this tag set: descriptions and guidance for specific tagging issues. (See
Tagging Documents.)
|
||||||||||||||||
|
Notes for Implementors
|
Provides material for implementors and people modifying or installing a Tag Set. (See
Notes for Implementors.)
|
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 <xref> 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 <xref>) that refer to other elements.
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.
|
|
“yyy-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.
Using the Tag Library to Learn This Tag Set
If you want to learn about the elements and the attributes in this Tag Set so you
can tag documents or learn how the STS standard model is constructed, here is a good
way to start.
- Read the Tag Library General Introduction, taking particular note of the next section that describes the parts of the Tag Library so you will know what resources are available.
- Next, if you do not know the symbols used in the Hierarchy Diagrams, read the “Key to the Near & Far® Diagrams”.
- Scan the Hierarchy Diagrams to get a good sense of the top-level elements and their contents. (Find what is inside a <standard>, now what is inside each of the three large pieces of a standard, keep working your way down. For the other top-level element, <adoption>, check its structures and work down.)
- Pick an element from one of the diagrams. (Look up the element in the Elements Section to find the full element, the definition, usage notes, content allowed inside the element, where the element may be used, and a list of any attributes. Look up one of the attributes to find its full name, usage notes, potential values, and whether it has a default.)
Finally, if you are interested in conversion from a particular source:
- Look at a standard produced by a standards producing organization (and look at the
DTD/schema for the other standard if there is one).
- Can all the information you want to store from the standard fit into the models shown in the diagrams?
- Do you have, or know how to get, all the information the models require? Will that information always be available for documents that are complete and correct?
- How difficult will it be to identify the parts of the information using the elements and attributes described in these models? Would changes to one or more models make this easier?
Terms and Definitions
|
Element
|
Elements are nouns, like “speech” and “speaker”, that represent components of standards
and accompanying metadata.
|
|---|---|
|
Attribute
|
Attributes hold facts about an element, such as which type of list (e.g., numbered,
bulleted, or plain) is being requested when using the List (<list>) tag, or the name of a pointer to an external file that contains an image. Each attribute
has both a name (e.g., @list-type) and a value (e.g., “bullet”).
|
|
Metadata
|
Data about the data, for example, bibliographic information. The distinction is between metadata
elements which describe a standard (such as the name of the
standards producing organization publishing the standard) versus elements which contain
the textual and graphical content of the standard.
|
Tag Library Typographic Conventions
| <alt-text> | The tag name of an element (written in lower case with the entire name surrounded by “< >”) |
| Alternate Title Text For a Figure, Etc. | The element name (long descriptive name of an element) or the descriptive name of an attribute (written in title case, with important words capitalized, and the words separated by spaces) |
| @name | The “@” sign before a name indicates an attribute name. |
| must not | Emphasis to stress a point |