Yours

4: Breaking Down the Components of a WeBWorK Problem

The ADAPT WeBWorK Handbook · LibreTexts

0%

Contents

    Text

    Size
    100%
    Theme
    Typeface
    Line length
    Spacing

    From LibreTexts, under CC BY 4.0, as the source states it; its equations are written in TeX, which the PDF shows typeset. This page at LibreTexts.

    Index: section, what it controls, and what to check when debugging.
    Section What it controls What to check when debugging
    OPL header Metadata, searchability, and attribution. Missing TITLE/DESCRIPTION or empty tags.
    Preamble Macros, rendering switches, and global knobs. Missing macro files, wrong load order, or disabled features.
    Setup Values, constraints, answers, and graders. Choice list mismatches, wrong correct answer, or grading mistakes.
    Statement PGML prompt text, structure, and blanks. Blank binding, missing inserts, or formatting breaks.
    Solution Explanations, trust, and grading alignment. Mismatch between solution conventions and the checker.

    Chapter 4 is a single worked problem sliced into OPL Header, Preamble, Setup, Statement, Solution, and a Put it together workflow page. It mirrors the OpenWeBWorK PG sample-problem structure while acknowledging the five-section reality so you can scan each layer quickly and edit the right section first.

    This chapter is not teaching new syntax. It is teaching how to read a working WeBWorK problem so you know where to edit safely.

    The five parts of a problem are visually distinguished throughout this chapter so you can spot where an edit belongs at a glance.

    Running example: a short multiple-choice prompt with two radio-button blanks, one vertical and one horizontal.

    Instead of treating a problem as a block of code, this chapter treats it as five parts that each have a job and each fail in predictable ways. The goal is not to memorize syntax, but to build a reliable editing habit: change one part, test it quickly, and keep the file readable for the next person.

    One-screen anatomy (table version)

    One-screen anatomy (table version) reference.
    Section name What readers usually change What usually breaks
    OPL header TITLE, keywords, DBsubject tags. Missing DESCRIPTION or empty tags.
    Preamble Macro list, display options, parser features. Missing macro file, wrong load order, or missing feature.
    Setup Answer objects, choice lists, and correctness rules. Choice list mismatches or a wrong correct answer.
    Statement Story wording, tables, blanks, formatting. Unbound blanks, missing variables, malformed PGML.
    Solution Explanation steps, rounding notes, units. Solution shows a different convention than the checker.

    If ADAPT reports only a generic error, do a fast local render from Testing and Debugging to get a line number before you troubleshoot the section tables below.

    Section pages

    Practical edit map

    Practical edit map: task, where to edit, and fast check.
    Task Where to edit Fast check
    Change options Setup (choice lists) Render and confirm the correct label still matches.
    Change prompt wording Statement (PGML) Confirm each blank still has an answer attached.
    Add another blank Setup then Statement Verify the new blank label maps to the right answer.
    Change the correct answer Setup (answer object) Confirm the Solution shows the same label.

    Section snapshots

    OPL header

    Why this exists: it makes the problem searchable and credits the author.

    OPL header: common edits and common failures.
    Common edits Common failures
    • Update TITLE or DESCRIPTION.
    • Adjust DBsubject tags.
    • Missing DESCRIPTION block.
    • Empty or mismatched tags.

    Preamble

    Why this exists: it declares the macros and global options that make the rest of the file possible.

    Preamble: common edits and common failures.
    Common edits Common failures
    • Add or remove macro files.
    • Enable a parser or display option.
    • Macro file not loaded.
    • Macro load order hides a feature.

    Setup

    Why this exists: it defines the values, constraints, and answer objects that the PGML uses.

    Setup: common edits and common failures.
    Common edits Common failures
    • Edit choice lists or correct answers.
    • Adjust layout or ordering options.
    • Correct answer no longer matches the list.
    • Statement points to the wrong answer object.

    Statement

    Why this exists: it is the PGML prompt students read, including data, structure, and blanks.

    Statement: common edits and common failures.
    Common edits Common failures
    • Rewrite the story or add a data table.
    • Insert or remove answer blanks.
    • Blank missing its attached answer.
    • Variable used before it is defined.

    Solution

    Why this exists: it shows the grading target and builds trust without becoming a second lecture.

    Solution: common edits and common failures.
    Common edits Common failures
    • Clarify the correct option or rationale.
    • Explain how the choice is determined.
    • Solution names a different option.
    • Solution label does not match grading.

    • 4.1: Full file
      Shows the full reference .pg file with section markers and a short anchor map. After finishing, you can scan the entire flow and confirm which section contains a change you just made. Use it as a reference copy after you edit in 4.2 to 4.5, not as the first editing target.
    • 4.2: OPL Header
      Breaks down the metadata header for the worked example, showing TITLE, DESCRIPTION, KEYWORDS, DBsubject/DBchapter/DBsection, Level, Language, and attribution fields with biology-specific classification choices. After finishing, you can write proper metadata for your own problems, choose appropriate DBsubject values for life sciences, and understand why this "section zero" comes before DOCUMENT(). Use it when writing headers for new problems or reviewing metadata quality before publishing.
    • 4.3: Preamble
      Focuses on the Preamble as the macro-loading layer, uses a radio-button example, and includes a broken example that shows how missing macros block rendering. After finishing, you can choose the right macro list for a choice-based problem and recognize when a missing macro causes a render failure. Use it when adding a new interaction type or cleaning up a legacy macro list.
    • 4.4: Setup
      Covers Setup as the place for answer objects, choice lists, correct answers, and layout options, with a broken example where the story and answer drift out of sync. After finishing, you can keep the choice list and correct answer aligned, decide when to set correctness by value versus index, and avoid mismatches between setup and statement. Use it when adjusting options, ordering, or grading behavior before you touch the prompt text.
    • 4.5: Statement
      Breaks down the Statement as PGML text plus blanks, with a blanks map, structure patterns table, and a broken example that shows a blank bound to the wrong answer object. After finishing, you can align each blank with its answer object and choose the right structure (paragraphs, lists, tables, inline math) without breaking readability. Use it when rewriting the story or adding choice-based inserts that follow the OpenWeBWorK technique samples.
    • 4.6: Solution
      Explains the Solution as a short, trust-building explanation aligned with the checker, with a broken example where the solution contradicts grading. After finishing, you can keep the solution consistent with choice labels and grading logic while adding minimal feedback hooks. Use it when students or graders need clarity about the expected method and format.
    • 4.7: Putting It All Together
      Turns the deep dive into a repeatable edit workflow with a common-edits table and preflight checks. After finishing, you can jump to the right section first, then verify alignment before importing to ADAPT. Use it as the final workflow page when you want a fast local render option and a techniques menu for swapping interaction types.

    This page titled 4: Breaking Down the Components of a WeBWorK Problem was last modified on Fri, 27 Feb 2026 15:31:28 GMT and is shared under a CC BY 4.0 license and was authored, remixed, and/or curated by Neil R. Voss.