Overview

Mathmaker creates elementary maths worksheets with detailed solutions.

The output documents can be compiled into pdf files by lualatex. Examples of available themes are: first degree equations, pythagorean theorem, fractions calculation...

It can run from command line, but can be controlled via http requests too.

License

Documentation (master release)

Documentation (latest development release).

Quickstart

Install

Required (non python) dependencies are python >=3.4, euktoeps >=1.5.4, xmllint, msgfmt, lualatex, luaotfload-tool and a bunch of LaTeX packages(1)

To install them:

  • on Ubuntu, python3.4 is already installed, so:

    $ sudo apt-get install eukleides libxml2-utils gettext texlive-latex-base
    

    And for the yet missing LaTeX packages: you can either install the complete texlive distribution (takes some room on the hard disk): run $ sudo apt-get install texlive-full, or install only the necessary packages:

    $ sudo apt-get install texlive-luatex texlive-latex-recommended texlive-xetex texlive-pstricks texlive-font-utils texlive-latex-extra texlive-base texlive-science texlive-pictures texlive-generic-recommended texlive-fonts-recommended texlive-fonts-extra
    
  • on FreeBSD(2):

    $ sudo pkg install python34 py34-sqlite3 gettext eukleides libxml2 texlive-full
    $ rehash
    

    Note

    Check how to fix eukleides install in the complete documentation

Once you’re done, you can proceed installing mathmaker:

$ pip3 install mathmaker

(this will automatically install three extra python3 libraries too: polib, PyYAML and python-daemon).

Note

FreeBSD users, check how to fix mathmaker install if it stops with an error in python-daemon install, in the complete documentation

Basic use

$ mathmaker pythagorean-theorem-short-test > out.tex
$ lualatex out.tex

or directly:

$ mathmaker pythagorean-theorem-short-test --pdf > out.pdf

Get the list of all provided sheets(3):

$ mathmaker list

Some settings

Check mathmaker --help to see which settings can be changed as command line arguments.

Some more settings can be overriden by user defined values in ~/.config/mathmaker/user_config.yaml. Read the complete documentation for more information.

Advanced use

It’s possible to create your own sheets in xml (only for the mental calculation theme yet). Read the complete documentation for more information.

Contribute

You can contribute to mathmaker:

As a wordings contributor

Mathmaker needs contexts for problems wordings. There are already some, but the more there is, the better. Existing wordings can be found here. You can submit any new idea as an enhancement proposal there (should be written in english, french or german).

Any question can be sent to nh dot techn (hosted at gmail dot com).

As a translator

You can help translating mathmaker to your language (or any language you like, if you have enough elementary maths vocabulary for that).

If the translation to your language isn’t started yet, there are several pot files to get here (see explanations about their respective roles there). You can use an editor like poedit or any other you like better, to create po files from them and start to translate.

If you want to add missing translations, or to correct some, you can find the po files in the subdirectories here.

Once you’re done, you can make a pull request here.

Any question can be sent to nh dot techn (hosted at gmail dot com).

As a developer

Before submitting a PR, please ensure you’ve had a look at the writing rules.

More details can be found in the documentation for developers.

Any question can be sent to nh dot techn (hosted at gmail dot com).

Contributors

Development

  • Lead developer: Nicolas Hainaux
  • Developers: Vaibhav Gupta
  • Clever advices: Olivier Cecillon

Translation

  • French: Nicolas Hainaux

Problems wordings

Nicolas Hainaux

Patience and chocolate cakes

Sophie Reboud

Changelog

New in version 0.7.1dev5 (2017-05-04)

  • Issue warnings instead of exceptions when the version of a dependency could not be determined.

New in version 0.7.1dev4 (2017-05-03)

  • New sheets about trigonometry: - vocabulary in the right triangle - write the correct formulae - calculate a length - calculate an angle

New in version 0.7.1dev3 (2016-10-21)

  • New sheets: - intercept theorem: “butterfly” configuration - intercept theorem: converse

New in version 0.7.1dev2 (2016-10-13)

  • New sheets: - expansion of simple brackets (declined in two versions) - clever multiplications (mental calculation) - intercept theorem: write the correct quotients’ equalities - intercept theorem: solve simple exercises

These sheets and all future sheets will be defined in xml files.

New in version 0.7.1dev1 (2016-09-14)

  • A new sheet (declined in two versions): expansion of double brackets. Defined in an xml sheet as for mental calculation sheets.

