# XML-LaTeX Authoring for WeBWorK Problems

Version: 50 Thu Aug 28 10:58:26 2008 -0400 Daniel Graham

# Overview

The goal of XML-LaTeXauthoring is to provide a new authoring method which is both user-friendly and flexible and produces PG (WeBWorK) output files.

An inescapable design factor is that a problem must ultimately be rendered in HTML to be used within PG. Since HTML can only implement a subset of LaTeX, the approach taken here is to use a combined XML-LaTeXformat for problem files with with LaTeXused for mathematics and XML (HTML) used for everything else. Automatic conversion of these XML-LaTeXfiles to PG format is accomplished by using an XSLT (extensible stylesheet language transformation) stylesheet and any of a variety of standards-compliant XSLT transformation tools. Such tools are freely available for most common platforms including Windows XP, Mac OS X and Linux. Conversion to another format, say LaTeX, would easily be accomplished by applying a different stylesheet.

# Files

Creating a library of reusable problems requires adherence to a sensible organizational scheme for xml files. The approach taken here requires that the folder (directory) structure on the author's computer provide a folder for each subject, a subfolder for each topic and a sub-subfolder for each problem, e.g.:

GameTheory/SubgamePerfection/DivideTheDollar


Each problem folder contains a problem file with with extension xml and any relevant graphics files.

Automatic processing of the problem file on, say, a Mac using xsltproc would be accomplished by running:

$xsltproc x2pg.xsl yourproblem.xml > yourproblem.pg  in the folder containing yourproblem.xml. The resulting yourproblem.pg can then be pasted into a problem template on a WeBWorK course site. Alternatively, a problem library can be created on the WeBWorK server using the structure: GameTheory/SubgamePerfection/DivideTheDollar.pg  where GameTheory would be the name of the problem library and SubgamePerfection would be the name of the problem collection. # The XML problem file This is the basic problem file from which everything else is derived. Here is a simple example: <problem> <question> What is the value of <m>\pi</m>? <numeric> 3.14159 </numeric> </question> </problem>  The resulting PG file would then be: DOCUMENT(); loadMacros( "PGbasicmacros.pl", "PGchoicemacros.pl", "PGanswermacros.pl", "PGauxiliaryFunctions.pl", "PGgraphmacros.pl", "PGunion.pl", "dukeTables.pl", ); TEXT(beginproblem()); BEGIN_TEXT What is the value of $$\pi$$? \{ ans_rule(20); \} END_TEXT$ans = " 3.14159 ";
ANS( num_cmp( $ans ) ); BEGIN_TEXT END_TEXT SOLUTION($sol);
ENDDOCUMENT();


## Mathematics

in-line: The delimiters are used for in-line math expressions such as \alpha^2 The delimiters are used for display equations such as F(b)-F(a) = \in_a^b f(x) dx

For PG output, <m> and </m> are replaced by $$, and$$, respectively, <mm> and </mm> are replaced by $and$, respectively, and the contained LaTeX math expression is left unchanged. Note that dollar signs are not used to delineate math expressions but are used by PG to denote variable names. For this reason, dollar signs should not be used, e.g., use <dollars>3</dollars> instead.

While the mathematics supported by PG is limited to in-line (single) display equations, support is provided for almost all symbols from TeX{}, LaTeX and AMS-LaTeX and for such environments as matrix, cases and aligned. XML compatibility requires, of course, that &lt; be used instead of <, &gt; instead of > and &amp; instead of &.

