diff --git a/doku.tex b/doku.tex index 7812313..6445d93 100644 --- a/doku.tex +++ b/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 logo.pdf cccbform-examples/" } +\directlua{ os.execute "cp cccbform.cls 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 -werden von \TeX{} generell ignoriert bzw. wie ein Leerzeichen zwischen Worten -behandelt. Eine leere Zeile (also (mindestens) zwei aufeinanderfolgende -Zeilenumbrüche) beginnt einen neuen Absatz. (Das geht auch mit -\mintinline{tex}{\par}.) \mintinline{tex}{\\} ist ein "einfacher" +\subsection{Leerzeichen \& Umbrüche} + +Zu Leerzeichen und Zeilenumbrüchen noch folgendes: \emph{Einfache +Zeilenumbrüche} werden von \TeX{} generell ignoriert bzw. wie ein Leerzeichen +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 -einzelnes Leerzeichen gelesen, erlauben aber generell Zeilenumbrüche wenn die -Zeile voll ist. \mintinline{tex}{~} erzeugt geschützte Leerzeichen, die nicht -umbrechen dürfen (und z.~B. bei Abkürzungen (\mintinline{tex}{z.~B.}) oder -Zahlen mit Einheiten verwendet werden sollten.) Nach Befehlen -(\mintinline{tex}{\foo}) werden (beliebig viele) Leerzeichen generell als -Token-Trenner ignoriert und entfernt (\mintinline{tex}{\TeX test} = \TeX test), -ein Verdoppeln des Leerzeichen bringt ebenfalls nichts. Stattdessen kann man -entweder leere Argumente angeben (\mintinline{tex}{\TeX{} test} = \TeX{} test) -oder das Leerzeichen ebenfalls mit einem Backslash schützen -(\mintinline{tex}{\TeX\ test} = \TeX\ test.) +möglichst vermieden werden sollte. + +Ein oder mehrere Leerzeichen werden wie ein einzelnes Leerzeichen gelesen, +erlauben aber generell Zeilenumbrüche wenn die Zeile voll ist. +\texcode{~} erzeugt geschützte Leerzeichen, die nicht umbrechen dürfen +(und z.~B. bei Abkürzungen (\texcode{z.~B.}) oder Zahlen mit Einheiten +verwendet werden sollten.) + +Nach Befehlen (\texcode{\foo}) werden (beliebig viele) Leerzeichen +generell als Token-Trenner ignoriert und entfernt (\texcode{\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}