New in version 0.7.0-6 (2016-08-19)

  • Added a setting to let the user change mathmaker’s path (to be used by the daemon)

New in version 0.7.0-5 (2016-08-19)

  • Bugfix

New in version 0.7.0-4 (2016-08-19)

  • If an IP address is passed as parameter to mathmaker’s daemon, it will return a 429 http status code (too many requests) if the last request from the same address is not older than 10 seconds.

New in version 0.7.0-3 (2016-07-18)

  • Fixed the install of locale files and font listing file

New in version 0.7 (2016-07-15)

  • Standardized structure (mathmaker becomes pip3-installable, available on PyPI and github; its documentation is hosted on readthedocs; tests are made with py.test)
  • A daemon is added (mathmakerd) to provide communication with mathmaker through http connections.
  • A bunch of mental calculation sheets
  • The use of XML frameworks for the sheets (yet only for mental calculation, so far)

Footnotes:

  1. Complete list of recommended LaTeX packages:
CTAN Package Name Package name (Ubuntu 14.04 )
fontspec texlive-latex-recommended
polyglossia texlive-xetex
geometry texlive-latex-base
graphicx texlive-pstricks
epstopdf texlive-font-utils
tikz texlive-latex-extra
amssymb texlive-base
amsmath texlive-latex-base
siunitx texlive-science
cancel texlive-pictures
array texlive-latex-base
ulem texlive-generic-recommended
textcomp texlive-latex-base
eurosym texlive-fonts-recommended
lxfonts texlive-fonts-extra
multicol texlive-latex-base
  1. Using pkg, you’ll have to install texlive-full; if you wish to install only the relevant LaTeX packages, you’ll have to browse the ports, I haven’t done this yet so cannot tell you exactly which ones are necessary.
  2. Complete list of provided sheets:
Theme Subtheme Directive name
algebra   algebra-balance-01
algebra   algebra-binomial-identities-expansion
algebra   algebra-expression-expansion
algebra   algebra-expression-reduction
algebra   algebra-factorization-01
algebra   algebra-factorization-02
algebra   algebra-factorization-03
algebra   algebra-mini-test-0
algebra   algebra-mini-test-1
algebra   algebra-short-test
algebra   algebra-test-2
algebra equations equations-basic
algebra equations equations-classic
algebra equations equations-harder
algebra equations equations-short-test
algebra equations equations-test
geometry right triangle converse-and-contrapositive-of-pythagorean-theorem-short-test
geometry right triangle pythagorean-theorem-short-test
mental_calculation lev11_1 divisions
mental_calculation lev11_1 mini_problems
mental_calculation lev11_1 multi_11_15_25
mental_calculation lev11_1 multi_decimal
mental_calculation lev11_1 multi_hole_any_nb
mental_calculation lev11_1 multi_hole_tables2_9
mental_calculation lev11_1 multi_reversed
mental_calculation lev11_1 ranks
mental_calculation lev11_1 tables2_9
mental_calculation lev11_1 test_11_1
mental_calculation lev11_2 multi_divi_10_100_1000
mental_calculation lev11_2 operations_vocabulary
mental_calculation lev11_2 polygons_perimeters
mental_calculation lev11_2 rectangles
mental_calculation lev11_2 test_11_2
numeric calculation fractions fraction-simplification
numeric calculation fractions fractions-product-and-quotient
numeric calculation fractions fractions-sum

Advanced features

User settings

The default settings are following:

PATHS:
    EUKTOEPS: euktoeps
    XMLLINT: xmllint
    LUALATEX: lualatex
    LUAOTFLOAD_TOOL: luaotfload-tool
    MSGFMT: msgfmt
    OUTPUT_DIR: ./

LOCALES:
    # Available values can be checked in the locale directory.
    LANGUAGE: en_US
    ENCODING: UTF-8
    # Values can be 'euro', 'sterling', 'dollar'
    CURRENCY: dollar

LATEX:
    FONT:
    ROUND_LETTERS_IN_MATH_EXPR: False

