Skip to main content

The PreTeXt Guide

Section 4.12 Interactive Exercises

PreTeXt has markup for a variety of interactive problem types, described individually in the subsections to follow. Generally, for a regular HTML build (Chapter 29), these will be interactive, informing the reader when their answer is correct, and providing feedback when their answer is not correct. When HTML is built to host on a Runestone server (Chapter 32), then student progress as part of a course will be recorded on the server. Some features, which will be noted below, such as execution of computer code, is more capable on a Runestone server.
Generally, an interactive exercise is authored much like a “regular” <exercise> (Section 3.9) with <statement>, <hint>, <answer>, <solution>. However, there is also some additional markup which serves as a signal that the exercise is more than a short-answer, or free-response, question. Usually, but not always, this signal is an additional element following <statement>. One consequence of this is that all but one type of interactive exercise will require a <statement> element to contain the question text.
Each type of interactive question has a static version for use in output formats like print, PDF, or braille. Details are given below. Note that since the ability for instant evaluation of a reader’s answer means an author provides the solution and other feedback, this can then be incorporated into a static version as an automatically-generated <answer> and/or <solution> (in addition to any others an author provides). Note that an author can provide a <hint> for use in all output formats, but there are not any automatically-generated <hint> for static versions of interactive problems. Visibility of these solutions can be controlled via the mechanism applicable to all exercises, see Section 26.4.
Note the opportunity to provide feeback to the reader using a <feedback> element in various locations. These are generally optional, but highly encouraged as a way to improve the quality of your reader’s experience.
These interactive questions are enabled by software from Runestone Academy (Chapter 32) and have extra capabilities when the online version of our output is hosted on Runestone servers. But you must use a @label attribute. This is described more carefully next, so that we can make reference to it from other locations.

Best Practice 4.12.1. Use label attribute for Runestone Components.

Many of our interactive exercises and programming environments are powered by software from Runestone Academy (Chapter 32). Not suprisingly, when you build online HTML for hosting on Runestone servers these components have more features than otherwise. This is managed by locating each component in a (massive) database. And so each exercise needs an identifier.
You accomplish this by placing a unique value in a @label attribute on an outermost element, such as an <exercise>, <task>, <project>, <video>, <program>, etc. You should choose these strings carefully, as they should not be changed, lest the database entries become confused. Under the hood, we get the content of docinfo/document-id element, and the @edition attribute of <document-id>, to form a database identifier such as AATA_2_easy-exercise. The <document-id> distinguishes your book from other books, and the edition allows you some flexibility. In other words, if you declare a new edition, you can change some of your @label as part of that process and you will get new database entries while preserving the old.
Short answer: before hosting your project on Runestone, decide on permanent values for <document-id>, @edition, and all necessary @label. (We expect to add a warning for Runestone builds when these values are not set.)

Subsection 4.12.1 True/False Exercises

A True/False exercise must have a <statement> element, and this element must have a @correct attribute, whose value is yes or no (there is no default value). That’s it. The presence of the @correct attribute is the signal that this is a True/False exercise.
The text of the statement is the assertion the reader must determine is true or not. The @correct attribute is how an author describes if the statment is true (yes) or false (no). This is enough information for a conversion to formulate a version of the question. An optional <feedback> element may follow the <statement>, and should provide more thatn a binary explanation of the exercise.
Presentation as an interactive element will vary cosmetically, according to the output type targeted.
A static version gets an automatic <answer> that is simply “True” or “False”. The automatic <solution> is the same, plus the content of <feedback>.

Subsection 4.12.2 Multiple-Choice Exercises

