Modifying This Tag Set
Modular DTD Design
This Suite has been written as a series of XML DTD modules that 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.
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 an authoring 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 the current 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 name of the element, the definition, usage notes, content allowed, and attributes list. Look up one of the attributes to find its full name, usage notes, and potential values.).
- Read the Tag Set Modules. New Tag Sets are created by writing, at a minimum, a new DTD module and new customization modules,
so you might want to read the modules in this order:
- The DTD module (JATS-journalpublishing1.dtd);
- The module that names all the Publishing-Tag-Set-specific customization and element modules (%journalpubcustom-modules.ent;);
- The module that names all the other modules in the Suite (%modules.ent;);
- The Publishing customization modules (%journalpubcustom-classes.ent;, %journalpubcustom-mixes.ent;, and %journalpubcustom-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).
Subsidiary section:
How To Make New Tag Sets
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>...