Documentation for Implementors

The Authoring DTD comprises a handful of DTD-specific modules that set up Parameter Entity over-rides 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 DTDs in addition to this one.

Because this is a Authoring Tag Set, thus optimized for creating new content, the 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 Archiving and Interchange 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 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. The module files are primarily intended for ease of constructing new DTDs 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 either:

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 a repository 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:

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


Learning the DTD

If you want to learn about the Suite in order to write a new DTD or to modify this one:


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 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 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 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 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 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.

The modules comprising the rest of the 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.

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 Tag Set.

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 tag set 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 XHTML table model, and then invokes the module containing that model

DTD Creation Note: To include the XHTML table model in a tag set, 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. (See next item.)

XHTML Table Model Module

(Parameter Entity %xhtml-table-1.mod;) The public XML DTD version of the XHTML table model. This module is invoked from the module %XHTMLtablesetup.ent;. (See previous item.) This is the default table model for this tag set.

XHTML Table Style Module

(Parameter Entity %xhtml-inlstyle-1.mod;) Declares the style attribute, which supports inline style markup for elements such as <td>and <tr> elements within XHTML tables.

OASIS XML Table Setup Module

(Parameter Entity %oasis-tablesetup.ent;) Note: Not used in the current Archiving Tag Set. Sets all Parameter Entities needed by the OASIS (CALS) Exchange table model, and then invokes the module containing that model

DTD Creation Note: To include the OASIS table model in a DTD, the DTD must reference this module. This module sets up all Parameter Entities needed to use the OASIS table model and references (invokes) the OASIS XML Exchange Table Model Module. This module has been modified to use a namespace prefix of “oasis” for all OASIS table elements, to disambiguate these elements and thus permit both the CALS and XHTML table models to be used in one tag set, should the developer choose to do this. There is a separate http://dtd.nlm.nih.gov/options/OASIS/tag-library/19990315/index.htmlTag Library describing the OASIS elements, attributes, and Parameter Entities.

OASIS XML Exchange Table Model Module

(Parameter Entity %oasis-exchange.ent;) Note: Not used in the current Archiving Tag Set. The OASIS (CALS) Exchange table model. This module is invoked in %oasis-tablesetup.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 Suite. These notations have been placed in their own module for easy expansion or replacement.