A multiple-choice exercise is signaled by a <choices> element (plural) following a <statement> and preceding an optional <hint>. The <choices> element is structured by a sequence of <choice> elements, whose content is a potential answer for the reader to choose. So the <statement> is the prompt or question, and the <choice> are the possible answers.
At least one <choice> has an attribute @correct set to the value yes. The default value of @correct is no. There may be several correct answers, indicated with this attribute. The presentation as an exercise with one answer or many is automatic. However, in the event there is exactly one correct answer, but you wish the reader to consider the possibility of multiple correct answers, you may set the @multiple-correct attribute on the <choices> element to yes. The default value is no.
Each <choice> element must be further structured with a <statement> and a <feedback>, which each can contain items such as paragraphs (<p>). In this way, the highly-encouraged feedback can be associated with each correct and incorrect choice.
The order of the <choice> as authored, is the order they will be given in a static version. To present the choices in different orders in an interactive version, set the @randomize attribute on the <choices> element to yes.
An automatic <answer> for the static version is simply the list markers for the correct choices. An automatic <solution> has an indication for each choice if it is correct or incorrect, along with the choice’s feedback.

Subsection 4.12.3 Parsons Problems

Parsons problems are named for Dale Parsons, one of their creators, along with Patricia Haden. They could also be called mixed-up blocks. A reader is presented with a set of blocks containing text, either computer code or natural language, and their goal is to assemble the blocks into a correct order. This could be a computer problem with a stated purpose, or could be a logical argument such as proof, or it could be a procedure such as a recipe. An interactive drag-and-drip interface is a very efficient presentation for a reader.
Similar to multiple-choice exercises, a <statement> is followed by a <blocks> element containing a sequence of <block> elements. The <blocks> element is the signal that this is a Parsons problem. The overall <exercise> element may have several attributes:
  • @numbered set to left or right indicates the blocks should be numbered, and on which side the numbers go. The default value is no.
  • @language set to natural indicates the text of the blocks is natural language, while the use of a computer language should be indicated by naming the actual language employed. A list of languages will soon be added in Section 4.15. The default is natural.
  • @indentation set to hide indicates that a computer code exercise will not include indentation common to each line of a block. In other words, the problem is slightly harder, as the interactive interface will require the reader to adjust the block horizontally to provide common indentation for the block. The default is show.
A <block> that has natural content is authored as usual, with a sequence of paragraphs (<p>) or similar. If the content is a computer language, then it should be authored as a sequence of lines, using the <cline> element, which allows for precise interpretation of indentation and non-standard characters. Include all indentation necessary for each line, no matter how @indentation is set. The content of the blocks, arranged properly, should form a syntactically correct program. If the reader is to provide indentation, PreTeXt will strip away the common amount of indentation.
A block may be a distractor, meaning it is not to be used at all in the solution. Indicate this with a @correct attribute on the <block> set to no (the default being yes). Furthermore, a given block of the solution can be authored with several alternatives, only one of which is correct. Indicate this by structuring a <block> with a sequence of <choice>. Each <choice> should be authored similarly to a <block>, and the one correct choice should have the <correct> attribute set to yes (the default being no).
The blocks should be authored in the correct order and the interactive interface will control the randomization. A block that is a distractor may be placed in any location amidst the other blocks. Each block should have an <@order> attribute that is a whole number, counting from 1. This is the fixed, mixed-up, order that will be presented in any static rendition. In static versions, sequences of blocks are in lists, which are numbered if the attribute has been set, but the left/right distinction is lost—all numbers are to the left. An automatic <answer> is provided if blocks are numbered, and it is just the block numbers in the correct order. An automatic <solution> is always generated with the text of the blocks listed in the correct order. For an exercise with computer code, the PreTeXt <program> element and the exercise’s @language attribute will produce a syntax-highlighted listing.
There is no provision for a <feedback> element. Further explanation may be provided in a <hint>, <answer>, or <solution>. Also, a good interactive interface can provide assistance to a reader by telling them if they have too few or too many blocks, or combining or removing blocks, and so on.
As of 2022-06-14 work is underway to relax the strict ordering assumed of the blocks. So there will be extra markup to specify a poset or directed acyclic graph on the blocks.

Subsection 4.12.4 Horizontal Parsons Problems

