Skip to main content

Section 7.1 WeBWorK Problems

You must extract WeBWorK content as described in the Chapter 36 before you will be able to see any WeBWorK content in your output. For most cases, you should be able to do this by running pretext generate webwork to process WeBWorK exercises.

A <webwork> tag must be inside an <exercise>, optionally preceded by an <introduction>, and optionally followed by a <conclusion>.

<exercise>
  <introduction>
  </introduction>

  <webwork>
  </webwork>

  <conclusion>
  </conclusion>
</exercise>

There are several methods for putting content into the <webwork>. (Note that an empty <webwork> with no attributes will simply produce the camelcase WeBWorK logo.)

Subsection 7.1.1 Using an Existing WeBWorK Problem

If a problem already exists and is accessible from the hosting course's templates/ folder, then you can try to simply include it as a @source attribute. For example if it is a problem in the Open Problem Library (OPL), then relative to the templates/ folder, its path is Library/... and you may use:

<webwork source="Library/PCC/BasicAlgebra/Exponents/exponentsMultiplication0.pg" />

Or if you have a problem's PG file, you can upload it into the hosting course's templates/local/ folder and use it with:

<webwork source="local/my_problem.pg" />

Warning 7.1.1. Not Every PG Problem is Compatible with PreTeXt.

Some problems that work fine within WeBWorK are not compatible with PreTeXt. Typically, these are exercises that use older PG coding techniques. To be compatible with PreTeXt, all of the macros used by a problem must be updated to give PreTeXt output. We have done this with modern PG macros and macros that are frequently used. But still, not every OPL problem (for example) is compatible with PreTeXt. In some cases, maybe it would be straightforward to train the macros to give PreTeXt output. But in many cases, older macros are not structured well and PreTeXt is all about good structure. So it could be a significant project to retrofit PreTeXt compatibility.

If you elect to use a problem that is incompatible with PreTeXt but you don't yet know that, a few things could happen. One is that when you process the problems to gather static representations, you will get an error message that the problem did not return valid XML.

Or you might coincidentally get valid XML back, but something is just missing or wrong. There's no automated check for that; you should read the output to check that the problem is complete. We recommend reading your PDF output with hints, answers, and solutions exposed, to be sure you are seeing the static version of the exercise.

If there is an incompatible OPL problem that you would really like to use, you have three options:

  • Author the problem in PreTeXt from scratch as described elsewhere in this section.

  • Edit the code for that OPL problem to use compatible macros.

  • Edit the incompatible macros to be compatible with PreTeXt.

The last two options involve contributing to the OPL and PG repositories on GitHub, so it is more expedient to use the first option.

Subsection 7.1.2 Perl-free Problems

If you'd just like to rattle off a quick question with no randomization, you can do as in this example.

<exercise>
  <webwork>
    <statement>
      <p><m>1+2=</m><var name="'3'" width="5" /></p>
    </statement>
  </webwork>
</exercise>

The <exercise> above could be given an optional <title>, <introduction>, and <conclusion>. The <webwork> inside could be given a <hint> and <solution>. These are discussed in Subsection 7.1.3.

In the above example, '3' is the @name attribute to a <var> element. There is actually no “variable” named “3”; we are just using the slot where more complicated exercises would place a Perl variable answer.

So the above is how to create an answer blank that is expecting \(3\) as the answer. What you give as a @name attribute will be passed to PG's Compute() constructor, so it needs to be valid input for Compute(). Note that you could pass a string encased in quotes, or a perl expression. Just be mindful of the difference:

  • 8**2 will process a perl real using exponentiation and lead to the MathObject Real 64.

  • '8^2' will process a perl string and lead to the MathObject Real 64.

  • 8^2 will process the perl real using bitwise XOR and lead to the MathObject Real 10.

The default context is Numeric, which understands numerical expressions and formulaic expressions in the variable \(x\text{.}\) You can activate some other context as in this example.

<exercise>
  <webwork>
    <pg-code>
      Context("ImplicitPlane");
    </pg-code>
    <statement>
      <p>The answer is <m>x+y=1</m>.</p>
      <p><var name="'x+y=1'" width="8" /></p>
    </statement>
  </webwork>
</exercise>

Many special contexts are automatically detected by PreTeXt, and it loads the appropriate macro file into the PG problem. However you may need to explicitly load a macro file as described in Subsection 7.1.3.

