Skip to content

WeBWorK assembly: replace ww-id pass with per-exercise representation files#2809

Draft
rbeezer wants to merge 8 commits intoPreTeXtBook:masterfrom
rbeezer:webwork-assembly-id-phase2
Draft

WeBWorK assembly: replace ww-id pass with per-exercise representation files#2809
rbeezer wants to merge 8 commits intoPreTeXtBook:masterfrom
rbeezer:webwork-assembly-id-phase2

Conversation

@rbeezer
Copy link
Copy Markdown
Collaborator

@rbeezer rbeezer commented Mar 30, 2026

This PR removes the dedicated WeBWorK identification pass and replaces the single monolithic webwork-representations.xml file with one XML file per exercise, named by the exercise's @assembly-id.

Motivation. The old pipeline stamped a @ww-id on every webwork element in a separate assembly pass, then used those IDs to look up entries in a single representations file. The @assembly-id, already computed in the assembly-label pass, serves the same purpose — and is the exercise's stable, meaningful identifier. Per-exercise files make incremental regeneration natural: only changed problems need to be re-sent to the server.

Commits follow the pipeline order:

  1. Assembly: remove WeBWorK identification (ww-id) pass — eliminates the webwork mode pass, the $all-webwork/$webworked variable chain, and the @ww-id stamping template.
  2. WeBWorK: use parent exercise @assembly-id as problem identifierextract-pg.xsl now reads ../assembly-id from the parent exercise.
  3. WeBWorK: use assembly-id of original exercise for copied-from reference — for @copy problems, the copied-from attribute now carries the assembly-id of the source exercise rather than the xml:id of the source webwork element.
  4. Script: write @assembly-id on webwork-reps elements — replaces ww-id attribute with assembly-id on each webwork-reps element written by the server communication loop.
  5. Script: write per-exercise WeBWorK representation files — each problem is written to {assembly-id}.xml in the representations directory instead of appending to a single file.
  6. Publisher variables: replace webwork-representations-file with webwork-representations-dir — the publication file variable switches from pointing to a single file to pointing to the directory.
  7. Assembly: use @assembly-id with per-exercise representation files — the representations pass loads {dir}/{assembly-id}.xml per exercise; error messages note the presence of an old-format webwork-representations.xml as a sign that regeneration is needed.
  8. HTML: read @assembly-id from webwork-reps for div and iframe — updates the two locations in HTML output that used @ww-id.

Breaking change. Existing generated WeBWorK files must be regenerated. The error messages in the assembly pass will identify the problem and point to the old file if present.

Testing. Tested against examples/webwork/sample-chapter/ using pretext/pretext on both master and this branch. WeBWorK representations were regenerated from https://webwork-ptx.aimath.org using the new per-exercise code (76 files produced, including all @copy problems). Before/after builds were run for HTML, LaTeX, and PG problem sets (webwork-sets); all three produced the same file counts with no warnings or errors. The only differences in output are the intended ones: ww-id-based identifiers replaced by assembly-id-based identifiers, image filenames now use the exercise label rather than an opaque counter, and PG file timestamps. The four assembly-* developer formats were also compared before/after on the sample-chapter; assembly-version output is identical, and the differences in the other three reflect only the identifier renaming.

🤖 Authored with Claude Code

rbeezer and others added 8 commits March 29, 2026 11:01
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…k-representations-dir

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@rbeezer
Copy link
Copy Markdown
Collaborator Author

rbeezer commented Mar 30, 2026

I plan to re-do the testing, but have already reviewed (and refined) this a lot.

Comments from @Alex-Jordan ?

@oscarlevin : see point 7 above about transitioning. If there is more that can be done to help the CLI, just say so,

@Tanaquil18
Copy link
Copy Markdown
Contributor

From what I can tell, this is a great thing, but is this something that's going to affect courses currently ongoing using books containing WeBWorK hosted on Runestone? Like ones going on for PROTEUS right now?

@bnmnetp rebuilds books every Saturday, but I don't think assets are usually regenerated with that rebuild and it seems like they'd need to be if this gets merged and Brad updates the author server's version of the CLI, right?

@rbeezer
Copy link
Copy Markdown
Collaborator Author

rbeezer commented Mar 30, 2026

There is no such thing as a good time. I'd likely commit in early May if I can keep this rebased. But comments are appreciated sooner rather than later. There is a lot here to keep in my head.

@oscarlevin
Copy link
Copy Markdown
Member

For the CLI, we already have a special step in processing that ensures there is a webwork-representation file (since not having that will break the build). I would guess that we could easily modify that to ensure we don't have a webwork-representation file or otherwise build the individual files. So I don't think Runestone will have any issue.

Maybe a more dire concern: what happens if you try to build and even one of the individual files is missing? Is this a critical error? The CLI could check that every single file is present on every build, but this might be time intensive for books with lots and lots of webwork.

@rbeezer rbeezer marked this pull request as draft April 2, 2026 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants