General Introduction

Purpose: Preservation of Intellectual Content

The intent of this Tag Set Suite is to “preserve the intellectual content of journals independent of the form in which that content was originally delivered”. The tags defined here will be used to describe journal articles that originate with many publishers and societies but whose content will be stored in repositories such as the NLM PubMed Central repository. Therefore, the Suite has been optimized for conversion from a variety of journal source tag sets, with the intent of providing a single format in which publishers can deliver their content to a wide range of archives. There are so many journal tag sets currently in use by publishers, repositories, content-aggregators, scientific societies, and compositors that this Suite cannot possibly incorporate all the variation to be found in such diverse models. But a wide variety of structures can be accommodated, since the content models for the elements have been made very flexible, including a wide range of elements with nearly all content structures optional.

The conversion focus also means that this is a larger, more inclusive tag set than might have been necessary if the intent had been, for example, to create only a Journal Authoring Tag Set. Many elements have been created explicitly so that information tagged by publishers would not be discarded when they converted material from another tag set into the Archival Tag Set created from this Suite. Because of the broad scope of the several proposed electronic archives, this Suite contains elements and attributes that may only occur in a very few journals. Attribute values that a particular tag set would probably restrict to a list of explicit options were declared as data character values, so that all options could be accepted. Care has been taken to provide several mechanisms (frequently, information classing “type” attributes) to preserve the intellectual content of a document structure when that structure is converted from another DTD or schema to this tag set, even if there is no exact element equivalent of the structure.

The exact replication of the look and feel of any particular journal has not been a consideration. Therefore, many purely formatting mechanisms have not been included in the tag set.

Scope: Journal Articles Plus

Although the Suite aims at much broader application, this Journal Archiving Tag Set models journal articles, where a journal article is defined as the typical research article found in an STM journal. By design, the definition of an article includes some article-like material also found in journals, for example, letters, editorials, short new pieces, obituaries, meeting reports, and book and product reviews.

By design, this is a model for journal articles, not for complete journals. Thus, there is no overarching model for a collection of articles. In addition, the following journal material has not been described by this tag set:

• Company or product display advertising;
• Job search or classified advertising;
• Calendars, meeting schedules, and conference announcements (except as these can be handled as ordinary articles or sections within articles); and
• Material specific to an individual journal, such as Author Guidelines, Policy and Scope statements, Editorial or advisory boards, detailed indicia, etc.

Introduction to the Journal Archiving Tag Set

The Journal Archiving Tag Set defines a document that is a top-level component of a journal such as an article, a book or product review, or a letter to the editor. Each such document is composed of one or more parts; if there is more than one part, they must appear in the following order:

• Front matter (required). The article front matter contains the metadata for the article (also called article header information), for example, the article title, the journal in which it appears, the date and issue of publication for that issue of that journal, a copyright statement, etc. This is not textual front matter as in books, this is bibliographic information about the article and the journal in which it was published.
• Body of the article (optional). The body of the article is the main textual and graphic content of the article. This usually consists of paragraphs and sections, which may themselves contain figures, tables, sidebars (boxed text), etc. The body of the article is optional to accommodate those repositories that just keep article header information and do not tag the textual content.
• Back matter for the article (optional). If present, the article back matter contains information that is ancillary to the main text, such as a glossary, appendix, or list of cited references.
• Floating Material (optional). A publisher may choose to place all the floating objects in an article and its back matter (such as tables, figures, boxed text sidebars, etc.) into a separate container element outside the narrative flow for convenience of processing.
• Following the front, body, back, and (optional) floating material, there may be either one or more responses to the article or one or more subordinate articles:
  • Response (rarely used). A response is a commentary on the article itself, for example, an opinion from an editor on the importance of the article or a reply from the original author to a letter concerning his article.
  • Sub-article. A sub-article is a small article that is completely contained inside another article, for example, a series of small news stories on the same topic where there is a single introduction, followed by small news pieces.

Modular DTD Design

The Archiving and Interchange Suite has been written as a set of XML DTD “modules”, each of which is a separate physical file. No module is an entire DTD by itself, but these modules can be combined into a number of different DTDs, for example, both an Archival and Interchange DTD and an Archival Authoring DTD. Modules are primarily intended for maintenance; all the elements of the same “type” (class) are stored together.

