Skip to main content

Section 31.1 A Runestone Build

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

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

(See Subsection 41.4.6.) Then perform the usual conversion to online HTML, as described in Chapter 28 but also include the publisher file via a string parameter. 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 server when hosted.

As of 2020-06-21 you need to add some files from Runestone to your local output, which will allow you to see some interactive features in action. Here's the recipe. (We will eventually automate this process.)

  1. Within your HTML output make a top-level directory named _static. We will be populating this directory in the last step.

  2. You will need to setup a virtual Pythion environment if you do not already have one (a one-time process) and then activate it. We'll assume this environment is called ptx. Instructions are at Section C.2.

  3. Obtain and install the Runestone Components library:

    (ptx) $ pip install runestone
    

    This is the point of this exercise because this package contains the files we want. But where are they?

  4. Run Python interactively: (ptx) $ python

  5. Make a Python tool available:

    >>> from pkg_resources import resource_filename
    
  6. You can now decipher where pip installed two files in your virtual environment as part of the runestone package:

    >>> resource_filename("runestone", "dist/runestone.js")
    >>> resource_filename("runestone", "common/js/jquery.idle-timer.js")
    

    You should get some enormously long filenames back from each of these commands. They should begin with your home/user directory, eventually include virtual-python (or whatever directory you used for virtual environments), followed immediately by ptx, a little while later runestone, and then finish with runestone.js or jquery.idle-timer.js. This is the information we need.

  7. Using the locations of these files from the previous step, copy each file into the _static directory you made at the start.

Note: the two particular files necessary may change. This is current as of 2020-07-15.

The above will build HTML output that can be hosted on a Runestone server. But you may want to see a local version that provides some preview of what the output looks like and how it behaves. Of course, many of the interactive features of the Runestone platform are also going to be missing. To make a local version, use a string parameter (Section 5.4) on your xsltproc command line (in addition to the necessary publisher file):

xsltproc -stringparam runestone.dev yes -stringparam publisher rune.xml
    pretext-html.xsl aota.xml

Be sure to set this parameter to no, the default, when you are ready to build a version that will be hosted. Or just remove it altogether.