Problem Authoring Background Information

Background Information on Problem Authoring

All WeBWorK problems are read from text files that are written in a language called PG (for Problem Generation) and stored on the WeBWorK server. Thus, to create new problems, one has to edit a file and ensure that it is on the server in a location that is accessible to WeBWorK.

PG language overview

The PG language is a collection of macros (subroutines) written in perl which facilitate writing mathematics questions. It began in 1995 and is continuously under development as mathematicians stretch the existing boundaries of existing online homework questions. PG currently has three dialects.

• The original PG language, developed by Michael Gage, Arnie Pizer and undergraduates at the University of Rochester leveraged the regular expression capabilities of Perl 4 (before object orientation had arrived in perl) and the perl parser to present mathematics questions and analyze the student answer strings. Because the subroutines which analyze the answers are macros are written at the same level as the macros which help present the questions it is comparatively easy to extend WeBWorK's capabilities in new directions. When writing new questions it is usually best not to copy the style used in the original PG questions, but to use the newer questions which incorporate MathObjects and PGML structures. Such questions are easier to maintain, provide better feedback to students and make the question writing process seem more like mathematics and less like programming. The underlying PG structure is still there when it is really needed, but current best practices suggest using MathObjects in most cases.
• Davide Cervone's MathObjects (sometimes called Parser objects in early documents) builds on the PG structure to provide more object orientation. In particular a MathObject such as Formula("x^2+(sin x)/x"); 'knows' how to print itself as a TeX string or as a TI-83 calculator notation string. It can also check a student's answer to see if it agrees, find its own derivative and more. There is a whole section of this wiki devoted to MathObjects. You can experiment interactively with writing fragments of PG code using MathObjects, PG and perl at PGLabs
• The PGML commands, also written by Davide Cervone, imitate the markDown language for creating web pages to facilitate the layout of WeBWorK questions. An interactive lab which also describes how the PGML commands work is linked to the PGLabs wiki page

Editing Problems

• Client-side
  Editing problems locally requires only that one have some editor to create the problem files: emacs, vi, TextEdit, NotePad, or even something like Word or WordPerfect. Be sure that you save the file that you create as a text file, not as a formatted (.doc, .rtf, etc.) file. All problem files have the same general format, given by this sample file.

  In the long term it will be to your advantage and others' if you adhere to the good problem coding standards suggested in this file: include problem tagging, description, and solutions.

• Server-side
  There is also a very simple built-in editor in WeBWorK that can be used to edit problems. Access to this is obtained by looking at an existing problem in the Library Browser or in an existing problem set, and then clicking the "Edit" link that appears by the problem. You can also use this editor to create new problems: edit a problem, and create a copy of it to use for your new problem. As before, it's a good idea to follow the format suggested by the sample problem file. (need information about this process?)

Ensuring Server Access

If an existing problem is edited using the built-in WeBWorK text editor, the problem that is created will be automatically put in a location that the WeBWorK server is able to find.

Problems edited on the client computer with a different editor must be moved to the server so that WeBWorK can find them. This is most easily done by uploading the file using WeBWorK's File Manager. All problem files located in the templates directory in a course are accessible by WeBWorK for use in that course. (need link to information about library/linked problems)

Next Steps

A good next step is to look at the basic problem templates, and subsequently the more advanced problem examples. If you are coding a problem and are looking for a specific technique, you may want to consult the index of problem coding techniques.