Structure of the Authoring DTD


Element Classes

Many of the elements in the Authoring 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 Archiving and Interchange DTD Suite are defined in a separate Default Element Classes Module (%default-classes.ent;).

Content models are built using sequences of elements by element name, but OR groups typically do not use element names, ORs offer choices of classes (the usual) or mixes. As an example, the content model for a Paragraph element is declared to be an OR group (that is, a choice) of data characters and any of the elements named in the Paragraph Elements mix (%p-elements;). 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.

Element classes can be viewed as building blocks 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 Article Authoring Class Over-ride Module to override the default Parameter Entity in the DTD Suite’s Default Element Classes Module module and create a new module containing the Element Declaration of the new block display item.


The Element Classes in the Suite

The classes described here — with a few exceptions noted below — are defined in the Archiving and Interchange DTD Suite Default Element Classes Module (%default-classes.ent;) 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.

Accessibility Class

(%access.class;) Elements added to make the processing of journal articles more accessible to people with special needs and the devices that meet those needs, for example, the visually handicapped. Includes, for example, the element <alt-text> which is a short phrase name or description of an object, usually a graphical object, that can be used “behind the picture” on a website or pronounced in an audio system.

Address Class

(%address.class;) Potential element components of an address, such as <country> or <fax>

Appearance Class

(%appearance.class;) Formatting elements used primarily in tables, for example, a horizontal rule (usage discouraged)

Appendix Class

(%app.class;) A construct containing only the appendix for use in the back matter of an article

Break Class

(%break.class;) Formatting element used to force a line break, primarily in tables and titles (usage discouraged)

Citation Class

(%citation.class;) Reference (a citation) to an external document as used within, for example, the text of a paragraph

Contributor Information Class

(%contrib-info.class;) Metadata about a contributor

Definition Class

(%def.class;) Definitions (<def>) and other elements to match with terms and abbreviations

Degree Class

(%degree.class;) The academic or professional degrees that accompany a person’s name

Display Class

(Several Parameter Entities: %caption.class;, %block-display.class;, %display-back-matter.class;, %inline-display.class;, %simple-display.class;, %simple-intable-display.class;) Graphical or other display-related elements, including figures, chemical formulas, and images [Parameter Entities %block-display.class;, %inline-display.class;, and %simple-display.class; defined in the %articleauthcustom-classes.ent; module]

Emphasis Class

(%emphasis.class;, %subsup.class;) Used to produce rendering/typographical distinctions, such as superscript, subscript, or bold text [Parameter Entity %emphasis.class; defined in the %articleauthcustom-classes.ent; module]

Identifier Class

(%id.class;) DOIs and other identifiers used by publishers at many levels, for example, for an <abstract> or a <fig>

Keyword Class

(%kwd.class;) Keywords and other elements which name a subject term, critical expression, key phrase, etc. associated with an entire document and used for identification and indexing purposes

Link Class

(Several Parameter Entities: %address-link.class;, %article-link.class;, %simple-link.class;, %fn-link.class;) Elements that associate one location with another, including cross references, and URIs for links to the World Wide Web

List Class

(%list.class;) The types of lists used in text, including numbered lists and bulleted lists

Math Class

(Several Parameter Entities: %math.class;, %block-math.class;, %inline-math.class;) The mathematical element (<mml:math>) and the elements that can contain them (such as <inline-formula> and <disp-formula>) [Parameter Entity %math.class; defined in the %articleauthcustom-classes.ent; module]

Name Class

(%name.class;) The various types of names (such as <collab>) for people who produce products or articles [Defined in the %articleauthcustom-classes.ent; module]

Paragraph Class

(Several Parameter Entities: %just-para.class;, %rest-of-para.class;, %intable-para.class;) Information for the reader that is at the same structural level as a paragraph, including both regular paragraphs and specially-named paragraphs that may have distinctive uses or different displays, such as dialogs and formal statements [Parameter Entities %rest-of-para.class; and %intable-para.class; defined in the %articleauthcustom-classes.ent; module]

Personal Name Class

(%person-name.class;) The element components of a person’s name (such as <surname>),which can be used, for example, inside the name of a contributor

Phrase Class

(%phrase.class;) Inline elements that surround a word or phrase in text because the subject (content) should be identified to support some kind of display, searching, or processing (such as <abbrev> to identify an abbreviation).

Reference Class

(%references.class;) The elements that may be included inside a <citation> (bibliographic reference) [Defined in the %articleauthcustom-classes.ent; module]

Reference List Class

(%ref-list.class;) A construct containing only the reference list (defined in References Module) for use in the back matter of an article

Section Class

(%sec.class;) The elements that are at the same hierarchical level as a section

Table Class

(Several Parameter Entities: %table.class;, %just-table.class;, and %table-foot.class;) Elements that contain the rows and columns inside the Table Wrapper element (<table-wrap>). The following XHTML table model elements can be set up for inclusion: <table>.


Modules in the DTD and Suite

