2023-11-09
WARNING: THE DOCUMENTATION IS NOT UP TO DATE. WE WILL PROVIDE AN UPDATE SOON.
This document describes the syntax of the mathe:buddy language (MBL), which can be used to create mathematical based online courses. MBL describes contents as well as randomized training exercises. It is also used to structure large courses with many levels and keeps track of the contents dependencies. Tags can be inserted to transform the definition into a semantical network. The latter can be used for example in chat bots or didactical learning concepts; e.g. smart repetition for optimized memoization.
Some concepts of MBL are taken (or copied) from other formal languages:
Markdown
, as it
provides a very expressive and memorable syntax.TeX
is used for equations, as most mathematical staff
at universities is firm to that language.SMPL
, which is developed in parallel to
MBL
, is a general purpose language with focus on expressive
math. It is used to generate random variables in exercises, as well as
to calculate sample solutions.The language definition of MBL is independent of concrete implementations. All concepts can be transferred to other learning management systems. The example implementation can be found here.
A large set of examples can be obtained from https://github.com/mathebuddy/mathebuddy-public-courses.
The following lines define a trivial level page:
My first level
###############
Welcome to mathe:buddy!
This section describes the text structuring and text formatting features.
Level Title
A level title is the main heading of a level file. Example:
My Course Title @myLabel ###############
Four or more hashtags (#
) are required. Labels are
optional.
Sections
A level can be separated into sections (headlines). Example:
My Section @sec:myLabel ==========
Four or more equal signs (=
) are required. Labels are
optional. We suggest to use prefix sec:
for section labels,
but this is optional.
Subsections
A section can be subdivided into one or multiple subsections. Example:
My Subsection @subsec:myLabel -------------
Four or more dashes (-
) are required. Labels are
optional. We suggest to use prefix subsec:
for subsection
labels, but this is optional.
Paragraphs
A paragraph consists of one or multiple lines of continuous text. Example:
This is text within a paragraph.
Even this text stands in a new line,
it will be visible directly behind the last line.
An empty line starts a new paragraph.
Bold, Italic and Colored Text
Basic text formatting options are bold text, italic text and colored
text. Bold text is embedded into a pair of double-asterisks
(**
). Italic text is embedded into a pair of
single-asterisks (*
). Colored text is embedded
into brackets and postposed by the color name
([...]@colorN
).
Examples:
Some **bold** text. Some *italic* text.
The word [sky]@color1 is written in primary color.
[Some text written in the secondary color.]@color2. You can also write [bold text]@bold and [italic text]@italic similar to color notation.
Colors are only defined implicitly by a number. The exact rendering
depends on the runtime environment, including the currently active color
profile. We restricted the degree of freedom per design to force
uniformly presented courses. color0
defines black color in
all cases.
Definitions, Theorems, Lemmas, ...
Definitions, Theorems etc. are embedded into a block. All lines that belong to a block are indented to the right by a tabulator, or four spaces respectively.
Examples:
DEFINITION Positive @def:positive
$n$, $n$ is **positive** if $n>0$. For any integer
THEOREM The Aristotelian Syllogism @thm:socrates
If every man is mortal and Socrates is a man, then Socrates is mortal.
The runtime environment may replace tag names
(e.g. THEOREM
) with corresponding terms of the local
language.
The complete list of supported tags is DEFINITION
,
THEOREM
, LEMMA
, COROLLARY
,
PROPOSITION
, CONJECTURE
, AXIOM
,
CLAIM
, IDENTITY
,
PARADOX
.
Examples
Examples are embedded into a block. All lines that belong to a block are indented to the right by a tabulator, or four spaces respectively.
EXAMPLE Addition of complex numbers @ex:myExample
$z_1=1+3i ~~ z_2=2+4i ~~ z_1+z_2=3+7i$
Full line equations can be inserted as described in subsection “nesting of blocks below. Example:
EXAMPLE Addition of complex numbers @ex:myExample
EQUATION
z_1=1+3i ~~ z_2=2+4i ~~ z_1+z_2=3+7i
Alignment
The default alignment of paragraphs is left. Block types
LEFT
, CENTER
and RIGHT
change the
alignment.
Example:
CENTER
This text is centered.
Links and References
Each section, subsection, equation, exercise, … can be labeled at
declaration. A label has the form @PREFIX:LABEL
, with
identifiers for PREFIX
and LABEL
. Using
prefixes is optional.
A link to a labeled object can be placed in paragraph text. One has
to write @PREFIX:LABEL
again.
The order of declaration and reference is arbitrary.
Example:
An introduction is given in @sec:intro.
Intro @sec:intro =====
We suggest to use the following prefixes:
prefix | used for |
---|---|
sec: |
sections |
subsec: |
subsections |
ex: |
exercises |
fig: |
figures |
eq: |
equation |
tab: |
table |
def: |
definition |
thm: |
theorem |
References to other files should be avoided, if destination levels are possibly unplayable/locked (read section course structure).
A link to a labeled object in another file is denoted by
@PATH/PREFIX:LABEL
, where PATH
is the relative
file path within the current course, without file extension
(.mbl
). Example: To link to theorem
thm:taylor
in file ../diff/taylor.mbl
, write
@../diff/intro/thm:taylor
.
It is also feasible to insert generic references with the asterisk
operator (*
). For example, @ex:taylor*
links
to the set of all exercises that have a label starting with
ex:taylor
(e.g. ex:taylor-simple
,
ex:taylor2
, …). The runtime environment inserts comma
separated links.
Comments
All characters after %
are ignored by the compiler,
until the current line ends.
Comments can e.g. be used to make notes to other developers, or temporarily hide unfinished stuff. Example:
This text is displayed in the output. % only a course developer can read this text.
Page Breaks
A level can be scrolled vertically by the student. Doom-scrolling
should be avoided (not only) for didactical reasons. Page breaks can be
inserted by a NEWPAGE
-block. Example:
TODO!!!!!
NEWPAGE
Nesting of blocks:
In general, format blocks are used in a sequence, i.e. a new block starts after the last block ended.
In some cases, a nesting of blocks is needed. The following example
uses text alignment and an equation within a
DEFINITION
:
DEFINITION My definition @def:myDef
Some paragraph text here.CENTER
This text is center aligned.EQUATION @myEquation
x^2 + y^2 = z^2 Another paragraph here.
Inner blocks are created by further indentation.
Warning: Attributes (for example
@options
in exercises) refer to the innermost declared
subblock. To explicitly end a subblock, use the END
keyword. Example:
---EXERCISE Test
FIGURE
@path
img/my-figure.svg
END
@text % The following lines belong to 'EXERCISE'
(x) correct answer ( ) incorrect answer
We distinguish two kinds of equations: inline equations are embedded into a text of a paragraph. Full equations are rendered in one or more separate lines. The latter are numbered by default.
Equations are encoded in TeX
notation.
Inline Equations
An inline equation is embedded into a pair of dollar signs. Example:
$E=mc^2$. It defines the energy $E$ of ... Einstein's famous formula is
Full Equations
(equations in display math mode)
Full equations are embedded into a block with keyword
EQUATION
. Example:
EQUATION @eq:myLabel
a^2 + b^2 = c^2
The label is optional.
A numbering is displayed right to the equation per default. An
asterisk *
hides the numbering. Example:
EQUATION* @eq:myLabel
a^2 + b^2 = c^2
Equations can be labeled with @
. For example,
@eq:myLabel
is displayed \(Eq~(1)\) (depends on the runtime
environment).
Aligned equations improve readability. For example you may stack equal signs vertically.
Each row must contains an ampersand character (&
)
for the alignment, and must end with a line feed \\
.
Example:
ALIGNED-EQUATION
(x+1)^2 &= (x+1)(x+1) \\
&= x^2 + x + x + 1 \\ &= x^2 + 2x + 1 \\
Remarks: The last linefeed via \\
is optional. The
spacing before &
is optional, but highly suggested to
improve readability.
Abbreviations
Equations are written in plain TeX
code. In some cases,
the notation is rather long. We introduce some abbreviations for a
shorter notation. The following table lists all implemented
abbreviations:
type | plain tex | short notation | |
---|---|---|---|
\(\mathbb{R}\) | \mathbb{R} |
\RR |
|
\(\mathbb{N}\) | \mathbb{N} |
\NN |
|
\(\mathbb{Z}\) | \mathbb{Z} |
\ZZ |
|
\(\mathbb{C}\) | \mathbb{C} |
\CC |
Using abbreviations is optional.
SMPL provides syntax to plot function graphs.
All other figures must be generated with external tools. We highly
recommend to generate files in the SVG
(Scalable Vector
Graphics) format using Inkscape).
Figures
A figure displays an image file. It is highly recommended to use
*.svg
as file format (scalable vector graphics).
Example:
FIGURE My figure title @fig:myFigure
WIDTH=75
PATH=images/myImage.svg
Attribute width-P
specifies the displayed width with a
percentage value for P
. E.g. width-75
renders
the figure with 75 % of the display width. Default is
width-100
.
Function Plots
Functions graphs are described in a block with keyword
FIGURE
.
Example:
FIGURE My Plot @fig:functions
WIDTH=75
CODE
let f(x) = x^2
let g(x) = 2*x
figure {
x_axis(-5, 5, "x") % x-min, y-max, label
y_axis(-0.5, 4.5, "y")
function(f)
function(g)
circle(0, 0, 0.1) % x, y, radius
circle(2, 4, 0.1)
}CAPTION
$f$ and $g$ Some functions
Part @code
defines two functions \(f(x)\) anf \(g(x)\). Function figures2d()
generates a new plot variable.
Itemize
An itemization lists a set of bullet points. Example:
My itemization:
- first item
- second item - third item
A line that starts with a dash (-
) is rendered as bullet
point.
Enumeration (numbers)
Enumerations list a sequence of numbered items. Example:
My enumeration:
#. first item
#. second item #. third item
A line that starts with a hashtag following a dot (#.
)
is rendered with numbering (1, 2, …).
Enumeration (letters)
Alphabetical enumerations list a sequence of items. Example:
My enumeration:
-) first item
-) second item -) third item
A line that starts with a dash following a closing parenthesis
(-)
) is rendered with preceding letters a)
,
b)
, … .
Note: Hierarchical itemizations are not supported for didactical reasons, as well as a mobile friendly presentation.
A table is described by a block with keyword
TABLE
. Each row of the table is written without line break.
Columns are separated by &
. The first row is considered
as headline.
Example:
TABLE My table title @tab:label
ALIGN=left
$x$ & $f(x)$
1 & 1
2 & 4 3 & 9
The alignment option align-X
specifies the placing of
the table. Parameter X
is one of left
,
center
, right
. Default is
align-center
.
Exercises provide interactive elements to the course. For example, multiple choice questions display multiple answers, from which students have to select all correct ones to gather scores.
Most exercises contain a @code
part to generate
randomized variables and to calculate the sample solution. It is denoted
in the Simple Math Programming Language (SMPL). The
documentation can be found here.
The following paragraphs describe all implemented exercise types.
Calculation Exercises
This type of exercise asks students to solve a question with one or more numeric solutions. Solutions can be scalars, vectors, matrices or sets.
EXERCISE My exercise @ex:myLabel
CODE
let x/y = rand(1, 5)
let z = x + y
let A/B = rand<2,3>(-5,5)
let C = A + B$ x+y= $ #z
Calculate $ A+B= $ #C Calculate
Note: let x/y = rand(1, 5)
is an abbreviation for
let x = rand(1, 5); let y = rand(1, 5);
with guarantee that
\(x \neq y\)
Part @code
draws random variables and generates the
sample solution.
Part @texts
describes the question text. Typography,
itemizations, equations, etc. can be included, as described above. Input
fields are generated for patterns #V
, where V
is a valid variable from part @code
. Take care, that input
fields are not inserted within equations.
Variables in math mode (inline equations embedded into dollar signs)
are substituted by values of code variables by default. In the example
above, \(x\) is e.g. shown as \(3\) (depending on the present value for
\(x\)). If the variable identifiers
should be rendered instead, the concerned variable name must written in
quotes, e.g. $ "x" + "y" $
(spacing is optional).
Input Types:
integers and real numbers
Without any options, an input field is generated for each input with
#V
, for a variable V
from part
@code
. The student has to type in the answer on a numeric
keyboard.
If option choices-X
is given, a set of X
possible answers is shown. Only one these answers is a correct one. All
other answers are incorrect. The student has to select the correct
solution to gather scoring.
Example:
EXERCISE Multiplication
CHOICES=4
CODE
let x/y = rand(10,20)
let z = x * y$x * y=$ #z Calculate
complex numbers
Per default, two input fields of the form [ ] + [ ]i
are shown to enter the solution in normal form.
If the option polar-form
is given, then the student as
to enter the solution in polar form.
Option choices-X
renders X
buttons, where
one of them shows the correct solution (refer to exercise type
integers and real numbers
).
Example:
EXERCISE Complex addition
CODE
let x/y = complex(rand(10,20), rand(10,20))
let z = x + y$x + y=$ #polar(z) Calculate
sets
Per default, if the set has length \(n\), then \(n\) input fields are shown to enter the solution from a numeric keyboard.
If option n-args
is given, students must figure out the
number of solution fields on their own.
Option choices-X
renders X
buttons, where
one of them shows the correct solution (refer to exercise type
integers and real numbers
).
Example:
EXERCISE Linear Equations
FLEX_ELEMENTS=true
CODE
let s = {-2, 2}$x^2 - 4 = 0$.
Solve $x=$ #s
matrices
Per default, an input matrix is shown with a text field for each element of the solution matrix.
If option n-rows
is given, students must figure out the
number of solution rows on their own.
If option n-cols
is given, students must figure out the
number of solution columns on their own.
Option choices-X
renders X
buttons, where
one of them shows the correct solution (refer to exercise type
integers and real numbers
).
Example:
EXERCISE Matrix Operations
FLEX_ROWS=true
FLEX_COLS=true
CODE
let A/B/C = rand<3,3>(0, 5) % 3x3-matrices
let D = A*B + C$A*B + C=$ #D Calculate
vectors
Exercises with vector solutions are technically matrix exercises with the number of rows, or columns respectively, set to one.
terms
EXERCISE Simple Integration @ex:intSimple
CODE
let F(x) = (1/3) x^3 + 7x$\int (x^2+7) dx = #build_term(F),score=2 +C$ Solve
Without any option, the student is required to enter
1/3*x^3 + 7*x
(or an algebraic equivalent solution) on a
keyboard.
Option term-tokens-X
lists a set of buttons. Each button
represents a part of the solution term. In the example, buttons
[1/3]
, [*]
, [x^3]
,
[+]
, [7]
, [x]
are shown in random
order. The student has to click on the buttons to construct the
solution. Attribute X
represents the overhead factor,
i.e. the number of additional buttons with (most likely) useless
options. The example sets X
to 1,5
. In this
case 9 instead of 6 buttons are shown (e.g. [1/5]
,
[/]
, [x^4]
).
Option forbid-X
does not allow X
in the
solution term. For example forbid-sin
forbids to use the
sinus function. List of supported values for X
(in
alphabetical order): abs
, acos
,
asin
, atan
, cos
,
exp
, log
, sin
, tan
.
For multiple forbiddings, repeat the forbid-X
option with
different identifiers for X
.
Option require-X
forces the student to use
X
in the answer. The set of supported values is equal to
the definition of forbid-X
.
Scoring of answers
Per default, each input field is weighted with 1 score. And the total score per exercise is defined as sum of scores of the input fields.
Example for custom scoring:
EXERCISE Scoring example
SCORES=5 % total score of the exercise (5/3 for fa; 10/3 for fb)
CODE
let a = rand(2,4)
let b = rand(5,8)
let fa = fac(a)
let fb = fac(b)$ a! = $ #fa,score=1 % relative score for solution fa is 1
Calculate $ b! = $ #fb,score=2 % relative score for solution fb is 2 Calculate
Option scores-X
defines that X
is the total
score for the exercise a student can receive at maximum.
Option score-V-X
defines that X
is the
maximum score for solution variable V
.
The sum of all score-V-Xi
must not necessarily
be equal to score-V-X
.
Static Multiple Choice Exercise
Multiple choice exercises list a set of answers, which can be
selected or deselected by the student with checkboxes. Correct answers
are indicated by [x]
. Incorrect answers are indicated by
[ ]
. Example:
EXERCISE My Multiple Choice Exercise @ex:myMultiChoice
ORDER=static
Choose the right answers:
[x] This answer is correct.
[ ] This answer is incorrect. [x] This answer is correct.
Each correct answer is scored with 1 points, each wrong answer is
scored with -1 points. The total score of the exercise can be weighted
with option scores-X
, where X
is the total
score.
Answers are displayed in random order per default. Option
static-order
suppresses random shuffling.
Dynamic Multiple Choice Exercise
Dynamic multiple choice exercises calculate the correctness of answers at runtime. Example:
EXERCISE My dynamic Multiple Choice Exercise
CODE
let x/y/z/w = rand(10, 20) % no pair of x, y, z, w is equal
let c1 = x > w
let c2 = y > w
let c3 = z > w
Choose the correct answer(s):$x > w$
[:c1] $y > w$
[:c2] $z > w$
[:c3] $1 > 0$ % statically true
[x] $1 < 0$ % statically false [ ]
Correctness of an answer is determined by a boolean variable
V
, in the form [:V]
.
You are allowed to mix static and dynamic answers: If variable
x
is a boolean variable, then [:x]
is correct
(incorrect) if \(x\) is true (false).
The notation [x]
indicates that the answer is
always true.
Single Choice Exercise
In single choice exercises, exactly one answer is true. All other answers are wrong. Instead of check boxes, radio buttons are displayed.
EXERCISE My Single Choice Exercise @ex:myMultiChoice
(x) This answer is correct.
( ) This answer is incorrect. ( ) This answer is incorrect.
The definition of single choice exercises is similar to the
definition of multiple choice exercises. We use round parentheses
( )
, instead of brackets [ ]
.
For dynamic single choice exercises, the exercise designer must take care, that no more than one option is correct. In case of more than one correct answers, the behavior is undefined.
Gap Exercise
Gap exercises provide an input field to enter words within fluent paragraph text.
EXERCISE My Gap Exercise @ex:myLabel
SHOW_GAP_LENGTH=true
SHOW_REQUIRED_LETTERS_ONLY=true
Garfield is a #"cat". Rain is #"wet".
Option show-length
hints the number of characters of the
solution word.
Option restricted-keyboard
displays a context-sensitive
keyboard that only shows characters needed for the solution. E.g. for
the first answer cat
from the example, the student only
sees keys [A]
, [C]
and
[T]
.
Arrangement Exercise
Arrangement exercises show a sequence of strings or numbers that must be reordered by the student.
EXERCISE Arrangement exercise
ARRANGE=true
ACCEPT_IMMEDIATELY=true
CODE
let n = rand(5,10) % length
let f = zeros<n>() % vector for the sequence
f[0] = 0
f[1] = 1
for k from 2 to n-1 { % calc sequence iteratively
f[k] = f[k-2] + f[k-1]
} Arrange the following numbers to get the first numbers of the Fibonacci sequence: #f
Note the use of k
for the loop variable. A variable
named i
would be considered as complex number
0+1*i
.
Preface: The answer field #f
would ask the student
to type in the elements of the row vector:
[0, 1, 1, 2, 3, 5, ...]
.
Writing #:order(v)
lists a randomly shuffled form of
vector v
. The student is required to reorder the vector to
finally get vector v
.
The option accept-immediately
accepts the answer
immediately when it is correct. If the option is missing, then the
student needs to submit the solution explicitly.
Timed Exercise
A timed exercise is repeatedly shown. Each instance uses different variables. Quick and correct responses results in a large high score. This question type might test, if students are already trained well to a specific topic.
EXERCISE Timed exercise
TIMER=3
ACCELERATE=true
STOP_AFTER_ERRORS=1
CHOICES=4
CODE
let x:y = rand(20,50)
let z = x + y$ x + y = #z $ Calculate
Option timed-X
enables timing. The student has
X
seconds to give an answer.
Option accelerate
decreases time per question.
Option multi-choice-X
lists X
options per
question.
Option stop-on-error-X
stops asking after X
incorrect answers.
Large courses need to be structured into multiple files. We use the following terms in the subsequent sections:
Course
: an entire course, e.g. “higher math 1”.Chapter
: a logical chapter of a course, e.g. “complex
numbers”.Unit
: a learning unit of a chapter, e.g. “basics of
complex numbers”, “complex functions, sequences and series”.Level
: a basic part of a unit, e.g. “normal form”,
“polar form”, “absolute value”.A course consists of multiple *.mbl
files. The file
hierarchy is /COURSE/CHAPTER/LEVEL_FILE.mbl
. Thus, each
file represents a level of the course. Units are defined in index files
(see below).
Example folder hierarchy for a course higher math 1
(hm1
):
hm1/course.mbl
...
hm1/cmplx/index.mbl
hm1/cmplx/start.mbl
hm1/cmplx/intro.mbl
hm1/cmplx/normal.mbl
hm1/cmplx/conj.mbl
hm1/cmplx/conj-props.mbl
hm1/cmplx/abs.mbl
hm1/cmplx/polar.mbl
...
hm1/diff/index.mbl
hm1/diff/...
...
File course.mbl
contains general meta data for the
course and lists all chapters.
Each chapter directory is organized by an index file, named
index.mbl
. The format of index files is described in the
next section.
index.mbl
)An index file defines meta data for a chapter. It also lists all files and its dependencies.
hm1/cmplx/index.mbl
% a comment line
TITLE
Complex Numbers
AUTHOR
TH Koeln
UNIT Complex Basics
(2,0) start ICON icons/start.svg
(1,0) gauss !start ICON icons/gauss.svg
(3,1) normal !start
(3,2) conj !normal
(4,2) conj-props !conj
(3,3) abs !conj
(2,4) polar !abs
UNIT Complex Functions, Sequences, Series
...
Each chapter consists of a set of units.
Each unit consists of a set of levels. A unit can be represented by a (directed) graph \(G=(V,E)\) with \(V\) the levels and \(E\) the dependencies between levels.
Each level is described by an *.mbl
file. A level is
only playable, if all presuming levels have been passed successfully. At
least one level must have no presuming level.
All Levels of a unit are listed below the UNIT UNIT_NAME
entry. Each level is described in the form:
(X,Y) A !B !C !D ...
.
Coordinates (X,Y)
describe the position of node
\(v \in V(G)\), where
(0,0)
is interpreted as top-left.
File A
is the level.
Files !B
, !C
, … (with
!
-prefix) represent the requirements of A
,
i.e. level A
depends on levels B
,
C
, ….
Requirements for other course chapters can be denoted by relative
paths, e.g. !../basics/sets
requires level
sets.mbl
in chapter basics
.
(Optional) Icons in SVG format can be inserted by keyword
ICON
.
Since all units are stored in the same file directory, prefixes to file names may be helpful.
Example:
...UNIT Complex Basics
(2,0) basics-start
(1,0) basics-gauss !basics-start
(3,1) basics-normal !basics-start
...
UNIT Complex Functions, Sequences, Series
(0,0) fss-start ...
course.mbl
)The course description file course.mbl
is similar
organized to level index files.
It mainly lists all chapters and its dependencies.
Example:
TITLE
A Short Demo Course
AUTHOR
TH Koeln
CHAPTERS
(0,0) basics
(2,0) essentials !basics (1,1) advanced !basics !essentials
Author: Andreas Schwenk, TH Köln