The PreTeXt Guide

Subsection 36.3.1 Extraction and Processing

Before anything else can be done, a PreTeXt project with WeBWorK problems must first have its WeBWorK content extracted and processed into multiple representations, which are then collected into an auxiliary XML file. We do this with the pretext/pretext script which uses Python and the Python requests module. It is not uncommon for your computer to not have requests installed, so you should check if it is there and install it if need be. You can check if it is installed from the command line with:

          python -c "import requests"
        

And if it isn't, you can install it with pip, specifically with:

          sudo pip install requests
        

(If you don't have pip installed, you could use:

          sudo easy_install pip
        

to install it.)

Once you know that you have the requests package installed, use the pretext script to extract PreTeXt content from the WeBWorK server into a folder, which you might call webwork-representations/ as in this example:

$ pretext -c webwork -s <server> -d webwork-representations aota.ptx

aota.ptx in the example is the root file for your PreTeXt project.

-c webwork means you are processing the WeBWorK components.

-s specifies the WeBWorK server. The WeBWorK server needs to be version 2.14 or later, specified with its protocol and domain, like https://webwork-ptx.aimath.org. It is important to get the protocol correct for your server (http versus https). If you do not have a server, you may use https://webwork-ptx.aimath.org.

If any of your hosting course, user for that course, password for the site, or password for the course user are not “anonymous”, then specify the server like

-s "(https://webwork-ptx.aimath.org,courseID,userID,site_password,course_password)"

The site_password is probably “anonymous”, but could be something different. Only server administrators can set this. Again, it is important to get the protocol correct for your server (http versus https).

-d specifies a path to the folder where the auxiliary files will be stored. That folder is named webwork-representations in the example. Any image files that the WeBWorK server generates will be stored inside this folder. An auxiliary XML file called webwork-representations.ptx will be created in this folder. (Note that you can name the folder whatever you like, but the auxiliary file that is created will always be named webwork-representations.ptx.)

Subsection 36.3.2 Representations and the Publisher File

You now have custody of the webwork-representations.ptx. It contains multiple versions of each of your WeBWorK exercises, each appropriate for different output formats. Early in a project, you may regenerate this file frequently as your project changes. Later in a project you might consider it to be (generated/manufactured/derived) source material. More on this in a bit. For now, you need to set up how the file is communicated to a conversion. This is accomplished with the publisher file (see Section 27.1).

The publisher file has a place where you can specify the name of the file with the representations, by default, webwork-representations.ptx. You are welcome to change the name at this juncture, but perhaps there is no point. We will proceed with the default. The absolute simplest publisher file you can create would look like

<publication>
  <source webwork-problems="webwork-representations.ptx"/>
</publication>

But there is an important caveat. The use of a relative path in this filename indicates the path to the file is relative to the location of the primary PreTeXt source file. So as written above, the webwork-representations.ptx file would be expected to be in the same directory as the PreTeXt source. If you are having with trouble with subsequent steps locating this file, try specifying the complete filename with a path starting from the very top of your filesystem. This publisher option is described at Subsection 41.6.2.

Realize that any changes to any of your WeBWorK problems, adding new ones, removing any, or rearranging the order will mean you need to regenerate webwork-representations.ptx. Together with the previous paragraph this suggests three approaches, and you might use all three during the life of your project.

1. Use a script to copy your source files into some scratch area, generate webwork-representations.ptx as part of every build since your project is changing rapidly, and copy these representations into the scratch area. (See Section 5.11.)

2. Regenerate webwork-representations.ptx only when necessary since your project is not changing much, and you have many problems, which takes significant time for your WeBWorK server to process. Copy it into a location relative to your source files (even if your build script then copies everything over to a scratch area).

3. Same as the previous step, but track webwork-representations.ptx (and the image files generated) as part of a git repository. You will want to be aware of when the result has changed (beyond just the timestamps).

Subsection 36.3.3 HTML output

When you execute xsltproc using pretext-html.xsl, now supply the publisher file to incorporate the representations. For example:

$ xsltproc -stringparam publisher publication.ptx pretext-html.xsl aota.ptx

You may need to specify paths to these files.

There are several string parameters you may pass to xsltproc.

If your WeBWorK processing produced image files from the WeBWorK server and you are rendering the corresponding problems as static, then you need to copy the images files (from where your file of representations was output) over to where your HTML output assumes images files are located.

Subsection 36.3.4 LaTeX output

When you execute xsltproc using pretext-latex.xsl, now supply the publisher file to incorporate the representations. For example, a single line:

$ xsltproc -stringparam publisher publication.ptx
-o mybook.tex pretext-latex.xsl aota.ptx

You may need to specify paths to these files.

One string parameter you can pass to xsltproc is latex.fillin.style, which can take values 'underline' (the default) or 'box'.

If your WeBWorK processing produced image image files from the WeBWorK server, then you need to copy the images files (from where your extracted auxiliary XML file was placed) over to where your TeX output assumes images files are located.

Subsection 36.3.5 Creating Files for Uploading to WeBWorK

All of the <webwork> that you have written into your project can be “harvested” and put into their own .pg files by the pretext script. These files are created with a folder structure that follows the chunking scheme you specify. This process also creates set definition files (.def) for each chunk (say, for each section): one for inline exercises (checkpoints) and one for divisional exercises. For <webwork> problems that come from the WeBWorK server, the .def file will include them as well. This archiving process creates set header .pg files for each set definition.

As with other WeBWorK processing, you must create the representations and specify a publisher file as described in Subsection 36.3.1 and Subsection 36.3.2. Then use xsltproc with the pretext-ww-problem-sets.xsl stylesheet. For example, a single line:

$ xsltproc -stringparam publisher publication.ptx
pretext-ww-problem-sets.xsl aota.ptx

You may need to specify paths to these files.

With a book, you can break up your problem set into multiple files according to a chosen depth of the hierarchy. See Subsection 41.1.1 for details on how to specify this.

This creates a folder named after your book title, which has a folder tree with all of the .pg and .def files laid out according to your chunk level. You can compress this folder and upload it into an active WeBWorK course where you may then assign the sets to your students (and modify, as you like).