Subsection 7.1.3 PG code in Problems

To have randomization in problems or otherwise take advantage of the algorithmic programming capabilities of Perl and WeBWorK's PG language requires using a <pg-code> tag. Having at least a little familiarity with coding problems in WeBWorK is necessary, although for simpler problems you could get away with mimicking the sample article in mathbook/examples/webwork/. A <statement>, optional <hint>, and optional <solution> follow.

<webwork>

  <pg-code>
  </pg-code>

  <statement>
  </statement>

  <hint>
  </hint>

  <solution>
  </solution>

</webwork>

If you are familiar with code for WeBWorK PG problems, the <pg-code> contains lines of PG code that would appear in the “setup” portion of the problem. Typically, this is the code that follows TEXT(beginproblem()); and precedes the first BEGIN_TEXT or BEGIN_PGML. If your code needs any special WeBWorK macro libraries, you may load them in a <pg-macros> tag prior to <pg-code>, with each such .pl file's name inside a <macro-file> tag. However many of the most common macro libraries will be loaded automatically based on the content and attributes you use in the rest of your problem.

Here is a small example. Following the example, we'll continue discussing <statement> and <solution>.

<webwork>
  <pg-code>
    Context("LimitedNumeric");
    $a = Compute(random(1, 9, 1));
    $b = Compute(random(1, 9, 1));
    $c = $a + $b;
  </pg-code>

  <statement>
    <p>Compute <m><var name="$a"/> + <var name="$b"/></m>.</p>
    <instruction>Type your answer without using the <c>+</c> sign.</instruction>
    <p>The sum is <var name="$c" width="2"/>.</p>
  </statement>

  <solution>
    <p><m><var name="$a"/> + <var name="$b"/> = <var name="$c"/></m>.</p>
  </solution>
</webwork>

Within a <statement>, <hint>, or <solution>, reference <var> tags by @name.

Within the <statement>, a <var> tag with either a @width or @form attribute creates an input field answer blank that expects the variable with that @name to be the answer.

A <var> can have @form with value essay, in which case it need not have a @name attribute. This is for open-ended questions that must be graded by a human. The form field will be an expandable input block if the question is served to an authenticated user within WeBWorK. But for the WeBWorK cells in PreTeXt HTML output, there will just be a message explaining that there is no place to enter an answer.

A <var> can have @form with value array. You would use this when the answer is a Matrix or Vector MathObject (a WeBWorK classification) to cause the input form to be an array of smaller fields instead of one big field.

A <var> can have @form with value popup or buttons for multiple choice questions.

If you are familiar with PG, then in your <pg-code> you might write a custom evaluator (a combination of a custom answer checker, post filters, pre filters, etc.). If you store this similar to

$my_evaluator = $answer -> cmp(...);

then the <var> can have @evaluator with value $my_evaluator.

An <instruction> is specific instructions for how the reader might type or otherwise electronically submit their answer. Contents of an <instruction> will be omitted from print and other static output forms. The <instruction> is a peer to <p>, but may only contain “short text” children.

Some general information on authoring WeBWorK problems can be found in a set of videos at webwork.maa.org/wiki/Problem_Authoring_Videos 1 . Not all of this is relevant to authoring within PreTeXt, but there are parts that will be helpful for constructing the Perl code necessary for randomized problems.

Subsection 7.1.4 WeBWorK in an <exercisegroup>

An <exercisegroup> is a collection of exercises with common instructions that are put into an <introduction>. If you put WeBWorK exercises in an exercisegroup, then when the exercises are exported to .pg problem files for use as online homework from a WeBWorK server it makes sense that the instructions from the <exercisegroup>'s <introduction> should be included in the .pg file. And so they are included there. Note that they are not included when you are building HTML or output for your project. (Rather, the <exercisegroup>'s <introduction> appears in its normal place.)

You should be aware of this when you write the <exercisegroup>'s <introduction>. It impacts the specific language you should use. For example, if you write “Differentiate the following functions.” or “Differentiate each of the functions below.”, then you have language that doesn't fit the individual problem when it is used for homework on a WeBWorK server. Instead you might write “Differentiate the function”. It makes sense as common instructions for the <exercisegroup> as well as the instructions for an individual exercise.

Subsection 7.1.5 Metadata

