User Guide — excel2moodle 0.3.0 documentation

# User Guide

## Writing questions into the spreadsheet

When writing questions several important things must be considered, as the program still is quite buggy and likely to crash, when unexpected input is reached.

### Question-type agnostic fields

For all of the qustion types the following fields must/may be included in the spreadsheet

> - `number`: mandatory The number of the question

> - `type`: mandatory any of `NFM`, `NF`, `MC`

> - `name`: mandatory the internal name of the question, not the title that will be seen when the question is viewed

> - `text`: mandatory, the question text. At least one this must be filled out. If it occures more than once, a new paragraph gets added for each.

> - `picture`: optional if left empty, no picture will be included

>   > - All pictures have to be in the folder `Abbildungen_SVG/KAT_XX` in the same dir as the spreadsheet

>   > - if a picture should be include, `1` (like true) should be written here.

>   > - If a picture from another Question should be used, write:

>   >   > - `1=ID` where `ID` is the number of the question that the picture should be used from.

### Creating valid questions of Type `NFM`

The following fields must be filled out additionally to the type-agnostic ones:

> - `bulletPoints`: mandatory list of bullet points seperated by `;`, each bullet Points consist of 4 parts:

>   > 1. Name: (Example: length)

>   > 2. Variable Name: (Example l )

>   > 3. `=`-Sign

>   > 4. Variable: (Example {l}): must be one letter enclosed by curly braces

>   > 5. Si-Unit: (Example m)

> - `result`: mandatory formula to calculate the result. Must follow those rules.

>   > - Decimal separator must be a `.` dot.

>   > - Variables must not be encapsulated by `{curly}` braces.

>   > - Example: `3.7*a/(b+4*c)-a**2/4` is a valid formula

> - `tolerance`: mandatory as fraction

> - `unit`: optional, 'not yet implemented'

> - `firstResult`: optional but recommended to verify the formula inside `result` with the equation-checker tool.

## Generating questions from the spreadsheet

To generate the Questions, the spreadsheet must be filled according to the example spreadsheet. If not the creation of the XML-Files will throw some errors.

> 1. Open the excel2moodle Programm by executing `py -m excel2moodle` on the command line (py works on windows, for unix based systems it would be `python` or `python3`)

> 2. Select the spreadsheet by clicking on the `select spreadsheet` button.

Now all Questions are created and should be shown in the Question List, sorted into their categories

## Creating an exam question selection

An exam most often will not include all questions present in the spreadsheet. Therefore only a selection of questions can be made with excel2moodle. The selection can be exported to a single `.xml` file, which then may be uploaded to moodle

Create an exam File:

> 1. click on every questions that should be included in the exam

> 2. check, if the total number of points and questions is as desired

> 3. Configure the export Settings to your liking. Possible is:

>    - Whether or not the questions should be categorized

>    - If for every `NFM` question the same variant should be used

>    - If yes, which variant this should be

> 4. Export the selected questions by clicking on `export selected questions to examfile`

> 5. You will be promted to specify the export location

Now a little overview is shown with the selected questions. If clicking OK those questions will be exported into the file specified at step 3

## Using the extra modules from the `Tools` section

Some functionality is separated from the main use-case, hence it lives outside the core subpackage inside the extra subpackage. Those functionality can be used either via cmd through the `excel2moodle.extra` subpackage and run as scripts, or it is accessible under the `Tools` section via the main window taskbar.

How to use the extra scripts or the tools counterpart is documented in the source-code documentation excel2moodle.extra package

### Available extra functionality

- Equation verification script and UI-tool