Skip to main content

Chapter 31 Conversion to Runestone

Runestone Interactive 1  is a textbook hosting system orginally designed for textbooks about computer science. It is similar in design and goals to PreTeXt, but is also complementary in important ways. In particular, Runestone excels at providing very interactive versions where student work in the textbook can be graded (automatically or manually), scores recorded, and that information can be viewed by an instructor. Any instructor can easily spin-up an instance of your book for their course, at no charge to the school or to the students.

The usual PreTeXt HTML output (Chapter 28) only needs minor modifications to run profitably on a Runestone server. You accomplish this via a publication file (Section 26.1). The absolute simplest publication file to accomplish this is

<publication>
  <html>
    <platform host="runestone"/>
  </html>
</publication>

(See Subsection 42.4.6.) Then perform the usual conversion to online HTML, as described in Chapter 28 but also be sure to specify the publication file. The output should appear like a usual PreTeXt document, but will now include a new menu on each page. This has options which allow a reader or instructor to interact with the Runestone server when hosted there.

Runestone textbooks are designed around interactive activities and active reading. We are well along in the process of exposing these capabilities via PreTeXt markup, as of 2022-04-13. So expect this list to expand, and feel free to influence priorities for new features. Some of this is subject to change as we gain experience.

  • Every feature of PreTeXt HTML output should function identically on a Runestone server.

  • Any <exercise> authored in PreTeXt will automatically be rendered as a Runestone short answer question, when the Runestone platform is targeted as the host. A student can use notation in formulating their answer, and Runestone will provide the instructor an efficient interface for reviewing student responses, provide feedback, and assign scores. See Subsection 42.4.7 for options that will silence this behavior.

  • We are almost finished designing markup for the various types of problems available in Runestone: True/False, multiple choice, Parsons problems, matching, and ActiveCode programming exercises. Hosted on Runestone, readers have their responses graded and get instant feedback, plus their results are saved at the site. For other HTML output, hosted on your own server, these problems are automatically graded and the reader gets instant feedback, but of course, responses and scores are not saved anywhere.

  • As much as possible, non-interactive versions of these problems will render in less-capable formats, like PDF, EPUB, and braille.

  • A <program> element with the attribute @interactive set to activecode will be realized as a Runestone ActiveCode element, where programs can be edited, compiled, and run. In some cases a CodeLens interactive trace utility is available. The @language must be set. Supported values for the language when hosted at Runestone are: python, python2, python3, c, cpp (C++), javascript, java, octave (Matlab), sql, and html. When hosted on your own server, python, javascript, sql, and html, are supported with in-browser routines. So you do not need to configure anything server-side for this capability.

  • More PreTeXt markup for Runestone books is coming and will go here.

  • All of the interactive exercises on a Runestone server can be worked by a student at the location in the book where they were authored, or a student may use the interface provided by the server to locate exercises assigned by an instructor, at a page disjoint from the text itself.

  • Students and instructors are provided extensive reports on progress.

  • Instructors may download a spreadsheet of scores at any time.

We will not attempt to duplicate Runestone's documentation here. Visit the Runestone Academy 2  site to learn more about all the features designed for hosting your textbook for everybody's courses.

runestone.academy
runestone.academy