Opening the book…
Preamble
The Preamble is the environment setup for the problem. It loads the macro files that make PGML work and unlocks specific interaction patterns the rest of the file assumes exist. For a reference list of commonly used macros, see Common PG Macros. For background on PG files, see PG Problem Files.
When a problem fails to load with a generic error, the cause is almost always a missing or mismatched macro in the preamble. This section is boring when it works and unforgiving when it does not, so most authors touch it last, not first.
How to read this code
When reading the preamble, ignore the story of the problem entirely. This section exists to answer one question only: what tools does this problem need in order to render and grade correctly. If something fails to load, displays as plain text, or shows missing widgets, the cause is almost always here.
The excerpt below is the exact preamble used in the worked example. It shows the macro files that are loaded before any values or text are defined.
DOCUMENT(); loadMacros( "PGstandard.pl", "PGML.pl", "parserRadioButtons.pl", "PGcourse.pl" );
Line notes
| Line or snippet | What it does | What you would change first |
|---|---|---|
DOCUMENT(); |
Initializes the problem file so WeBWorK knows where it begins. | Almost never changed. |
PGstandard.pl |
Provides core PG functionality used by nearly all problems. | Always required. |
PGML.pl |
Enables PGML formatting and answer blanks. | Remove only if converting away from PGML. |
parserRadioButtons.pl |
Enables radio button answer widgets. | Add or remove when changing interaction type. |
PGcourse.pl |
Loads course-level helpers and defaults. | Usually left alone. |
A common mistake is copying an example from elsewhere and missing a macro that enables a widget. When that happens, the problem often renders with no useful error message unless you test locally.
Why this exists: it declares which macro files and features the problem can use.
| Common edits | Common failures |
|---|---|
|
|
Macro selection (what to load)
| Macro | What it enables | When you need it | Common failure | Canonical example |
|---|---|---|---|---|
| PGstandard.pl | Core PG functions and helpers. | Always (baseline PG utilities). | Undefined basic functions. | OpenWeBWorK PG samples: most core examples. |
| PGML.pl | PGML prompt blocks and inserts. | Any PGML-first prompt. | BEGIN_PGML fails or renders raw text. | OpenWeBWorK PG samples: PGML intro pages. |
| parserRadioButtons.pl | Radio-button answer widgets. | Single-correct multiple choice prompts. | Radio buttons do not render. | OpenWeBWorK PG samples: radio button techniques. |
| PGcourse.pl | Course macros and shared helpers. | You rely on course-wide helpers. | Custom helper not found. | OpenWeBWorK PG samples: course macro usage. |
For radio-button interactions, load parserRadioButtons.pl and mirror the official radio button technique pages in the OpenWeBWorK PG samples so the UI matches the pattern you want.
Useful reference samples include parserMultiAnswer and NumericalTolerance in the OpenWeBWorK PG samples, which show canonical patterns for coordinated blanks and tolerance handling when you move beyond single-choice prompts.
Some older examples use legacy macros or interaction widgets that still appear online; prefer the patterns shown in the official PG sample problems when choosing an interaction style.
When it breaks
| Symptom | Likely cause | Fix |
|---|---|---|
| Macro not found error | Missing macro file in loadMacros(). |
Add the macro and keep load order consistent. |
| Choice widget renders as plain text | Radio button macro file not loaded. | Load parserRadioButtons.pl in the Preamble. |
| PGML block not recognized | Missing PGML.pl. |
Load PGML.pl before the PGML block. |
Broken example: missing macro for the interaction
This problem fails before the statement even renders. The author copied a radio button example but did not load the macro that provides the widget. In ADAPT, this often appears as a generic error with no line number.
DOCUMENT(); loadMacros( "PGstandard.pl", "PGML.pl", "PGcourse.pl" );
Later in the file, the setup uses RadioButtons.
What went wrong
- The interaction widget exists in setup, but the macro that defines it was never loaded.
- The PG file parses, but rendering fails when the widget is encountered.
- ADAPT typically reports a generic error loading the problem.
How to recognize it
- The file worked in another problem you copied from.
- The error appears before any text renders.
- Local rendering reports an undefined subroutine or missing macro.
How to fix it
Add the missing macro to loadMacros() and re-render immediately. This is why preamble problems should always be tested locally before import.
This page titled 4.3: Preamble was last modified on Fri, 27 Feb 2026 15:21:00 GMT and is shared under a CC BY 4.0 license and was authored, remixed, and/or curated by Neil R. Voss.
The book could not be loaded just now.