How To Make New DTDs


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 full 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 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: 1) the DTD itself, 2) a module to name its component modules, and 3) as many over-ride modules (class, mix, and/or model) and new elements modules as necessary. Thus, typical modules for a new DTD are:

  • DTD — The DTD module (articleauthoring.dtd) for the new DTD base DTD (At a minimum, this module declares the top-level element (such as article, book, help-topic, 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); and
  • New Model Modules — DTD-specific new elements (for example, a new Book DTD might add book-specific metadata elements or a DTD for historical material might add a module to define annotations.)


How To Build a New Custom DTD


The Concept

The basic idea for a new DTD is that all lower-level elements (paragraphs, lists, figures, etc.) will be defined in modules — either the modules of the base Suite or in new DTD-specific modules rather than in the DTD itself. The new DTD will be fairly short and include only definitions of the topmost elements, at least the document element and maybe its children.

Modules are defined (declared) using External Parameter Entities in the Suite’s Module to Name the Modules or in the DTD-specific Module of Modules. Modules are called (referenced) in the DTD proper, in the order needed to define the Parameter Entities in sequence.

This Authoring DTD was written as an example of the new best-practice customization technique. A new variant DTD that follows this plan will probably consist of the following modules:

  • A DTD module to define the top-level elements (for example, articleauthoring.dtd);
  • A DTD-specific Module of Modules to name new non-Suite modules in the DTD (for example, %articleauthcustom-modules.ent;);
  • A DTD-specific definition of element classes to add new classes and over-ride the default classes (for example, %articleauthcustom-classes.ent;);
  • A DTD-specific definition of element mixes to add new mixes and over-ride the default mixes (for example, %articleauthcustom-classes.ent;);
  • A DTD-specific module of content model over-rides (for example, %articleauthcustom-models.ent;);
  • DTD-specific modules to hold new element declarations; and
  • All or most of the modules in the Suite.


Making a Variant DTD

To show the process, here is a series of instructions for making a new DTD, illustrated by showing how the Authoring DTD was created from the modules of the whole Suite.

  1. Modules — Write a new DTD-specific Module of Modules, which defines all new customization modules the DTD needs. (As an example, the Authoring DTD created the module %articleauthcustom-modules.ent;, which contains the definitions of the class-over-ride module %articleauthcustom-classes.ent;, the mix-over-ride module %articleauthcustom-mixes.ent;, and the models-over-ride module %articleauthcustom-models.ent;.)
  2. Class Over-rides — Write a DTD-specific class-over-ride module, defining any over-rides to the Suite classes. These classes are defined in the default classes module, %default-classes.ent;. (As an example, the Authoring DTD created the module %articleauthcustom-classes.ent;, in which several new models, including %rest-of-para.class.class; and %name.class;, were declared.)
  3. Mix Over-rides — Write a DTD-specific mix-over-ride module, defining any over-rides to the Suite mixes. These mixes are defined in the default mixes module, %default-mixes.ent;. (As an example, the Authoring DTD created the module %articleauthcustom-mixes.ent;, in which mixes such as %emphasized-text; and %simple-phrase; were declared.)
  4. Model Over-rides — Create a DTD-specific content-model-over-ride module, defining any over-rides to the content models and attribute lists for the Suite. (As an example, the Authoring DTD created the module %articleauthcustom-models.ent;, in which element collections (suffixed “-elements”) that will be mixed with #PCDATA were redefined, full content models over-rides (suffixed “-model”) were redefined, and some new attributes and attribute lists were added.)
  5. New Elements — Write any new element modules needed. These will define any new block-level or phrase-level elements. (As an example, the Authoring DTD includes the module %nlmcitation.ent;, in which a more prescriptive citation element, <nlm-citation>, is declared.)
  6. DTD Module — With those modules in place, construct a new DTD module. Within that module:
    • Use an External Parameter Entity Declaration to name and then call the DTD-specific modules of modules. (For the Authoring DTD, the module %articleauthcustom-modules.ent;)
    • Use an External Parameter Entity Declaration to name and then call the Suite Modules of Modules, which names all the potential modules. (For the Authoring DTD, the module %modules.ent;)
    • Use an External Parameter Entity reference to call the DTD-specific class over-rides. (For the Authoring DTD, the module %articleauthcustom-classes.ent;)
    • Use an External Parameter Entity reference to call the Suite default classes. (For the Authoring DTD, the module %default-classes.ent;)
    • Use an External Parameter Entity reference to call the DTD-specific mix over-rides. (For the Authoring DTD, the module %articleauthcustom-mixes.ent;)
    • Use an External Parameter Entity reference to call the Suite default mixes. (For the Authoring DTD, the module %default-mixes.ent;)
    • Use an External Parameter Entity reference to call the DTD-specific content models and attribute list over-rides. (For the Authoring DTD, the module %articleauthcustom-models.ent;)
    • Use an External Parameter Entity reference to call in the standard Common Module (%common.ent;) that defines elements and attributes so common they are used by many modules.
    • Use an External Parameter Entity reference to call any DTD-specific module defining block-level or phrase-level elements. (For the Authoring DTD, the module %nlmcitation.ent; in which a more prescriptive citation element, <nlm-citation>, is declared)
    • Select, from the Module of Modules, those modules which contain the elements needed for the DTD (for instance, selecting lists and not selecting math elements) and calling in each of the modules needed. (The Authoring DTD calls these in alphabetical order, since the order does not matter.)
    • Define the document element and any other unique elements and entities needed for this DTD. (For example, the Authoring DTD declares only four elements — <article> [the top-level element] and its components: <front>, <body>, and <back>.)


Authoring and Suite Naming Rules


Element and Attribute Naming Rules

  • CASE — Element, attribute, and entity names that originate with this Tag Set or with the Suite are in all lower case. Element and attribute names taken from PUBLIC modules (e.g., MathML and various table modules) incorporated into these Tag Sets are in the case in which they were found in the original module.
  • TWO-WORD NAMES — Elements named with two words are separated by a hyphen, for example, <def-list> and <term-head>.
  • WORD STANDARDIZATION — Abbreviations are standardized so that, for example, “keyword” is always used as “kwd” (as in the element <kwd-group>) and group is not abbreviated (as in the element <kwd-group>). The naming rules are described in the Authoring and Suite Naming Rules section of this Tag Library.

Parameter Entity Names for Classes and Mixes

PARAMETER ENTITY: SAME FUNCTION, SAME NAME — The Suite modules and initial DTDs have used a series of Parameter Entity naming conventions consistently. While parsing software cannot enforce these Parameter Entity naming or usage conventions, these conventions can make it much easier for a person to know how the content models work and what must be modified to make a DTD change.

CLASSES — Classes are functional groupings of elements used together in an OR group. Each class is named with a Parameter Entity, and all class Parameter Entity names end in the suffix “.class”:

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

A class, by definition, should never be made “empty”; the class should be removed from all models where you do not want the class elements included.

MIXES — Mixes are functional OR groups of classes; mixes should never contain element names directly. All mixes must be declared after all classes, since mixes are composed of classes. Mix names have no set suffix; for example, they may end in “-mix” or “-elements”. Content models and content model over-rides use mixes and classes for all OR groups. Only content model sequences are made up of element names directly.

MODEL OVER-RIDES — Parameter Entity mixes for over-riding a content model are of two styles: 1) inline mixes and 2) full content model replacements. These two groupings have been defined and named separately to preserve the mixed-content or element-content nature of the models in DTDs derived from the Suite.

