Asciidoctor Moodle-Question

Asciidoctor Moodle-Question is a set of Asciidoctor extensions that allows you to add questions as multiple choice and gap text and convert them to Moodle XML format. The questions are defined using plain text in your AsciiDoc document.

Installation and Update

There are two options to install Asciidoctor Question. The first is to use gem install on the command line:

$ gem install asciidoctor-moodle --pre

The second is to add the following entry to your project’s Gemfile.

Gemfile

gem 'asciidoctor-moodle', '~> 1.0.0.dev'

and execute bundle in the command line.

$ bundle

To update asciidoctor-moodle type

$ gem update asciidoctor-moodle

Generating a Question Document from a Terminal

You can load Asciidoctor question in a terminal using the -r (require) and -b (backend) flags.

asciidoctor -r asciidoctor-moodle -b moodle sample.adoc

Creating a Question

Tip	The next documentation is more readable on https://asciidoc.univ-nantes.io/

A question is written inside a literal block, which needs at least two attributes.

Anatomy of a question

[question, question-type] // (1) (2)
....                      // (3)
Question in appropriate syntax
....

The first positional attribute in the attribute list specifies that this block is a question.
The second positional attribute defines the type of this question (mc or gap)
Place the attribute list directly on top of the delimited literal block (....). You can also use an example (====) or open block (--) as an alternative.

The following question types are available:

I used HTML <p> to format the output in Moodle to fit the tabular’s case.

Table 1. Resume
Question type	Input	Output
mc	`[question, mc] .... Which of these are capitals ? - [X] Romes - [ ] Sydney - [X] Paris ....`
gap	`[question, gap] .... <p> If debugging is the process of removing </p> <p> software bugs, then programming must be </p> <p> the process of __putting them in__. </p> - Edsger Dijkstra ....`
tf	`[question, TF, True] .... <p> Donald Knuth said : </p> <p> "Premature optimization is the root of all evil." </p> ....`
matching	`[question, matching, wrote the first computer programme in the world, decrypted Enigma Machine's messages, invented the merge sort algorithm] .... Match each author with his contribution ? - Ada Lovelace : - Alan Turing : ....`
cmc	`[question, CMC, Merge sort algorithm, Bombe] ==== John von Neumann's invented * Merge sort algorithm * Quicksort algorithm * ShellSort algorithm <p> Enigma's message machine was decrypted by </p> - Bombe - Decryptma - Decrypte's machine ====`
ordering	`[question, ordering] .... Arrange the layers with the deepest at the bottom: * VM * OS * Material ....`
ddt	`[question, ddt] .... “Computers are good at following instructions, but not at reading your mind.” – Donald Knuth, the “father of analysis of algorithms” ....`
short	`[question, short, Paris, case=case] .... What city is the capital of France ? ....`
num	`[question, num, unit="cm=1,dm=0.1",tolerance=1, ans=4] ==== 2cm + 2cm = ====`
mw	`[question, mw] .... “Computers are good at following instructions, but not at reading your mind.” – Donald Knuth, the “father of analysis of algorithms” ....`

Details format

MC (multiple choice question) :

[question, mc|MC, shuffle=shuffle] //Used of the named attributes.

[question, mc|MC, shuffle] //Or just set the third attribute.

If you want the answers to be shuffle for each try. You can either use 'MC' or 'mc'.

- [X] correct1
- [*] correct2
- [ ] false

You can either tick the correct(s) answer(s) with X or *.

The question is on 1 point, the point you receive for a good answer is 1/nbCorrectAnswersPossibles.

Warning

You need space bewteen [ ] if it’s false.

Gap (gap fill question)

You gap your text with :

The gap is __here__

You gain 1 point for each gap correctly fill.

TF (true or false question)

You can only write one question by question’s block. One point for each question’s block.

Good Bad

Good	Bad
`[question, TF, true] .... Question to which correct answer is true .... [question, TF, false] .... Question to which correct answer is false ....`	`[question, TF, true, false] .... Question to which correct answer is true Question to which correct answer is false ....`