The Journal Article Archival and Interchange DTD for the National Library of Medicine has been built from these modules; both this DTD and the individual modules will be described in this Tag Library.

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, the description of each element in the Element Section of this documentation names the module in which that element is defined.

There are many advantages to such a modular approach. The smaller units are written once, maintained in one place, and used in many different DTDs. This makes it much easier to keep lower level structures consistent across document types, while allowing for any real differences that analysis identifies. A DTD for a new function (such as an authoring DTD) 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.

Tag Sets Developed from the Suite

As of this writing, the following publicly available Tag Sets have been created from this Suite:

• Journal Archiving and Interchange Tag Set (Archiving) — A public Tag Set into which publishers’ original XML (or SGML) content can be converted, providing a common format for storing this material and for transferring content to any one of a number of archives. This Tag Set has been designed to be open and inclusive, to allow journal articles to be translated from a wide variety of proprietary journal article DTDs and schemas. It is permissive by design, intended to capture whatever warts and wrinkles exist in Publishers’ content.
• Journal Publishing Tag Set (Publishing) — A public Tag Set for use as a repository tag set by archives which desire consistent processing and searching capability. The Publishing Tag Set is a more prescriptive and restrictive subset of the Journal Archiving and Interchange Suite than the Journal Archiving Tag Set (above). This Tag Set may also be used to transfer content between archives or as a base tag set for Publishers.
• Article Authoring Tag Set (Authoring) — A public Tag Set intended for writing and editing new journal articles. The Authoring Tag Set has been designed to enable “good” journal coding and to provide assistance to authors and editors through more restricted models than the interchange and repository tag sets allow.
• NCBI Book, Book Collection, and Historical Book Tag Sets — The NCBI Book Tag Set defines elements and attributes that describe the content of books such as pamphlets and monographs. The NCBI Book Collection Tag Set describes a document that contains metadata for a grouping or “collection” of books, potentially followed by textual information about the books in the collection, and a listing of the books; the content of the books is not included. The NCBI Historical Book Tag Set is a layer on top of the NCBI Book Tag Set specifically designed to describe historical materials by adding structures relevant to the digitization of historical works, for example metadata concerning the digital edition. The three NCBI book tag sets were written to specific NCBI book requirements and are therefore not generic tag sets in the same way that all the journal article tag sets are generic.

Information about these tag sets may be found at the following site:http://ddd.nlm.nih.gov

Accessibility

Because access for a wide range of output devices, as well as for the visually impaired, is becoming more and more important in the STM journal community, the modules in this Suite were designed to follow, as much as possible, the W3C Web Content Accessibility Guidelines 2.0 working draft (22 August 2002), which was the latest accessibility specification available when the Suite was initially constructed. This Specification specifies accessibility guidelines on many levels from design through application. The guidelines which pertain to the modeling of materials were followed to at least Level-2 compliance. For example, a Long Description <long-desc> element was defined as part of many other elements, such as Figure <fig>, so it can be added not only to all figures and other graphical objects, but to any section of the text (for example, to a Boxed Text <boxed-text>) to provide an accessible description of the object. The xml:lang attribute was added to all section-level elements and many paragraph-level elements to permit explicit indication of the language of the content, as required by these guidelines. The Abbreviation or Acronym <abbrev> element (also to be used for acronyms) was added to meet Checkpoint 4.3.

Terms and Definitions

How To Start Using This Tag Library

The NCBI Archiving Tag Set is available on the NLM Journal Archiving and Interchange Tag Suite website including: the Tag Set models expressed as DTDs, XSD schemas, and RELAX NG schemas; one or more tagged sample documents; and this Tag Library documentation (a set of linked HTML files). The DTD file delivery includes the Archiving DTD; the DTD customization files needed for Archiving to over-ride the declarations in the NLM modular Suite, any new modules that define DTD-specific elements, and the modules that comprise the full Suite.

How you use the documentation will depend on what you need to learn about the modules and the DTD.

If you want to learn about the elements and the attributes in this Tag Set, so that you can tag documents or to learn how the journal article model is constructed, here is a good way to start.

