Modifying This Tag Set
The Authoring Tag Set comprises a handful of Tag-Set-specific modules that set up parameter
entity overrides and uses (by reference) the base modules of the full Journal Archiving and
Interchange Suite. The modules of that Suite were developed as part of an effort to create XML
applications through which materials on health-related disciplines could be shared and reused
electronically. Although the full Suite was developed to support electronic production, the
structures should be adequate to support some print production as well. The Suite has been used
to construct many tag sets in addition to this one.
Because this is a Authoring Tag Set, thus optimized for creating new content, this Tag Set is
far smaller (fewer elements, and fewer choices in many contexts) than either the Archiving or the
Publishing Tag Sets. Where, in the Archiving Tag Set, there may have been several ways to express
the same information, the goal was to allow only one way in this Authoring Tag Set. It was not
the intention to limit the expressive power licensed by this Tag Set, but rather to limit the
meaningless choices that a full interchange Tag Set needs to make to accommodate conversion from
as wide a variety of formats as possible. The philosophy for the Archiving Tag Set was to accept
as many varied forms of many structures as possible unchanged. The philosophy for the Publishing
Tag Set was to accept a wide variety of structures and to regularize those that matter to the
archive. The philosophy of this Authoring Tag Set is to prefer a single structural form, or at
least a single style of tagging, whenever possible. Similarly the Archiving and Publishing Tag
Sets allow for formatting such as list numbering and citation references to be preserved. This
Tag Set assumes that such objects will need to be generated as part of production.
Modular DTD Design
The Authoring Tag Set has been written as a set of DTD “modules” that make
use of the modules of the JATS DTD Suite. Each module is a separate physical
file, no module is an entire DTD by itself, and modules can be combined into a number of
different tag sets. The modules are separate physical files that, taken together, define all
element structures (such as tables, math, chemistry, paragraphs, sections, figures, footnotes,
and reference elements), as well as attributes and entities in the Suite. The module files are
primarily intended for ease of constructing new tag sets and ease of maintenance.
Modules in the Suite are primarily intended to group elements for maintenance. There are
different kinds of modules. A module may:
- Be a building block for a base tag set (such as the Module to Name the Modules module)
- Define the elements inside a particular structure. For example, the Bibliography References (Citation) Elements Module names all the potential components of bibliographic reference lists.
- Name the members of a “class” of elements, where class is a named grouping of elements that share a similar usage or potential location. For example, the Phrase-Level Content Elements Module defines small floating elements that may occur within text, such as inside a paragraph or a title, or that describe textual content, for example, a disease name, drug name, or the name of a discipline.
- Be a module of “editorial convenience”. For example, the Common (Shared) Element Declarations Module module holds elements and attributes used in the content models of the various class elements.
The major disadvantage of a modular system is the longer learning curve, since it may not
be immediately obvious where within the system to find a
particular element or attribute cluster. To help with this, each element page includes an
expanded content model and also 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 tag sets. This makes it much easier to keep
lower level structures consistent across document types, while allowing for any real differences
that analysis identifies. A tag set for a new function (such as a Repository Tag Set) or a new
publication type can be built quickly, since most of the necessary components will already be
defined in the Suite. Editorial and production personnel can bring the experience gained on one
tagging project directly to the next with very little loss or retraining. Customized software
(including authoring, typesetting, and electronic display tools) can be written once, shared
among projects, and modified only for real distinctions.
How to Start Using This Tag Library
If you want to learn about this Tag Set in order to write a new Tag Set based on this Tag
Set or to modify this Tag Set:
- Skim the first two chapters of this Tag Library, the How to Use and the Tag Library General Introduction.
- Read the parameter entities that name the classes (in the module %default-classes.ent;).
- If you do not know the symbols used in the Document Hierarchy diagrams, then read the “Key to the Near & Far® Diagrams”.
- Use the Document Hierarchy diagrams to give you a good sense of the top-level elements and their contents.
- Pick an element from one of the diagrams. (Look up the element in the Elements Section to find the full element, the definition, usage notes, content allowed inside the element, where the element may be used, and a list of any attributes. Look up one of the attributes to find its full name, usage notes, potential values, and whether it has a default.)
- Read the DTD Modules. New tag sets are created by writing, at a minimum, a new DTD module
and new tag-set-specific customization modules, so you might want to read the modules in this
order:
- The DTD module (JATS-articleauthoring1.dtd);
- The module that names all the Authoring-Tag-Set-specific customization and element modules (%articleauthcustom-modules.ent;);
- The module that names all the other modules in the Suite (%modules.ent;);
- The book customization modules (%articleauthcustom-classes.ent;, %articleauthcustom-mixes.ent;, and
%articleauthcustom-models.ent;);
You might also wish to familiarize yourself with the relationship between the “customization” modules and the “default” modules for classes, mixes, and models, so you might read the Suite class and mix modules next (%default-classes.ent; and %default-mixes.ent;);
- Any one of the many class-defining modules from the Suite (for example, the %list.ent;; module).
Questions and Answers
BITS Question and Answer Model
The Book Interchange Tag Suite (BITS), which is an extension of JATS, has defined XML structures
for the questions and answers that can be used, for example, to tag back-of-the-chapter questions. Some JATS users would like
to use these structures to
tag, for example, Continuing Medical Education (CME) or legal quizzes associated with a journal
article. It this the intent of the JATS Standing Committee to add the BITS question/answer model to
JATS, eventually. But the model is insufficiently tested at this time, and the decision has been made to wait
until book publishers shake the bugs out of the models before making questions and answers part of
NISO JATS.
This chapter provides the instructions for users who do not wish to wait; who want to use BITS
questions/answers in their JATS documents immediately. Since BITS is based on JATS, it is relatively simple to add the BITS
Q&A model to a JATS DTD. Warning: The BITS models are in flux and any implementations based
on current models will be out of step with BITS when BITS is revised.
BITS Questions and Answers
The BITS Q&A model defines elements that might be used to describe questions
and answers. The result is a very basic model, expected
to be customized and extended, that allows for
simple questions followed by their
corresponding answers or for a multiple
choice setup, where questions are followed
by multiple alternative answers, along with
the correct answer and an explanation.
By design, these elements do not constitute the full model for a
quiz, test, exam, etc.; the intent was that such a model
could be built using these question/answer components. Possibly more useful to many JATS users, the
BITS Q&A models can be used to encode Question and Answer material within the text of
an article. For example, a medical article may end with 2 or 3 questions for the patient, or with a
CME (Continuing Medical Education) quiz that may be tagged as a separate article.
How to Add Question/Answers to JATS
The Question and Answer Module
The question and answer elements are in a module that has the
file name “BITS-question-answer1.ent”
(formal public identifier:
"-//NLM//DTD BITS Question and Answer Module v1.0 20131225//EN"). This module can be downloaded
as part of the BITS modules. The module is named in the regular JATS catalog, so it can be used with
JATS without changing the catalog.
The module uses parameter entities defined in ordinary JATS, such
as the “ID class” and “section optional title model” parameter
entities, so that any customization overrides you have made to a JATS Tag Set will apply to the
Q&A module as well. For eaxmple, if you have added a new emphasis element to the emphasis class, that new
element will be available in the paragraphs of questions and answers.
Modifying the JATS DTD
To add questions and answers to a JATS DTD:
- Download the latest version of the BITS DTD at https://jats.nlm.nih.gov/extensions/bits/#id48297/. The DTD and documentation are available by anonymous FTP: ftp://ftp.ncbi.nih.gov/pub/jats/extensions/bits/1.0/.
- Copy the Question and Answer module (“BITS-question-answer1.ent”) into the directory where you store your JATS DTD modules.
- Add the following lines to your DTD-specific module of modules to include the new module
in your possibilities. (For example, if you were modifying the Archiving DTD, you would add these
lines to the JATS-archivecustom-modules1.ent module.)
<!-- BITS QUESTION AND ANSWER MODULE --> <!-- Element declarations for BITS questions and answers (not complete tests, but used to put build quizzes and tests. --> <!ENTITY % question-answer.ent PUBLIC "-//NLM//DTD BITS Question and Answer Module v1.0 20131225//EN" "BITS-question-answer1.ent" - Add the following lines to your base DTD, to include the
Q&A module in your customized JATS DTD. (For
example, if you were modifying the Archiving DTD, you would add these lines to the
(JATS-archivearticle.dtd) module.) The lines may be added any time after the custom classes,
mixes, models, and common are called in.
<!-- BITS QUESTION AND ANSWER MODULE --> <!-- Element declarations for BITS questions and answers (not complete tests, but used to put build quizzes and tests. --> %question-answer.ent; - In your custom classes, custom mixes, and custom models files, change any classes, mixes, or models
necessary to put the new structures where you want them. (For example, if you were modifying the
Archiving DTD, you might modify the JATS-archivecustom-classes1.ent,
JATS-archivecustom-mixes1.ent, and/or
JATS-archivecustom-models.ent modules.)
BITS placed these Q&A elements in the block display class as shown below, but you may want to allow them in fewer locations:
<!-- DISPLAY CLASS ELEMENTS --> <!-- Graphical or other image-related elements. The display elements may occur within the text of a table cell or paragraph although they are typically at the same hierarchical level as a paragraph. --> <!ENTITY % block-display.class "address | alternatives | answer | answer-set | array | boxed-text | chem-struct-wrap | code | fig | fig-group | graphic | media | preformat | question | question-wrap | supplementary-material | table-wrap | table-wrap-group" > <!-- QUESTION AND ANSWER CLASS --> <!-- Questions and answers (also in block display class, for use in other places). --> <!ENTITY % question-answer.class "answer | answer-set | question | question-wrap" > - Add a <question-wrap> to an XML instance to test.
Where Question/Answer Elements can be Used
Since BITS is a loose, Archive-like Tag Set that restricts very little and allows structures
in a wide variety of places, Question Wrappers, Questions, Answer Sets, and Answers can be used in
many places, for example, inside <sec>, inside <body>, or inside <boxed-text>.
One design choice made in BITS was to allow any of the question/answer elements wherever in
text any one of them might be used. Thus <answer>, <answer-set>,
<question>, and <question-wrap> were added to the Block Display Class as well
as inside a table cell. Any modification of a JATS DTD to add question/answers will need to
specify where they can be used.
Semantic Attributes Specific to Q/A
Many existing models of questions, answers, and tests were examined during the modeling for
BITS Questions and Answers. The number of attributes and semantics of those attributes were two of
the areas where granularity in the quiz/exam/test models examined differed the most. Many of the
attributes in the examples seemed too specific to a particular discipline or situation.
The BITS questions/answers were given the ubiquitous JATS attributes:
- @content-type,
- @specific-use,
- @id,
- @rid to point to portions of the text,
- @xml:base, and
- @xml:lang.
In addition, the question/answer models were given a fairly restricted set of semantic attributes:
|
audience |
Defined only on the top-level wrapper element to name the perspective audience for the question(s). This text attribute provides
a very short description of the intended audience, for example, “patients”, “dermatology-students”.
|
|
correct |
Marking answers as correct (yes) or not (no)
|
|
answer-type |
Allowed on both answers and answer sets with the value list:
|
Overview of BITS Q&A Structures
The elements that comprise the BITS Q&A are described in the BITS Tag
Library, as part of the description of each element. For convenience,
this material has been summarized below for the elements:
- <question-wrap>
- <question>
- <answer>
- <answer-set>
- <explanation>
The top-level element question-wrap wrapper holds one question, its optional
answer(s), and any explanations. Question/answer sets may be assigned DOIs or other identifiers.
This top-level element is optional, and questions and answers can be used in other contexts.
The intent is to give archives, libraries, and aggregators a way to capture question and answer
material, wherever they appear in content.
The interior structure of questions and answers can be very complex, mimicking the complexity
of a section, but each question and answer could also be described with a single, typically labeled paragraph.
The structure is very fluid and enabling, and not at all directive or enforcing.
Here are two simple questions with answers:
... <question> <p>How many moons does Mars have?</p> <p>(Name them for extra credit)</p> </question> <answer answer-type="short-answer"> <p>Two: Phobos and Deimos</p> </answer> ... <question> <p>From the point of view of England, what were the underlying causes of World War II?</p> </question> <answer answer-type="essay"> <p>Answer must be no longer than 2500 words.</p> </answer> ...
Question Wrap
This element is a holder for one question and its answer (or answer set) as well as any
explanations:
Each question-wrap may contain:
- Optionally, one or more identifiers, such as DOIs at the beginning (<object-id>);
- One question (required);
- One answer or one answer-set (optional); and
- As many explanations as necessary.
Here is multiple-choice style question inside a question-wrap:
...
<question-wrap>
<question>
<p>Where was the first permanent English
settlement in the New World?</p>
</question>
<answer-set answer-type="multiple-choice">
<answer correct="no"><label>A</label>
<p>Plymouth</p>
</answer>
<answer correct="yes"><label>B</label>
<p>Jamestown</p>
</answer>
<answer correct="no"><label>C</label>
<p>Roanoke</p>
</answer>
<explanation>
<p>Established by the Virginia Company of London, Jamestown
was the first permanent English settlement in the New World;
it flourished from 1607 to 1699. Although the Roanoke colony
was founded earlier (in 1587), that colony failed; upon returning
from a trip to England for supplies, its Governor found the
settlement abandoned. Although one of the earliest New England
colonies, Plymouth (in modern Massachusetts) was not founded
by the Pilgrims until 1620.</p>
</explanation>
</answer-set>
</question-wrap>...
Question
A question is a request for an answer, typically used in
the text for review or as part of a quiz, exam, etc. A question may ask a question, but it may also
make a statement that the student is to discuss in an essay or to mark as true or false.
Each question may contain:
- Optionally, one or more identifiers, such as DOIs at the beginning (<object-id>);
- The same things that can be inside a section (including for most JATS Tag Sets, section-level metadata, a label, a title, subtitles, and alternate titles followed by paragraph-level objects or embedded sections, or both.) Everything is optional; a question could be defined by just a paragraph or a fully labeled section with interior subsections.
Answer
An answer is a response to a question. Each answer may contain:
- Optionally, one or more identifiers, such as DOIs at the beginning (<object-id>);
- Optionally, a label, a title, subtitles, and alternate titles;
- Followed by just sections or paragraph-level objects followed by sections;
- Followed by the same back matter as sections allow; and
- Followed by as many explanations (explanation) as needed
Answer Set
A set of answers to a single question, for example, five labeled multiple-choice answers. Each answer-set may contain:
- Optionally, one or more identifiers, such as DOIs at the beginning (<object-id>),
- A choice of as many answers (answer) as necessary, interspersed with paragraphs (p) and explanations (explanation)as needed.
Here is a simple true-false answer set:
... <question-wrap> <question> <p>Peregrine White was the first English child born in North America.</p> </question> <answer-set answer-type="true-false"> <answer correct="no"><p>True</p></answer> <answer correct="yes"><p>False</p></answer> <explanation> <p>The first English child born in North America was Virginia Dare. She was born in August 1587, in the short-lived colony of Roanoke. Although the settlement was later abandoned and the fate of its inhabitants a mystery, records brought to England by her grandfather, the governor of the colony, later in 1587 note her birth and baptism. Born in November 1620, Peregrine White was the first child born in the Plymouth colony.</p> </explanation> </answer-set> </question-wrap>...
Explanation
Explanations are the catchall of designing question/answers. Each question (inside a question-wrap), each answer, and each answer-set may take one or more explanations. Each explanation contains one or more paragraphs of text that provide a description of a question/answer, answer, or answer set. The explanation may describe, for example, why this
particular answer is incorrect, or where in
the text the material for this question
can be found, et al.
Note the explanation in this example:
...
<question-wrap>
<question>
<p>Where was the first permanent English
settlement in the New World?</p>
</question>
<answer-set answer-type="multiple-choice">
<answer correct="no"><label>A</label>
<p>Plymouth</p>
</answer>
<answer correct="yes"><label>B</label>
<p>Jamestown</p>
</answer>
<answer correct="no"><label>C</label>
<p>Roanoke</p>
</answer>
<explanation>
<p>Established by the Virginia Company of London, Jamestown
was the first permanent English settlement in the New World;
it flourished from 1607 to 1699. Although the Roanoke colony
was founded earlier (in 1587), that colony failed; upon returning
from a trip to England for supplies, its Governor found the
settlement abandoned. Although one of the earliest New England
colonies, Plymouth (in modern Massachusetts) was not founded
by the Pilgrims until 1620.</p>
</explanation>
</answer-set>
</question-wrap>...
Subsidiary section:
Authoring Tag Suite Naming Conventions
How To Make New Tag Sets
Element Classes
Many of the elements in the Authoring Tag Set 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 tag sets. Base classes for the JATS 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.
Implementor’s Note: Element classes can be viewed
as building blocks used to build larger parameter entities for element mixes. 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 your Tag-Set-specific
Class Override Module to override the default parameter entity that is
defined in the Suite’s Default Element Classes 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 JATS 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 |
|
|
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 <mixed-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 NISO JATS XHTML-inspired Table Module elements
can be set up for inclusion: <table>.
|
Parameter Entities Modules to Customize and Change
Parameter entities are the major mechanism for customizing a tag set or creating a new tag
set from the modules in the full Suite. Individual tag sets will be constructed by (1)
establishing element and attribute combinations and content models using parameter entities in
one of the Tag-Set-specific customizing modules and (2) choosing appropriate modules from the
Suite that declare the elements needed. For example, if the base tag set contained 6 kinds of
lists and 2 table models, a more specific tag set 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 tag set are: (1) the DTD itself, (2) a module to
name its component modules, and 3) as many override modules (class, mix, and/or model) and new
elements modules as necessary. Thus, typical modules for a new Tag Set are:
- DTD — The DTD module (articleauthoring1.dtd) for the new Tag Set 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.);
- Tag-Set-specific Module of Modules — Module to name all the new modules created expressly for the new Tag Set;
- Class overrides — Tag-Set-specific overrides of the Suite default element classes;
- Mix overrides — Tag-Set-specific overrides of the Suite default class mixes;
- Model overrides — Tag-Set-specific content model overrides for the content models in the modules of the Suite (using “-elements” and “-model” parameter entities); and
- New Model Modules — Tag-Set-specific new elements (for example, a new Book Tag Set might add book-specific metadata elements or a Tag Set for historical material might add a module to define annotations.)
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 Tag Set 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 overrides use mixes and classes for all OR groups. Only
content model sequences are made up of element names directly.
MODEL OVERRIDES — Parameter entity mixes for
overriding 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 "| %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 override 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; >
How To Build a New Custom Tag Set
The Concept
The basic idea for a new tag set 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 tag-set-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 declared using external parameter entities in the Suite’s Module to Name the Modules or in the tag-set-specific Module of Modules. Modules
are referenced in the DTD proper, in the order needed to
define the parameter entities in sequence.
This Authoring Tag Set was written as an example of the new best-practice customization
technique. A new variant Tag Set that follows this plan will probably consist of the following
modules:
- A DTD module to define the top-level elements (for example, articleauthoring1.dtd);
- A Tag-Set-specific Module of Modules to name new non-Suite modules in the DTD (for example, %articleauthcustom-modules.ent;);
- A Tag-Set-specific definition of element classes to add new classes and override the default classes (for example, %articleauthcustom-classes.ent;);
- A Tag-Set-specific definition of element mixes to add new mixes and override the default mixes (for example, %articleauthcustom-classes.ent;);
- A Tag-Set-specific module of content model overrides (for example, %articleauthcustom-models.ent;);
- Tag-Set-specific modules to hold new element declarations; and
- All or most of the modules in the Suite.
Making a Variant Tag Set
To show the process, here is a series of instructions for making a new Tag Set,
illustrated by showing how the Authoring Tag Set was created from the modules of the whole
Suite.
- Modules — Write a new Tag-Set-specific Module of Modules, which defines all new customization modules this Tag Set needs. As an example, the Authoring Tag Set created the module %articleauthcustom-modules.ent;, which contains the definitions of the class-override module %articleauthcustom-classes.ent;, the mix-override module %articleauthcustom-mixes.ent;, and the models-override module %articleauthcustom-models.ent;.
- Class overrides — Write a Tag-Set-specific class-override module, defining any overrides to the Suite classes. These classes are defined in the default classes module, %default-classes.ent;. As an example, the Authoring Tag Set created the module %articleauthcustom-classes.ent;, in which several new models, including %rest-of-para.class.class; and %name.class;, were declared.
- Mix overrides — Write a Tag-Set-specific mix-override module, defining any overrides to the Suite mixes. These mixes are defined in the default mixes module, %default-mixes.ent;. As an example, the Authoring Tag Set created the module %articleauthcustom-mixes.ent;, in which mixes such as %emphasized-text; and %simple-phrase; were declared.
- Model overrides — Create a Tag-Set-specific content-model-override module, defining any overrides to the content models and attribute lists for the Suite. As an example, the Authoring Tag Set created the module %articleauthcustom-models.ent;, in which element collections (suffixed “-elements”) that will be mixed with #PCDATA were redefined, full content models overrides (suffixed “-model”) were redefined, and some new attributes and attribute lists were added.
- New Elements — Write any new element modules needed. These will define any new block-level or phrase-level elements. For the Authoring Tag Set, there are no such modules, but, for example, the Book Tag Set made from this Tag Set defines book-specific metadata.
- 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 Tag-Set-specific module of modules, for the Authoring Tag Set, 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 Tag Set, the module %modules.ent;.
- Use an external parameter entity reference to call the Tag-Set-specific class overrides, for the Authoring Tag Set, the module %articleauthcustom-classes.ent;.
- Use an external parameter entity reference to call the Suite default classes, for the Authoring Tag Set, the module %default-classes.ent;.
- Use an external parameter entity reference to call the Tag-Set-specific mix overrides, for the Authoring Tag Set, the module %articleauthcustom-mixes.ent;.
- Use an external parameter entity reference to call the Suite default mixes, for the Authoring Tag Set, the module %default-mixes.ent;.
- Use an external parameter entity reference to call the Tag-Set-specific content models and attribute list overrides, for the Authoring Tag Set, 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 Tag-Set-specific module defining block-level or phrase-level elements. For the Authoring Tag Set, there are no such modules, there are no such modules, but, for example, the Book Tag Set made from the Suite defines book-specific metadata in the Book Metadata Module.
- Select, from the Module of Modules, those modules which contain the elements needed for your Tag Set (for instance, selecting lists and not selecting math elements) and call in each of the modules needed. The Authoring Tag Set 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 Tag Set. For example, the Authoring Tag Set declares only four elements — <article> [the top-level element] and its components: <front>, <body>, and <back>.