Question File Format

From Java.Inquisition

Inquisition uses an XML dialect for its question file format. Probably the easiest way to get a grasp of the syntax is to look at the contents of the demo question set.

The following describes version "4" of the file format.

Contents 1 Basic structure 2 Multiple Choice Question 3 Drag And Drop Question 4 HTML Markup

[edit] Basic structure

The basic structure of the file looks like the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE QuestionSet SYSTEM "inquisitionQuestions.dtd">
<QuestionSet version="4">
  <Name>...</Name>
  <Description>...</Description>
  <RecommendedTimePerQuestion>...</RecommendedTimePerQuestion>
  <Category>...</Category>
  <Questions>

  ...
   
  </Questions>
</QuestionSet>

• Name: A name for this set of questions
• Description: Free form text to describe the questions, their author, publication date, web links etc. Supports HTML markup.
• Category: Used to group related question files within in Inquisition
• RecommendedTimePerQuestion: time allowed for each question, in seconds
• Questions: the actual questions (see below)

[edit] Multiple Choice Question

<MultipleChoiceQuestion shufflable="true" singleOptionMode="false">
  <QuestionText>...</QuestionText>
  <Options>
    <Option correct="true">...</Option>
    <Option correct="false">...</Option>
  </Options>
  <ExplanationText>...</ExplanationText>
</MultipleChoiceQuestion>

• shufflable attribute: true or false, indicates whether the options within a question can be shuffled randomly. Sometimes it's useful to make a question shufflable so that you don't have to think about randomising the options yourself. Other times, it makes sense to have some sort of order to the options.
• singleOptionMode attribute: if true, indicates whether there is a single correct option. If false, indicates that there are (potentially) multiple correct options.
• QuestionText: The text for the question, supports HTML markup plus some custom markup:
  • <java>...</java>: interpret the contents as Java code, and use syntax highlighting.
  • <CopyToExplanation>...</CopyToExplanation>: copy the contents to an indicated point in the explanation text.
• Option: the options support HTML markup
• ExplanationText: An explanation for the answer. Supports HTML markup plus some custom markup:
  • <java>...</java>: As above
  • @1@, @2@...etc: used to refer to options in the answer. Options are labelled by Inquisition automatically from A..Z. @1@ would be replaced by the letter given to the first option in the XML file (regardless of how that option had been shuffled by Inquisition).
  • @allcorrect: Replaced with a comma separated list of all the labels of the correct options.
  • <CopyFromQuestion/>: inserts anything to copy across from the question

[edit] Drag And Drop Question

<DragAndDropQuestion reuseFragments="false">
  <QuestionText>...</QuestionText>
  <ExtraFragments>
    <Fragment>Gordon</Fragment>
    <Fragment>Popsicle</Fragment>
  </ExtraFragments>
  <ExplanationText>...</ExplanationText>
</DragAndDropQuestion>

• reuseFragments attribute: specifies whether the fragments can be reused multiple times, or once only, in drag and drop.
• QuestionText: The text for the question, supports HTML markup plus some custom markup:
  • <java>...</java>: interpret the contents as Java code, and use syntax highlighting.
  • <CopyToExplanation>...</CopyToExplanation>: copy the contents to an indicated point in the explanation text.
  • <slot>...</slot>: The contents between the slot tags are removed and a slot is created for drag and drop.
• Fragment: Additional options for the user to drag and drop.
• ExplanationText: An explanation for the answer. Supports HTML markup plus some custom markup:
  • <java>...</java>: As above
  • <CopyFromQuestion/>: inserts anything to copy across from the question.
  • <slot>...</slot>: The contents of slot tags are not removed in the explanation.

[edit] HTML Markup

The Inquisition file format allows HTML markup in the Description, QuestionText, ExplanationText and Option tags. This ends up being rendered in Java Swing text components which support only HTML version 3.2. It's typically easier to use CDATA sections in these tags, which would otherwise require characters like <, > and & to be escaped.

   <Description><![CDATA[Description text goes here, and can contain <b>HTML</b> markup<p>Etc]]></Description>

In fact, characters like < and > might still need to be escaped if you're using them not as part of HTML. For example:

  <QuestionText>
  Is 3 &lt; 5 or is 3 &gt; 5?
  </QuestionText>