A horizontal Parsons problem is very similar to the traditional vertical problems just described in Subsection 4.12.3. Except they are horizontal. Which means the blocks are very short (a word or symbol) and they are rearranged by the reader to form a horizontal bit of text. They are ideal for constructing a single line of computer code, such as a regular expression, or a short sentence. While similar, they have a few features which are different.
To indicate a horizontal problem, set the @layout attribute on the <blocks> element to the value horizontal. The default value is vertical and so is not necessary for the traditional versions.
The syntax for blocks is the same, and they are authored in an order that yields a correct answer. The use of an @order attribute on each <block> indicates a rearrangment to be used for a static version. Blocks may be reused. To do this, place an @xml:id on a single instance of a block to be reused. Then, to indicate its reuse as part of a correct version, use a @ref attribute on a <block>. Since the duplicate instance is not shown to the reader, the use of @order and @ref is mutually-exclusive. You can set the @reuse attribute on the @blocks element to the value yes to force the interface to allow the reader to reuse blocks, even if there is no duplication in the correct version. Otherwise, the interface reacts to the presence or absence of blocks with the @ref attribute.
Distractors may be included in the same manner as for vertical Parsons problems, by setting the @correct attribute on a <block> to the value no. The default is yes. It does not make much sense to indicate a reusable block (in either form) as a distractor, so don’t.
Another option on the @blocks element is the @randomize attribute. The default value is yes. When the value is set to no, then the blocks are always presented to the reader in the same order, which is the one given by the @order attribute.
As of 2022-11-28, the implemenation of these problems assumes that the blocks rearrange to be computer code. So you can set the @language attribute on the <exercise> element to natural, but it will not have much effect. Markup like <em> on the text of a block will be unpredictable, as will attempts to use mathematics. And the text of blocks will always be in a monospaced font, perhaps with some syntax highlighting if @language is set properly.

Subsection 4.12.5 Matching Exercises

A matching exercise asks a reader to pair a premise with a response. Similar to multiple-choice exercises and Parsons problems, a <matches> element follows a <statement> and this is the signal. The <matches> element is structured as a sequence of <match> elements, each of which has a <premise> element and the matching <response> element. Since the content of each premise and response is best kept short and simple as a phrase, the elements may also be simple phrases without the additional structure of <p> elements, or similar. That’s it.
An interactive interface should randomize at least one of the lists of premises and responses, consulting the authored version for the correct pairings. For a static version, an author should put an <order> element on each <match> whose value is a whole number, starting from 1. Then the <premise> will appear in the authored order, while the <response> will be re-ordered according to the attribute.
A single <feedback> element may be given, as a peer of <statement>, in addition to authored <hint>, <answer>, or <solution>. For a static version an automatic <solution> presents the problem in the order the <match> were authored.

Subsection 4.12.6 Clickable Area Exercises

Clickable Area is a misnomer, assuming an interactive version of this type of problem. Perhaps “Select Text” would be better. In any event “area” is not meant to connote a geometric notion, instead this is about a sequence of characters, either in natural language or in computer code.
A <statement> is a prompt, describing which sort of areas should be selected by the reader. Such as: Locate all the nouns in the following paragraph. This is followed by an <areas> element, which is the signal for this type of exercise. The <areas> element holds either (a) PreTeXt paragraphs or similar, or (b) a sequence of <cline>, understood to be program code. In the latter case, a @language attribute on the <areas> element will enable the right syntax highlighting in some output formats.
Within the content of the <areas> element an <area> element can be used to surround a run of characters. These cannot cross XML boundaries, such as a <cline> or <p>. A @correct attribute, with values yes or no, indicates the text is to be selected (clicked on) or that it is a distractor (tempting to click on). The default is yes, so only distractors need to be indicated.
A single overall <feedback> may be placed following the <areas> element.
Now an interactive version will allow the reader to click on and off the marked areas of text, and provide information about which are correct and which are not, in addition to general feedback.
Generally, a static version of the problem will not be clickable. <wink/> So your prompt might say something generic like “select” or “locate” since a reader might work the problem on paper by circling or underlining the areas. A static version includes an automatic <answer> which is a list of the correct areas as text, followed by a list of the incorrect areas as text. An automatic <solution> repeats the text in the <areas> element, and uses (accessible) visual cues to note the correct and incorrect text.

