Modifying This Tag Set
The Authoring Tag Set comprises a handful of Tag-Set-specific modules that set up parameter entity overrides and uses (by reference) the base modules of the full Journal Archiving and Interchange Suite. The modules of that Suite were developed as part of an effort to create XML applications through which materials on health-related disciplines could be shared and reused electronically. Although the full Suite was developed to support electronic production, the structures should be adequate to support some print production as well. The Suite has been used to construct many tag sets in addition to this one.
Because this is a Authoring Tag Set, thus optimized for creating new content, this Tag Set is far smaller (fewer elements, and fewer choices in many contexts) than either the Archiving or the Publishing Tag Sets. Where, in the Archiving Tag Set, there may have been several ways to express the same information, the goal was to allow only one way in this Authoring Tag Set. It was not the intention to limit the expressive power licensed by this Tag Set, but rather to limit the meaningless choices that a full interchange Tag Set needs to make to accommodate conversion from as wide a variety of formats as possible. The philosophy for the Archiving Tag Set was to accept as many varied forms of many structures as possible unchanged. The philosophy for the Publishing Tag Set was to accept a wide variety of structures and to regularize those that matter to the archive. The philosophy of this Authoring Tag Set is to prefer a single structural form, or at least a single style of tagging, whenever possible. Similarly the Archiving and Publishing Tag Sets allow for formatting such as list numbering and citation references to be preserved. This Tag Set assumes that such objects will need to be generated as part of production.
Modular DTD Design
The Authoring Tag Set has been written as a set of DTD “modules” that make use of the modules of the JATS DTD Suite. Each module is a separate physical file, no module is an entire DTD by itself, and modules can be combined into a number of different tag sets. The modules are separate physical files that, taken together, define all element structures (such as tables, math, chemistry, paragraphs, sections, figures, footnotes, and reference elements), as well as attributes and entities in the Suite. The module files are primarily intended for ease of constructing new tag sets and ease of maintenance.
Modules in the Suite are primarily intended to group elements for maintenance. There are different kinds of modules. A module may:
- Be a building block for a base tag set (such as the module Module to Name the Modules)
- Define the elements inside a particular structure. For example, the Bibliography References (Citation) Elements Module names all the potential components of bibliographic reference lists.
- Name the members of a “class” of elements, where class is a named grouping of elements that share a similar usage or potential location. For example, the Phrase-Level Content Elements Module defines small floating elements that may occur within text, such as inside a paragraph or a title, or that describe textual content, for example, a disease name, drug name, or the name of a discipline.
- Be a module of “editorial convenience”. For example, the module Common (Shared) Element Declarations Module holds elements and attributes used in the content models of the various class elements.
The major disadvantage of a modular system is the longer learning curve, since it may not be immediately obvious where within the system to find a particular element or attribute cluster. To help with this, each element page includes an expanded content model.
There are many advantages to such a modular approach. The smaller units are written once, maintained in one place, and used in many different tag sets. This makes it much easier to keep lower level structures consistent across document types, while allowing for any real differences that analysis identifies. A tag set for a new function (such as a Repository Tag Set) or a new publication type can be built quickly, since most of the necessary components will already be defined in the Suite. Editorial and production personnel can bring the experience gained on one tagging project directly to the next with very little loss or retraining. Customized software (including authoring, typesetting, and electronic display tools) can be written once, shared among projects, and modified only for real distinctions.
How to Start Using This Tag Library
If you want to learn about this Tag Set in order to write a new Tag Set based on this Tag Set or to modify this Tag Set:
- Skim the first two chapters of this Tag Library, the How to Use and the Tag Library General Introduction.
- Read the parameter entities that name the classes (in the module %default-classes.ent;).
- If you do not know the symbols used in the Document Hierarchy diagrams, then read the “Key to the Near & Far® Diagrams”.
- Use the Document Hierarchy diagrams to give you a good sense of the top-level elements and their contents.
- 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.)
- Read the DTD Modules. New tag sets are created by writing, at a minimum, a new DTD module
and new tag-set-specific customization modules, so you might want to read the modules in this
- The DTD module (JATS-articleauthoring1.dtd);
- The module that names all the Authoring-Tag-Set-specific customization and element modules (%articleauthcustom-modules.ent;);
- The module that names all the other modules in the Suite (%modules.ent;);
- The book customization modules (%articleauthcustom-classes.ent;, %articleauthcustom-mixes.ent;, and %articleauthcustom-models.ent;);
- Any one of the many class-defining modules from the Suite (for example, the %list.ent; module).
Namespaces and MathML
When JATS was first designed, many software tools did not handle multiple redefinitions of the same namespace cleanly and correctly. Therefore, the following namespace prefixes, namespace URIs, and xsmlns declarations are declared in the MathML DTD setup modules or in the MathML 2.0 and MathML 3.0 QName modules (and MathML 2.0 and MathML 3.0 schema modules for XSD and RNG):
- The XLink prefix is set to “xlink”.
- The XLink namespace URI is set to “http://www.w3.org/1999/xlink”
- The XLink xmlns pseudo-attribute is set as follows, for use in attribute lists: "xmlns:xlink CDATA #FIXED 'http://www.w3.org/1999/xlink'
- The MathML namespace prefix is set to “mml”.
- The MathML namespace URI is set to “http://www.w3.org/1998/Math/MathML”.
- The MathML xmlns pseudo-attribute is set as follows, for use in attribute lists: "xmlns:mml CDATA #FIXED 'http://www.w3.org/1998/Math/MathML'
- W3C Schema Instance
- The W3C Schema namespace prefix is set to “xsi”.
- The W3C Schema namespace URI is set to “http://www.w3.org/2001/XMLSchema-instance”.
- The W3C schema xmlns pseudo-attribute is set as follows, for use in attribute lists: xmlns:xsi CDATA #FIXED 'http://www.w3.org/2001/XMLSchema-instance'.
This definition outside the ordinary JATS modules has annoying subsetting implications. It means that if you do not include the MathML setup modules and MathML modules in your tag set, you will not have those namespaces defined
Thus, if you want to use the JATS modules to create a tag set that does not include MathML, there are two options open to you:
- Include the MathML setup modules and MathML DTD modules and ignore them in your tagging and in your documentation; or
- Write your own namespace setup module that declares the namespaces mentioned above.