.. Documentation of matholymp document generation. Copyright 2014-2020 Joseph Samuel Myers. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Additional permission under GNU GPL version 3 section 7: If you modify this program, or any covered work, by linking or combining it with the OpenSSL project's OpenSSL library (or a modified version of that library), containing parts covered by the terms of the OpenSSL or SSLeay licenses, the licensors of this program grant you additional permission to convey the resulting work. Corresponding Source for a non-source form of such a combination shall include the source code for the parts of OpenSSL used as well as that of the covered work. .. _document-generation: Document generation =================== Matholymp provides a script :command:`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. :command:`mo-document-generate` expects to be run from a directory containing: * A file :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 :file:`templates/` with various LaTeX templates for documents and PDF backgrounds and logos. * A subdirectory :file:`papers/{year}/` containing LaTeX sources or PDFs of exam papers (from leaders, before headings and backgrounds are added by the script). * A subdirectory :file:`data/` containing data from the registration system: :file:`countries.csv`, :file:`people.csv` (the full CSV file of people, downloaded while logged in administratively) and subdirectories :file:`flags/` and :file:`photos/` unpacked from the ZIP files downloaded from the registration system. * A subdirectory :file:`out/` (which may initially be empty), where output files are placed by the script. Example files ------------- The :file:`examples/document-generation/` directory in the matholymp source distribution includes versions of :download:`documentgen.cfg <../examples/document-generation/documentgen.cfg>` and LaTeX templates that may be used as a basis for configuring document generation. It also includes an example exam paper :download:`English-day1.tex <../examples/document-generation/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 :command:`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 :command:`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 :file:`data/photos/` not corresponding to any photo from the registration system and edit :file:`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 :samp:`--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 :file:`language-list.txt` of which contestants have requested papers in which languages, and a checklist :file:`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 :file:`papers/{year}/` directory, with PDFs having names such as :file:`English-day1.pdf` (or just :file:`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 :file:`FrenchSwiss-day1.pdf`, for example). If the paper is produced using LaTeX, only the file with a name such as :file:`English-day1.tex` needs to go in that directory; :command:`mo-document-generate` will run :command:`pdflatex` on such a file automatically (the generated PDF will go in the :file:`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 :samp:`--day {day}` to generate these only for a particular day; the language name is as used in filenames): .. parsed-literal:: 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 :samp:`--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 :samp:`--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 :samp:`all`; use :samp:`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 :command:`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:: \begin{document} \begin{center} \includegraphics[width=16cm,height=20cm,keepaspectratio]{Language-dayN-scan.png} \end{center} \end{document} The following steps may be helpful for the process of making a scan transparent in GIMP: * :menuselection:`Layer --> Transparency --> Add Alpha Channel`. * :menuselection:`Select --> By Colour`. * Click on the colour you want to become transparent (i.e., white). The selection is highlighted with some dashed lines. * :menuselection:`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. Certificates ^^^^^^^^^^^^ If generating certificates for awards, :file:`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 :file:`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 :file:`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 :file:`upload-scores` to use :command:`roundup-admin` to upload the scores. On the system running the registration system, as the user running that system, then do: .. parsed-literal:: sh upload-scores *path-to-roundup-admin* *path-to-instance*