Documentation:WeBWorK/Problem Authoring Templates/PG Structure

WeBWorK problems are stored in PG files. These files are typically organized in the following way:

Tagging and Description

The tagging and description section describes the problem for future users and authors. The purpose of the tagging information is to make the problem easier to find by searching or browsing. Each tag must appear on its own line, starting at the first character, and be in the following format: ## Tagname(tag value). There are three required tags, DBsubject, DBchapter, and DBsection, placing the problem in the hierarchy that's exposed in the Library Browser. Problems should also have a Level, denoting its difficulty on a predefined scale.

Optional tags include Keywords, for easier searching, as well as tags to indicate authorship (Author and Institution), and to link to a specific textbook (TitleText1, EditionText1, AuthorText1, Section1, and Problem1).

More information on tagging can be found on the WeBWorK MAA wiki.

## DBsubject('Arithmetic')
## DBchapter('Integers')
## DBsection('Addition/subtraction')
## Level(2)
## KEYWORDS('arithmetic', 'adding')
## Author('Davor Cubranic')
## Institution('University of British Columbia')

Note that non-ascii characters may appear especially when using quotation marks (" ") to tag a question. A specific case that has brought our attention is that the default mode of the Text editor on a Mac laptop is "rich text mode", which is a non-ascii character. If one right clicks inside the editor and selects "substitution", one should see "smart quotes" are selected by default. If one wants to use the Text editor, one should change it into plain text mode (format menu -> make plain text).

Initialization

The initialization section loads required macros for the problem. It must' begin with the DOCUMENT(); command, followed by the loadMacros command that loads additional commands used by the problem. For basic problems, the following is sufficient — template files for specific problem types will tell you if any other macros should be loaded.

DOCUMENT();
loadMacros(
"PGstandard.pl",
"MathObjects.pl",
);

Problem Set-up

In this section, define variables specific to the problem, for instance various parameters or the correct answer value. These variables are used in subsequent sections either in the text displayed to the student, or to check the answer. You should begin this section with Context, to tell WeBWorK the type of variables that are used. In this example, we use Context("Numeric") to indicate that the following commands work on scalar numbers.

There are many ways to assign value to variables. The two we show here are:

1. by a random draw from a range of values (random, which in this case chooses from a sequence starting at 2, ending at 9, and incrementing by 1, thus choosing integers in the range [2, 9])
2. by computing a value (Real) from a math expression, in this case the real number calculated by adding one to the value of $a. These are the so-called MathObjects, and they lie at the heart of WeBWorK's functioning. For instance, MathObjects know how to compute or simplify fairly complicated mathematical expressions, how to display themselves in a sensible way in the text of the problem, and how to compare themselves to the student's answer . See MAA WeBWorK wiki for an introduction to MathObjects and follow its links to learn additional features as needed.

Context("Numeric");

$a = random(2, 9, 1);
$a_plus_1 = Real("$a + 1");

See MAA WeBWorK wiki for an introduction to contexts and a list of other types of contexts, such as matrices or intervals.

Text

The text section gives the text that is shown to the student. It begins with a line containing TEXT(beginproblem());. Everything between the BEGIN_TEXT and END_TEXT lines (each of which must appear alone on a line) is shown to the student. These are usually accompanied with a Context()->texStrings, to tell MathObjects (such as $a in the previous example) to display themselves using TeX formatting, and Context()->normalStrings to turn the default behaviour back on.

The text can be formatted with a number of special characters and variables:

• mathematical equations can be typeset with a LaTeX-like formatting macros within \( and \) delimiters (displayed inline with text) or \[ and \] (displayed in their own block).
• line breaks are denoted with $BR and new paragraphs with $PAR.
• additional formatting is done using special variables to typeset text in bold (between $BBOLD and $EBOLD) or italic ($BITALIC and $EITALIC)
• if you need to execute any code in the text section, enclose it with \{ and \} delimiters. The resulting value is converted to text and inserted at that point in the section. There are quite a few built-in functions that are used in this manner to, for instance, show images or tables. More fundamentally, this method is used to insert a field for a student's answer. In the following example, we use ans_rule(6) to insert a blank text entry field six characters wide:

TEXT(beginproblem());
Context()->texStrings;
BEGIN_TEXT
What number is one greater than \( $a \)?
$PAR
\( $a + 1 = \) \{ ans_rule(35) \}
END_TEXT
Context()->normalStrings;

Answer and Solution

The answer and solution section specifies how the answer(s) to the problem is(are) marked for correctness. Optionally, it can also give a solution that is shown to the student after the problem set is complete.

The student's answer is evaluated with the ANS command, in which we give it an "answer checker" that compares the student's entry with the correct value (here, $a_plus_1->cmp()).

The optional solution is only visible to students after the homework deadline. In it, you are free to explain the correct solution using a combination of text and math formulas just as in the problem text. The only difference is that this section is enclosed in a BEGIN_SOLUTION and END_SOLUTION pair, rather than BEGIN_TEXT/END_TEXT.

Finally, your document must end with ENDDOCUMENT(); as the last command in the file.

ANS($a_plus_1->cmp());

Context()->texStrings;
BEGIN_SOLUTION
Because \( $a + 1 = $a_plus_1 \), the correct answer is \( $a_plus_1 \).

END_SOLUTION
Context()->normalStrings;

ENDDOCUMENT();

Note

Because PG files are really syntactically correct Perl code, you are free to use all of Perl's standard functionality. (Well, almost: functions that would expose potential security holes, such as accessing files or running processes, are disabled.) In particular, this means that you are free to include comments in your file, starting them with the standard Perl comment character #. You will see comments in the attached complete PG file.

Complete source code

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WeBWorK expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WeBWorK browser-based problem editor.

Template file source.