• Read the Tag Library General Introduction, taking particular note of the next section which describes the parts of the Tag Library, so you will know what resources are available. Stop just before the section “How To Make New DTDs From These Modules”.
• Next, if you do not know the symbols used in the Document Hierarchy diagrams, read the “Key to the Near & Far® Diagrams”.
• Scan the Document Hierarchy diagrams to get a good sense of the top-level elements and their contents. (Find what is inside an <article>, now what is inside each of the four large pieces of an article, keep working your way down.)
• Pick an element from one of the diagrams. (Look up the element in the Elements Section to find the full name of the element, its definition, usage notes, content allowed, and any attributes. Look up one of the attributes to find its full name, usage notes, and potential values.).
• Finally, if you are interested in conversion from a particular source:
  • Look at an article in a printed or online journal or look at the DTD/schema for the other journal. Can all the information you want to store from an article 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?
  • Now look at some non-article content, such as a news column, a book review, or some letters to the editor. Are there tags to handle all these article types and all their components?

If you want to learn about the Suite in order to write a new DTD:

• Skim the Tag Library General Introduction. (Start really reading at the section “How To Make New DTDs From These Modules”. Scan the DTD modules.)
• 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 name of the element, the definition, usage notes, content allowed, and attributes list. Look up one of the attributes to find its full name, usage notes, and potential values.).
• Read the DTD Modules, given at the end of this documentation.
  New DTDs are created by writing a new DTD module and new customization modules, so you might want to read (in order) the DTD module (archivearticle.dtd), the module that names all the other modules (%modules.ent;), the module that names all customization modules (%archivecustom-modules.ent;), and the customization modules themselves (%archivecustom-classes.ent;, %archivecustom-mixes.ent;, %archivecustom-models.ent;, and %nlmcitation.ent;). (You might also wish to familiarize yourself with the relationship between the “customization” modules and the “default” modules for classes, mixes, and models.) Those can be followed by any one of the class modules (although the Suite has been designed to have the %common.ent; module precede any other class module).

Structure of This Tag Library

This Tag Library contains the following sections:

Tag Library Typographic Conventions

Modular DTD Design

This Suite has been written as a series of XML DTD modules that can be combined into a number of different DTDs. 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.

Modules in the Suite are primarily intended to group elements for maintenance. There are different kinds of modules. A module may either:

• Be a building block for a base DTD (such as the Module to Name the Modules module)
• Define the elements inside a particular structure. For example, the Bibliography References (Citation) Elements Module 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 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 Common (Shared) Element Declarations Module module holds elements and attributes used in the content models of the various class elements.

Parameter Entities Modules to Customize and Change

Parameter Entities are the major mechanism for customizing a DTD or creating a new DTD from the modules in the Suite. Individual DTDs will be constructed by 1) establishing element and attribute combinations and content models using Parameter Entities in one of the DTD-specific customizing modules and 2) choosing appropriate modules from the Suite that declare the elements needed. For example, if the base DTD contained 6 kinds of lists and 2 table models, a more specific DTD, such as an authoring DTD, might use a Customize Classes Module to redefine the List Class to name only 3 lists and redefine the Display Class to allow only one table model.

The standard modules to create a customized DTD are: the DTD itself, a module to name its components, and as many over-ride modules and new elements modules as necessary. Typical modules for a new DTD are:

• DTD — The DTD module (.dtd) for the new DTD base DTD (At a minimum, this module declares the top-level element (such as article, book, or report) and any other structural elements unique to the new document type.)
• DTD-specific Module of Modules — The DTD-specific module of modules, to name all the new modules created expressly for the new DTD
• Class Over-rides — DTD-specific over-rides of the Suite default element classes
• Mix Over-rides — DTD-specific over-rides of the Suite default class mixes
• Model Over-rides — DTD-specific content model over-rides for the content models in the modules of the suite (using “-elements” and “-model” Parameter Entities)
• New Models — DTD-specific new elements (for example, a new Book DTD might add book-specific metadata elements)

Element Classes Concept

Many of the elements in the Journal Archiving DTD have been grouped into loose element classes. There is no hard and fast rule for what constitutes a class; each one is a design decision, a matter of judgment. These classes are designed to ease customization to meet the particular needs of new DTDs. Base classes for the Suite are defined in a separate Default Element Classes Module (%default-classes.ent;).

