Home

dgs (Document Generation System, pronunciation: [ˈdeɡeʃ]) is a system for generating problem formulations, reference solutions and all related documents for correspondence seminars, Náboj and other targets such as lecture handouts or homework sheets. The purpose of DeGeŠ is to take raw Markdown text, templates, pictures and structure and produce PDF or HTML documents that can be printed or published on the web.

Structure

DeGeŠ operates on the file system, using a concept of nodes. A node is a directory containing a valid meta.yaml metadata file. If the file is not present, the Makefile will likely not recognize the recipe; if it is malformed, the builder will most likely crash with an error message.

For instance: in FKS, each volume has two semesters, each semester comprises three rounds, each round has seven problems, each problem has a title, author, formulation and a solution).

[Markdown, Markdown, Markdown, ...] ---`pandoc`---> `XeLaTeX`  \
[picture, picture, ...] ---(various tools)---> pictures        }----> PDF file
metadata `meta.yaml`   -\                                      |
[XeLaTeX template]     --> (filled template)                   /

• Various people can write Markdown files and create pictures. They need not care about the rest of the document.
• Metadata can contain just about anything that is required inside the document.
• Templates are defined globally for the entire module. Template inheritance is highly recommended.

Context builder

The core part of DeGeŠ is the context builder, which crawls all the required nodes and builds a huge nested dictionary: the document context. The context is then accessible by Jinja2 and filled into the templates where necessary. Each module can have multiple context builders and multiple templates (this is generally a 1-to-1 relationship).

Modules

Different tasks call for different modules, structures and templates.

Seminar

- problems
- solutions
- whole semester booklet
- camp invite

• Náboj

  • booklet
  • tearoff (problems only, with barcodes, to be used during the competition)
  • answers (for chief evaluator)
  • answers (grouped modulo 5, to be used by evaluators during the competition)
  • envelopes (to be printed and put on tables)

• scholar

  • handout (for university tutorials)
  • handout with solutions (for tutors)
  • homework
  • homework with solutions

Directories

core

This is the core of DeGeŠ.

fonts

DeGeŠ uses local, not system-wide fonts.

i18n

Contains language-specific redefinitions and overrides (for instance decimal point vs comma).

tex

• core.tex required packages and general settings
• hacks.tex contains various temporary or permanent hacks that try to circumvent the limitations of TeX. It should be shrinking slowly but the opposite is true. But one can dream...
• fonts.tex (from fonts/)

utilities

Python scripts and base classes for context builders.

source

Contains repositories with source files. This should be modified somehow.

output

Output is spewed here. The internal structure mirrors source at all times.

input

Temporary and semi-temporary files. Can be deleted by make distclean.