The inline Parameter Entities to be intermingled with character data (#PCDATA) in a mixed content model are named with a suffix “-elements”. For example, “%institution-elements;” would be used in the content model for the element <institution>:

 <!ENTITY % institution-elements "| %break.class; | %emphasis.class; | %subsup.class;" >
 <!ELEMENT  institution (#PCDATA %institution-elements;)* >

All inline mixes begin with an OR bar, so that the mix can be removed leaving just character data (#PCDATA):

 <!ENTITY % rendition-plus "| %emphasis.class;  | %subsup.class;" >

The over-ride of a complete content model will be named with a suffix “-model” and should include the entire content model, including the enclosing parentheses:

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

File Naming Conventions

DTD — This Tag Library describes the components for the Article Authoring 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 Authoring 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:

*.dtd

A module that can be used as the top level of an XML hierarchy. Used for the Authoring DTD top level, articleauthoring.dtd, but also taken unchanged for public DTD modules that have been included in this DTD such as the MathML Tag Set and the XHTML table model.

*.ent

A DTD fragment for incorporation into a full DTD. May contain element declarations, entity declarations, etc., for example, articlemeta.ent.

*.mod

A DTD fragment for incorporation into a full DTD. May contain element declarations, entity declarations, etc. This extension has the same meaning as *.ent and is only used to maintain the extension names dictated by the inclusion of PUBLIC DTD and/or schema fragments, for example, mathml2-qname-1.mod.

*.xsd

A W3C XML Schema (XSD) schema or schema module, for example, journalpublishing.xsd.

*.rng

A RELAX NG schema module, for example, journalpublishing.rng and articlemeta.ent.rng.

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

This tag set has chosen not to model several structures and functions that might appropriately have been part of a journal article tag set. These may be implemented in a later version of the Suite. Such components include:

  • Questions and Answers (except as they can be modeled with the current tag set 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.