A <webwork> without a source attribute can have a plain text <description>. This should be a summary of what the exercise asks a user to do, including any relevant pedagogical details of the exercise. For example:

<webwork>

  <description>
    Add two fractions with distinct one-digit prime denominators.
  </description>

  ...

</webwork>

A longer description may be broken into lines where the lines are plain text.

<webwork>

  <description>
    <line>
      Add two fractions with distinct one-digit prime denominators.
    </line>
    <line>
      One fraction is always positive, the other always negative.
    </line>
  </description>

  ...

</webwork>

The content of the description will be written into a PG COMMENT command, making the description visible in a WeBWorK Library Browser.

Subsection 7.1.6 Reusing a <webwork> by @xml:id

If a <webwork> has an @xml:id, then another <webwork> can “copy” the first one simply by using a @copy attribute whose value is the first <webwork>'s @xml:id. The @seed of the first <webwork> is ignored, and the second <webwork> may set its own @seed. For example:

<exercise>
  <webwork xml:id="foo" seed="1">
    <pg-code>
      $a = random(1,9,1);
      $answer = $a+1;
    </pg-code>
    <statement>
      <p>
        Enter <m><var name="$a"/>+1</m>.  <var name="$answer" width="10"/>
      </p>
    </statement>
  </webwork>
</exercise>

<exercise>
  <webwork copy="foo" seed="2"/>
</exercise>

The @copy attribute should point to a <webwork> that has PreTeXt-authored source, not to a <webwork> with a @source attribute. (If you want to copy one with a @source attribute, just reuse the same @source value.)

Subsection 7.1.7 Images

Subsubsection 7.1.7.1 Using a Local image file

Planned.

Subsubsection 7.1.7.2 Using TikZ

In a problem statement (or hint, or solution), you may use an <image> with a <latex-image> child, as long as the host WeBWorK server is version 2.16 or later. See Subsubsection 4.14.3.2 for generalities about using <latex-image>.

However, if a <latex-image> is inside a <webwork>, you must use \(...\) instead of $...$ to encase any inline math in the image. And if you have display math, that should use \[...\] instead of $$...$$.

Your latex-image code can use variables that you defined in the <pg-code> section. Scalar variables may be used simply by using their perl names including the dollar sign sigil. For example, \draw ($a,$b) -- ($c,$d); where $a, $b, $c, and $d are variables. However, any instance of \$ in code will be interpreted as an escaped dollar sign first, so rare situations may require you to be more explicit. The alternative is to include variables just as you would anywhere else in a problem statement, using a <var> element like <var name="$a"/>. You would also need to use a <var> element if you would like to insert a perl array, for example <var name="@a"/>.

In perl, $, @, and % each have special meaning. So you may wonder about using them in your latex-image code. The short answer is that you should use them just as you would use them in a regular document. So when you would like a dollar sign, write \$. For a percent sign, use \%. An “at” character does not need escaping, so write @.

As mentioned above, do not use a dollar sign to encase math. If you want to put a comment in the code, you may write it in the usual way like % This is a comment.

Your project's <docinfo> may contain a <latex-image-preamble> element. If so, and if that preamble content should affect the latex-images inside the <webwork>, then you need to get that preamble content up on the WeBWorK host course. In many cases, you will need to get that preamble content up on the host course for the image to even compile. See Section 36.3.

When the WeBWorK server makes one of these images for the first time, it caches the image. Generally, if you then edit the image source code, the WeBWorK server will not rebuild the image. So while you are developing an image, you may want to put $refreshCachedImages = 1; into your <pg-code> for the problem. This will force the WeBWorK server to rebuild the image. Once the image is stable, remove that line from the <pg-code>. Otherwise every time someone views the image in an embedded interactive HTML exercise, the WeBWorK server will rebuild the image. Beyond the extra strain on the server, this will cause a lag for your readers.

See the WeBWorK sample chapter for examples.

Subsubsection 7.1.7.3 Using @pg-name

In a problem statement (or hint, or solution), you may use an <image> with a @pg-name. This attribute's values should be the name of an image created in the <pg-code> section. For example, an image created using init_graph from PGgraphmacros.pl.

See the WeBWorK sample chapter for examples.

Subsection 7.1.8 Using a Local PG Problem File

Planned.

webwork.maa.org/wiki/Problem_Authoring_Videos