% !TeX program = lualatex
% karol-doc.tex — Handbuch zum Paket karol
\documentclass[11pt]{article}
\usepackage[margin=2.4cm]{geometry}
\usepackage{fontspec}
\usepackage[provide=*, ngerman]{babel}
\usepackage{robotkarol}
\usepackage{parskip}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{hyperref}
\hypersetup{colorlinks, linkcolor=blue!50!black, urlcolor=blue!50!black}

\lstdefinestyle{tex}{
	language=[LaTeX]TeX, basicstyle=\ttfamily\small,
	keywordstyle=\color{blue!60!black}, commentstyle=\color{gray},
	columns=fullflexible, keepspaces=true, moretexcs={
		karolzeile,karolpaar,karolgitter,karollegende,karolsetup,
		karol,ziegel,marke,quader,wand,bbefehl,bwiederholemal,
		bwiederholesolange,bwiederholeimmer,bwenndann,bwenndannsonst,
		bluecke,bbedingung,bkommentar,baufruf,banweisung,bhauptprogramm,
		ibefehl,iaufruf,ianweisung,ikommentar,ihauptprogramm,
		iwiederholemal,iwiederholesolange,iwiederholeimmer,iwenndann,
		isonst,ibedingung,iluecke,bist,bnichtist,iist,inichtist,
		karolfigur,karolonline}}