[question, TF, true]
....
Question to which correct answer is true
....

[question, TF, false]
....
Question to which correct answer is false
....

[question, TF, true, false]
....
Question to which correct answer is true

Question to which correct answer is false
....

Matching (matching question)

The matching question is based on a pool of questions/text and a pool of answers.

The pool of answers is shared by all the questions/text.

Each questions is linked to a correct answer.

It’s represented as a dropdown menu in-line in the text.

[question, matching, Answer1, Answer2, Answer3]
....
General text need.

- Sentence1 :

- Sentence2 :
....

In this exemple the first sentence (Sentence1) match the first argument (Answer1) after 'matching'.

The second second sentence (Sentence2) match the second argument (Answer2) after 'matching'.

Answer3 isn’t linked to any sentence but it will still be part of the pool of possible answers.

Tip	You can use either * or - for listing the sentences.

Warning

Depending on your Moodle’s version you will need at least 2 questions and 3 answers or one answer for each question if there is more than 2 questions, to be imported correctly.

CMC (cloze mutliple choice)

Unlike matching questions, each CMC question has it own pool of answers.

Each questions is linked to a correct answer.

It’s represented as a dropdown menu in-line in the text.

You can use either a delimiter or a block list format to write the possible answers.

List Delimiter

List	Delimiter
`[question, CMC, Correct1, Correct2] ==== Question 1 * False1 * AlsoFalse1 * Correct1 Question 2 - Correct2 - False2 - AlsoFalse2 ====`	`[question, CMC, Correct1, Correct2] ==== Question 1 ---- * False1 * AlsoFalse1 * Correct1 ---- Question 2 ---- - Correct2 - False2 - AlsoFalse2 ---- ====`

[question, CMC, Correct1, Correct2]
====

Question 1

* False1
* AlsoFalse1
* Correct1

Question 2

- Correct2
- False2
- AlsoFalse2

====

[question, CMC, Correct1, Correct2]
====

Question 1

----
* False1
* AlsoFalse1
* Correct1
----
Question 2

----
- Correct2
- False2
- AlsoFalse2
----
====

Tip	You can use either * or - to enumerate the answers, whether you are using a List or a delimiter.

Warning

For delimiter of a list you can only use ---- or ====, — won’t work.

Warning

If you don’t have a correct answer for each question, Moodle won’t accept your file.

Ordering

You need to list the items in the same order as the correct answer. Moodle will shuffle them.

Tip	You can use either * or - for listing the sentences.

Warning

Depending on your version of Moodle, you will need at least 2 or 3 items in the list for it to be imported correctly.

DDT (drag and drop into text) and MW (missing Words)

Simply enclose the portion of the text you with to label with asterisks (*).

You can’t have more draggable texts (possible answers) than gaps.

Warning

The text you enclose needs to be on the same line to be imported correctly.

Good Bad

Good	Bad
`[question, ddt] .... “Computers are good at following instructions, but not at reading your mind.” – Donald Knuth, the “father of analysis of algorithms” ....`	`[question, ddt] .... “Computers are good at following instructions, but not atreading your* mind.” – Donald Knuth, the “father of analysis of algorithms” ....`

[question, ddt]
....
“Computers are good at *following instructions*,
but not at *reading your mind*.”
– Donald Knuth, the “father of analysis of algorithms”
....

[question, ddt]
....
“Computers are good at *following
instructions,* but not at*reading *your* mind.”
– Donald Knuth, the “father of analysis of algorithms”
....

Short (answer)

You can either tag with "Short" or "short".

Num (Numerical)

You can either tag with "num" or "Num".

If the tolerance is 1 and the answer is 4, then [3, 5] is an interval for a possible answer.

If a student writes the correct answer without the correct unit, they will lose half of the marks.

Warning

Use coma (,) to separate units, and the dot (.) for decimal.