Content models are built using sequences of elements, and OR groups that are classes (typically) or mixes. As an example, the content model for a Paragraph element is declared to be an OR group (that is, a choice) of text, numbers, or special characters and any of the elements named in the Paragraph Elements mix. The mix %p-elements; is declared to be a large OR group of many other element-defining classes: the Block Display Class Elements, the Mathematical Expressions Class Elements, the List Class Elements, the Citation Class Elements, et al.

These element classes can be viewed as building blocks that will be used to build larger Parameter Entities for element mixes. (Note: A mix describes a usage circumstance for a group of elements, such as all the paragraph-level elements, all the elements allowed inside a table cell, all the elements inside a paragraph, or all the inline elements). For example, to add another block display item to the Block Display Class Elements, you would edit the %block-display.class; Parameter Entity in the DTD-specific Archive Class Over-ride Module to override the default Parameter Entity in the Suite’s Default Element Classes Module module and create a new module containing the Element Declaration of the new block display item.

How To Build a New Custom DTD

Modules in the Archiving and Interchange Suite

The Suite was created to allow a multiplicity of Tag Sets, based on the needs of the intended use, for example, an authoring Tag Set versus one for a repository. The Journal Archiving Tag Set (archivearticle.dtd) and its specific customization modules (%archivecustom-classes.ent;, %archivecustom-mixes.ent;, %archivecustom-models.ent;, and %archivecustom-modules.ent;) define an archival and interchange focused Tag Set. The following modules are critical for the customization process that creates that DTD:

The modules comprising the rest of the Suite are:

Archiving and Suite Naming Rules

 <!ENTITY % list.class "def-list | list">

 <!ENTITY % access-date-elements "| %date-parts.class; | %x.class;" >
 <!ELEMENT  access-date (#PCDATA %access-date-elements;)* >

 <!ENTITY % rendition-plus "| %all-phrase;" >

 <!ENTITY % kwd-group-model "(title?, (%kwd.class; | %x.class;)+ )" >
 <!ELEMENT  kwd-group %kwd-group-model; >
 

File Naming Conventions

DTD — This Tag Library describes the components for the Journal Archiving Tag Set. This Tag Set is described in a DTD, an XSD schema, and a RELAX NG schema. For the DTDs, the base DTD module (delivered as the file journalpublishing.dtd) calls in all the other DTD fragment modules as External Parameter Entities. Each module specific to this DTD (therefore, not part of the Suite) takes the prefix “journalpubcustom-”. The same prefix has been followed in the other two constraint languages schemas.

Each DTD and DTD fragment module has been assigned a unique formal public identifier (fpi). File names are never referenced directly in the comments in the DTD; the file is referred to by the name of the external Parameter Entity, which names the fpi and a system name for the file. The external Parameter Entity has been set to the initial delivery filename.

The Publishing DTD, the individual DTD-fragment modules of the DTD and the Suite, the XSD schema modules, and the RELAX NG schema modules have been given DOS/Windows 3-digit suffixes indicating their type:

While the tag set cannot dictate graphic file names, the comments do suggest that best practice for naming graphic files in documents tagged according to this Suite would be to limit the names and path names to these characters: letters (both upper and lower case), numbers, underscore, hyphen, and period. All such names will be assumed to be case sensitive. DOS-style file extensions may be used.

Later Version Work

Modeling several structures and functions that might appropriately be part of a DTD using this Suite has been delayed until a later version of the Suite. Such components include:

• Questions and Answers (except as they can be modeled with the current DTD by using paragraphs and lists);
• Proper systematic identification keys (except as they can be tagged using regular list structures);
• Continuing Medical Education material;
• Forms and fill-in-the-blank areas;
• Conflict of Interest statements and Financial Disclosures (except as they can be modeled using paragraphs and footnotes);
• Electronic and Digital Rights Management material;
• Advertising included in a journal (for example, employment listings, classified advertising, and display advertising);
• Calendars, meeting schedules, and announcements (except as these can be handled as ordinary articles or sections within articles); and
• Material specific to an individual journal such as Author Guidelines, Policy and Scope statements, Editorial or advisory boards, detailed indicia, etc.