The initial lines are simply comments. All comments in Perl begin with a #.
The lines DOCUMENT(); ...ENDDOCUMENT(); which bracket everything in the problem appear to simply be delimiters, but actually serves an important purpose. From .../webwork/system/courseScripts/PG.pl we read,
As described in the synopsis, this file and the macros DOCUMENT() and ENDDOCUMENT() determine the interface between problems written in the PG language and the rest of WeBWorK, in particular the subroutine createPGtext() in the file translate.pl.
DOCUMENT() must be the first statement in each problem template. It initializes variables, in particular all of the contents of the environment variable become defined in the problem environment.
ENDDOCUMENT() must the last executable statement in any problem template. It returns the rendered problem, answer evaluators and other flags to the rest of WeBWorK, specifically to the routine createPGtext() defined in translate.pl.
The HEADER_TEXT(), TEXT(), and ANS() functions load the header text string, the problem text string, and the answer evaluator queue respectively.
Next we have the loadMacros() function. Its purpose is to make available all of the functions and libraries that have been written for WeBWorK. I usually keep the list the same even if I am not using all the macros alluded to (e.g. PGgraphmacros.pl). Also, if you have some local macros, they can be included as well (e.g. Dartmouthmacros.pl). Keep those with the others in /webwork/system/courseScripts/. The option for local macros referred to above really is intended for locally written macros which you want to be available to all courses using WeBWorK. If you are really writing local macros for your course alone, you can put them in the macros subdirectory of your templates directory, and then uncomment the $macroDirectory = ;SPMquot;${templateDirectory}macros/;SPMquot;; in your webworkCourse.ph file.
Next we set the variable $showPartialCorrectAnswers = 0;. This means that if a student gets some of the answers correct on a multi-part problem, no indication will be given as to which ones are correct. If you want to provide provide that information, set the variable equal to 1. Usually you will have $showPartialCorrectAnswers = 0; for True/False and Multiple Choice type questions and have $showPartialCorrectAnswers = 1; for more complicated of questions. Remember, unless you have implemented an elaborate hints system, it can be quite hard for a student to track down an error especially on a question with multiple answers. The student has no clue whether the error is syntactical or conceptual. Giving some hints by acknowledging partial correct answers can be an important factor in how students feel about WeBWorK.
Now comes the behind-the-scenes set up. Perl statements appear here, perhaps defining random parameters for your problem, defining functions you may want or need, and so on.
Finally, we come to the part of the problem the students will see indicated by the line TEXT(beginproblem());. This rather innocuous looking statement also does a great deal. From PGbasicmacros.pl we find, beginproblem() generates text listing number and the point value of the problem. It will also print the file name containing the problem for users listed in the PRINT_FILE_NAMES_FOR PG_environment variable (in .../webwork/courses/course_XYZ/webworkCourse.ph).
The problem which is to be displayed to the student is entered in a
text environment. Many kinds of things are entered here.
Perhaps you have defined a quadratic of the form
This too will need to be evaluated (and massaged) to generate
acceptable HTML or LATEX code. In any event, all of this code must
be passed to an evaluation function. You will see this accomplished
in several (not necessarily interchangeable) ways.
The standard construct is
This passes all the statements between the BEGIN_TEXT and
END_TEXT through the evaluation routine EV3 described
in more detail than you want in PGbasicmacros.pl. Be a
little careful if you need to use quotes in a problem. They can lead
to unexpected results. You are better off using $LQ (left
double quote) and $RQ (right double quote), which will be
interpreted correctly.
Other variations of the BEGIN_TEXT ...END_TEXT
construction which you may see in sample problems are:
EV2 is an older version of the evaluator than EV3,
and behaves slightly differently. Again see PGbasicmacros.pl
if so inclined. The BEGIN_TEXT ...END_TEXT
construct is equivalent to the TEXT(EV3(;SPMlt;;SPMlt;'EOT')); construct,
but looks friendlier to use. Also note the single quotes surrounding
the EOT in the EV3 invocation; they are required so
that
The final construct, TEXT(blah, blah, blah), is the simplest,
but does no interpretation or evaluation. Nonetheless, it seems to be
indispensable for certain problem constructions such as the matching
and multiple choice examples below (at least for older versions of WeBWorK).
or