Since HTML output requires one sort of markup and the LaTeX produced by WeBWorK's hardcopy requires another, WeBWorK uses "macros" such as $PAR. This macro is automatically converted to <p> for HTML output and to \par for LaTeX output. The XML problem file format is closer to and sometimes identical to the HTML format. E.g., entering <p>This is a paragraph.</p> in an XML problem file would give${PAR}This is a paragraph.${PAR} when transformed to PG output. WeBWorK would then make a further translation dependending upon whether HTML or LaTeX (hardcopy) output is needed. Here is the complete list of XML and corresponding markup: bold: string => Displays string in bold font. a,b,c => \{a,b,c\} in LaTeX math expressions and {a,b,c} otherwise. line => Displays line centered between the margins. 5 =>$5 in HTML and \$5 in LaTeX. word => Displays word in emphasis font (usually italic). word => Displays word in italic font. This is a paragraph. => This is a paragraph. in HTML and \par This is a paragraph.\par in LaTeX. 5 => 5% in HTML and 5\% in LaTeX. => ~~', i.e., an escaped single quote. hello => Wraps "hello" in appropriate double quotes. => in HTML and { } in LaTeX. [Used in empty table cells.] => _ in HTML and \_ in LaTeX. ## versions An optional versions section gives a list of lists with a row for each version and a column for each variable. For example: <problem name="The Power Rule"> <versions> <variables>$a,   $b,$c,   $d </variables> <version> '3', '5', '15', '4' </version> <version> '4', '7', '28', '6' </version> <version> '5', '9', '45', '8' </version> </versions> <question> What is the derivative of <m> <v>a</v>x^<v>b</v> </m> with respect to <m>x</m>? <formula> <v>c</v>x**<v>d</v> </formula> </question> </problem>  Here are three versions of the problem. In the second version, for example, the question would ask for the derivative of 4x^7 and would give 28x**6 as the correct response. The actual version assigned to a student would be chosen randomly by WeBWorK from the available versions. ## pg In addition to or instead of the versions section, it is possible to give PG (modified perl) code to be passed directly to PG. The following pg section, for example, would yield the same result as the versions section of the example given above: <pg>$a=random(3,5,1);
$b=2*$a-1;
$c=$a*$b;$d=$b-1; </pg>  Note that random(3,5,1) randomly selects either 3, 4 or 5 with equal probability. If a pg section is used it should be included before the versions section, if present, and otherwise prior to the question section. ## comments Comments that are meant for the author's eyes only can be included anywhere: <!-- This comment will be ignored completely when the document is processed. -->  Parts, Subparts & Subsubparts To get an outline structure within a problem such as: 1. This is part 1. a. This is part 1.a b. This is part 1.b i. This is part 1.b.i ii. This is part 1.b.ii c. This is part 1.c 2. This is part 2.  use the following inside the <question> </question> tags in p.xml: <parts> <part> This is part 1 </part> <subparts> <subpart> This is part 1.a </subpart> <subpart> This is part 1.b </subpart> <subsubparts> <subsubpart> This is part 1.b.i </subsubpart> <subsubpart> This is part 1.b.ii </subsubpart> </subsubparts> <subpart> This is part 1.c </subpart> </subparts> <part> This is part 2 </part> </parts>  ## Tables Use: <table numcols="3" padding="3" rules="first" lines="first" frame="void" firstcolwidth="60" othercolwidth="44"> <row> <cell format="em"><space/></cell> <cell format="em">clover</cell> <cell format="em">wheat</cell> </row> <row> <cell format="em">arrester</cell> <cell>5</cell> <cell>2</cell> </row> <row> <cell format="em">sparks</cell> <cell>3</cell> <cell>4</cell> </row> </table>  to get a simple table with 3 columns:  clover wheat arrester 5 2 sparks 3 4 Or use: <table numcols="3" padding="5" rules="all" lines="all" frame="box" firstcolwidth="60" othercolwidth="50"> <row> <cell format="em" elements="2">Row, Col</cell> <cell format="em">coop</cell> <cell format="em">fink</cell> </row> <row> <cell format="em">coop</cell> <cell elements="2">2,2</cell> <cell elements="2">0,3</cell> </row> <row> <cell format="em">fink</cell> <cell elements="2">3,0</cell> <cell elements="2">1,1</cell> </row> </table>  to get the strategic form of a familiar two-player game:  Col Row coop fink coop  2 2  3 0 fink  0 3  1 1 ### Parameters Generally, it is possible to have a frame around the table, frame="box" or not, frame="void". It also possible to have no interal vertical lines, rules="none", a rule separating the first column from the rest of the table, rules="first" or rules separating each of the columns, rules="all". Similarly, it is possible to have no interal horizontal lines, lines="none", a line separating the first row from the rest of the table, lines="first" or lines separating each of the rows, lines="all". Use firstcolwidth to set the width of the first column and othercolwidth to set the width of each of the remaining columns. These settings are used to set the respective pt widths in LaTeX output and are multiplied by 1.25 to set the pixel widths in HTML output. Currently format="em" (emphasis) is the only non-null cell format option. ## Graphs ### image The image environment corresponds to PG's image function and is used to insert a static image: <image width="200" height="200">myimage.png</image>  The width and height parameters are optional and both default to 200. WeBWorK expects to find myimage.png in the same directory as the problem file. [Hint: Use WeBWorK's file manager to upload the graphic file from your own computer to the relevant problem directory.] ### graphic The graphic environment corresponds to PG's plot_functions and graphic and and is used to support the creation of dynamic plots which, for example, vary with the version of the problem. The following, for example: <graphic xrange="-4,4" yrange="-4,4" axes="0,0" grid="0,0" width="400" height="400"> <function color="red" thickness="1" label="-3,A"> sin(1+1.1*cos(x)) </function> <function color="blue" thickness="1" label="-2,B"> cos(1+1.1*cos(x))*(-1.1)*sin(x) </function> <function color="green" thickness="1" label="-1,C"> -sin(1+1.1*cos(x))*1.1*1.1* sin(x)* sin(x)+ cos(1+1.1*cos(x))... </function> </graphic>  produces: The graphic parameters xrange and yrange are required. The other parameters are optional and are shown with their default values. The grid parameter specifies the number of horizontal and vertical gridlines to display. Setting grid="0,0" produces grid lines at each integer value along the horizontal and vertical axes and the default, grid="1,1", produces no gridlines at all. The axes parameter gives the coordinates of the point through which the axes will be drawn. The default when axes is not specified is not to display the coordinate axes. The defaults for width and height produce a thumbnail-sized image in html output which can be clicked to show an enlarged view. These settings have no effect on hardcopy output which is scaled to fit the page width. More than one function element can be specified. The color parameter is required. The label parameter is optional and, if provided, will display name in the same color as the function at the x-coordinate corresponding to pos and at the y-corrdinate corresponding to the value of the function. PG requires that the function must be described using perl and not LaTeX notation, e.g., using x**2 rather than x^2 to denote x raised to the second power. It is also necessary to enter the function on a single line, i.e., with no line breaks. ## Responses ### solution The solution environment corresponds to a PG solution. When show solutions is checked in WebWork, such solutions are gathered and displayed at the end of each question. In LaTeX output for answer keys, the solutions are displayed in boxes where they occur in the question. The optional vspace parameter in solution specifies the vertical space to be left for a student explanation in normal (non answer-key) LaTeX output. The default value is "1in". It has no effect on PG output: <solution vspace="1"> An explanation of the solution to one or more responses goes here. </solution>  ### comment The comment environment corresponds to a PG COMMENT. These are intended for instructors and are displayed in the library browser below the rendered problem: <comment> This is an instructor comment. </comment>  ### hint The hint environment corresponds to a PG HINT. Hints are shown to students after a specified number of attempts which defaults to 1: <hint> This is a hint for students. </hint>  ### Multiple Choice #### choose The choose environment corresponds to a PG new_multiple_choice question. In LaTeX output this gives an itemized list with check boxes listed either vertically or horizontally depending upon the value for display. In PG output this gives a vertical list with radio buttons: <choose display="horizontal"> <choice> first choice </choice> <choice credit="1"> second choice </choice> <choice> third choice </choice> <choice last="1"> none of the above </choice> </choose>  The last attribute for choice is optional and defaults to last="0". Choices for which last="1" will be displayed in the order given at the end of the list of choices. Other choices, if any, will be permuted in the displayed list of choices. At least one choice entry with the attribute credit="1" is required. Full credit will be given for selecting any such entry. Note that a variable can be used to indicate the correct choice, e.g., with <versions> <variables>$a     </variables>
<version>   'first'  </version>
<version>   'second' </version>
<version>   'third'  </version>
</versions>
...
<choose>
<choice> first  </choice>
<choice> second </choice>
<choice> third  </choice>
<choice credit="1"> <v>a</v> </choice>
</choose>


