General Introduction

Purpose: Preservation of Intellectual Content

The intent of this DTD 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 DTDs, 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 DTDs 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, because the content models for the elements have been made very flexible, including a wide range of elements with nearly all structures optional.

The conversion focus also means that this is a larger, more inclusive DTD than might have been necessary if the intent had been, for example, to create only a journal-authoring DTD. Many elements have been created explicitly so that information tagged by publishers would not be discarded when they converted material from another DTD to an archival interchange or repository DTD created from this Suite. Because of the broad scope of the several proposed electronic archives, this Suite contains elements and attributes that may occur only in a very few journals. Attribute values that a particular DTD would restrict to a list of 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 attributes) to preserve the intellectual content of a document structure when that structure is converted from another DTD or schema to this one, 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.

Introduction to the Journal Archiving and Interchange DTD

The Journal Archiving and Interchange DTD defines a document that is a component of a journal such as an article, a book or product review, a letter to the editor, etc. Each such document may have up to four components, which must appear in the following order:

• Front matter (required). The article front matter contains the metadata (header information) such as the article title, the journal in which it appears, the date and issue of publication for that issue of that journal, etc.
• Body of the article (required). 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 front matter and body may be all there is to an article.
• Back matter for the article (optional). If present, contains information that is ancillary to the main text, such as a glossary, appendix, or list of references.
• Optionally, either one or more responses 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 (rarely used). A sub-article is a small article that is completely contained inside another article.

For the purposes of the review of draft 1.0 of the Journal Archiving and Interchange DTD, the DTD draws on all the modules in the Suite, as provided.

Modular DTD Design

The Archiving and Interchange DTD Suite has been written as a set of XML DTD modules called 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 Repository DTD. Modules are primarily intended for maintenance; all the elements of the same “type” (class) are stored together.

The first DTD (an Archival and Interchange DTD for the National Library of Medicine) has been built from these modules, and 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, because 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, because most of the necessary components will already be defined in the DTD 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.

Potential DTDs from This Suite of Modules

It has been proposed that three DTDs be created initially from the modules in this DTD Suite:

• Archival Repository DTD — An XML DTD used by one or more archives internally to store their content, to make the repository more uniform for consistent processing and searching. This DTD may also be used to transfer content between archives. This DTD will be designed to be open and inclusive to allow journal articles to be translated from a wide variety of proprietary journal article DTDs. As an example, the repository DTD can include more than one table model to enable conversionless inclusion of both the CALS-derivative and the XHTML-derivative table models that publishers have used.
• Archiving and Interchange DTD — A DTD into which publishers’ original XML (or SGML) content can be converted, providing a common format for transferring content to any one of a number of archives. This DTD may also be used to transfer content between archives. The initial Archiving and Interchange DTD will be written as a proper subset of a larger Archival Repository DTD, so that all documents tagged according to the Archival and Interchange DTD will be, by definition, also deliverable as Archival Repository DTD documents without conversion. This will allow lossless transfer of journal articles between archives.
• Authoring DTD— A Journal Publishing DTD has also been developed that is intended for writing and editing new journal articles. This is a more prescriptive and restrictive subset of the Journal Archiving and Interchange DTD, designed to enable “good” journal coding and to provide assistance to the authors and editors through more restricted models than the repository and interchange DTDs allow.

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, which was the latest accessibility specification available when the Suite was constructed. This Specification specifies accessibility guidelines on many levels from design through application. The guidelines that 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 <fig>; therefore, it can be added not only to all figures and other graphical objects but to any section of the text (for example, to a sidebar <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 element (also to be used for acronyms) was added to meet Checkpoint 4.3[3.5].

Terms and Definitions

How to Start Using This Tag Library

A full DTD Suite delivery package includes the Journal Archiving and Interchange DTD, the customization file for each DTD, the files that make up the full Archiving and Interchange DTD Suite modules, one or more tagged sample documents, and this documentation, as a set of linked HTML files. 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 the Suite 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 that 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 and 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>, then 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 for the other journal. Can all of 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 of 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 of these article types and all of their components?

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

• Skim the Tag Library General Introduction. (Start reading at the section “How to Make New DTDs from These Modules”. Read the Parameter Entities that name the classes. Scan the DTD modules.)
• If you do not know the symbols used in the Document Hierarchy diagrams, then read the “Key to the Near and 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 a new customization module; therefore, you might want to read (in order) the DTD module (archivearticle.dtd), the module that names all the other modules (%modules.ent;), and the customization module (%archivecustomize.ent;). Then read any one of the class modules.

Structure of This Tag Library

This Tag Library contains the following sections:

Tag Library Typographic Conventions

Modular DTD Design

This DTD 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 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 %modules.ent;)
• define the elements inside a particular structure, for example, the Reference 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 Class 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 module that holds elements and attributes used in the content models of the class elements

Parameter Entities to Customize and Change

The Archiving and Interchange DTD Suite makes intensive use of Parameter Entities as 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 and 2) then choosing appropriate modules from the Suite that declare the elements needed. Two modules are central to this reuse: the Module to Name the Modules (which names all of the component modules in the DTD Suite) and the Customization or Customize Classes module (which defines Parameter Entities that will be used to build element models and attribute lists). New DTDs can be constructed by:

