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:

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:
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:
  • essay”,
  • fill-in-the-blank”,
  • multi-select (student must select one or more)”,
  • multiple-choice (student must select one)”,
  • short-answer”, and
  • true-false”.

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.
../graphics/question-wrap.png
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 sections:

Tag Set Suite Naming Conventions

Modules in the Journal Publishing Tag Set and JATS DTD Suite