then each choice would be correct for one of the versions. Note that while the correct entry duplicates another choice entry, no duplication will occur in output.

#### select

A PG new_checkbox_multiple_choice is specified by a select environment. This environment is identical to the choose environment save for the fact that radio buttons are replaced by check boxes in PG output and credit requires that all of the correct answers and none of the other answers must be checked.

### Fill in the blank

#### numeric

This provides a fill-in-the-blank mode corresponding to PG's num_cmp answer evaluator:

<numeric> CORRECT ANSWER GOES HERE </numeric>


Usage example:

What is the ratio of the circumference of a circle to its diameter?
<numeric abstol="0.01"> 3.14159 </numeric>


Attributes:

attribute default
mode std
reltol 0.1
abstol 0.001
units xxx
• mode:

strict, frac, arith, or std:

strict: allow only numbers, e.g, 7.23. allow numbers and fractions, e.g., 5/6. allow numbers, fractions and arithmetic expressions, e.g., 2^3. allow numbers, fractions, arithmetic expressions and any expression evaluating to a number, e.g., log(3).
• reltol:

a percentage number between 0 and 100.

The reltol parameter sets a percentage tolerance, i.e., credit is given when:

|studentAnswer - correctAnswer| < |0.01*reltol*correctAnswer|

• abstol:

