# How to create the TeX source¶

## Creating the File¶

Since these exercises are based on applets, we must use the type `japs.problem.applet`

as document class:

```
\documentclass{japs.problem.applet}
```

Then follows the declaration of the required meta information:```
\begin{metainfo}
\name{My Exercise}
\begin{description}
a multiple choice problem
\end{description}
\copyrightinfo{(c) by me}
\status{pre}
\begin{components}
\component{applet}{<Reference to problem applet>}{applet}
\end{components}
\corrector{<Reference to problem corrector>}
\generic{<Reference to generic document>}
\begin{changelog}
13.02.2009 initial
\end{changelog}
\end{metainfo}
```

The default applet and corrector names are:

- MCDefaultProblemApplet
- MCDefaultProblemCorrector

The reference must point to a meta XML file inside the content tree of the Mumie installation.

Now comes the `execute`

environment for the applet:

```
\begin{execute}
\begin{applet}[<Width>][<Height>]{applet}
\param{embeddingMode}{applet}
\end{applet}
\end{execute}
```

The applet's width and height must be at least equal to the required content's size in order to prevent scrollbars inside the applet.

The problem's "real" content is defined in a `content`

environment, its title can be set via the `title`

command. The `hidden`

environment for the following content is required because nothing of the problem's data should be directly visible in the document:

```
\begin{content}
\title{My Exercise}
\begin{hidden}
... % <-- here comes the content!
\end{hidden}
\end{content}
```

**Note:** All following data declarations must be defined inside the hidden environment; their order inside the questions or even the whole problem is not important.

## Adding Questions¶

A question is defined through its data below a `common/problem/question_X`

path. Its *answer type* is set with a `type`

element, which may be `unique`

, `multiple`

or `yesno`

:

```
\data{common/problem/question_1/type}{multiple}
```

The question's task is set via the `task`

element, which may contain TeX texts along with *variables* for displaying values inside the text:

```
\data{common/problem/question_1/task}{Select the equivalent(s): \$f\$=}
```

The question's calculations are based on a specific *number field* which is `real`

per default but also may be `integer`

, `rational`

, `complex`

or `complex-rational`

. The number field is declared in a `field`

element. We choose the real numbers, which are also the default, so the following declaration could be omitted:

```
\data{common/problem/question_1/field}{real}
```

The rendering precision can be changed via the `precision`

element; its values must be whole numbers. We choose a precision of 2, which is also the default, so the following declaration could be omitted:

```
\data{common/problem/question_1/precision}{2}
```

## Defining Variables¶

We already used a variable called *f* but did not declare it yet. Variables are referenced in texts using a "%%$...$%%" statement with their identifier as content. Note that the "%%$%%" character must be quoted outside a mathematical environment in TeX! Their mathematical content is defined below a `vars`

path inside a question (or even answer, see below). Their name is bound to their path. We distinguish two types of variables: *functions* and *numbers*.

A function's content is defined inside a `content`

element and contains an algebraic expression containing other variables or constants. This expression can be written in or outside a mathematical environment, which affects the data format in the further processing (math mode uses MathML). Since the syntax without math mode is easier to write, we have:

```
\data{common/problem/question_1/vars/f/content}{a|_.b*a|_.c}
\data{common/problem/question_1/vars/f1/content}{a|_.(b+c)}
\data{common/problem/question_1/vars/f2/content}{a|_.(b*c)}
```

It executes an *action* for the variables it contains. The default is `replace`

which substitutes every contained variable with its value. Another possibility is the `calculate`

action which substitutes the variables and calculates the expression. The calculation will give a *number* if every variable can be substituted and reduced to a number. We choose the `replace`

action, which is also the default, so the following declaration could be omitted:

```
\data{common/problem/question_1/vars/f/action}{replace}
```

In general every leave in such an *operation tree* must be a (random) number. Unlike functions, they must always be declared inside a mathematical environment must not reside in a `content`

element. Nevertheless numbers could also be treated as constant functions and may be defined therefore outside a mathematical environment (see variable *y*):

```
\[
\data{common/problem/question_1/vars/a}{\ppdrandint{user/problem/question_1/vars/a}{2}{9}}
\data{common/problem/question_1/vars/b}{\ppdrandint[Z]{user/problem/question_1/vars/b}{-5}{5}}
\data{common/problem/question_1/vars/c}{\ppdrandint{user/problem/question_1/vars/c}{3}{5}}
\data{common/problem/question_1/vars/x/content}{2}
\]
\data{common/problem/question_1/vars/y/content}{2}
```

This creates the variables

*a*,

*b*and

*c*inside the intervals [2,9], [-5,5]/{0}, [3,5] and the constants

*x*and

*y*with the value 2. Other types of random numbers can be used, but observe that the question's number field must be changed if the two number fields are incompatible (e.g. a complex number inside a real calculation):

- whole numbers:
`\ppdrandint[zero]{path}{min}{max}`

- real numbers:
`\ppdrandreal[zero]{path}{min}{max}`

- rational numbers:
`\ppdrandrat[zero]{path}{num_min}{num_max}{den_min}{den_max}`

Rational numbers are the only who have two entries to be defined (numerator and denominator). The`zero`

flag indicates that the resulting number may be equal to zero (value`z`

) or that it must be different to zero (value`Z`

). The expression`[z]`

is the default and can be omitted.

As we saw, variables can be defined for questions which we call *global variable*. But it is also possible to define them only for an answer, which we call then *local variable*. Observe that local variables overwrite global ones and that global variables may contain local ones.

## Adding Answers¶

An answer is defined with data below a `common/problem/question_X/choice_Y`

path. The text is set with an `assertion`

element:

```
\data{common/problem/question_1/choice_1/assertion}{\$f1\$}
\data{common/problem/question_1/choice_2/assertion}{\$f2\$}
\data{common/problem/question_1/choice_3/assertion}{None of the answers above.}
```

The correct solution is set by the

`solution`

element. Its values may be `true`

, `false`

and `compute`

. The later stands for an automaticaly evaluated solution defined by a *relation*. We use this type for a correction that tests two variables of equality:

```
\data{common/problem/question_1/choice_1/solution}{compute}
\data{common/problem/question_1/choice_1/correction/relation/left_side/content}{f}
\data{common/problem/question_1/choice_1/correction/relation/sign}{=}
\data{common/problem/question_1/choice_1/correction/relation/right_side/content}{f1}
\data{common/problem/question_1/choice_2/solution}{compute}
[...] % same as for choice 1
\data{common/problem/question_1/choice_3/solution}{false}
```

Note that all variables must exist in order to solve the relation. On fixed solutions, the relation is useless.

Finally we set an explanation for an incorrect solution:

```
\data{common/problem/question_1/choice_1/explanation}{Note that ...}
```