Subsection 4.12.7 Fill-in-the-Blanks Exercises

As of 2022-06-14 a major effort is underway to provide comprehensive markup for fill-in-the-blank problems. Until then, there is transitional markup intended only to supply a migration path for projects originally authored for Runestone servers (Chapter 32). So (a) our documentation is sparse, and (b) there will be no backward-compatible improvements. So in particular, new projects should wait for the new markup. Also, studying examples may be a useful way to augment what is described here.
A <statement> is enriched with empty <var/> elements which will render as the blanks in the problem.
The signal for a fill-in problem is a <setup> element containing a sequence of <var> elements. Each <var> contains a sequence of <condition> elements that describe possible values (via regular expressions) which might appear in a blank. The first condition describes the correct answer(s), and then the subsequent conditions are descriptions of probable incorrect answers. Each <condition> has a <feedback>. So the first condition to match an entry provided via a blank will be noted as correct or incorrect, and its feedback will be relayed.
The <var> of the statement and the <var> of the setup are in a 1-1 correspondence, which establishes how the setup is associated with a blank. The <var> in the statement may have a @width attribute whose value controls how many characters would be visible in the blank.
A static version will include an automatic <solution> which “fills in” each blank with a correct answer, and then duplicates the feedback text, in order.

Subsection 4.12.8 Coding Exercises and Projects

A Coding Exercise is formed by placing a <program> element after the <statement> of an <exercise>. The main distinction is that this is a signal that the interactivity is provided by the <program>, and therefore the <exercise> will not be understood as a short answer exercise (Subsection 4.12.9). For this reason, the <program> should be requested as one of the interactive realizations (Subsection 4.15.2, Subsection 4.15.3).
The identical construction may be used with any PROJECT-LIKE (List 4.2.2) such as an <activity>. As of 2022-06-17 this only applies to the form that uses a <statement>, but will soon also apply to <task> within PROJECT-LIKE.
Realize that it is always possible to place a <program> inside of a <statement>, and if there is no <program> that is after the <statement> (or another signal for an interactive exercise) then the <exercise> will be classified as a short-answer exercise. It may be instructive to understand that in a static realization, a <program> at the end of a <statement> may be visually identical to an <exercise> where the <program> is after the <statement>, even though the former is a short-answer exercise and the latter is a coding exercise (which will render differently for different output formats and hosting platforms).

Subsection 4.12.9 Short Answer Exercises

Short Answer questions might also be known as Free Response questions, or Essay questions. A PreTeXt <exercise>, or a PROJECT-LIKE that is not structured by <task>, is implicitly of this nature. But you still need to signal that you wish such a problem to be interactive, typically with a text box where the student can enter an answer. So, similar to other types of exercises, add a <response/> element immediately after the <statement>. (We expect to add attributes for this element to influence the behavior of the text box.)
In an online setting, it is a simple matter to provide a place for a reader to type in an answer, response, or essay. But then what? Until artificial intelligence is brought to bear, somebody (not something), such as an instructor for a course of enrolled students, will need to read a response and provide a score and/or comments that can be saved and distributed back to the students. So the first prerequisite is that HTML output is being built for a capable platform. As of 2022-06-15, this means a Runestone server (Chapter 32), but it could easily also be a WeBWorK server.
A publisher can control when a response area is created in HTML output (Subsection 44.4.13). The default is to only have this area present when it is possible for a response to be graded and scored. However, an option will cause a response box to be created always. A reader can reflect on the question by typing in a response, and the text will be saved on that particular device only. When it is impossible for a response to be graded, placeholder text will warn the reader.