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.0.26.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.)