The DTD Suite was created to allow a multiplicity of DTDs, based on the needs of the intended use, for example, an authoring DTD versus one for a repository. The Authoring DTD (articleauthoring.dtd) and its specific customization modules (%articleauthcustom-classes.ent;, %articleauthcustom-mixes.ent;, %articleauthcustom-models.ent;, and %articleauthcustom-modules.ent;) define an authoring DTD focused on consistent modeling, processing and searching capability. The following modules are critical for the customization process that creates that DTD:

Authoring DTD

(File name articleauthoring.dtd) The top-level Authoring DTD Module that declares the document element (<article>) and the other top-level elements that define a journal article (front matter, body, and back matter). All elements but these few — and the element <nlm-citation> — are declared in the modules of the Suite. The DTD invokes all the other modules it uses, by reference, as external Parameter Entities: first the Authoring DTD-Specific Module of Modules is called to name all Article Authoring-specific customized modules, then the Suite Module of Modules is called to name all the potential modules from the Suite, then customized and default modules are called (for Parameter Entities naming element classes, mixes, and models), then the Common Module for shared elements and attribute lists is called, and finally all the other modules are called as needed, including the DTD-specific element module, %nlmcitation.ent;.

Module to Name Authoring DTD-Specific Modules

(Parameter Entity %articleauthcustom-modules.ent;) Defines all the external modules that are specific to the Authoring DTD (except itself, which must be both named and called inside a DTD). A DTD selects from these modules by referencing the module names through external Parameter Entities. The entities are declared in the Authoring DTD-Specific Module of Modules (%articleauthcustom-modules.ent;), but referenced (or not) in the DTD proper. To include a set of elements (such as all the lists or all the MathML elements), a DTD references the external Parameter Entity of the module that contains these declarations.

Note: The Authoring DTD-Specific Module of Modules and the Suite Module to Name the Modules need to be the first two external modules called by the Authoring DTD. Customization modules for classes, mixes, and models will typically be called following the Authoring DTD-Specific Modules and the Module to Name the Modules.

Suite Module to Name the Modules

(Parameter Entity %modules.ent;) Defines all the external modules that are part of the modular Archiving and Interchange DTD Suite (except itself, which must be both named and called inside a DTD). A DTD selects from these modules by referencing the module names through external Parameter Entities. The entities are declared in the Module to Name the Modules (%modules.ent;), but referenced (or not) in the DTD proper. To include a set of elements (such as all the article metadata or all the display elements) a DTD references the external Parameter Entity of the module that contains these declarations.

Note: The Authoring DTD-Specific Modules and the Suite Module to Name the Modules need to be the first two external modules called by the Authoring DTD. Customization modules for classes, mixes, and models will typically be called following the Authoring DTD-Specific Modules and the Module to Name the Modules.

Authoring DTD Class Customizations Module

(Parameter Entity %articleauthcustom-classes.ent;) Sets up Parameter Entities that will be used to override default classes prescribed by the %default-classes.ent; module

Note: This module must be called after the Authoring DTD-Specific Modules (%articleauthcustom-modules.ent;) and the Suite Module to Name the Modules (%modules.ent;) but before any other module, including specifically the %default-classes.ent; module (which this module overrides) and the %articleauthcustom-mixes.ent; and %articleauthcustom-models.ent; modules (which build on this module).

Suite Default Element Classes Module

(Parameter Entity %default-classes.ent;) Sets up the Parameter Entities that name the element members of each class that will be used to establish the content models

Note: This module must be called before the Article Authoring Over-ride Mixes Module (%articleauthcustom-mixes.ent;) and the Default Element Mixes Module (%default-mixes.ent;), as well as the Article Authoring Over-ride Models Module, %articleauthcustom-models.ent; (which builds on those modules).

Authoring DTD Mix Customizations Module

(Parameter Entity %articleauthcustom-mixes.ent;) Sets up Parameter Entities that will be used to override default mixes (groupings made of “classes”) prescribed by the %default-mixes.ent; module

Note: This module must be called after the Article Authoring Over-ride Classes Module (%articleauthcustom-classes.ent;) and the Default Classes Module (%default-classes.ent;) but before any other module, including specifically the %default-mixes.ent; module (which this module overrides) and the %articleauthcustom-models.ent; module (which builds on this module).

Suite Default Element Mixes Module

(Parameter Entity %default-mixes.ent;) Sets up the Parameter Entities that name mixes (groupings made of “classes”) that will be used to establish the content models

Note: This module must be called before the Article Authoring Over-ride Models Module (%articleauthcustom-models.ent;) or any “base” module of the interchange Suite.

Journal Publishing DTD Models/Attributes Customizations Module

(Parameter Entity %articleauthcustom-models.ent;) Sets up Parameter Entities that will be used to override default content model Parameter Entities set elsewhere in the Suite. Also defines customizable attribute Declared Values and attribute lists for the DTD being defined.

Note: This module must be called after the Article Authoring Over-ride Mixes Module (%articleauthcustom-mixes.ent;) and Default Mixes Module (%default-mixes.ent;) but before any “base” module of the interchange Suite.

Authoring DTD NLM Citation Module

