# robotkarol — Robot Karol worlds and block programs for teaching material

Version 3.7 (2026-09-03) — Anselm Wagner <anselm.wagner@posteo.de>

The `robotkarol` package draws worlds and Blockly-style block programs in the
visual style of the German teaching environment *Robot Karol Online*
(https://karol.arrrg.de/), for use in worksheets, exams, and slides.
Colours and proportions were measured from the original interface and
rebuilt with TikZ; no artwork is copied.

## Features

* `karolwelt` environment: full 2-D worlds rendered either as a 3-D
  oblique view (with room frame, brick stacks, markers, walls, and the
  Karol avatar) or as a 2-D top view matching the original interface.
* `\karolzeile`: compact string notation for one-row worlds
  (`\karolzeile{> Z 2 {2M} M Q}`), drawn with the very same building
  blocks as `karolwelt` — a one-row world is visually a `karolwelt` with
  `laenge=1`, only the input is shorter. Plus helpers for before/after
  pairs, empty grids, and legends.
* `karolbloecke` environment and block commands (`\bbefehl`,
  `\bwiederholemal`, `\bwenndannsonst`, …) reproducing the Blockly
  editor: exact colours, flat design, condition plugs, number pills,
  ghost blocks and empty sockets for cloze exercises.
* Inline blocks (`\ibefehl`, `\iwenndann`, `\iwiederholemal`, …) set a
  single block into running text: the block's text baseline sits exactly
  on the surrounding baseline, the label takes the surrounding font size,
  and the notches are shallower so the block's height stays close to the
  line height. Blocks that would span several lines in a stack appear
  inline with their header only.
* Two figures, switched with `\karolfigur{karol}` (default) or
  `\karolfigur{emma}` (long hair and a flower).
* The fonts of the online interface: labels in Noto Sans, program text in
  Hack (falling back to DejaVu Sans Mono when Hack is not installed).
  Load the package as `\usepackage[schrift=dokument]{robotkarol}` to use
  the document's own `\sffamily`/`\ttfamily` instead — that also avoids
  loading `fontspec`.
* A toner-saving print mode: `\usepackage[druck]{robotkarol}` — or
  `\karolsetup{druck=true}` at any point, group-local — redraws every
  view in greyscale. It is deliberately not minimal but *sufficient*:
  areas stay as light as possible while everything that carries meaning
  remains legible — brick stacks stay countable, markers stand out on
  the bricks they sit on, and a `\bbefehl` is still told apart from a
  `\baufruf`.
* `\karolonline{2t7t}` links to a task in Robot Karol Online: it
  typesets `karol.arrrg.de/#2t7t` — what you actually have to type —
  and links it to `https://karol.arrrg.de/#2t7t`. This is why the
  package loads `hyperref` (at the very end of the preamble, so your
  own `\usepackage[...]{hyperref}` still works). Load the package as
  `\usepackage[hyperref=false]{robotkarol}` to prevent that; the
  command then sets the same text without a link.
* `karolcode` environment for syntax-highlighted Karol source text and
  helpers for structograms (via `struktex`).
* All colours and dimensions adjustable through `\karolsetup`.

## Requirements

LuaLaTeX (the package warns if `\directlua` is missing), expl3, TikZ,
listings, struktex, graphicx, and — unless loaded with
`schrift=dokument` — fontspec and the Noto Sans fonts (both in TeX
Live). Unless loaded with `hyperref=false`, it also loads hyperref.

## Installation

Put `robotkarol.sty` where LaTeX finds it, e.g.

    TEXMFHOME/tex/latex/robotkarol/robotkarol.sty

and refresh the file database (`mktexlsr`) if your distribution needs it.
`robotkarol.cwl` is a command list for TeXstudio's auto-completion and
belongs in that editor's `completion/user` directory; it is not needed to
typeset documents.

## Files

| File | Purpose |
|---|---|
| `robotkarol.sty` | the package |
| `robotkarol-doc.tex`, `robotkarol-doc.pdf` | manual (German, English abstract) |
| `robotkarol-beispiel.tex`, `robotkarol-beispiel.pdf` | example document |
| `robotkarol-cheatsheet.md` | quick reference |
| `robotkarol.cwl` | TeXstudio auto-completion |

## Documentation

See `robotkarol-doc.pdf` (German, with an English abstract). A quick start:

```latex
\usepackage{robotkarol}
...
\begin{karolwelt}[breite=5, laenge=3]
  \karol[x=1, y=2, richtung=osten]
  \ziegel[x=2, y=2, anzahl=4]
  \marke[x=5, y=2]
\end{karolwelt}

Karol checks \iwenndann{IstZiegel} and repeats \iwiederholemal{5}.
```

## License

LaTeX Project Public License, version 1.3c or later
(https://www.latex-project.org/lppl.txt). This work has the LPPL
maintenance status `maintained`; the current maintainer is Anselm Wagner.

Copyright (C) 2026 Anselm Wagner <anselm.wagner@posteo.de>