Document generation

Matholymp provides a script mo-document-generate to generate a range of documents, such as name badges and exam papers in the right languages with each contestant’s contestant code printed on them, from registration system data.

mo-document-generate expects to be run from a directory containing:

  • A file documentgen.cfg configuring the document generation (parts of this file can stay the same from year to year, but parts will need updating for each year’s event).
  • A subdirectory templates/ with various LaTeX templates for documents and PDF backgrounds and logos.
  • A subdirectory papers/year/ containing LaTeX sources or PDFs of exam papers (from leaders, before headings and backgrounds are added by the script).
  • A subdirectory data/ containing data from the registration system: countries.csv, people.csv (the full CSV file of people, downloaded while logged in administratively) and subdirectories flags/ and photos/ unpacked from the ZIP files downloaded from the registration system.
  • A subdirectory out/ (which may initially be empty), where output files are placed by the script.

Example files

The examples/document-generation/ directory in the matholymp source distribution includes versions of documentgen.cfg and LaTeX templates that may be used as a basis for configuring document generation. It also includes an example exam paper English-day1.tex that sets suitable page margins that are compatible with how the included LaTeX templates position various headings on the page.

Graphic design

The LaTeX templates provided are those used for EGMO. In various places they conditionally include PDF files with backgrounds or logos that are not included; you will need to provide such files for your event if generating affected documents. It is likely that you will need to adapt these templates to fix the layout of the backgrounds you provide, unless those are laid out exactly the same as those used for EGMO. (If nothing else, the clipping when the logo is included is unlikely to be correct for another event.)

Document generation tasks

The following describes how to generate various documents with mo-document-generate. In all cases, the commands should be run from the directory with contents detailed above. Although the examples generally describe how to generate a full set of documents, you can also generally generate documents relating to individual people, by giving that person’s number (in the registration system) or contestant code in place of all.

Name badges

To generate all name badges:

mo-document-generate --background badge all

Omit --background if each badge is to be printed onto card with the appropriate background pre-printed, instead of including the backgrounds in the PDFs generated by mo-document-generate.

To generate name badges using photos that have been provided for producing name badges, where the person concerned does not wish them to be public on the registration site but the registration system support for specifying permissions for particular uses of photos has not been enabled, you need to copy the relevant photos into new subdirectories of data/photos/ not corresponding to any photo from the registration system and edit people.csv to enter values in the Photo URL column that cause those photos to be selected.

Invitation letters

To generate an invitation letter for a given person:

mo-document-generate invitation-letter *number*

To generate invitation letters for all participants:

mo-document-generate invitation-letter all

Desk labels

To generate labels for contestant desks for the exams (the example template expects to put these on 127mm by 76mm cards, but of course you can change the template to print them in some other way):

mo-document-generate desk-label all

This prints labels in a default order (all Contestants 1, then all Contestants 2, and so on). The --exam-order file option may be used to specify a text file listing contestant codes if a different order is required.

Checklist of languages

To generate a checklist language-list.txt of which contestants have requested papers in which languages, and a checklist language-status.txt of which languages have papers available:

mo-document-generate language-list all

Exam papers

Give the English papers to leaders in LaTeX form with appropriate page margins. Collect translations and put them in the papers/year/ directory, with PDFs having names such as English-day1.pdf (or just English.pdf for a single-day competition); in the filename, all characters that are not ASCII letters are omitted from the language name (so a paper for “French (Swiss)” would be FrenchSwiss-day1.pdf, for example). If the paper is produced using LaTeX, only the file with a name such as English-day1.tex needs to go in that directory; mo-document-generate will run pdflatex on such a file automatically (the generated PDF will go in the out/ directory, and be updated automatically if the LaTeX source changes). If both the PDF and LaTeX source are present, only the PDF will be used, so watch out for a PDF being out of date with respect to the LaTeX file. If a leader wishes to use Word, make sure that the page margins are correct and again get a matching PDF file. Given the appropriately-named LaTeX sources or PDFs of papers from leaders, there are then several documents that can be generated.

For draft papers to display:

mo-document-generate paper new-drafts

That will generate draft papers for all translations that are new or modified since the previous run (if any) of that command. To generate drafts instead for a specific language (add --day day to generate these only for a particular day; the language name is as used in filenames):

mo-document-generate paper language

For final papers for exams (this will generate a PDF of each day’s papers, that includes papers for each contestant in the right languages marked with their contestant code, as well as such PDFs of papers for leaders in all the languages requested by their students; omit the --day day option if there is only one day at the competition):

mo-document-generate --day 1 paper all
mo-document-generate --day 2 paper all

This prints papers in a default order (all Contestants 1, then all Contestants 2, and so on). The --exam-order file option may be used to specify a text file listing contestant codes if a different order is required. To generate papers for individual contestants in separate files, a contestant code may be used in place of all; use all-split to generate papers for all contestants in separate files.

For final papers for the website (if papers are being printed with pre-printed backgrounds, use both commands, otherwise just the first command; these commands generate the files to be imported to the website with mo-static-papers-import):

mo-document-generate paper all-languages
mo-document-generate --background paper all-languages

Handling handwritten papers

If a leader handwrites their translation, scan the paper (black and white with appropriate threshold), crop the scan and make it transparent. Then you can create a LaTeX file for the document to include the scan; the main part should look like:


The following steps may be helpful for the process of making a scan transparent in GIMP:

  • Layer ‣ Transparency ‣ Add Alpha Channel.
  • Select ‣ By Colour.
  • Click on the colour you want to become transparent (i.e., white). The selection is highlighted with some dashed lines.
  • Edit ‣ Clear.
  • Save the file as PNG.

Coordination forms

To generate coordination forms (the example template will need adapting if you have more than four contestants per team):

mo-document-generate coord-form all

Add --background if a background design is to be used in the forms, but they are not printed on paper with that design pre-printed.


If generating certificates for awards, people.csv needs to have been downloaded after the final results and medal boundaries were entered, and the medal boundaries must also have been entered in documentgen.cfg. Then do:

mo-document-generate participation-certificate all
mo-document-generate award-certificate gold
mo-document-generate award-certificate silver
mo-document-generate award-certificate bronze
mo-document-generate award-certificate hm

Add --background if the certificates are to be printed complete with background, instead of just printing names, roles and countries on pre-printed certificates.

Bulk upload of scores

If the network access at the olympiad site is so poor as to cause problems for entering scores online during the competition, it may be necessary to enter scores in a spreadsheet offline and then upload them to the registration system in bulk. In that case, create a CSV file (with BOM) in data/scores-in.csv, with columns “Contestant Code” and “Pn” for each problem. Then do:

mo-document-generate scores-commands all

This generates a Unix shell script upload-scores to use roundup-admin to upload the scores. On the system running the registration system, as the user running that system, then do:

sh upload-scores path-to-roundup-admin path-to-instance