• defining in a DTD module the document element (the top-level such as article, book, or report) and any other structural elements unique to the new document type
• selecting, from the Module to Name the Modules, those modules that contain the elements needed for the DTD (for instance, selecting lists and not selecting math elements)
• redefining selected content models and attribute lists through the use of Parameter Entities in the Customization Module

Element Classes

Many of the elements in the Journal Archiving and Interchange DTD have been grouped into loose element classes. These classes are designed to make it easy to customize these DTDs to meet the particular needs of new DTDs, such as an authoring DTD. Most classes are defined in separate modules that bear their name, although a few that are defined are in the Common Module. Thus, the Link Class is defined in the Link Module, the List Class is defined in the List Module, etc. For such class modules, comments at the top of the module name the Parameter Entity used to invoke the class and define the default class membership. (The real class membership is always defined in the DTD-specific Customization Module.) For example, to add a new type of list to the List Class elements, you would edit the List Class Elements Parameter Entity in the Customization Module, add the new Element Declaration to the List Module, and be sure that the DTD was invoking the list module.

These element classes can be viewed as building blocks that will be used to build larger Parameter Entities for element mixes. A mix describes a usage circumstance that all the elements share (such as all the paragraph-level elements, all the elements allowed inside a table cell, all the elements inside a paragraph, or all of the inline elements). Content models are built from these mixes. As an example, the content model for a Paragraph <p> is declared to be an OR group (that is, a choice) of data characters and any of the elements named in the mix called %inside-para;, where the inside-paragraph-mix is declared to be a large OR group of many other element-defining classes: the Block Display Class, the Math Class, the List Class, the Link Class, etc.

There are also a few groupings that are not pure classes but just groupings of convenience. For example, there is no “Address Class”; there is a Parameter Entity called %address-elements; that holds a few of the elements, such as country, email, and fax number, that are the contents of an address element <address> and are defined in the Common Module. There is no hard and fast rule for what constitutes a class; each one is a design decision, a matter of judgment.

How to Build a New DTD

As an illustration, one series of steps to build a new DTD could be as follows.

1. Create a new customization module, defining any overrides to the classes or to other Parameter Entities. This will set up the Parameter Entities and element class definitions used for the content models and attribute lists for the new DTD.
2. Write any new class modules you need or add any additional elements or attributes to the existing class modules and element group modules.
3. Construct a new DTD module, within that DTD:
   • Define the document element and any other unique elements.
   • Use an External Parameter Entity to reference the standard Module to Name the Modules (%modules.ent;), which names all the potential modules.
   • Use an External Parameter Entity to reference the new specific Customization Module (suggested entity: %xxxcustomize.ent;, where “xxx” is the name of the DTD) that establishes the structures.
   • Use an External Parameter Entity to reference the standard Common Module (%common.ent;) that defines elements and attributes so common they are used in many places in the other modules.
   • Use many External Parameter Entities to reference all of the modules you need for your DTD (Note: Do not reference the modules you do not need. For example, if you do not want to use MathML tagging, first use the Customization Module to change the definition of the Math Class (%math.class;), then do not call the MathML Setup Modules (%mathmlsetup.ent;). This module is the one that calls in all of the other MathML Modules.).
   • Define any Parameter Entities needed in the DTD module itself.

The idea is that all lower-level elements (paragraphs, lists, figures, etc.) will be defined in the modules, not in the DTD itself. The DTD will be fairly short and only include definitions of the topmost elements. In the case of the Journal Archiving and Interchange DTD, the elements <article>, <front>, <body>, and <back> are defined.

The Element Classes in the Suite

The classes described here are defined in the Journal Archiving and Interchange DTD Customization Module and have been used to divide the elements into physical modules. The documentation for the classes and their current default element contents are listed in the Parameter Entity Section toward the end of this Tag Library. In the Parameter Entity Section, the names of the elements in a group or class are listed within quotation marks, separated by vertical bars. For example, Phrase Class will be listed as “%phrase.class;” and shown to contain:

"abbrev | named-content"

which means that the two elements <abbrev> and <named-content> are defined as Phrase Class elements.

Modules in the Archiving and Interchange DTD Suite

There is, thus far, one DTD in the module Suite, the Journal Archiving and Interchange DTD (archivearticle.dtd). The DTD module and its specific customization module (%archivecustomize.ent;) define an archival repository and interchange focused DTD. The following modules are critical for the customization process that creates that DTD:

The modules composing the rest of the DTD Suite are:

Archiving and Interchange
Suite Naming Conventions

Phase II DTD Work

In the interest of getting a version of this Suite into production as quickly as practical, several structures and functions that might be appropriately included in a journal DTD have been delayed until a future version of this Suite. Such components include:

• questions and Answers, except as they can be modeled with the current DTDs 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 the journal (for example, job ads, classified advertising, and display advertising)
• calendars, meeting schedules, and announcements, except as these can be handled as ordinary articles or sections within articles
• material specific to an individual journal, such as Author Guidelines, Policy and Scope statements, Editorial or advisory boards, detailed indicia, etc.