a fractional number between zero and 1.

The abstol parameter sets an absolute tolerance, i.e., credit is given when:

|studentAnswer - correctAnswer| < |abstol|


If both reltol and abstol are set, then credit is given if either condition is satisfied. If neither is set, then reltol="1" is the default.

• units:

Specify units to be used in evaluating the answer. If, for example, <numeric units="m/min"> 60 </numeric> were specified, then the answers 1 m/s and 86.4 km/day would both be regarded as correct. Supported units include the following:

• TIME

s: seconds miliseconds minutes hours days years
• LENGTHS

m: meters centimeters kilometers millimeters micrometer micrometer nanometer Angstrom
• ENGLISH LENGTHS

in: inch feet mile light years
• VOLUME

L: liter milliliters cubic centermeters
• VELOCITY

knots: nautical miles per hour
• MASS

g: grams kilograms
• ENGLISH MASS

slug: slugs
• FREQUENCY

Hz: Hertz kilo Hertz mega Hertz
• FORCE

N: Newton micro Newton micro Newton dyne pound ton
• ENERGY

J: Joule kilo Joule erg foot pound calorie kilocalorie electron volt kilo Watt hour
• POWER

W: Watt kilo Watt horse power 746 W
• PRESSURE

Pa: Pascal kilo Pascal atmosphere
• ELECTRICAL UNITS (incomplete)

#### formula

This provides a fill-in-the-blank mode corresponding to PG's fun_cmp answer evaluator. A text box for the answer is displayed in in PG and an underlined space in LaTeX output:

<formula> CORRECT ANSWER GOES HERE </formula>


Usage example:

What is the largest root of the quadratic equation <m>ax^2+bx+c=0</m>?
<formula variables="[a,b,c]"> (-b+sqrt(b**2-4*a*c))/(2*a) </formula>


Attributes:

attribute default
variables [x], ... see below
range [0,1], ... see below
points 3
• variables - a list of variable names with the following defaults:

• "[x]": for one variable
• "[x, y]": for two variables
• "[x_1, x_2, x_3, ...]": for three or more variables.
• range - a list of variable ranges with the following defaults:

• range="[0,1]": for one variable
• range="[[0,1],[0,1]]": for two variables and so forth.
• points - the number of points to be sampled

Mathematical expressions (formulas) which contain variables can be entered. Say the correct answer to a formula problem is (x+y)**2 and a student submits x^2+2x*y+y^2. The variables for this problem would be x and y and, since this is the default for two variables, no variables entry would be necessary. Supposing that the defaults for range and points are also used, PG would randomly choose 3 points from the [0,1] range for x, call them x1, x2 and x3, and 3 values from the [0,1] range for y, call them y1, y2 and y3. Then the correct and student answers would be evaluated at the three points (x1, y1), (x2, y2) and (x3, y3) and the results would compared using the defaults for reltol and abstol as described under numeric above.

#### word

This provides a fill-in-the-blank mode corresponding to PG's str_cmp answer evaluator. A text box for the answer is displayed in in PG output and an underlined space in LaTeX output:

<word characters="4"> CORRECT ANSWER GOES HERE </word>


Usage example:

A game of incomplete information in which the informed player moves
first is called a <word characters="12"> signalling </word> game.


Attributes:

attribute default
characters 4

The answer evaluator first removes whitespace from the beginning and end of the answer provided, then treats one or more whitespaces within answer as a single space character and finally ignores the case of letters in comparing the answer given by the student to correct answer. The characters parameter sets the length in characters of the space provided for the answer.