(Parameter Entity %nlmcitation.ent;) Adds the model for the NLM structured bibliographic citation element (<nlm-citation>). This model for a cited reference loosely reflects the NLM’s formal bibliographic style. The model allows the tagging of all “legal” NLM citations and enforces the sequence in which content must appear. However, this model does not provide guidance on what information is required for each type of cited content; such guidance must be controlled editorially.

Note: This is the only module defining a new element added to the Suite by this DTD. The module %nlmcitation.ent; was initially written as part of the Journal Publishing DTD and is used without change by this DTD.>

The modules comprising the rest of the DTD Suite that are used in this DTD are:

Common (Shared) Elements Module

(Parameter Entity %common.ent;) Declarations for elements, attributes, entities, and notations that are shared by more than one class module

Note: This module must be called before any of the modules comprising the interchange Suite.

Article Metadata Elements Module

(Parameter Entity %articlemeta.ent;) Declares the metadata elements (issue elements and article header elements) used to describe a journal article

Back Matter Elements Module

(Parameter Entity %backmatter.ent;) Declares elements that are not part of the main textual flow of a work, but are considered to be ancillary material such as appendices, glossaries, and bibliographic reference lists

Display Class Elements Module

(Parameter Entity %display.ent;) Declares the display-related elements, such as figures, graphics, math, chemical expressions and structures, tables, etc.

Format Class Elements Module

(Parameter Entity %format.ent;) Declares elements concerned with rendition of output, for example, printing on a page or display on a screen. This module includes the elements in the Appearance Class, the Break Class, and the Emphasis Class.

Link Class Elements Module

(Parameter Entity %link.ent;) Declares elements that are links (internal or external) by definition, such as URLs (<uri>) and internal cross references (<xref>)

List Class Elements Module

(Parameter Entity %list.ent;) Declares the elements in the List Class; these are all lists except the lists of bibliographic references (citations). Lists are considered to be composed of items.

Math Class Elements Module

(Parameter Entity %math.ent;) Declares the elements in the math classes such as display equations

Paragraph-Like Elements Module

(Parameter Entity %para.ent;) Declares structural, non-display elements that may appear in the same places as a paragraph. These elements are named in the various paragraph class Parameter Entities.

Subject Phrase Class Elements Module

(Parameter Entity %phrase.ent;) Declares the Phrase Class elements, that is, names the inline, subject-specific elements. At the time of this DTD’s creation, there are only two phrase-level elements, Abbreviation or Acronym (<abbrev>) and Named Special (Subject) Content (<named-content>). If more specific subject words (such as “gene”) are added to later versions of this DTD, they should be added to the %phrase.class; Parameter Entity and defined in this module or in the Common Module, %common.ent;.

Bibliographic Reference (Citation) Class Elements Module

(Parameter Entity %references.ent;) Declares the bibliographic reference elements

Section Class Elements Module

(Parameter Entity %section.ent;) Declares the elements of the Section Class, that is, declares all section-level elements in the Authoring DTD. At the time of this DTD’s creation, there is only one such element, Section (<sec>) itself, but future expansion to named sections (such as <methodology> or <materials>) or any new section-level structures would be added here.

MathML Setup Module

(Parameter Entity %mathmlsetup.ent;) Invokes the MathML modules

DTD Creation Note: To include the MathML elements, a DTD must reference this module. This module sets up all Parameter Entities needed to use the MathML tagset and references (invokes) the MathML 2.0 DTD Module, which, in turn, invokes all the other MathML modules.

MathML 2.0 DTD Module

(Parameter Entity %mathml.dtd;) Mathematical Markup Language (MathML) 2.0, an XML application for describing mathematical notation and capturing both its structure and content

MathML 2.0 Qualified Names 1.0

(Parameter Entity %mathml-qname.mod;) Declares Parameter Entities to support namespace-qualified names, namespace declarations, and name prefixing for MathML, as well as declares the Parameter Entities used to provide namespace-qualified names for all MathML element types

Extra Entities for MathML 2.0

(Parameter Entity %ent-mmlextra;) Used for MathML processing

Aliases for MathML 2.0

(Parameter Entity %ent-mmlalias;) Used for MathML processing

XHTML Table Setup Module

(Parameter Entity %XHTMLtablesetup.ent;) Sets all Parameter Entities needed by the HTML 4.0 (XHTML) table model, and then invokes the module containing that model

DTD Creation Note: To include the XHTML table model, a DTD must reference this module. This module sets up all Parameter Entities needed to use the XHTML table model and references (invokes) the XHTML Table Model Module.

XHTML Table Model Module

(Parameter Entity %htmltable.dtd;) The public XML version of the HTML 4.0 (XHTML) table model. This module is invoked in %XHTMLtablesetup.ent;.

XML Special Characters Module

(Parameter Entity %xmlspecchars.ent;) Standard ISO XML special character entities used in this DTD

Custom Special Characters Module

(Parameter Entity %chars.ent;) Custom special character entities created specifically for use in this DTD

Notation Declarations Module

(Parameter Entity %notat.ent;) Container module for the Notation Declarations to be used with this DTD Suite. These notations have been placed in their own module for easy expansion or replacement.