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.)
Within your HTML output make a top-level directory named
_static. We will be populating this directory in the last step.
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.
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?
Run Python interactively:
(ptx) $ python
Make a Python tool available:
>>> from pkg_resources import resource_filename
You can now decipher where
pipinstalled two files in your virtual environment as part of the
>>> 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
jquery.idle-timer.js. This is the information we need.
Using the locations of these files from the previous step, copy each file into the
_staticdirectory 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.