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 Practice4.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.)
Subsection4.12.1True/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>.
Subsection4.12.2Multiple-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.
Subsection4.12.3Parsons 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.16. 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.
It is possible to specify a partial ordering of blocks using the @name and @depends attributes of <block>. @name is used to assign the block a string identifier. @depends should be a space-separated list of the @name of each block that must precede the current block. The interactive version of the exercise will mark as correct any ordering of blocks that is valid according to the described dependencies. Static versions of the answer will only display the cannonical answer as determined by the order of the blocks in the source document.
If a Parsons problem that has a @language set to a value that is valid for an activecode (Subsection 4.16.3), it can be made runnable in interactive versions of the book - when the student completes the exercise, they can run the code they built. To do so, define a <program> element as a sibling to the <blocks>. The program can have all of the normal attributes for an activecode, but does not need the @interactive attribute to be set. It should have an empty body as the student work will be used as its contents. If it is necessary to add additional code to the program, you can add either or both a <program-preamble> and <program-postamble> element as siblings to the <program>. The <program-preamble> will be placed before the student’s code, and the <program-postamble> will be placed after the student’s code. Both elements can have an @indent with some text to use as the indentation for every line in the block; use this to align the added code to the expected format of a correct answer.
Subsection4.12.4Horizontal 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.
Subsection4.12.5Matching 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.
Subsection4.12.6Clickable 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.
Subsection4.12.7Fill-in-the-Blanks Exercises
A fill-in-the-blank problem allows the reader to submit free text that is evaluated for correctness. The signal for a fill-in problem is a <statement> containing a sequence of <fillin> elements with a sibling <evaluation> element. Randomized elements to appear in the statement and solution and to be used in evaluation of reader responses requires the presence of an additional <setup> element that is also a sibling to the <statement>. The presence of the <setup> provides the ability for the statement and evaluation of the responses to incorporate random, dynamically generated elements.
The body of the <statement> is the same as for any exercise-like statement, with the addition of two elements of markup. A <fillin> is placed at the location a blank would be required for the reader’s response. Details for this element are described in the next paragraph. When the question includes a <setup>, content can reference the string or TeX representation of the object (if defined) by using a <eval> element, where the name of the object is provided by a @object attribute.
The <fillin> element is required to have an @answer attribute that contains an answer that would be evaluated as correct, in the case that the question has a known, static, valid answer, or an @ansobj attribute that contains the variable name of a dynamically generated object representing a correct answer, in the case that the problem has an associated <setup>. In addition, the <fillin> is required to have a @mode that characterizes the mode by which the submitted answer will be parsed. Current possible modes are string, number, and math (only for the dynamic implementation). The <fillin> element may have a @width attribute specifying the number of characters for the static-version blank. For questions that involve dynamic evaluation, a @name attribute may be used to identify a variable name that will reference the reader’s response during dynamic evaluation of other blanks. (A standard ans variable will always be available in the context of each individual response’s evaluation.)
The <evaluation> block will have a sequence of <evaluate> elements, one associated with each of the corresponding <fillin> elements appearing in the <statement>. By default, the association is by order. If each <fillin> has an associated @name, the association does not need to be in order. Within each <evaluate> element, there will be a sequence of <test> elements that define a comparison rule for the test and the associated feedback provided when the test evaluates as true. Default behavior is that the @answer or @ansobj attribute of the corresponding <fillin> is used for comparison to evaluate a correct response. If the author wishes to override this default or wishes to provide specific feedback for a correct response which will also be used for the automatic solution for static versions, the author will identify one <test> element with the attribute @correct="yes".
Within each <test>, the author needs to specify which type of comparison will be used. For non-dynamic questions, three comparisons are available: <numcmp>, <strcmp>, and <jscmp>. For dynamic questions that include <setup>, additional options include <mathcmp> comparisons involving math objects and <logic> elements to construct more complex boolean tests involving these objects, described later. Feedback that is provided to the reader when the comparison is true, beyond saying the response is correct/incorrect, is provided in a <feedback> element which can itself contain structured PreTeXt text including <eval> elements to reference dynamically generated objects.
A <numcmp> and a <strcmp> can specify that the comparison should be to match the provided answer for the corresponding <fillin> by including the attribute @use-answer="yes". Otherwise, these comparisons must specify the value being compared. A <numcmp> provides this with an attribute @value that indicates the matching value. If the <numcmp> includes the optional @tolerance attribute, any response in the range of from the given value plus or minus the tolerance will be accepted. Alternatively, the <numcmp> can directly provide a @min and @max attribute to specify an arbitrary interval. A <strcmp> that does not include the @use-answer will have content that defines a matching string or more generally a matching regular-expression. By default, PreTeXt augments the provided string to match the entire response after stripping leading and trailing white space. The attribute @strip="no" overrides this behavior so that, for example, the match can look for the presence of a pattern within the response rather than matching the entire response. In addition, the attribute @case="insensitive" makes the regular expression ignore case during the comparison.
A comparison involving <jscmp> allows the author to provide arbitrary Javascript code that will evaluate to either true/false or a string containing feedback for a valid match, where the reader’s evaluated response is available as a variable ans and all of the reader’s responses are in an array ans_array. This allows custom evaluation that can allow the evaluation of one blank to depend on what was answered in another blank. The Javascript is evaluated in the context of a local, anonymous function. Nevertheless, the author should take care that no commands are included that invoke mutable side-effects.
To create dynamic, randomizable versions of a fill-in-the-blank question, a <setup> element is required as a sibling of the <statement> and <evaluation> elements. For the interactive version of these questions, the problem will created with a random number generator initialized with a seed that is stored by the Runestone Component for the reader. This results in the reader seeing the same version the next time they open the question. A button allowing the reader to request a new randomized version changes the seed and regenerates the question. Static representations need to provide consistent versions each time, so the <setup> requires a @seed attribute.
Within the <setup>, the author provides statements that will initialize Javascript objects that will be accessible in the <statement>, <solution>, and <evaluation> elements. The author can provide Javascript code within a <setupScript> child of the <setup>. It is likely that the script contents will need to be escaped to avoid XML conflicts, for example by individually escaping problematic characters or surrounding the code with <![CDATA[...]]>. In the context in which the script runs, there is an object v representing the dynamic variable namespace. Any object that the author wants to access should be created as a member of that object, such as v.myObject = .... The name myObject could then be used (without reference to v) in an @ansobj attribute of a <fillin>, in an @object attribute of an <eval> or directly in a <jscmp> comparison.
To provide randomization, a random number generator based on the current seed is available in the <setupScript> using the object name RNG. The RNG object includes the following methods for generating various types of random values.
RNG.random(): Uniform random values between \(0\) and \(1\text{.}\)
RNG.randSign(): Random values \(+1\) and \(-1\text{.}\)
RNG.randInt(a,b): Random integer from \(a,a+1,a+2,\ldots,b\text{.}\)
RNG.randUniform(a,b): Random floating value \(a < x < b\text{.}\)
RNG.randDiscrete(a,b,dx,nonzero): Random value \(x\) from \(a,a+dx,a+2dx,\ldots\) with \(x \le b\text{.}\) If nonzero=true (optional parameter), then \(x=0\) is excluded.
Using this generator will ensure that subsequent visits by the reader to the question will see the same version.
If the author wishes for reader responses to be parsed to assess format prior to evaluating correctness, <setupScript> should include a declaration of an entry v.types. The value can either be a single parser function applied to all blanks or an array of separate parser functions, one for each <fillin>. A parser function takes a string representing the response for the blank and returns the parsed object. If there is an error in the structure of the response, the function should throw new TypeError(errMsg), and the errMsg will be provided as feedback for the response without performing any of the tests.
The Runestone Component that implements interactivity takes the HTML generated from the <statement> after the <setup> is processed and performs substitutions of any <eval> elements. The recomputed HTML is then inserted into live webpage. A <postRenderScript> entry in <setup> can be used as a second script that runs as a call-back after this substitution occurs. Such a script would be useful if the script requires access to the actual webpage elements and not just defining objects for the evaluation context.
Math Objects in Dynamic Problems.
A Javascript library that supports some mathematical objects in the dynamic setup and evaluation of fill-in-the-blank problems. In order to access these objects, an XML-interface is provided to interact with the objects in the <setup> and <evaluation> elements. Any <fillin> elements expecting to parse as mathematical objects should use @mode="math" and assign @ansobj to the name of a dynamic expression object created in <setup> that represents a correct answer.
For the <setup> stage, a sequence of <de-object> elements can be used to define mathematical dynamic expression objects. Each <de-object> will have a @name attribute representing the object name. The mathematical nature of the <de-object> is indicated with a @context attribute. Currently supported expression types are to represent numbers using @context="number" and formulas using @context="formula".
The content of the <de-object> element is an XML element that defines the actual expression. The following choices are available, described in the following paragraphs:
<de-random>: create a randomly generated number
<de-number>: create a number by providing its value or formula
<de-expression>: create an expression or formula involving variables by directly providing a formula or by performing a substitution or a derivative on a previously-defined expression object
<de-evaluate>: create a number by evaluating an expression object by replacing each variable with a specified number value
As elements are defined in sequence, formulas used at any stage may include the name of any previously generated object as a valid symbol in the formula.
To define a random number, use a <de-random> element. The same random number generation routines provided by the RNG object are accessible through this element using a @distribution attribute and additional attributes for the distribution parameters, some of which come with default values.
@distribution="uniform": Parameters are @min=0, @max=1 as decimal values. Gives a value from the interval \((\mathrm{min},\mathrm{max}\text{.}\)
@distribution="sign": No parameters. Gives \(\pm 1\) as possible values.
@distribution="integer": Parameters are @min, @max as integer values. Value is an integer chosen inclusively between \(\mathrm{min}\) and \(\mathrm{max}\text{.}\)
@distribution="discrete": Parameters include @min, @max, @by="1", and @nonzero="yes". Values chosen from the sequence \(\mathrm{min} + k \cdot \mathrm{by}\text{,}\)\(k=0, 1, 2, \ldots\) that are not greater than \(\mathrm{max}\text{.}\)
In practice, all distributions can be obtained using just the uniform and discrete distributions.
To define a number by formula, including defining rational numbers as fractions, use a <de-number> element. The content of the element should be a single number or a formula that results in a constant value. Symbols of previously defined numbers as well as mathematical constants like pi or e may be part of the formula. Any undefined symbols will result in an error.
To define an expression using a formula that might involve variables, use a <de-expression> with @mode="formula". The content of the element can be a mathematical formula that includes both numbers and variables. Previously defined numbers and expressions can be used in the formula by referencing their object name.
To define an expression that is the partial derivative of another expression with respect to a variable, use <de-expression> with @mode="derivative. Such an expression must have a <formula> child that contains an object representing the original expression. The content can be either a <eval> with @object to reference a previously-defined object or a separate <de-expression> defining an expression not saved as a separate object. In addition, the element must contain a <variable> element with @name indicating the name of the variable of differentiation.
Formula evaluation and substitution follow a similar pattern. Formula evaluation to compute a number is performed with a <de-evaluate> element, which requires that every variable in the expression is assigned a specific numerical value. Formula substitution is like function composition and allows for any subset of the involved variables to be assigned either number or expression values and uses <de-expression> with @mode="substitution". In either event, the element requires a <formula> child element to specify a starting expression using a <eval> element to specify a previously-defined <de-object> or a <de-expression> element to generate a new formula expression. For each variable that will be replaced by a value or another expression, we will include a <variable> with @name specifying which variable is being replaced. The content of the <variable> element can be an <eval> to reference an existing object or any of the elements that can be used to generate a <de-object>.
Automatic reduction and simplification can be applied to elements created by <de-evaluate> and <de-expression> by including the attribute @reduce="yes". Elements created by <de-number> always reduce the resulting number. Reductions include reducing arithmetic involving numerical values and simple algebraic identities. The identities that are applied include the following where \(u\) and \(w\) represent any expression:
\(\displaystyle u \pm 0 \rightarrow u\)
\(\displaystyle 0 \cdot u \rightarrow 0 \rightarrow u\)
\(\displaystyle 0 \div u \rightarrow 0 \rightarrow u\)
\(\displaystyle 1 \cdot u \rightarrow u \rightarrow u\)
\(\displaystyle -1 \cdot u \rightarrow -u \rightarrow u\)
\(\displaystyle u \div 1 \rightarrow u \rightarrow u\)
\(\displaystyle u \div (-w) \rightarrow -u \div w\)
\(\displaystyle (-u)+(-w) \rightarrow -(u+w)\)
For the <evaluation> block, two comparison elements are accessible—<mathcmp> for testing whether two math objects are equivalent and <logic> for constructing compound tests involving simple Boolean logical operations. The <mathcmp> comparison is performed by numerically evaluating the two expressions being compared over a range of values for each variable present and verifying that they are numerically within a comparison tolerance.
To compare the reader’s submitted response to the provided correct answer with <mathcmp>, use @use-answer="yes". To compare the submitted response to any other object, the <mathcmp> element should have a single evaluated math object as content, which could include a newly generated expression using <de-expression> that is based on the submitted responses. To compare two different math objects, the <mathcmp> should have two math objects. For convenience, there are some implicit representations available as well, illustrated in Listing 4.12.2.
<!-- Compare submitted response with fillin answer -->
<mathcmp use-answer="yes"/>
<!-- Compare submitted response with pre-computed object -->
<mathcmp obj="objName"/>
<!-- Compare submitted response with pre-computed object (alternate) -->
<mathcmp>
<eval obj="objName"/>
</mathcmp
<!-- Implicit mathcmp with submitted response (alternate) -->
<eval obj="objName"/>
<!-- Compare submitted response with newly generated object -->
<mathcmp>
<de-expression/>
</mathcmp>
<!-- Implicit mathcmp with submitted response (alternate) -->
<de-expression/>
<!-- Compare with newly generated object with pre-computed object -->
<mathcmp>
<de-expression/>
<eval obj="objName"/>
</mathcmp>
<!-- Compare two newly generated objects -->
<mathcmp>
<de-expression/>
<de-expression/>
</mathcmp>
Listing4.12.2.Possible structures for using <mathcmp> within a <test>. The <de-expression> would be replaced by any valid construction as described for the <setup>.
Compound logical structures are created using the <logic> element in the place of a comparison. To specify which operation is being used, the @op attribute is set to one of @op="and", @op="or", or @op="not". The operations are considered \(n\)-ary, meaning that the contents should be one or more comparison elements, which might include additional logic. The @op="and" will evaluate as true when all of the children comparisons evaluate as true. The @op="or" will evaluate as true when at least one of the children comparisons evaluates as true. The @op="not" is technically implemented as the negation of @op="and", and so will evaluate as true when at least one of the children comparisons evaluates as false. In the absence of any <logic>, there is always an implicit @op="and" so that any sequence of comparisons within a single <test>, all comparisons are required to evaluate as true.
Static Representations.
A static version will include an automatic <solution> which “fills in” each blank with the correct answer that is provided by the <fillin>. The feedback text specified in the <evaluation> that associated with a correct response for each of the <fillin> blanks are then provided in sequence. Consequently, the author should ensure that the feedback for a <test> with @correct="yes" makes sense in the context of a back-of-the-book solution and not just as immediate feedback in an interactive setting.
If the author provides an optional <solution> element, this text will also be included as a solution. This solution may contain <eval> elements in the same manner as described for the <statement> element. The automatic solution can be disabled by including @include-automatic="no" as an attribute of the <solution>.
To build the static version, PreTeXt needs to generate the dynamic substitution rules. Each dynamic question that includes <setup> is processed using its corresponding static seed to evaluate the potential substitutions. The resulting substitutions are stored in one of the generated files. Using the PreTeXt-CLI, the substitution file is generated using the command pretext generate dynamic-subs -t static-target where static-target is replaced by a static project target such as PDF.
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.
Subsection4.12.8Coding 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.16.2, Subsection 4.16.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).
Subsection4.12.9Short 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.
An author can also supply an @attachment attribute on the <exercise> element. When set to yes the short answer question will allow the student to upload a single document in support of their answer. This document might be a diagram or an entire essay in PDF format.
A publisher can control when a response area is created in HTML output (Subsection 44.4.14). 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.
Subsection4.12.10Group Work Exercises
A collection of <exercise> may be optionally selected for work by a group of readers. This behavior is only available when hosted on a Runestone server. We re-purpose a <worksheet> specialized division for groups of such exercises.
To enable this behavior, place a @groupwork attribute on a <worksheet> element, with a value of yes. Then all of the contained <exercise> will be provided by Runestone as group work.
