XML-LaTeX Authoring for WeBWorK Problems

Version:	50
Date:	Thu Aug 28 10:58:26 2008 -0400
Author:	Daniel Graham <daniel.graham@duke.edu>

Contents

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 `<m></m>` are used for in-line math expressions such as `<m>\alpha^2</m>`
display:	The delimiters `<mm></mm>` are used for display equations such as `<mm>F(b)-F(a) = \in_a^b f(x) dx</mm>`

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 < be used instead of <, > instead of > and & instead of &.

Other markup

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:	`<bold>string</bold>` => Displays `string` in bold font.
braces:	`<braces>a,b,c</braces>` => `\{a,b,c\}` in LaTeX math expressions and `{a,b,c}` otherwise.
center:	`<center>line</center>` => Displays `line` centered between the margins.
dollars:	`<dollars>5</dollars>` => `$5` in HTML and `\$5` in LaTeX.
em:	`<em>word</em>` => Displays `word` in emphasis font (usually italic).
italic:	`<italic>word</italic>` => Displays `word` in italic font.
p:	`<p>This is a paragraph.</p>` => `<p>This is a paragraph.</p>` in HTML and `\par This is a paragraph.\par` in LaTeX.
percent:	`<percent>5</percent>` => `5%` in HTML and `5\%` in LaTeX.
quote:	`<quote/>` => ~~', i.e., an escaped single quote.
quotes:	`<quotes>hello</quotes>` => Wraps "hello" in appropriate double quotes.
space:	`<space/>` => ` ` in HTML and `{ }` in LaTeX. [Used in empty table cells.]
underscore:	`<underscore/>` => `_` 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`.
frac:	allow numbers and fractions, e.g., `5/6`.
arith:	allow numbers, fractions and arithmetic expressions, e.g., `2^3`.
std:	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
  
  ms: miliseconds
  
  min: minutes
  
  hr: hours
  
  day: days
  
  yr: years
- LENGTHS
  
  m: meters
  
  cm: centimeters
  
  km: kilometers
  
  mm: millimeters
  
  micron: micrometer
  
  um: micrometer
  
  nm: nanometer
  
  A: Angstrom
- ENGLISH LENGTHS
  
  in: inch
  
  ft: feet
  
  mi: mile
  
  light-year: light years
- VOLUME
  
  L: liter
  
  ml: milliliters
  
  cc: cubic centermeters
- VELOCITY
  
  knots: nautical miles per hour
- MASS
  
  g: grams
  
  kg: kilograms
- ENGLISH MASS
  
  slug: slugs
- FREQUENCY
  
  Hz: Hertz
  
  kHz: kilo Hertz
  
  MHz: mega Hertz
- FORCE
  
  N: Newton
  
  microN: micro Newton
  
  uN: micro Newton
  
  dyne: dyne
  
  lb: pound
  
  ton: ton
- ENERGY
  
  J: Joule
  
  kJ: kilo Joule
  
  erg: erg
  
  lbf: foot pound
  
  cal: calorie
  
  kcal: kilocalorie
  
  eV: electron volt
  
  kWh: kilo Watt hour
- POWER
  
  W: Watt
  
  kW: kilo Watt
  
  hp: horse power 746 W
- PRESSURE
  
  Pa: Pascal
  
  kPa: kilo Pascal
  
  atm: atmosphere
- ELECTRICAL UNITS (incomplete)
  
  C: Coulomb
  
  V: volt
  
  mV: milivolt
  
  kV: kilovolt
  
  MV: megavolt
  
  F: Farad
  
  mF: miliFarad
  
  uF: microFarad
  
  ohm: ohm
  
  kohm: kilo-ohm

s:	seconds
ms:	miliseconds
min:	minutes
hr:	hours
day:	days
yr:	years

m:	meters
cm:	centimeters
km:	kilometers
mm:	millimeters
micron:	micrometer
um:	micrometer
nm:	nanometer
A:	Angstrom

in:	inch
ft:	feet
mi:	mile
light-year:	light years

L:	liter
ml:	milliliters
cc:	cubic centermeters

knots:	nautical miles per hour

g:	grams
kg:	kilograms

slug:	slugs

Hz:	Hertz
kHz:	kilo Hertz
MHz:	mega Hertz

N:	Newton
microN:	micro Newton
uN:	micro Newton
dyne:	dyne
lb:	pound
ton:	ton

J:	Joule
kJ:	kilo Joule
erg:	erg
lbf:	foot pound
cal:	calorie
kcal:	kilocalorie
eV:	electron volt
kWh:	kilo Watt hour

W:	Watt
kW:	kilo Watt
hp:	horse power 746 W

Pa:	Pascal
kPa:	kilo Pascal
atm:	atmosphere

C:	Coulomb
V:	volt
mV:	milivolt
kV:	kilovolt
MV:	megavolt
F:	Farad
mF:	miliFarad
uF:	microFarad
ohm:	ohm
kohm:	kilo-ohm

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

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

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.