Some explanations:

  • The PATHS: section is here to provide a mean to change the paths to euktoeps, lualatex and xmllint mainly. In case one of them is not reachable the way it is set in this section, you can change that easily.
  • The PATHS: section contains also an OUTPUT_DIR: entry. This is the directory where mathmaker will store the possible picture files (.euk and .eps). Default value is “current directory”. You can set another value, at your liking.
  • The entries under LOCALES: allow to change the language, encoding, and default currency used.
  • The LATEX: section contains an entry to set the font to use (be sure it is available on your system). The ROUND_LETTERS_IN_MATH_EXPR: entry is disabled by default (set to False). If you set it to True, a special font will be used in math expressions, that will turn all letters (especially the ‘x’) into a rounded version. This is actually the lxfonts LaTeX package. It doesn’t fit well with any font. Using “Ubuntu” as font and setting ROUND_LETTERS_IN_MATH_EXPR: to True gives a nice result though.

Your settings file must be ~/.config/mathmaker/user_config.yaml.

Command-line options

Several command-line options correspond to settings that are defined in ~/.config/mathmaker/user_config.yaml. Any option redefined in command-line options will override the setting from the configuration file.

Type mathmaker --help to get information on these command-line options.

http server (mathmakerd)

Once everything is installed, it’s possible to run a server to communicate with mathmaker through a web browser.

Run the server:

$ mathmakerd start

Then go to your web browser and as url, you can enter:

http://127.0.0.1:9999/?sheetname=<sheetname>

and replace <sheetname> by an available sheet’s name (from mathmaker list), for instance:

http://127.0.0.1:9999/?sheetname=pythagorean-theorem-short-test

mathmaker will create the new sheet, compile it and return the pdf result to be displayed in the web browser.

At the moment, mathmakerd stop doesn’t work correctly, you’ll have to kill it directly (ps aux | grep mathmakerd then kill with the appropriate pid).

It’s possible to pass an IP address in an extra parameter named ip, like:

In this case, mathmakerd will check if the last request is older than 10 seconds (this is hardcoded, so far) and if not, then a http status 429 will be returned. In order to do that, mathmakerd uses a small database that it erases when the last request is older than one hour (also hardcoded, so far).

xml sheets

As a directive to mathmaker it is possible to give a path to an xml file.

Creating a new xml file that can be used as a model by mathmaker is more for advanced users, though it’s not that difficult.

At the moment (version 0.7), it’s only possible to create mental calculation sheets this way. So there’s not much to change from a raw model.

Let’s have a look at mathmaker/data/frameworks/mental_calculation/lev11_1/divisions.xml:

<?xml version="1.0" encoding="UTF-8"?>

<sheet header="" title="Mental calculation" subtitle="Divisions" text="" answers_title="Answers">

    <!-- Default values: type="std" unit="cm" font_size_offset="0" -->
    <!-- Available layout types: std|short_test|mini_test|equations|mental -->
    <layout type="mental" font_size_offset="-1">
            <exc>
                    <line nb="None">
                            <exercises>all</exercises>
                    </line>
            </exc>
            <ans>
                    <line nb="None">
                            <exercises>all</exercises>
                    </line>
            </ans>
    </layout>

    <!-- Default value: id='generic'
             No default for kind and subkind, they must be given -->
    <!-- Available kinds for mental calculation: tabular, slideshow -->
    <exercise id="mental_calculation" kind="tabular">

            <!--No default for kind and subkind, they must be given -->
            <question kind="divi" subkind="direct">
                    <nb source="intpairs_2to9">20</nb>
            </question>

    </exercise>

</sheet>

The <sheet> tag has attributes that let you easily change the title of the sheet, a subtitle etc.

The <layout> part can’t be changed (yet) except the unit and font_size_offset attributes. The later one is especially practical to resize the whole sheet at once.

The <exercise> part is the one you can change alot. Keep the id="mental_calculation" and kind="tabular" attributes though (they can’t be changed yet) but you can put the questions you like inside.

Each question is defined this way:

<question kind="divi" subkind="direct">
    <nb source="intpairs_2to9">20</nb>
</question>

You must set at least a kind and a subkind attributes. Then inside the question, you set at least one numbers’ source. This question says: “I want 20 questions about direct division (i.e. each one will be of the form a ÷ b = ?) the numbers being integers between 2 and 9”. (For divisions the pair of integers will be b and the solution; mathmaker will compute a automatically).

Another example, taken from mathmaker/data/frameworks/mental_calculation/lev11_1/mini_problems.xml:

<question kind="addi" subkind="direct" context="mini_problem">
    <nb source="intpairs_5to20">5</nb>
</question>

You see you can set the lower and upper values as you like. Just respect the syntax (if you write intpairs_5_to_20 this won’t work). And this time a context is added to the question. So it means “I want 5 simple additive problems, the numbers being integers between 5 and 20”.

