[Home] [MBL Reference] [SMPL Reference]

Mathe:Buddy Language (MBL)

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:

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.

Hello, world!

The following lines define a trivial level page:

My first level
###############

Welcome to mathe:buddy!

Typography

This section describes the text structuring and text formatting features.

Equations

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.

Figures

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).

Itemizations and Enumerations

Note: Hierarchical itemizations are not supported for didactical reasons, as well as a mobile friendly presentation.

Tables

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

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.

Course Structure

Large courses need to be structured into multiple files. We use the following terms in the subsequent sections:

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.

Level Index Files (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 ....

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 Description File (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