5. Setting up an event

Each event has a folder with a project file, freemapper-print.toml. It names the event, the map, the layouts and the sheet elements. Without a course file the program prints the map with title, logos and scale check bar. With one, it prints a sheet for every course, with the course overprint (chapter 8).

The work takes three commands:

1. init creates the project file.
2. You edit the file in a text editor and run check until the sheets look as they should.
3. export writes one PDF per layout, or one per course when the project has a course file.

The example examples/rummelsburg-competition-layouts shows the whole way with every command and its output.

Creating the project file: init

freemapper-print init citysprint --map maps/rummelsburg.omap --title "Stadtsprint Rummelsburg"

This creates the folder citysprint if it does not exist yet, and freemapper-print.toml in it. init never overwrites an existing project file. The file stores the path to the map relative to itself, so you can move the folder as long as the map moves with it.

The new file holds:

• the title from --title, or the file name of the map without the option;
• the map kind. It comes from --kind, else from the freemapper.toml next to the map, else from the symbol set and the scale of the map, and init says which. If none of these gives one, the program stops and asks for --kind sprint, --kind schoolyard or --kind forest;
• a contour interval. If the freemapper.toml next to the map names one (freemapper writes it when the interval differs from the standard of the map kind), init takes that. Otherwise it proposes one: 2 m for sprint maps, 5 m for forest maps, none for schoolyard maps. A comment in the file says which of the two it is. Look up the map's contour interval and correct it;
• a title block with {event} and 1:{print_scale} · {contour_interval} at the top left of the map frame and a scale check bar at the bottom right;
• one layout at the scale of the map. init tries A4 with an 8 mm passe-partout, then A4 with a wider one (in 2 mm steps up to 24 mm), then A3, and takes the first sheet check has nothing to report about. The map "Rummelsburger Bucht" is a strip that fits no A4 or A3 sheet. If no sheet fits, the file keeps A4 with 8 mm, and init starts its message with "Warning:" and prints what check will report.

init sets the sheet language, used for the date, the decimal separator and the credit line on the sheet, to the program language. It is stored in event.lang.

The project file

The file is TOML. Each line has the form key = value, and sections stand in square brackets. A key the program does not know is an error that names file, line and column, so a typo is never ignored silently. A value out of range is an error with the line and column of the value. Paths are relative to the project file.

format = 1

[event]
title = "Stadtsprint Rummelsburg"
date = 2027-05-15                  # optional, for {date}
organiser = "OL-Verein Musterstadt" # optional, for {organiser}
lang = "de"                        # sheet language: de or en, default de

[sources]
map = "rummelsburg.omap"

[map]
kind = "sprint"                    # sprint, schoolyard or forest
contour_interval_m = 2.0           # contour interval in metres, for {contour_interval}

[print]
copyright = """
Karte: Rummelsburger Bucht, Remo Madella, MOO Challenge Berlin 2025
"""                                # optional, replaces the sources from the map

[[shared]]                         # shared sheet elements, chapter 7
id = "title"
kind = "title_block"
lines = ["{event}", "1:{print_scale} · {contour_interval}"]
anchor = { to = "map_frame", corner = "top_left", offset_mm = [2.0, 2.0] }

[[layouts]]                        # one or more layouts, chapter 6
id = "a4-4000"
paper = "A4"
print_scale = 4000

Checking: check

freemapper-print check citysprint

check takes the project file or its folder. It draws every layout in memory, writes no file, and prints one line per layout with paper, orientation, scale and factors, followed by the notes. It ends with "Checked 1 layout, no notes." or "Layouts with notes: 1 of 2."

The exit code is 0 when no layout has anything to report, and 1 when one has a note or cannot be drawn. Lines that start with "Info:", for added north lines and an intended crop (map_frame.crop), do not count. A script can therefore run check before export. A note never stops the export. Some notes are expected, such as the overflow of a map larger than the sheet. Chapter 10 explains each note.

Writing the PDFs: export

freemapper-print export citysprint
freemapper-print export citysprint --layout a4-4000
freemapper-print export citysprint --out-dir ~/Desktop/print

export writes one PDF per layout and names it after the layout id, for example a4-4000.pdf. Without --out-dir the PDFs go into the folder out next to the project file, which the program creates when needed. A folder given with --out-dir must exist. --layout exports only that layout and can be repeated. A PDF of the same name is overwritten.

For each layout export prints the same lines as check, with the path of the PDF in the first one. The layouts are drawn one after another, so only one sheet is in memory at a time. The exit code is 0 once all PDFs are written, also when there were notes.

Before writing, the program checks the free space: it needs the size of the PDF plus a 50 MB reserve. The PDF is first written as a partial file (<name>.pdf.….part) and gets its name only when it is complete on the disk. On a full disk an older PDF of the same name stays as it was, and no half-written PDF is left behind; the same holds for any other error. The message says how much space is needed and how much is free, or that the disk does not say. The partial file is named <name>.pdf.<process id>.<counter>.part, so two exports into the same folder do not share it. export removes partial files older than an hour from the folder out of the project.

If out, or a folder inside the project that you give with --out-dir, is a link that leads out of the project folder, the program writes nothing there and says "a link leads out of the project folder". Replace the link with a real folder. An --out-dir outside the project, also on another drive, works.