Note that you can put several different numbers’ sources inside one <question>. For instance:

<question kind="multi" subkind="direct">
    <nb source="intpairs_2to9">1</nb>
    <nb source="table_11">1</nb>
    <nb source="decimal_and_one_digit">1</nb>
</question>

This means there will be three questions, all being direct multiplications, but one pair of numbers will be integers between 2 and 9; one pair will be from the table of 11 (like 34 × 11), and one will be a decimal number and a one digit number (like 150,3 × 0.01).

Last explained feature: in some sheets you’ll find <mix> sections, like this one, taken from mathmaker/data/frameworks/mental_calculation/lev11_2/test_11_2.xml:

<mix>
    <question kind="area" subkind="rectangle" picture="true"></question>
    <question kind="multi" subkind="direct"></question>
    <question kind="multi" subkind="direct"></question>
    <question kind="vocabulary" subkind="multi"></question>
    <nb source="table_15">1</nb>
    <nb source="table_11">1</nb>
    <nb source="intpairs_2to9" variant="decimal1">1</nb>
    <nb source="intpairs_2to9" variant="decimal2">1</nb>
</mix>

It means the numbers’ sources will be randomly attributed to the questions. Each time a new sheet is generated from this framework, the numbers from table of 15 will be attributed . The rules to follow for a <mix> section are:

  • Put as many numbers’ sources as there are questions. For instance in the example above we could have written this too:
<mix>
    <question kind="area" subkind="rectangle" picture="true"></question>
    <question kind="multi" subkind="direct"></question>
    <question kind="multi" subkind="direct"></question>
    <question kind="vocabulary" subkind="multi"></question>
    <nb source="table_15">3</nb>
    <nb source="intpairs_2to9" variant="decimal1">1</nb>
</mix>
  • Any numbers’ source must be assignable to any of the questions.

Now the question is: how to know about the questions kinds and subkinds, and the possible contexts, variants or whatever other attributes? Well it is planned to add an easy way to know that (like a special directive) but there’s nothing yet. The better, so far, may be to look at the provided sheets in mathmaker/data/framworks/mental_calculation/ and see what’s in there.

FreeBSD notes

eukleides fix

eukleides currently does not work out of the box. The pkg-installed version has a functional euktoeps script, it is required, so keep it somewhere. Then do pkg remove eukleides and re-install it from source:

  • get the 1.5.4 source from http://www.eukleides.org/, for instance wget http://www.eukleides.org/files/eukleides-1.5.4.tar.bz2

  • then tar xvzf eukleides-1.5.4.tar.bz2

  • then possibly modify the prefix for install in the Config file, at your liking

  • remove the making of documentation and manpages from the install target in the Makefile (they cause errors)

  • install the required dependencies to compile eukleides: pkg install bison flex gmake gcc

  • do gmake and then gmake install. This will provide functional binaries.

  • replace the euktoeps script by the one you did get from the pkg installed version.

  • if necessary (if lualatex complains about not finding eukleides.sty), reinstall eukleides.sty and eukleides.tex correctly:

    # mkdir /usr/local/share/texmf-dist/tex/latex/eukleides
    # cp /usr/local/share/texmf/tex/latex/eukleides/eukleides.* /usr/local/share/texmf-dist/tex/latex/eukleides/
    # mktexlsr
    

python-daemon error at install

You might get an error before the end of mathmaker‘s installation:

/usr/local/venv/mm0/lib/python3.4/site-packages/setuptools/dist.py:294: UserWarning: The version specified ('UNKNOWN') is an invalid version, this may not work as expected with newer versions of setuptools, pip, and PyPI. Please see PEP 440 for more details.
  "details." % self.metadata.version
creating /usr/local/venv/mm0/lib/python3.4/site-packages/python_daemon-UNKNOWN-py3.4.egg
Extracting python_daemon-UNKNOWN-py3.4.egg to /usr/local/venv/mm0/lib/python3.4/site-packages
Adding python-daemon UNKNOWN to easy-install.pth file
Installed /usr/local/venv/mm0/lib/python3.4/site-packages/python_daemon-UNKNOWN-py3.4.egg
error: The 'python-daemon>=2.1.1' distribution was not found and is required by mathmaker
[mm0] root@testmm0:/usr/local/src/mathmaker #

Fix it this way:

# pip3 install python-daemon --upgrade

And finish the install:

# pip3 install mathmaker