progress

doku.tex

@@ -1,6 +1,8 @@
 %% NB: Dieses Dokument baut so 3-10 Minuten je nach Dateisystem-Performance…
 %%     (Sehr viele Beispiele die jeweils komplette eigenständige Dokumente sind.)
 \documentclass[ngerman,10pt]{scrreprt}
+\setcounter{secnumdepth}{\subsubsectionnumdepth}
+\setcounter{tocdepth}{\subsubsectiontocdepth}
 \KOMAoptions{BCOR=1cm,DIV=10,open=any}
 \usepackage{calc,tikz,minted,fontspec,luacode,babel,csquotes,hyperref}
 \hypersetup{colorlinks,urlcolor={magenta!75!black},linkcolor={green!50!black}}
@@ -52,8 +54,7 @@
 
 % set up example build directory
 \directlua{ os.execute "mkdir -p cccbform-examples" }
-\directlua{ os.execute "cp cccbform.cls cccbform-examples/" }
+\directlua{ os.execute "cp cccbform.cls logo.pdf cccbform-examples/" }
-\directlua{ os.execute "cp logo.pdf cccbform-examples/" }
 % stuff to add before/after examples to form a full document
 \begin{luacode*}
 HEADER1 = [[
@@ -214,7 +215,22 @@ Dieses Dokument gibt eine Übersicht über alles, was hilfreich sein könnte.
 Allein schon existierende Formulare anzusehen oder zu kopieren und anzupassen
 sollte jedoch für die meisten Zwecke ausreichen.
 
-\subsection{Für \TeX-Neulinge}
+\section{Voraussetzungen}
+
+Eine aktuelle \TeX-Distribution (auf den meisten Systemen vermutlich \TeX~Live)
+inklusive ggf. dem \texttt{luatex}-Unterpaket, zusätzlich \texttt{latexmk} und
+-- sofern noch nicht vorhanden -- \texttt{make} sollten auf der Programmseite
+ausreichen.
+
+Die verwendete Schrift heißt "Recursive" und kann auf
+\url{https://recursive.design} oder Google Fonts gefunden werden.  Wir brauchen
+nur die "Variable Font", die entweder \texttt{*\_vf*} oder
+\texttt{*-VariableFont\_*} heißt, alle anderen Einzelschriften sind unnötig.
+Die Schrift muss an einem Ort installiert werden, wo die
+\texttt{luatex}-Font-Suche sie findet -- die meisten Standard-Ordner sollten
+funktionieren.
+
+\section{Für \TeX-Neulinge}
 
 Das meiste sollte auch ohne \TeX-Kenntnisse gehen, es gibt jedoch eine Reihe
 von Sonderzeichen, die besondere Bedeutung haben.  Als eines der wichtigeren
@@ -226,25 +242,60 @@ Backslash selbst wird z.~B. durch \texcode{\textbackslash} und nicht
 Symbole malen und bekommt eine Liste möglicher Übereinstimmungen und wie man
 diese jeweils erzeugt. Das Symbol sollte generell ohne
 \texttt{\textbackslash usepackage} auskommen und im \texttt{textmode}
-funktionieren -- diese Infos stehen ggf.  über/unter dem Zeichen.)
+funktionieren -- diese Infos stehen ggf. über/unter dem Zeichen.)
 
-Zu Leerzeichen und Zeilenumbrüchen noch folgendes: Einfache Zeilenumbrüche
+\subsection{Leerzeichen \& Umbrüche}
-werden von \TeX{} generell ignoriert bzw. wie ein Leerzeichen zwischen Worten
+
-behandelt.  Eine leere Zeile (also (mindestens) zwei aufeinanderfolgende
+Zu Leerzeichen und Zeilenumbrüchen noch folgendes: \emph{Einfache
-Zeilenumbrüche) beginnt einen neuen Absatz. (Das geht auch mit
+Zeilenumbrüche} werden von \TeX{} generell ignoriert bzw. wie ein Leerzeichen
-\mintinline{tex}{\par}.)  \mintinline{tex}{\\} ist ein "einfacher"
+zwischen Worten behandelt.  Eine \emph{leere Zeile} (also (mindestens) zwei
+aufeinanderfolgende Zeilenumbrüche) beginnt einen neuen Absatz.  (Das geht auch
+mit \texcode{\par}.) \texcode{\\} ist ein "einfacher"
 Zeilenumbruch in der Ausgabe (ohne den Absatz zu beenden), der hier aber
-möglichst vermieden werden sollte.  Ein oder mehrere Leerzeichen werden wie ein
+möglichst vermieden werden sollte.
-einzelnes Leerzeichen gelesen, erlauben aber generell Zeilenumbrüche wenn die
+
-Zeile voll ist.  \mintinline{tex}{~} erzeugt geschützte Leerzeichen, die nicht
+Ein oder mehrere Leerzeichen werden wie ein einzelnes Leerzeichen gelesen,
-umbrechen dürfen (und z.~B. bei Abkürzungen (\mintinline{tex}{z.~B.}) oder
+erlauben aber generell Zeilenumbrüche wenn die Zeile voll ist.
-Zahlen mit Einheiten verwendet werden sollten.)  Nach Befehlen
+\texcode{~} erzeugt geschützte Leerzeichen, die nicht umbrechen dürfen
-(\mintinline{tex}{\foo}) werden (beliebig viele) Leerzeichen generell als
+(und z.~B. bei Abkürzungen (\texcode{z.~B.}) oder Zahlen mit Einheiten
-Token-Trenner ignoriert und entfernt (\mintinline{tex}{\TeX test} = \TeX test),
+verwendet werden sollten.)
-ein Verdoppeln des Leerzeichen bringt ebenfalls nichts.  Stattdessen kann man
+
-entweder leere Argumente angeben (\mintinline{tex}{\TeX{} test} = \TeX{} test)
+Nach Befehlen (\texcode{\foo}) werden (beliebig viele) Leerzeichen
-oder das Leerzeichen ebenfalls mit einem Backslash schützen
+generell als Token-Trenner ignoriert und entfernt (\texcode{\TeX test}
-(\mintinline{tex}{\TeX\ test} = \TeX\ test.)
+= \TeX test), ein Verdoppeln des Leerzeichen bringt ebenfalls nichts.
+Stattdessen kann man entweder leere Argumente angeben
+(\texcode{\TeX{} test} = \TeX{} test) oder das Leerzeichen ebenfalls mit einem
+Backslash schützen (\texcode{\TeX\ test} = \TeX\ test.)
+
+\subsection{Befehlsstruktur}
+
+\TeX\ ist eine sehr flexible Makro-Sprache, aber sowohl \LaTeX\ als auch diese
+Klasse geben sich Mühe, das meiste davon zu verstecken und sehr einheitliche
+Struktur vorzugeben.  Befehlsaufrufe haben generell die Form
+\texcode{\Befehl{Arg1}{Arg2}...{ArgN}}, wobei Argumente in geschweiften
+Klammern immer angegeben werden müssen.  Einige Befehle akzeptieren auch
+\emph{optionale Argumente}, welche als Konvention eckige Klammern benutzen --
+diese können entweder angegeben oder komplett weggelassen werden.
+Zusätzlich gibt es manchmal auch "gesternte" Varianten, wo ein \texttt{*}
+unmittelbar auf den Namen folgt.  Diese machen in der Regel nahezu das gleiche
+wie die normale Variante ohne Stern.
+
+\subsection{Erzeugen von PDFs}
+
+Sind alle Tools installiert, so sollte ein \texttt{make} ausreichen.  (Das
+Makefile findet automatisch alle neuen \texttt{.tex}-Dateien.)  Soll nur ein
+einzelnes Dokument gebaut werden, so sollte \texttt{make foo.pdf} zu einem
+\texttt{foo.tex} genau dieses eine Dokument bauen.
+
+\emph{Wirklich} alle Dokumente zu bauen dürfte beim ersten Mal mehrere Minuten
+dauern.  (Diese Dokumentation hier enthält viele Beispiele, die tatsächlich
+eigenständige Dokumente sind.  Der Overhead für alle je $2\times$
+\texttt{lualatex} zu starten, mehrere temporäre Dateien zu schreiben, etc. etc.
+kann gut 3--10 Minuten fressen.)
+
+\chapter{Befehle}
+
+Bereitgestellte Befehle fallen grob in 4 Kategorien -- Titel, Inhalt, Struktur, Hervorhebung.  Zusätzlich hat die Klasse selbst ein paar Optionen.
 
 \section{Klassen-Optionen}
 
@@ -257,14 +308,19 @@ drucken die Elemente mit, was dann wiederum anders komisch aussehen kann\dots
 \subsection{\texttt{noform}}
 
 Wird das Dokument also stattdessen mit
-\mintinline{tex}|\documentclass[noform]{cccbform}| begonnen, werden keine
+\texcode|\documentclass[noform]{cccbform}| begonnen, werden keine
 PDF-Formular-Felder erzeugt sondern nur die "falschen" als Bilder erzeugt. Das
 stellt sicher, dass reine Druckvorlagen (die eh nicht ausgefüllt werden sollen)
 mit allen Viewern fehlerfrei gedruckt werden können.
 
-\chapter{Befehle}
+\subsection{\texttt{example} und \texttt{shortexample}}
 
-Bereitgestellte Befehle fallen grob in 4 Kategorien -- Titel, Inhalt, Struktur, Hervorhebung.
+Diese sind lediglich für Beispiele -- wie hier in dieser Doku -- gedacht.
+\texttt{example} wählt A6 als Format aus, reduziert die Ränder auf fast nichts,
+und passt ein paar Befehle an das kleinere Format an. \texttt{shortexample}
+macht das gleiche, berechnet aber am Ende die tatsächliche Höhe und verkürzt
+das ausgegebene Dokument.  Fast alle Beispiele hier sind
+\texttt{[shortexample]}s.
 
 \section{Titel}
 
@@ -291,7 +347,11 @@ also nicht beim verarbeiten des restlichen Inhalts.)
 \Text{(...und hier geht's weiter.)}
 \end{ShortExample}
 
+\filbreak
+\subsubsection{\texcode{\AddressTitle*{Titel}}}
+
 Es gibt auch die Variante mit \texttt{*}, welche zusätzlich das Logo einbettet.
+\nopagebreak[2]
 
 \begin{ShortExample}[8.865cm]{addresstitlestar}{Titel, Adresse und Logo}
 \AddressTitle*{Beispieltitel}