\lstset{style=tex}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\key}[1]{\texttt{#1}}

\title{Das Paket \pkg{robotkarol}\\[2pt]
	\large Robot-Karol-Welten und Blockprogramme für Unterrichtsmaterial}
\author{Anselm Wagner\thanks{\texttt{anselm.wagner@posteo.de}}}
\date{3. September 2026 \quad Version 3.7}

\IfFileExists{hologo.sty}{\usepackage{hologo}}{\newcommand{\hologo}[1]{#1}}

\begin{document}
\maketitle

\begin{abstract}\noindent
Das Paket \pkg{robotkarol} zeichnet Welten und Blockprogramme im Stil von
\emph{Robot Karol Online} (\url{https://karol.arrrg.de/}) für
Arbeitsblätter, Präsentationen und Prüfungen. Welten können als
3D-Schrägbild oder als 2D-Draufsicht ausgegeben werden; Farben und
Formen sind der Weboberfläche nachempfunden. Einzelne Blöcke lassen
sich als Inline-Blöcke in den Fließtext setzen, Aufgaben der
Online-Umgebung mit \verb|\karolonline| verlinken. Ein Druckmodus stellt
alle Ansichten auf tonersparende Graustufen um. Das Paket benötigt
\hologo{LuaLaTeX}\footnote{Genauer: eine Engine mit
	\texttt{\textbackslash directlua}; getestet mit LuaLaTeX.}
und expl3. \emph{English:} draws worlds and Blockly-style block
programs of the German teaching environment Robot Karol for worksheets;
3D oblique or 2D top view; single blocks can be set inline in running
text, aligned to the surrounding baseline; a toner-saving greyscale
print mode; requires LuaLaTeX.
\end{abstract}

\tableofcontents

\section{Schnellstart}

\begin{lstlisting}
\usepackage{robotkarol}   % Kompilierung mit LuaLaTeX
\end{lstlisting}

\begin{minipage}[c]{0.52\textwidth}
\begin{lstlisting}
\begin{karolwelt}[breite=5, laenge=3]
  \karol[x=1, y=2, richtung=osten]
  \ziegel[x=2, y=2, bisx=4]
  \marke[x=5, y=2]
\end{karolwelt}
\end{lstlisting}
\end{minipage}\hfill
\begin{minipage}[c]{0.44\textwidth}
\begin{karolwelt}[breite=5, laenge=3, skalierung=0.85]
	\karol[x=1, y=2, richtung=osten]
	\ziegel[x=2, y=2, bisx=4]
	\marke[x=5, y=2]
\end{karolwelt}
\end{minipage}

\section{Die Umgebung \texttt{karolwelt}}

\begin{lstlisting}
\begin{karolwelt}[<Schlüssel>]
  <Objekte>
\end{karolwelt}
\end{lstlisting}

\subsection{Koordinatensystem}

Die Koordinaten folgen Robot Karol Online: \key{x} zählt die
\emph{Spalten} von links (1 bis \key{breite}), \key{y} die
\emph{Zeilen von hinten} (1 bis \key{laenge}). In der 2D-Draufsicht
ist die Zeile $y=1$ folglich die \emph{oberste} Zeile; in der
3D-Ansicht liegt sie am weitesten hinten. \key{hoehe} bezeichnet wie
in Karol Online die \emph{Raumhöhe} (Anzahl Ziegellagen bis zum
oberen Rahmen) und wirkt nur auf den 3D-Rahmen.

\subsection{Schlüssel der Umgebung}

\begin{tabular}{@{}llp{7.6cm}@{}}
\key{breite} & 5 & Anzahl Spalten \\
\key{laenge} & 5 & Anzahl Zeilen \\
\key{hoehe} & 6 & Raumhöhe des 3D-Rahmens in Ziegellagen \\
\key{ansicht} & \key{3d} & \key{3d} (Schrägbild) oder \key{2d}
	(Draufsicht) \\
\key{skalierung} & 1 & Skalierungsfaktor des Bildes \\
\key{titel} & & Beschriftung über dem Bild \\
\key{hinweis} & & kursiver Hinweis unter dem Bild \\
\end{tabular}

\subsection{Objekte}

Alle Objekte werden über Schlüssel platziert. \key{bisx}/\key{bisy}
(auch \key{bisX}/\key{bisY}) füllen rechteckige Bereiche.

\begin{lstlisting}
\karol[x=1, y=1, richtung=osten]  % genau einmal je Welt
\ziegel[x=2, y=3, anzahl=4]       % Stapel aus 4 Ziegeln
\ziegel[x=1, y=5, bisx=5]         % Reihe einzelner Ziegel
\marke[x=3, y=3]                  % gelbe Marke
\marke[x=5, y=1, farbe=cyan!60]   % Marke in eigener Farbe
\quader[x=4, y=1, bisy=5]         % Quaderwand; \wand = Synonym
\end{lstlisting}

\key{richtung} akzeptiert \key{osten}, \key{westen}, \key{norden} und
\key{sueden} sowie die Synonyme \key{rechts}, \key{links},
\key{hinten} bzw.\ \key{oben} und \key{vorn}, \key{vorne} bzw.\
\key{unten} (Vorgabe: \key{sueden}). Marken liegen stets \emph{oben auf} dem
Ziegelstapel ihrer Zelle; Karol steht auf Stapel und Marke.

\subsection{Beispiel in beiden Ansichten}

\begin{center}
\begin{karolwelt}[breite=4, laenge=4, skalierung=0.8,
		titel={3D-Ansicht}]
	\karol[x=1, y=4, richtung=osten]
	\ziegel[x=2, y=4]\ziegel[x=3, y=4, anzahl=2]
	\ziegel[x=4, y=4, anzahl=3]\ziegel[x=4, y=3, anzahl=4]
	\ziegel[x=4, y=2, anzahl=5]\ziegel[x=4, y=1, anzahl=6]
	\ziegel[x=3, y=1, anzahl=7]\ziegel[x=2, y=1, anzahl=8]
	\ziegel[x=1, y=1, anzahl=9]
	\marke[x=1, y=1]
\end{karolwelt}
\qquad
\begin{karolwelt}[breite=4, laenge=4, ansicht=2d,
		titel={2D-Ansicht}]
	\karol[x=1, y=4, richtung=osten]
	\ziegel[x=2, y=4]\ziegel[x=3, y=4, anzahl=2]
	\ziegel[x=4, y=4, anzahl=3]\ziegel[x=4, y=3, anzahl=4]
	\ziegel[x=4, y=2, anzahl=5]\ziegel[x=4, y=1, anzahl=6]
	\ziegel[x=3, y=1, anzahl=7]\ziegel[x=2, y=1, anzahl=8]
	\ziegel[x=1, y=1, anzahl=9]
	\marke[x=1, y=1]
\end{karolwelt}
\end{center}

In der 2D-Ansicht zeigen Zahlen die Stapelhöhe; Ziegelzellen sind
rosa, Marken eine einfarbige Fläche, die kleiner als das Feld ist —
so bleibt der Ziegel ringsum sichtbar und „Marke auf Ziegel“
erkennbar. Quader sind grau, Karol ist der schwarze Richtungskeil.

\section{Einzeilige Welten: \texttt{\textbackslash karolzeile}}

Für schnelle eindimensionale Welten gibt es die kompakte
Zeichenketten-Notation (bis Version 2.x hieß das Kommando
\texttt{\textbackslash karolwelt}). Gezeichnet wird mit denselben
Bausteinen wie in der Umgebung \texttt{karolwelt}: gleiche Projektion,
gleiches Bodengitter, gleiche Ziegel, Marken, Quader und derselbe
Avatar. Eine Zeilen-Welt ist damit optisch nichts anderes als eine
\texttt{karolwelt} mit \key{laenge}\,=\,1 -- nur die Eingabe ist kürzer.

\begin{center}
\begin{tabular}{@{}c@{\qquad}l@{}}
\karolzeile[skalierung=0.8]{> Z 2 {2M} {3>} M Q} &
\begin{minipage}[c]{6.6cm}
\begin{lstlisting}
\karolzeile{> Z 2 {2M} {3>} M Q}
\end{lstlisting}
\end{minipage}
\end{tabular}
\end{center}

\begin{tabular}{@{}ll@{}}
\verb|> < ^ v| & Karol mit Blickrichtung \\
\verb|.| & leeres Feld \\
\verb|Z|, \verb|2|\,…\,\verb|9| & Ziegel bzw.\ Stapel \\
\verb|M|, \verb|Q| & Marke, Quader \\
\verb|{...}| & mehrere Objekte auf einem Feld, von unten nach
	oben: \verb|{M>}|, \verb|{2M}|, \verb|{3>}| \\
\end{tabular}

\subsection{Schlüssel}

\begin{tabular}{@{}lll@{}}
\key{skalierung} & 1 & Skalierungsfaktor des Bildes \\
\key{nummern} & \texttt{true} & Feldnummern anzeigen \\
\key{titel} & --- & Zeile über dem Bild \\
\key{hinweis} & --- & kursive Zeile unter dem Bild \\
\key{hervorheben} & --- & Komma-Liste von Feldnummern \\
\key{rahmen} & \texttt{false} & Raumrahmen wie in \texttt{karolwelt} \\
\key{hoehe} & 3 & Raumhöhe des Rahmens in Ziegellagen \\
\end{tabular}

Die \textbf{Feldnummern} stehen vor der vordersten Gitterkante und nicht
auf dem Feld: im Schrägbild würde sie sonst jeder Ziegelstapel verdecken.
\key{hervorheben} zeichnet einen magentafarbenen Rahmen knapp außerhalb
des Feldes und färbt dessen Nummer mit -- ein roter Rahmen wäre neben den
reinroten Ziegelkanten nicht zu erkennen (Farbe: \key{hervorfarbe}).
Den Raumrahmen zeichnet \verb|\karolzeile| nur auf Wunsch; für eine
einzelne Reihe ist er meist zu wuchtig.

\begin{center}
\karolzeile[skalierung=0.8, hervorheben={1,4}]{> Z 2 {2M} M Q .}
\qquad
\karolzeile[skalierung=0.8, rahmen, hoehe=3]{> Z 2 {2M} M Q .}
\end{center}

Dazu gibt es

\begin{tabular}{@{}lp{7.4cm}@{}}
\verb|\karolpaar[keys][keys2]{vorher}{nachher}| & Vorher-nachher-Paar;
	\texttt{keys} gilt für beide Bilder, \texttt{keys2} nur für
	„nachher" \\
\verb|\karolgitter[keys]{n}| & leeres Gitter aus $n$ Feldern \\
\verb|\karollegende| & Standardlegende der Weltsymbole \\
\verb|\karollegendenitem{Welt}{Text}| & einzelner Legendeneintrag \\
\end{tabular}

\section{Blockprogramme}

Die Umgebung \texttt{karolbloecke} stapelt Blockly-Blöcke; Farben und
Formen entsprechen der Karol-Online-Oberfläche.

\begin{center}
\begin{minipage}[c]{0.56\textwidth}
\begin{lstlisting}
\begin{karolbloecke}
  \bwiederholesolange{NichtIstWand}{%
    \bwenndann{IstZiegel}{%
      \bbefehl[1]{Aufheben}}
    \bbefehl[1]{Schritt}}
\end{karolbloecke}
\end{lstlisting}
\end{minipage}\hfill
\begin{minipage}[c]{0.40\textwidth}
\begin{karolbloecke}[skalierung=0.9]
	\bwiederholesolange{NichtIstWand}{%
		\bwenndann{IstZiegel}{%
			\bbefehl[1]{Aufheben}}
		\bbefehl[1]{Schritt}}
\end{karolbloecke}
\end{minipage}
\end{center}

\begin{tabular}{@{}lp{8.2cm}@{}}
\verb|\bbefehl[n]{Name}| & Anweisung (violett); optionale Zahl als
	Pille \\
\verb|\bwiederholemal{n}{...}| & Zählschleife \\
\verb|\bwiederholesolange{Bed}{...}| & kopfgesteuerte Schleife \\
\verb|\bwiederholeimmer{...}| & Endlosschleife \\
\verb|\bwenndann{Bed}{...}| & einseitige Verzweigung \\
\verb|\bwenndannsonst{Bed}{...}{...}| & zweiseitige Verzweigung \\
\verb|\bbedingung{IstZiegel}| & Bedingung mit linkem Stecker; auch
	im Fließtext; leeres Argument = weißer Leersockel \\
\verb|\bist{Norden}| & Himmelsrichtung als Auswahlmenü \\
\verb|\bnichtist{Norden}| & dasselbe verneint \\
\verb|\bluecke[Breite]| & gestrichelter Geisterblock \\
\verb|\bkommentar{Text}| & Kommentar (khaki, \texttt{//}) \\
\verb|\baufruf[n]{Name}| & Aufruf einer eigenen Anweisung (rot) \\
\verb|\banweisung{Name}{...}| & Definition einer eigenen Anweisung \\
\verb|\bhauptprogramm| & Hauptprogramm-Hut \\
\end{tabular}

\subsection{Himmelsrichtungen}

Die acht Blöcke \verb|Ist|\,/\,\verb|NichtIst| zeigen die Richtung in
Robot Karol Online nicht als Text, sondern als Auswahlmenü: eine helle
Pille mit Auswahldreieck. \verb|\bist{...}| und \verb|\bnichtist{...}|
bilden das nach und nehmen die Richtung als Argument.

\begin{center}
\begin{karolbloecke}[skalierung=0.9]\bist{Norden}\end{karolbloecke}\quad
\begin{karolbloecke}[skalierung=0.9]\bnichtist{Westen}\end{karolbloecke}
\end{center}

Für sich allein ergeben sie ein vollständiges Bedingungsplättchen. Als
Argument eines Kontrollblocks steuern sie nur dessen Beschriftung bei --
das Plättchen baut dort wie gewohnt \verb|\bbedingung|:

\begin{center}
\begin{minipage}[c]{0.52\textwidth}
\begin{lstlisting}
\bwenndann{\bist{Norden}}{%
  \bbefehl{Schritt}}
\end{lstlisting}
\end{minipage}\hfill
\begin{minipage}[c]{0.44\textwidth}
\begin{karolbloecke}[skalierung=0.9]
	\bwenndann{\bist{Norden}}{%
		\bbefehl{Schritt}}
\end{karolbloecke}
\end{minipage}
\end{center}

Dasselbe Auswahldreieck trägt der Aufrufblock \verb|\baufruf|: dort
wählt man in der Oberfläche die aufzurufende Anweisung aus. Die
Definition \verb|\banweisung| zeigt den Namen dagegen in einer Pille
ohne Dreieck.

\begin{center}
\begin{karolbloecke}[skalierung=0.9]
	\banweisung{TueEtwas}{\bbefehl[1]{Schritt}}
\end{karolbloecke}\qquad
\begin{karolbloecke}[skalierung=0.9]\baufruf{TueEtwas}\end{karolbloecke}
\end{center}

Beispiel Lückenaufgabe mit Leersockel und Geisterblock:

\begin{center}
\begin{karolbloecke}[skalierung=0.9]
	\bwiederholesolange{}{%
		\bluecke
		\bbefehl[1]{Schritt}}
\end{karolbloecke}
\end{center}

\section{Inline-Blöcke im Fließtext}

Die \verb|\i...|-Kommandos setzen genau \emph{einen} Block in die
laufende Zeile. Die Textgrundlinie des Blocks liegt dabei exakt auf der
Grundlinie des umgebenden Textes, und die Beschriftung übernimmt dessen
Schriftgröße; Kerbe, Nase und Innenabstände sind flacher als im Stapel,
damit die Blockhöhe der Zeilenhöhe nahekommt.

\begin{lstlisting}
Mit \iwenndann{IstZiegel} prüft Karol, ob ein Ziegel vor ihm liegt;
\iwiederholemal{5} wiederholt fünfmal, \ibefehl{Schritt} geht weiter.
\end{lstlisting}

\noindent
Mit \iwenndann{IstZiegel} prüft Karol, ob ein Ziegel vor ihm liegt;
\iwiederholemal{5} wiederholt fünfmal, \ibefehl{Schritt} geht weiter.

\medskip\noindent
{\sloppy
Blöcke, die im Stapel mehrzeilig wären -- Schleifen, Verzweigungen und
eigene Anweisungen --, erscheinen inline \textbf{nur mit ihrem Kopf}.
\verb|\iwenndann{IstZiegel}| ergibt also den Block \iwenndann{IstZiegel}
ohne Rumpf. Für echte Rümpfe bleibt die Umgebung \texttt{karolbloecke}
zuständig.\par}

% Inline-Blöcke sind höher als eine normale Textzeile: Zeilen strecken.
\begingroup\renewcommand{\arraystretch}{1.45}
\begin{tabular}{@{}lp{8.2cm}@{}}
\verb|\ibefehl[n]{Name}| & Anweisung \ibefehl[3]{Schritt} \\
\verb|\iaufruf[n]{Name}| & Aufruf einer eigenen Anweisung \\
\verb|\ianweisung{Name}| & Kopf einer eigenen Anweisung \\
\verb|\ikommentar{Text}| & Kommentar \\
\verb|\ihauptprogramm| & Hauptprogramm-Hut \\
\verb|\iwiederholemal{n}| & Kopf der Zählschleife \iwiederholemal{5} \\
\verb|\iwiederholesolange{Bed}| & Kopf der kopfgesteuerten Schleife \\
\verb|\iwiederholeimmer| & Kopf der Endlosschleife \\
\verb|\iwenndann{Bed}| & Kopf der Verzweigung \\
\verb|\isonst| & sonst-Balken \isonst{} \\
\verb|\ibedingung{Bed}| & Bedingung \ibedingung{IstMarke} \\
\verb|\iist{Norden}| & Himmelsrichtung \iist{Norden} \\
\verb|\inichtist{Norden}| & verneint \inichtist{Osten} \\
\verb|\iluecke[Breite]| & Geisterblock \iluecke{} \\
\end{tabular}
\endgroup

\medskip\noindent
Die \verb|\b...|-Kommandos erkennen den Fließtext selbst und setzen dort
ebenfalls inline; die \verb|\i...|-Fassungen ersparen nur die leeren
Rumpf-Argumente und erzwingen den Modus auch im Stapel.

Inline-Blöcke sind breite, unzerbrechliche Kästen. In schmalen Spalten
kann \hologo{TeX} sie nicht immer umbrechen -- dann hilft
\verb|\sloppy| oder eine höhere \verb|\tolerance| für den Absatz.

\section{Text-Programme und Struktogramme}

Die Umgebung \texttt{karolcode} setzt Karol-Quelltext mit
Syntaxhervorhebung (\pkg{listings}); \verb|\kb{...}| und
\verb|\kw{...}| formatieren Bezeichner und Schlüsselwörter im
Fließtext. Für Struktogramme lädt das Paket \pkg{struktex} und
ergänzt \verb|\leeranweisung| sowie \verb|\stklucke[Breite]|.

\section{Globale Einstellungen: \texttt{\textbackslash karolsetup}}

\begin{lstlisting}
\karolsetup{feldbreite=8.4mm, befehlfarbe={RGB}{116,91,165}, ...}
\end{lstlisting}

\subsection{Schriften}\label{sec:schriften}

Die Oberfläche von Robot Karol Online setzt ihre Beschriftungen in
\emph{Noto Sans} und den Programmtext des Editors in \emph{Hack}. Das
Paket tut das seit v3.6 ebenso: Beschriftungen der Blöcke, Feldnummern
und Stapelzahlen erscheinen in Noto Sans, \texttt{karolcode} sowie
\verb|\kb| und \verb|\kw| in Hack. Dafür lädt das Paket
\pkg{fontspec}. Noto Sans liegt in \TeX\ Live; Hack nicht -- ist es im
System installiert, wird es benutzt, sonst DejaVu Sans Mono, aus dessen
Vorläufer Hack hervorgegangen ist. Welche der beiden es geworden ist,
steht in der \texttt{.log}-Datei.

Wer die Schriften des eigenen Dokuments übernehmen will -- oder
\pkg{fontspec} nicht geladen haben möchte --, lädt das Paket mit

\begin{lstlisting}
\usepackage[schrift=dokument]{robotkarol}
\end{lstlisting}

\noindent
Dann benutzt das Paket \verb|\sffamily| und \verb|\ttfamily| des
Dokuments; die Ausgabe ist Zeichen für Zeichen dieselbe wie bis v3.5.
Umschalten geht auch mitten im Dokument, in einer Gruppe nur dort:

\begin{tabular}{@{}ll@{}}
\key{schrift=karol} & Noto Sans und Hack (Vorgabe) \\
\key{schrift=dokument} & \verb|\sffamily| und \verb|\ttfamily| des Dokuments \\
\key{textschrift=\{...\}} & eigene Schrift für Beschriftungen \\
\key{codeschrift=\{...\}} & eigene Schrift für Programmtext \\
\end{tabular}

\noindent
Die beiden letzten Schlüssel nehmen den Umschaltbefehl selbst:

\begin{lstlisting}
\karolsetup{textschrift={\fontspec{Fira Sans}}}
\end{lstlisting}

\noindent
Ein \verb|\karolsetup{schrift=karol}| in einem Dokument, das mit
\key{schrift=dokument} geladen wurde, ist wirkungslos (mit Warnung) --
die Schriften sind dann gar nicht geladen.

Titel und Hinweis einer Welt bleiben absichtlich in der Schrift des
Dokuments: sie sind Text des Dokuments, keine Beschriftung der
Zeichnung. Für eigenen Text in der Paketschrift gibt es die Umschalter
\verb|\karolschrift| und \verb|\karolcodeschrift|.

\subsection{Weltfarben}

Sie wirken auf \verb|\karolzeile| \emph{und} die Umgebung
\texttt{karolwelt}, die dieselben Bausteine zeichnen.

\begin{tabular}{@{}lll@{}}
\key{feldbreite} & 8.4\,mm & Zell-/Feldbreite aller Welten \\
\key{ziegelfarbe} & reines Rot & Lagenkante; Körper daraus abgeleitet
	(\texttt{!59!black}) \\
\key{ziegelkoerperfarbe} & 150,8,8 & nur die Ziegelflächen \\
\key{ziegelkantenfarbe} & 255,0,0 & nur die Lagenkanten \\
\key{markenfarbe} & 250,205,60 & Markenplatte \\
\key{quaderfarbe} & 128,128,128 & Quader\,/\,Wand \\
\key{bodenfarbe}, \key{gitterfarbe} & 45,45,215 & Bodengitter \\
\key{hervorfarbe} & 226,0,122 & \key{hervorheben} \\
\end{tabular}

\subsection{Figur der Welten}

Das Paket bringt zwei Figuren mit: \key{karol} (Vorgabe) und
\key{emma} mit langem Haar und einer Blume in der Hand. Umgeschaltet
wird mit

\begin{lstlisting}
\karolfigur{emma}           % gleichwertig: \karolsetup{figur=emma}
\end{lstlisting}

\noindent
Die Einstellung wirkt auf \verb|\karolzeile| \emph{und} die Umgebung
\texttt{karolwelt}; in einer Gruppe gesetzt gilt sie nur dort.

\begin{center}
\begin{tabular}{@{}c@{\qquad}c@{}}
\karolzeile[nummern=false, skalierung=1.1]{> ^ < v} &
{\karolfigur{emma}\karolzeile[nummern=false, skalierung=1.1]{> ^ < v}} \\[2pt]
\texttt{karol} & \texttt{emma} \\
\end{tabular}
\end{center}

Emma ist aus derselben Figur gebaut wie Karol -- sie ist ein Nachbau,
keine Kopie. Ihre Farben heißen \key{karolEmmaShirt},
\key{karolEmmaHaar}, \key{karolEmmaBluete} und \key{karolEmmaStiel} und
lassen sich mit \verb|\colorlet| ändern.

\subsection{Blockfarben}

\begin{tabular}{@{}lll@{}}
\key{befehlfarbe} & 116,91,165 & Anweisungsblöcke \\
\key{schleifenfarbe}, \key{verzweigungfarbe} & 91,165,91 &
	grüne Kontrollblöcke \\
\key{bedingungfarbe} & 91,128,165 & Bedingungen \\
\key{anweisungfarbe} & 165,91,98 & eigene Anweisungen \\
\key{kommentarfarbe} & 165,150,91 & Kommentare \\
\key{hutfarbe} & 130,123,117 & Hauptprogramm-Hut \\
\end{tabular}

Die Blockfarben sind aus der Karol-Online-Oberfläche übernommen.

\subsection{Druckmodus}\label{sec:druck}

Arbeitsblätter werden selten in Farbe vervielfältigt. Der Druckmodus
zeichnet deshalb alle Ansichten -- Welten, Zeilen-Welten und
Blockprogramme -- in Graustufen:

\begin{lstlisting}
\usepackage[druck]{robotkarol}   % das ganze Dokument
\karolsetup{druck=true}          % ab hier; in einer Gruppe nur dort
\karolsetup{druck=false}         % zurueck zur Farbdarstellung
\end{lstlisting}

\noindent
Der Leitgedanke ist \emph{nicht} das absolute Minimum an Toner, sondern:
so wenig wie möglich, so viel wie nötig. Was eine Aufgabe trägt, muss
erkennbar bleiben. Deshalb tragen die Konturen die Information, und die
Flächen bleiben so hell wie möglich:

\begin{itemize}
\item Ziegel sind \emph{weiß} mit schwarz umrandeten Lagen -- der
	Stapel bleibt seitlich abzählbar, kostet aber praktisch keine Farbe.
\item Der Quader ist die einzige große graue Fläche der Welt: er teilt
	seine Form mit dem Ziegel und muss sich von ihm abheben.
\item Die Marke ist mittelgrau. Sie ist klein, und sie liegt oft auf
	einem Ziegel, von dem sie sich absetzen muss.
\item Bei den Blöcken bekommt der häufigste -- \verb|\bbefehl| -- die
	weiße Fläche; die formgleichen \verb|\baufruf| und
	\verb|\banweisung| heben sich durch einen deutlich dunkleren Ton ab.
	Alles übrige unterscheidet sich ohnehin schon durch die Form
	(C-Maul, Hut, Bedingungsplättchen).
\item An die Stelle des 3D-Anschliffs tritt eine schwarze Kontur, und
	die Eingabepillen bekommen einen Rand: auf einem weißen Block wären
	sie sonst nicht zu sehen.
\end{itemize}

\begin{center}
\begin{tabular}{@{}c@{\qquad}c@{}}
\karolzeile[skalierung=0.85]{> Z 2 {2M} M Q} &
{\karolsetup{druck=true}\karolzeile[skalierung=0.85]{> Z 2 {2M} M Q}} \\[4pt]
\begin{karolbloecke}[skalierung=0.85]
	\bwiederholemal{4}{%
		\bbefehl{Schritt}
		\baufruf{Drehen}}
\end{karolbloecke} &
{\karolsetup{druck=true}
\begin{karolbloecke}[skalierung=0.85]
	\bwiederholemal{4}{%
		\bbefehl{Schritt}
		\baufruf{Drehen}}
\end{karolbloecke}} \\[2pt]
\texttt{druck=false} (Vorgabe) & \texttt{druck=true} \\
\end{tabular}
\end{center}

\noindent
Die Farbschlüssel aus den vorigen Abschnitten bleiben dabei
unangetastet: sie wirken wieder, sobald der Druckmodus aus ist -- im
Druckmodus selbst haben sie keine Wirkung, denn eigene Farben würden das
Graustufenschema gerade aufheben. Eigene \emph{Markenfarben}
(\verb|\marke[x=2, y=1, farbe=cyan]|) werden in ihren Grauwert
umgesetzt, bleiben also als verschiedene Grautöne unterscheidbar. Die
beiden Farben, die es nur im Druck gibt, heißen
\key{karolDruckKontur} (Blockkonturen und Pillenränder) und
\key{karolDruckAkzent} (Auswahldreieck der Pillen); sie lassen sich mit
\verb|\definecolor| ändern.

\section{Aufgaben verlinken: \texttt{\textbackslash karolonline}}
\label{sec:online}

Eine Aufgabe in Robot Karol Online steckt vollständig in ihrer Adresse:
auf \url{https://karol.arrrg.de/} folgt eine Raute und der
Aufgabencode. \verb|\karolonline| macht daraus einen Verweis und setzt
dabei nur, was man tatsächlich eintippen muss:

\begin{lstlisting}
Die Aufgabe steht unter \karolonline{2t7t}.
\end{lstlisting}

\noindent
Das ergibt: Die Aufgabe steht unter \karolonline{2t7t}. Der Verweis
führt auf \url{https://karol.arrrg.de/#2t7t}. Der Code wird dabei
unverändert übernommen -- auf Groß- und Kleinschreibung kommt es bei
den Aufgabencodes nicht an.

\subsection{Mit oder ohne \pkg{hyperref}}\label{sec:hyperref}

Der Verweis braucht \pkg{hyperref}. Ob \pkg{robotkarol} es lädt,
entscheidet eine Paketoption:

\begin{tabular}{@{}ll@{}}
\key{hyperref=true} & \pkg{hyperref} wird geladen (Vorgabe) \\
\key{hyperref=false} & \pkg{hyperref} wird nicht geladen \\
\end{tabular}

\noindent
Ohne \pkg{hyperref} setzt \verb|\karolonline| denselben Text, nur ohne
Verweis; das Dokument übersetzt in beiden Fällen unverändert.

Geladen wird erst am Ende der Präambel (im Haken
\texttt{begindocument/before}) -- \pkg{hyperref} möchte als letztes
Paket geladen werden. Ein Dokument darf es deshalb auch selbst laden,
mit eigenen Optionen und an beliebiger Stelle, ohne Optionskonflikt:

\begin{lstlisting}
\usepackage{robotkarol}
\usepackage[colorlinks]{hyperref}
\end{lstlisting}

\noindent
Geladen wird dabei ohne Optionen: wie Verweise aussehen -- farbig,
umrahmt oder unsichtbar --, stellt das Dokument selbst ein, etwa mit
\verb|\usepackage[hidelinks]{hyperref}| oder \verb|\hypersetup{...}|.

Und weil \verb|\karolonline| nicht die Paketoption abfragt, sondern ob
es \verb|\href| beim Setzen wirklich gibt, verlinkt es auch in einem
Dokument, das \pkg{hyperref} trotz \key{hyperref=false} selbst geladen
hat.

Ein Verweis ist ein unteilbarer Block. Steht er in einer schmalen
Spalte, braucht der Absatz unter Umständen ein \verb|\sloppy| (wie die
Inline-Blöcke auch).

\section{Hinweise und Migration}

\begin{itemize}
\item Das Paket benötigt \textbf{LuaLaTeX}.
\item Bis v2.x hieß das Zeichenketten-Kommando
	\texttt{\textbackslash karolwelt}; ab v3.0 heißt es
	\texttt{\textbackslash karolzeile}, der Name \texttt{karolwelt}
	bezeichnet die neue Umgebung. Bestehende Dokumente: einfaches
	Suchen/Ersetzen.
\item Die kurzen Objektnamen \verb|\karol|, \verb|\ziegel|,
	\verb|\marke|, \verb|\quader| und \verb|\wand| sind nur
	\emph{innerhalb} der Umgebung \texttt{karolwelt} belegt. Ein
	Dokument darf sie also selbst verwenden -- außerhalb der Umgebung
	behalten sie ihre eigene Bedeutung.
\item Vorgegeben ist die Figur \key{karol}. In v3.5 war für kurze Zeit
	\key{emma} die Vorgabe; wer sie behalten will, schreibt in die
	Präambel ein \verb|\karolfigur{emma}|.
\item Neu in v3.7 ist außerdem \verb|\karolonline| für Verweise auf
	Aufgaben der Online-Umgebung (Abschnitt~\ref{sec:online}).
	\textbf{Dafür lädt das Paket jetzt \pkg{hyperref}} -- wer das nicht
	will, lädt es mit \key{hyperref=false}
	(Abschnitt~\ref{sec:hyperref}).
\item Neu in v3.7 ist der Druckmodus
	(\verb|\usepackage[druck]{robotkarol}|,
	Abschnitt~\ref{sec:druck}). Ohne ihn ist die Ausgabe dieselbe wie
	in v3.6 -- mit einer Ausnahme: die \emph{Marke} sitzt jetzt in
	beiden Modi mittig auf ihrem Feld. Bis v3.6 fehlte in ihren
	Bildkoordinaten der Tiefenanteil, sie saß rund 0,3\,mm zu weit
	links und berührte auf einem Ziegel dessen linke Kante.
\item Seit v3.6 setzt das Paket seine Beschriftungen in den Schriften
	von Robot Karol Online und lädt dafür \pkg{fontspec}. Wer die
	bisherige Ausgabe will, lädt es mit der Paketoption
	\key{schrift=dokument} -- siehe Abschnitt~\ref{sec:schriften}.
\end{itemize}

\section*{Lizenz}

\pkg{robotkarol} steht unter der \LaTeX{} Project Public License,
Version 1.3c oder später (\url{https://www.latex-project.org/lppl.txt}),
mit dem Wartungsstatus \emph{maintained}. Copyright \copyright{} 2026
Anselm Wagner.

Farben und Proportionen sind aus der Oberfläche von \emph{Robot Karol
Online} gemessen und mit \pkg{TikZ} nachgebaut; es wurden keine Grafiken
übernommen.

\end{document}